Working with GIT

Brian Bagnall

Working with GIT


This section describes how to contribute code to the EV3 leJOS project using Eclipse and GIT. The basic steps are:
1. Sign up with Sourceforge, then join the leJOS project.
2. Installing Eclipse
3. Download the current leJOS source code.
4. Changing and adding code to the leJOS classes
5. Pushing your changes to GIT.

Sourceforge

  1. You will need a Sourceforge ID to commit code to GIT. If you are not already a Sourceforge user, you can register at https://sourceforge.net/
  2. Once you have a Sourceforge ID, you can write to one of the leJOS project admins and ask to be added to the project. You should mention roughly what code you want to work on. The list of admins can be found at https://sourceforge.net/p/lejos/_members/
  3. Once an admin has contacted you back to confirm you are on the project, you will be able to commit code using GIT.

Install the development environment

leJOS uses the Eclipse development environment. Because of the tools we use make sure it is a recent version. Eclipse can be downloaded from here:
http://www.eclipse.org/downloads/
The best configuration for leJOS development is "Eclipse IDE for Java Developers". Documentation on how to install Eclipse can be found here:
http://wiki.eclipse.org/Eclipse/Installation
You will also need to install a Java JDK. Both the Oracle version and OpenJDK work fine. Version 7 is recommended, but version 6 works with some limitations.

Download the current leJOS source code

WARNING: This section is different from the section [Developing with leJOS]. If you have already done the steps in that section, you should delete the projects you imported from GIT. DO NOT delete the projects you might have started on your own, only delete projects like ev3classes, DBusJava, etc... which were previously imported from GIT. You will also want to physically delete all the contents of your local GIT repository before continuing, otherwise GIT will complain that the directory is not empty later. In Windows, this repository is probably C:\Users\YOU\git\ev3. Delete the entire ev3 directory.
The leJOS source code is stored in a Sourceforge git repository. In this section we will obtain a copy of this for local use. If you are not familiar with git you may want to read the following:
http://git-scm.com/book
http://wiki.eclipse.org/EGit/User_Guide

To import the leJOS files:
1. Click on the "File" menu and choose "Import...".
2. For the import source choose "git" and then "projects from git" and click next.
3. Choose "URI" and click next.
4. You need a personalized URI available on Sourceforge. Make sure you are logged into the Sourceforge website, then go to this page to obtain your URI:
https://sourceforge.net/p/lejos/ev3/ci/master/tree/
The URI is listed at the top of the page and should say "Read/Write Access" next to it. The URI looks something like this:
git clone ssh://YOURUSERID@git.code.sf.net/p/lejos/ev3 lejos-ev3
However, the only part you want to copy and paste into the Eclipse URI field is the following:
ssh://YOURUSERID@git.code.sf.net/p/lejos/ev3
Once you past this into the URI field it will populate several other fields, including your username. Enter the password you use with Sourceforge, then for convenience check the box "Store in Secure Store"
Click next.
5. Ensure that the branch is set to master, and click next.
6. Check that you are happy with the chosen local destination directory (probably best not to change this unless you know what you are doing) and click next.
7. After a short while the git clone should be complete and you can click next.
8. You should now see a list of projects that you can import. Deselect any projects that you do not require, you must have the "DbusJava", "ev3classes", and "jna" projects, others are optional. (NOTE: You can later choose to import other projects easily. See "Checking out other projects" below) Click finish.
9. All of the projects should import without any errors (there may be warnings), if there are any errors, resolve these before proceeding.
10. The master version of the projects that you have imported is the very latest HEAD version. This may have changes in it that are incompatible with the latest SD card release of leJOS. This particularly applies to the ev3classes project. You should switch that project to the latest tagged version of leJOS. To do this you right-click on the project name in Eclipse, and select Team > Switch To> Other... > Tags, and select the latest tag, which is currently 0.7.0-alpha. You should check the forums to see if any other projects have changes made to them that are incompatible with the latest SD card release.

Writing Code Using Current GIT Libraries

The snapshot project contains the latest full build of leJOS. Under Windows we can't build the entire snapshot project (only under Linux). If you want to use the latest snapshot:
1. Go to Window > Preferences > leJOS EV3.
2. Enter or browse to the physical location of snapshot. e.g. C:\Users\YOU\git\ev3\ev3snapshot
3. Eclipse will now use the leJOS classes in snapshot. However, these can get out of date after a few days. If you want to use the latest leJOS classes, you need to of course start a leJOS Project: File > New > other > LeJOS EV3 > LeJOS EV3 Project.
4. Once the project is set up, right click it and select Properties. Click the Projects tab and add ev3classes.
If you make changes to the ev3classes project, you will need to build it again using the build.xml file for that project (see below).
Unless there are major low-level changes to the leJOS EV3 project, you should now be able to successfully create and upload Java code to the EV3 using the latest classes in ev3classes. If it stops working after you do a pull from GIT, chances are a major change happened with the leJOS project snapshot needs to be rebuilt by one of the developers of leJOS.

Setting Local Properties

In the projects you have downloaded above, and any other optional projects such as ev3samples, there are ANT files such as build.xml, which build the projects and upload them to the EV3. These are accompanied by build.properties files, which contain settings, such as the IP address to upload the files to.
Some of these settings need to be changed, but if you change the build.properties file directly, then it will be marked as changed and eGIT will prompt you to upload it the next time you do a commit.
In order to customize properties, you should create a local properties file for each project you intend to build. In Eclipse, select the project on the left Package Explorer so it is highlighted, then select File > New > File. A window pops up. Enter local.properties in the File name field, then click Finish. Double click local.properties and enter a single line with the IP address of your EV3:
ev3.host = 192.168.0.18
Save the file. Now you can build projects (see next section).
NOTE: If you want to use USB instead, change to ev3.host = 10.0.1.1

Building Projects

If you want to be able to use the latest leJOS classes from the developers in GIT, you will need to be able to build the ev3classes project. Building it creates a jar file which is uploaded to the EV3 brick. Before you can successfully do that, you need to build DbusJava. Also, if you want to build other projects like ev3samples or ev3menu, you will need to build both DBusJava and ev3classes.
Build the projects in this order:
1. DbusJava
2. jna
3. ev3classes
4. Any other projects (like ev3samples)
To build a project, first turn on your EV3 brick and make sure the IP address on the main screen is the same as the one in local.properties.
In Eclipse, open the project you are going to build and right click on build.xml. Select Run as > Ant Build. This will build the project and upload it to the EV3 brick.

Changing Code

To change code, open a class source file under the Java profile in Eclipse. The leJOS API classes are under ev3classes\src. Once you make an edit to a class, you will see a > symbol next to the class and the package containing the class.
To add a new class, right click the package you want the class to appear under and select New > Class. The class will have a ? next to it until you push the changes into GIT.

Reverting Changes Back to Original

With GIT, the latest version of code in the repository is called the HEAD revision. If you have made changes to project code (you will see a > next to the class) and want to erase those changes and revert back to the HEAD revision, right click the class, select Replace With > HEAD revision. It will ask you if you want to do this, click OK and the code will now be in sync with the HEAD revision in GIT.

Pushing Code Updates to GIT

Before uploading your code to the GIT repository, you will need to do a "Pull" to make sure there are no conflicts. If you omit this step you will likely encounter errors about "non-fast-forward". To do a pull, right-click on the project you edited. Example, right click on ev3classes, then select Team > Pull. After it has updated, make sure there are no conflicts then continue.
Now right click any class or the project you made edits in (such as ev3classes) and select Team > Commit...
A new dialog will show all the classes that have changes. Select the classes you want to push, enter a commit message describing what changes you made, then select Commit and Push. After a while a message appears confirming the changes have been accepted by GIT.

Checking out other projects

If you later decide to check out other projects, you can do so easily. Git stores a local copy of all the projects. Follow these steps to select from those:
1. In Eclipse select File > Import...
2. Under Git choose Projects from Git...
3. On the next window select "Existing local repository" and click Next
4. The next screen lists all the locally available repositories. You probably have only one unless you are involved with other projects from Git. Click the one with the ev3 directory and click next.
5. The next screen shows all the projects but you can't select them yet. Make sure "Import existing projects" is checked, and make sure "Working Directory" at the top of the chain is highlighted, then click Next again.
6. On the next screen it is probably a good idea to click Deselect All, assuming you are selecting just a few to import. Ignore the grayed out projects (they are already imported and don't need to be checked). Check the ones you want and click Finish.


Related

EV3 Wiki: Developing with leJOS
EV3 Wiki: Home