Posted: 07 February 2013
Tags: libGDX, git, Eclipse, github

Using libGDX sources with github and Eclipse

These are my notes on using the libGDX source at github with Eclipse and occasionally with the git command line. Please let me know if you have any corrections or think anything needs to be clarified more.

1. Setup github
2. Get libGDX sources into Eclipse
3. Add "upstream" remote
4. Building the library
5. Make a change
6. Using this build in your existing libGDX-based projects
7. Pushing a change up to github
8. Updating with changes from "upstream"
9. Updating your fork at github

Setup github

Got 'bitiotic' account on github.

Forked libgdx/libgdx to bitiotic/libgdx on github.

Install git and ant. If you're running on Windows like I am, I recommend getting cygwin setup and installing git that way so you have a command-line way of running git (i.e., without Eclipse). There are lots of other options for installing git on Windows, though.

Get libGDX sources into Eclipse

Setting up your local git repository

Cloned my forked repository (bitiotic/libgdx) down to my desktop via Eclipse eGIT. Called it "libgdx-github". (Select Clone a Repository from the "Git Repositories" view's drop-down menu.)

Read the libGDX process for setting up a cloned libGDX repository at the libGDX documentation page. (That is more likely to stay up to date.)

Make sure user.email and user.name are set correctly in your git repository (either globally or in a specific repository's .git config). I changed these with git on the command-line, and not via eGIT.

Importing libGDX into Eclipse

First, update the binaries in the checkout (as they're thankfully not included in the source):

ant -f fetch.xml

Second, import all the projects into Eclipse: File -> Import ... -> Git -> Projects from Git -> Local -> "libgdx-github"

Be sure to Import Existing Projects... and use the top-level directory ("Working Directory - X:\path\to\libgdx-github")

You should see a long list of projects in the wizard like "cuboc", "gdx", "gdx-audio", "superjumper", etc.

As an aside, I used an Eclipse "Working Set" in the package explorer to keep all these new packages organized and make it easy to "hide" them. This is easy to do when importing the packages from git, or afterwards in the Package Manager. Its just an organizational view thing, and doesn't impact the packages on disk or their visibility of each other.

Add "upstream" remote

Add an "upstream" "Remote" to your new git repository. This will allow you to pull changes from the official libGDX tree into your local one. Use the command-line git:

git remote add upstream https://github.com/libgdx/libgdx.git

(I was unable to get this to work via the eGIT UI.)

Building the library

Eclipse should build all the Java packages in the background automatically. Except for the -html ones as there is a dependency on the GWT libraries that must be fixed up manually (for licensing reasons). (Or ignored, as I have done, until you need them.)

To make sure the desktop stuff built correctly open package gdx-tests-lwjgl -> src -> com.badlogic.gdx.tests.lwjgl. Right-click on LwjglTestStarter.java and select Run As -> Java Application. This should pop up a window with a long list of libGDX tests, click one and try it out. I recommend the "StageTest", as it should make more sense than some of the other tests which don't do much visually.

You should be able to run any of the example games at this point.

Fixing the *-html project errors

Assuming you have GWT installed, you just need to fixup the HTML projects to get rid of the red warnings.

Clicking on the projects/packages themselves isn't helpful, as this is Eclipse. You have to open the "Problems" view. You should see several errors about "The web.xml file does not exist". Just right-click on the error here, and Quick Fix it. You'll get a dialog for which you just need to click Finish.

Running gdx-tests-gwt

To run the GWT tests, you must explicitly compile them. Eclipse just auto-builds the Java code. The GWT compiler converts that Java into JavaScript. Right-click the gdx-tests-gwt project, and select Google -> GWT Compile. The defaults in the first part of the Wizard are fine. Start the compile. When it asks for a WAR directory, you must pick the tests/gdx-tests-gwt/war directory (or you must copy the index.html and the WEB-INF directory yourself). If that succeeds, right-click on the project and select Run As -> Web Application. The "Development Mode" view that pops up will provide what looks like a helpful URL. Beware! It will look like this:

http://127.0.0.1:8888/index.html?gwt.codesvr=127.0.0.1:9997

Do not click that, instead just take the first part:

http://127.0.0.1:8888/index.html

The difference is performance (try it!). The first one will run in some an odd hybrid mode (lamely called "Developer mode") where your web browser communicates with code running in Java in Eclipse (this mode also requires a browser plugin). The second URL will run the code in "Production Mode" and will actually execute the JavaScript that was generated.

If you immediately get a "404 not found" error, then not all the required files got dumped in the war directory you're running from. (Probably the compile didn't happen or failed.)

Generating the Javadoc

If you make changes to Javadoc and want to see the results, you can just run the Eclipse javadoc generator: Select a project or package then in the Project menu choose Generate Javadoc.... I generally choose a directory outside of the default to generate the javadoc (no need to pollute the libgdx tree). If you click through this wizard, one of the last options is to generate an ant script that will regenerate the documentation.

To generate the more "official" documentation, run ant docs in the libgdx root. The docs will be dumped in dist/docs.

Make a change

Assuming you've found a bug to fix or some documentation or tests to improve, go ahead and make the change. Make some tests or extend an existing test.

Its best practice in git and with github to create a new branch for changes. Its okay to create this branch after you've started editing some files, as the edited files will "move" to the new branch when you create it. In eGIT use the "Git Repositories" view, right click on the Branches entry and select Switch To -> New Branch .... Make sure the new branch is off of the correct parent (the local master). (Alternatively, you can create the new branch while right-clicking on the appropriate parent branch.)

Commit your changes (with Team -> Commit ...) to your branch from time to time. You can have multiple separate commits on the branch. Note that the whole set of commits of the branch will be considered one "patch" ("pull request") at github.

If you want to use the change locally, you can merge the branch back into your master. Or you can upload the branch to github if you'd like to submit the change back to libGDX.

Using this build in your existing libGDX-based projects

To use my locally-built libGDX build, I go through the extra step of creating a complete distribution, "installing" the build elsewhere in my system, and then pointing my projects at that build. This makes it easier to upgrade libGDX independently of having all my projects use the update.

Just run

ant

in the build directory to populate the dist/ subdirectory will all the necessary .jar files and native libraries. (This uses the build.xml file to build the libGDX distribution image.)

I then copy this off to a ../../builds/libgdx-vx.y.z-SNAPSHOT-$(date +%Y%m%d).N directory. (I haven't tried pointing gdx-setup-ui at this, but I should.)

Pushing a change up to github

Once you've committed your changes locally to your fix branch, you can push the whole new branch up to github. Just right-click on the repository in the "Git Repositories" view, and select Push to Upstream to just push all outstanding commits and local branches up to github (or use Push... to have a bit more control over what gets pushed up). Changes which have not been committed will not be pushed up to github. Ideally, you'll only have changes on your new branch, and thus you'll end up with a new branch at github.

Another reason for using a branch is github's workflow. They expect you to push a branch with a set of changes you'd like to submit (they call it submitting a "pull request"). So if you're hoping to submit changes back to libGDX, please put each set of commits you'd like to be considered as a coherent patch on a single branch.

Be aware that the libGDX build creates a lot of files in the source tree that may not be in .gitignore, or may be modified by Eclipse while running (especially in the GWT area). Be sure to only commit the files you really mean to commit. On the other hand, be sure to commit and push all the files required to make your patch work! (Run git status on the command line to double-check the state of your repository.)

This push-first, request-pull-later model is why you fork the libgdx/libgdx project at github (vs. just cloning the libgdx/libgdx project directly into Eclipse): so you can write your changes up to github and share them from there.

You can then send a pull request to the libGDX maintainers, via github. Basically, just select your topic branch and click the "pull request" button. For more details, check out the the github pull request help page.

Having a branch associated with the pull request makes it easy to incorporate changes that the maintainers suggest to your patch -- just make the changes, and push them into the same branch at github. They're automatically considered part of the original pull request.

Actually logging into github

Note that syncing a repository down from github to your local machine does not necessarily exercise your login credentials at github (since you probably just used the public "https" protocol to read the files). Not until you push changes will you discover if logging into github works. You must use the "ssh" protocol to connect to github with your account credentials (or the "git" protocol with a git credential manager). Not that I wasted a bunch of time diagnosing this or anything ... See more tips and suggestions for diagnosing github login issues at: http://sitaramc.github.com/gitolite/putty.html.

Updating with changes from "upstream"

Assuming you've configured your "upstream" remote correctly, you can go to the Git Repositories viewer, open your libgdx project, open Remotes -> upstream and right click on the green-arrow-going-left entry. Choose Fetch to fetch all the changes from the core libgdx tree. This just stores the commits locally and updates the "upstream/*" branches, but doesn't do anything to your local branches.

Updating the binary bits

Its probably a good time to run ant -f fetch.xml at the command-line in your local checkout to update the native libraries to match the code you just downloaded.

Given that a bunch of non-git-managed native files are in your libGDX repository, its not really possible to work on multiple branches that diverge very much --- the native bits won't necessarily be compatible.

Incorporating upstream changes

Now that the changes are stored locally, you need to incorporate them into your branches. If you're planning on sending changes up to github to be pulled into libGDX, I think you should follow a rebase workflow. This means that after fetching changes, you rebase your local branches to the latest upstream and you let the libGDX maintainers merge your changes.

In the Eclipse UI, make sure the branch you want to rebase (the branch with your local changes) is checked out. Right-click, select Rebase .... In the dialog you'll be asked which branch the current branch should be rebased on. Select "upstream/master" as the basis for the rebasing. See Eclipse rebasing guide for more details.

I recommend keeping your local "master" branch up to date this way, and not making changes on the "master" branch (keep all your changes on "topic" or "feature" branches).

For a command-line based approach, I refer you to an expert at StackOverflow

Updating your fork at github

Github does not (as of January 2013) have a UI for merging changes into a forked project from the original project. So you need to fetch the main libGDX branch changes into your local copy (see above), and then push them up to github.

Specifically, that means fetching from "upstream" rebasing to the upstream * pushing changes up to github

In practice, this will all happen as a side-effect of you fetching upstream changes, rebasing to them, and then pushing all your commits (and branches) up to github.