How to Compile

How to Compile

From Plex

Jump to: navigation, search
 This article or section is incomplete and may require expansion and/or cleanup.
Please improve the article, or discuss the issue on the talk page.

Contents

What is Git?

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 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.

What is GitHub?

According to GitHub's website:

GitHub is the easiest (and prettiest) way to participate in that collaboration: fork projects, send pull requests, monitor development, all with ease.

GitHub is a Git repository hosting service, providing a conduit for developers to collaborate on projects, make comments and suggestions, and visually see the evolution of those projects.

How to Start?

There are two basic ways to start. You can fork Elan's repository on GitHub, or you can simply clone it. I recommend the former because that way you get instant off-site backup of your work.

Getting the Code

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.

Prerequisites

Please note that Plex will only run on Mac OS X 10.5 / Intel platform.

Before you can download the source code and compile, it you have to get several packages (along with git) before you can continue. The easiest way to get these packages is to download and install MacPorts. If you already have these packages installed or prefer to download and compile them on your own, by all means be my guest.

Packages

  • Xcode (preferably 3.1)
  • git
  • gawk
  • libsdl
  • libsdl_image
  • libsdl_mixer
  • glew
  • fribidi
  • freetype
  • python24
  • mysql5
  • lzo
  • libmad
  • samba3
  • pcre
  • fontconfig

Getting Xcode

You need to make sure that you have at least Xcode 3.1 (the latest version is part of the iPhone SDK). The SDK can be found at http://developer.apple.com/iphone/sdk1/.

Getting MacPorts

MacPorts is free package control software. The instructions for downloading and install MacPorts is available at http://www.macports.org/install.php.

Installing the Packages

From the terminal window type the following commands (please note the $ should not be included in your commands, $ represents the command prompt). 

sudo port install gawk git-core +svn

If building sqlite fails in this process try the following and run the above command again: 

sudo port clean sqlite3

As an alternative, a pre-built Git installer found at http://code.google.com/p/git-osx-installer/. 

sudo port install libsdl libsdl_image libsdl_mixer glew fribidi freetype python24 mysql5 lzo libmad pcre fontconfig

Plex requires an older version of samba3 than provided by macports. To get this version do the following: 

mkdir Samba3
mkdir Samba3/files
cd Samba3
curl http://trac.macports.org/export/34870/trunk/dports/net/samba3/Portfile >Portfile
curl http://trac.macports.org/export/34870/trunk/dports/net/samba3/files/patch-source_smbd_utmp_c.diff > files/patch-source_smbd_utmp_c.diff
sudo port install

Performance & Speed is important to Plex and so some of the code have started making use of Boost libraries. Get Boost to your plex with 

sudo port install boost

And if that gave you an error about Makefile:2: *** missing separator. Stop. Don't panic. The error is resolvable by doing this (as already discussed here [1]) 

sudo port clean boost
sudo port install jam boost

Quick and Dirty

Setting up Git Environment

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 "barkley@woof.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

Create and/or edit the ~/.gitignore file and add the following to it: 

.DS_Store
*.o
*.lo
.libs
*.la

Forking the Repository

GitHub provides a great tutorial (Keeping A Git Fork in Sync with the Forked Repo) for forking repository. Follow this tutorial for a better understanding on how repository forking works (it does require a GitHub account).

Getting the Repository

We need to clone the Plex repository. 

git clone git://github.com/elan/plex.git

If you get an error about the remote HEAD refers to nonexistent ref, ignore it and continue making a branch and checking out as mentioned couple of steps down.

Alternatively, if you decided to create your own fork of the Git repository, you should clone your repository. 

git clone git@github.com/[username]/plex.git

If you run into any complications cloning your own repository, you may not have set up your SSH keys properly. Review Github's Guides on Providing Your SSH Key.

At this point you’ll need to wait a while.

If you've cloned Elan's repository, When it’s done, you can make yourself a copy of the branch to work on. As of this documentation, the latest development branch is v0.5. You can change v0.5 for whatever is the latest development branch. First change the directory into the repository that you've just cloned. 

cd plex
git branch --track [my-branch] origin/v0.5
git checkout [my-branch]

Contributing

Building the Code

Now we’ll build the code and run it. You can also do this inside XCode, of course. 

xcodebuild -parallelizeTargets -configuration Debug
export PLEX_HOME=/Applications/Plex.app/Contents/Resources/Plex
./build/Debug/Plex.app/Contents/MacOS/Plex

Time to write some code!

Saving Changes

Similar to Subversion, Git allows you to group files into change sets. Change sets are group of changes that are applied with each revision iteration. These change sets can be initiated by using a combination of the following commands: 

git rm <file-spec>                       # Remove a file
git mv <old-file-spec> <new-file-spec>   # Moves or renames a file
git add <file-spec>                      # Adds a modified (or untracked) file to the change set

Once you've modified the repository you can run two simple commands to figure out what has changed. 

git status
git diff

git status gives you a quick snap shot of all the files that have been renamed, moved, deleted, modified, or untracked.

  • Changes to be committed are changes to the repository that you've staged (or included) for the next change set committal.
  • Changed but not updated are changes to the repository that git has detected but you haven't told git what to do with it. Until you use git add or git rm, git will not know what to do with those files and keep reporting that to you.
  • Untracked files are those files that exist in directory structure, but you've never told Git that you should include it into the version controlled repository.

git diff shows you all the differences between the HEAD (see Revision Control: Common Vocabulary to get an understanding of what the HEAD is) and your current repository.

If you want to see the difference between the currently staged files and the HEAD you should run: 

git diff --cached

Once all of your changes are completed you can combine them into a change set. Each change set (or commit) must be accompanied by a message. This message is used to let others know why you made the changes that you made. Similar to Subversion, a change set is committed to the repository using: 

git commit -m "My message"

It is common practice to keep the change sets succinct and the changes within that set be related to one another. Unrelated changes should be committed in a different change set.

However, unlike Subversion, the commit command does not send the changes back to the central repository. Instead, Git compresses those changes and commits them to your local repository (yes there is a local repository on your computer). If you have write commits to a remote repository then you must run a push command.

Pushing to Your GitHub Repository

After making updates to your local repository, your local repository is no longer synchronised with your remote repository. Git has a few mechanisms to communicate that to you, one of which is git status.

If your repository is not in sync, git status will report something to the affect of: 

 Your branch is ahead of the tracked remote branch 'origin/v0.5 by 5 commits

There are other tools that report similar findings, such as git checkout.

To syncrhonize your remote repository to your local repository, you must perform git push command. git push talks to the remote repository to figure out what has changed locally and remotely, and sends those changes to the remote repository.

If you are working from a recently created branch, and you have not pushed this branch to the remote repository before, then Git has no clue where it needs to be stored and under what alias it should be stored as. Git allows a very robust work-flow and gives you the ability to reference multiple remote repositories from your local repository. This is useful for a multi-developer environment such as Plex, it allows for you to check other people's code out without creating a separate local repository for each remote one. 

git push origin [branch_name]

This will now tell git, that you want to save the branch that you are working in to your remote repository (aliased to origin) using [branch_name]. In the background, git will add an entry to the local repository's configuration file so that whenever you run git push it will always push it to the remote branch on the repository (aliased origin).

Now, whenever you have commits to send to the remote repository, it is as simple as running: 

git push

TODO: What is a non-fast forward commit -- how to overcome it?

Creating Patches for Plex Maintainer

TODO

Getting the Latest Changes

TODO

From Someone Else's Repository

Like Subversion, Git has mechanisms to get the latest changes from the remote repository. You can accomplish this by issuing a pull: 

git pull

From My Own Repository

TODO

Conclusion

So now you’re set. You can do development on one or more branches locally, push them to GitHub, get updates from elan's branch (or other people’s branches!) and when the code is ready to be integrated, simply issue a pull request on the GitHub site.

This was a short tutorial. We didn't even even cover all the different cool things you can do with Git, but hopefully this will serve as a reasonable primer. Notice we never discussed “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 off-site backup without it. If you’re starting to get more involved and the committers are slowing you down with, just ask for it and we’ll work with 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

  • The source of it all, Git's website.
  • The greatest Git hosting repository, GitHub
  • 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.
  • Get this booklet on Git! The nine bucks is more than worth it.
  • A nice cheat-sheet for the common commands and their usage.
  • Really good Git resources by Scott Chacon.
  • Real simple to follow screencasts, GitCasts.
  • Other good guides, resources, and tutorials at GitHub's Guides.
  • A really good blog post from GitHub providing additional resources to newbies.
Retrieved from "http://wiki.plexapp.com/index.php/How_to_Compile"