Posted: 07 February 2013
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.
- Setup github
- Get libGDX sources into Eclipse
- Add "upstream" remote
- Building the library
- Make a change
- Using this build in your existing libGDX-based projects
- Pushing a change up to github
- Updating with changes from "upstream"
- Updating your fork at github
ant. If you're running on Windows like I am, I
recommend getting cygwin setup and
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.)
user.name are set correctly in your git
repository (either globally or in a specific repository's
config). I changed these with
git on the command-line, and not via
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:
Projects from Git
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
-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
LwjglTestStarter.java and select
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.
*-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
To run the GWT tests, you must explicitly compile them. Eclipse just
auto-builds the Java code. The GWT compiler converts that Java into
gdx-tests-gwt project, and select
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
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
The "Development Mode" view that pops up will provide what looks like a
helpful URL. Beware! It will look like this:
Do not click that, instead just take the first part:
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
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
Branches entry and select
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
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.
in the build directory to populate the
dist/ subdirectory will all
.jar files and native libraries. (This uses the
build.xml file to build the libGDX distribution image.)
I then copy this off to a
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
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
upstream and right click on the green-arrow-going-left
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
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
.... 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
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.