Use the Source, Luke
OK, so you’d like to build from source and contribute to the project. Git (and GitHub) make this really easy, and give you powers far beyond what non-distributed version control systems like Subversion provide.
The problem with Subversion and CVS in open source projects is that they’re like a walled fortress, and you’re either on the inside or the outside. If you’re a “member” you’re given commit access, and then you can develop on your own branches, checkpoint your work, etc. However, life isn’t so good on the outside. You essentially work without a version control system! You can pull in updates as they get committed to the repository (hoping they merge cleanly with your code), but in terms of keeping order to your local changes and check-pointing them, you’re shit out of luck.
Distributed version control systems like Git essentially democratize the process, giving everyone first-class revision control capabilities. GitHub takes this a step further and puts the “official” people making releases of a project on the *exact* same footing as everyone else with an Internet connection. With a click of a button, you can fork an existing project, work on it with a bunch of your friends, and then request a pull from the parent project. Check out the fork tree for the Ruby on Rails source.
I’ve used quite a few revision control systems (CVS, Perforce, Subversion, and Clearcase — ick), and Git is the only one that both got me excited and fundamentally changed the way I work.
There are two basic ways to start. You can fork my repository on GitHub, or you can simply clone it. I recommend the former because that way you get instant offsite backup of your work.
- Download and install MacPorts.
- Download and install XCode. I use the new 3.1 version that’s part of the iPhone SDK.
Now install Git (which pulls in quite a bit of stuff with it). Why you need to manually specify gawk is beyond me. If you’re uncomfortable with the Terminal, you probably want to do some calisthenics or a shot at this point.
$ sudo port install gawk git-core +svn
Let's get your Git environment set up. Skip the "color" configuration if you don't like color highlighting.
$ git config --global user.name "Barkley Dawg" $ git config --global user.email "email@example.com" $ git config --global color.diff auto $ git config --global color.status auto $ git config --global color.branch auto $ git config --global core.excludesfile ~/.gitignore
Edit the ~/.gitignore file and add the following to it:
.DS_Store *.o *.lo .libs *.la </pre Now we need to clone the repository. As I mentioned above, you can either clone mine, or fork on GitHub and clone that one. The example below clones mine; simply substitute your URL if you forked.$ git clone git://github.com/elan/xbmc-fork.git
At this point you'll need to wait a while, during which time you probably want to have MacPorts install the rest of the dependencies:$ sudo port install libsdl libsdl_image libsdl_mixer glew fribidi freetype python24 mysql5 lzo libmad pcre fontconfig py-pyobjc
(Note that for SAMBA, you should follow the instructions here).
Now sit back and relax, or do shots of tequila while your machine crunches away. When it's done, you can make yourself a branch to work on. I'm currently working on the v0.5 branch for releases, so you can create yourself a tracking branch starting from there to work from, and check it out:$ git branch --track my-branch origin/v0.5 $ git checkout my-branch
Now we'll build the code and run it. You can also do this inside XCode, of course.$ xcodebuild -parallelizeTargets -configuration Debug $ export XBMC_HOME=/Path/To/OSXBMC.app/Contents/Resources/XBMC $ ./build/Debug/XBMC
Time to write some code! If you want to merge in the latest changes to the branch, you can issue a pull:$ git pull origin/v0.5
In order to push to the remote repository, you'll need to tell it which local branch to push. This next operation will only work if you did fork my repository (in which case you would likely add my v0.5 branch as a remote).$ git push origin my-branch # First time. $ git push origin # Subsequent times.
So now you're set. You can do development on one or more branches locally, push them to GitHub, get updates from my branch (or other people's branches!) and when the code is ready to be integrated, simply issue a pull request on the GitHub site.
I haven't really even covered all the different cool things you can do with Git, but hopefully this will serve as a reasonable primer. Notice I never talked about "commit access" -- why is that? Well, if you're doing the occasional one-off patch or experiment, you really don't need it, and you get all the benefits of version control and offsite backup without it. If you're starting to get more involved and you want commit access because I'm slowing you down with my pokey pulls, just ask for it and I'll give it to you, provided you're not a raging psychopath. That's the funny thing about Git; commit access doesn't stand in the way of getting stuff done. And remember, using Git means you never have to say you're sorry!
Some great Git resources:
- This is a brilliant video of Linus talking about Git at Google. Really hilarious, if only to watch him call lots of people stupid in a way only he can get away with.
- I can't recommend this booklet on Git enough. The nine bucks is more than worth it.
- A nice cheat-sheet for the common commands and their usage.
Please let me know if any of the above doesn't work for you. We'll be moving these instructions somewhere more permanent once I know they're correct. Also, I'll post most Git tips over time. I've been especially loving the bash autocompletion.