Working With Androidplot Source

Working With Androidplot Source

We try to keep these pages as up to date as possible, but typos are inevitable, especially immediately following new releases. If you spot an error, please let us know either in the forums or shoot an email to oops@androidplot.com. Thanks!

Overview

This page will show you how to obtain a copy of the Androidplot source code, how to compile it and how to contribute code back to the project.

Androidplot makes use of a Git repository on Bitbucket to store it’s source.  If you’ve got a git client installed, you can get the latest copy of the Androidplot source by cloning using this command:

git clone https://bitbucket.org/androidplot/androidplot.git

You can also download an archive of all sources by going to the Androidplot Bitbucket Downloads page, clicking “Branches”  and downloading a copy of the “master” branch in whichever archive format you prefer.

If you want to contribute to the project then you’ll need a Bitbucket account.  The good news is they are free.  You can set one up here.  Once you’ve got a Bitbucket account, you’re ready to get going.

Fork Androidplot

All this is, is cloning the Androidplot repository into your private Bitbucket account.  You’ll find an option for that if you browse the Androidplot Bitbucket page, or you can just click here.  You now have your  own personal online copy or “fork” of the Androidplot repository.

Create a Local Repository

Once you’ve finished forking, you’re ready to create a local repository of your fork on your computer.  Depending on how you’ve set things up you can use either http or ssh.  For the sake of simplicity I’ll be using http along with the fictional userid “joeblow” in the command line examples that follow.

git clone https://joeblow@bitbucket.org/joeblow/androidplot.git


Once you enter this command you will be prompted for your bitbucket account password.  Upon successfully entering it, a directory called androidplot will be created in the current working directory containing a copy of the androidplot source and a clone of your personal fork of the androidplot repository.  At this point let’s cd into the newly created androidplot directory and verify that it has properly associated the local repository with the remote “origin”:

cd androidplot git remote -v

You should see something like this:

Notice the “origin” labels to the left.  This is the alias for our remote fork of the official Androidplot git repository. 

Compile the code

While the Androidplot repository does contain project files for  IntelliJ IDEA, it officially uses Maven to build and to continue this tutorial you’ll need to install and configure Apache Maven 3.0.4 to get Maven builds working.  If you don’t already have it installed you can download it here.  There are installation instructions at the bottom of the download page.

You’ll also need to install and configure Java JDK 1.6.x and the Android SDK.  Be sure to set both the JAVA_HOME and ANDROID_HOME environment variables as well.

Once you’ve got everything setup, cd into the androidplot directory and try to build using Maven:

mvn package

This will compile and run unit tests against the Androidplot core sources, generate javadocs and produce 3 jars containing sources, classes and javadoc respectively.  These will be located in  Androidplot-Core/target.

After it finishes building and packaging core, it compiles the DemoApp against the freshly build jar library and packages it into an APK.

If all went well you should see something like this printed at the end:

Contributing to Androidplot

You’ve made a modification to the Androidplot source that you think others might find useful and you want to contribute it back to the project.  First, thanks!  Second, you’re going to need to submit what is called a Pull Request.  For those who are unfamiliar, a pull request is basically you saying “Hey guys, I’ve made an interesting change to my fork of Androidplot.  Here are those changes.  If you like them, go ahead and merge them into Androidplot’s main repository.”  In order to accomplish this you first need to get all of your code changes pushed to your forked copy of Androidplot on Bitbucket.  If you followed the setup steps above, then this should be what your remote alias “origin” is currently pointing at.  There are a zillion and one ways to handle branching etc. in Git.  If you are branching then chances are you don’t really need this tutorial in the first place.  For everybody else, to push your currently active branch (most likely “master”) use this command:

git push origin HEAD

Once that’s completed, you are ready to submit your pull request to Androidplot.  To do this, log into your bitbucket account, browse to your copy of the Androidplot repository and look for “Pull Request” at the top-right of the page.  Once you click on it, you will be brought to the “Create a Pull Request” page.  On the left drop-down, make sure the correct branch is selected.  To the right of that are two more drop-downs.  The top one should say “androidplot/androidplot” and the bottom one should say “master”.  Enter a title and description that adequately describes the changes you are contributing and click “Create Pull Request” at the bottom.  You’ve just submitted your changes for review.  Be aware that once you’ve submitted the pull request it’s possible that some, all or none of the changes will be accepted.  Partially accepting a pull request is called cherry picking a pull request and can complicate things on the contributor’s part.  Here’s a good thread about this scenario.  As a result of this scenario and a couple others it’s strongly suggested that you branch your changes into a feature branch before submitting the pull request.  Here’s a good post about the how and why.

 Useful Links

If you’d like to learn more than just the absolute basics above, then the links below are a good place to begin.

 

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code class="" title="" data-url=""> <del datetime=""> <em> <i> <q cite=""> <strike> <strong> <pre class="" title="" data-url=""> <span class="" title="" data-url="">