Tutorial

Eclipse with Github

Programming alone is sometimes difficult, but one programmer can only do so much. It’s better to work as a team. Groups of programmers can share the load, but having multiple people working on the same code adds additional challenges.  You’ll need extra communication to keep everyone productive, and additional tools to keep from losing work.

Professional environments use Revision Control Systems to store the code, communicate the changes, and keep people from overwriting each other’s work.  FRC programming teams should also use Revision Control.

Probably the most popular revision control system right now is git, a distributed version control system created by Linus Torvalds, the same guy who created Linux. You can use git from the command line, or from within development environments such as Eclipse, IntelliJ, and Visual Studio Code.  GitHub is a web-based hosting service for git, and the GitHub corporation is a FIRST sponsor.  All programming mentors and students can get free GitHub accounts, and FIRST teams can get upgraded Team Accounts.

To say that git is “distributed” means that every programmer will have a copy of the code, along with the history of the changes.  There is also one remote repository of the code out on the internet. Programmers will occasionally pull changes from the remote repository to their local copy and occasionally push their own changes up to the remote repository.  In this way, everyone eventually has the same code and the same history.

Combinations of the code files are called “commits“, and the word “commit” here is both a noun and a verb.  Committing your changes creates a commit that you can retrieve later.

OK, I know that that was a lot of information.  Honestly, git is a really deep subject, and companies that use it develop really complicated methodologies for its use.  I do not recommend that FRC teams try to use everything in the git toolkit, or try to emulate commercial practices.  Especially at first.  Instead, let’s lay out the minimal functions.

Installing and configuring git

You are not required to install git, since there is a version packaged within Eclipse.  However, you may choose to install it anyway.  Instructions are at:  https://git-scm.com/ .

You should configure git to know who you are.  This information will be added to the repository very time you commit.  Open the Eclipse Preferences dialog and select Team > Git > Configuration.  Add user settings for “user.email” and “user.name”:

eclipse_git_config

Cloning an existing repository

Suppose that there is a repository on GitHub that you’d like to download to your laptop.  Making a local copy is called making a clone.

Consider the code repository at:  https://github.com/firebears-frc/testrobot0.  Go ahead and visit that page in a browser.  Press the green button labeled “Clone or Download” and then press the little clipboard button.  This will copy the repository’s formal URL into your clipboard.

vsc_git_clone

Now go to Eclipse:

  1. From the main menu select File > Import…
  2. In the Import dialog, select Git > Projects from Git.
  3. Select Clone URI
  4. The Source Git Repository page should already be populated from your clipboard.
  5. For Branch Selection, select at least the “master” branch
  6. For Location Destination, make sure you’ve selected a plausible location, such as in your Documents directory.
  7. Specify the project type.  In this case, choose to import existing Eclipse projects.  Hit the Finish button

At this point you now have a clone of the repository on your machine.  You won’t be able to push changes up to the remote repository unless the owner has granted you permission, but you can read, edit, and deploy this code to the robot.

Creating a new repository

Suppose you have a robot project on your local machine that has never been under git control, but you’d like to upload it into GitHub.

Open the project in Eclipse and then open a browser to https://github.com.

  1. In the browser, log into your GitHub account.  Click on a green button that says either “New” or “New Repository”.
    vsc_git_new_repo.png
  2. Github will ask for a repository name.  Give it the same name as project directory on your laptop.  You can also specify a description. Probably you should make it a public repository.
    However, do not add a README file or a .gitignore file or a license file.  Your GitHub remote repository must be totally empty at this point.
  3. After creating the repository, your browser will go to a page which displays your new repository URL.  Copy this value into your clipboard.
  4. In Eclipse, right-click on the project name and select Team > Share Project…
    1. Check the box for “Use or create repository or create new one.
    2. Click on the Location of your project
    3. Click the “Create Repository” button
    4. Click the “Finish” button.  Your project will now be initialized as a local git repository.
  5. Now you need to commit all your files.  Right-click on the project and select Team > Commit… This will expose the Git Staging view.
    1. Drag all files from “Unstaged Changes” to “Staged Changes”
    2. Type in a Commit Message describing this commit.  Normally you should put in something informative, but in this case just say “Initial commit”.
    3. Click Commit and Push…
    4. The Destination Git Repository dialog will be filled in based on your clipboard.
    5. Click the Next button twice to get to the “Push Confirmation” dialog.  Push the Finish button.
  6. Now go back to your browser and visit the page for your new repository.  You should now see all the files listed on the web page.

Committing changes to the code

From now on, when you add files, delete files, or modify files, git and Eclipse will keep track of how your code differs from the most recent commit.  The Git Staging view keeps track of what has changed.  When you are ready to make a commitment, drag the files you want committed into the “Staged Changes” area.  Usually you’ll commit all changes, but you might choose to just stage a subset.

eclipse_git_commit0

Type in a commit message.  Try to write informative messages, since you and others will be reading this later.  Good messages say things like “Updated autonomous commands for new encoder” or “Code changes after first regional”.   Bad messages contain jokes or gibberish or say things like “changed stuff”.

After entering a useful message, hit the “Commit” button.  This will commit your changes locally, but will not yet push those changes upstream to Github.

Pulling changes back from the repository

Suppose someone else has made changes to the code and pushed them up to the remote repository.  You’d like to fetch those changes and merge them into our code.  This is called doing a pull from the remote.

You can pull at any time, but it is usually best to commit your code locally before pulling.  That is to say, commit the code but don’t push it up yet.  Follow the directions in the previous section to do the commit.

To pull down changes, right-click on the project and select Team > Pull.   The best case scenario (which is usually what happens) is that upstream changes will be seamlessly added to your code and everything will work perfectly.

One thing that might go wrong is that the changes pulled in will invalidate or undo something you are doing.  You should always look over the incoming changes.  Check the Problems view in Eclipse to see if new errors have been added.  Recompile and run any relevant tests.

The worst case scenario is that someone else will have changed files that you are working on, and you will need to “merge” changes.  The Git Staging view will show which files are in conflict.

eclipse_git_merge1

Right click on one of the conflicted files and and select the Merge Tool, which will show the differences between your commit and the incoming commits.  In the picture below, local changes are on the left and incoming are on the right.  Edit the left pane to be the compromise between these changes.

eclipse_git_merge2.png

After you’ve modified a conflicted file and saved the changes, go back to the Git Staging view and drag the into the “Staged Changes” area.   After merging all the conflicts, hit the “Commit” button.

Pushing your changes up to the repository

If you are ready to release your changes to the rest of the group, you can push your commits up to the remote repository.

If you are the only programmer working on a repository, you can push changes from the Git Staging view and its “Commit and Push…” button.

eclipse_git_commit

If  there are multiple programmers, you should just “Commit”.   Later, you can push all changes by right-clicking the project and selecting Team > Push to Upstream.

Synching with the remote repository

There’s an important discipline that everyone must develop with respect to the remote repository, which is that you should always pull in remote changes before pushing up your own.  If there are incoming changes, then you must recheck the merged code to verify that it is OK.

With multiple programmers, you should perform the following steps manually:

  1. Commit your changes locally.
  2. Pull remote changes, and deal with any merge conflicts.
  3. Verify that the merged code compiles correctly and that the code works correctly.  If there are any problems, fix them and then go back to step 1.
  4. Push all commits to the remote repository.

Further Reading:

 

Tutorial

Installing Eclipse

Eclipse is a sophisticated professional development environment for Java, C++, and other languages.   Eclipse was the officially supported development environment for FRC for the 2015 through 2018 seasons.  In 2019, WPILib has shifted their focus to developing in Visual Studio Code, but you’ll find that Eclipse is still an excellent platform for FRC development.

FRC robot programs will be built using GradleRIO, which can execute from inside any development environment.

Step 0:  Install prerequisites

You must install Java.  Even if you will be developing in C++, you’ll need Java installed to run Eclipse and GradleRIO.  You should define your JAVA_HOME environment variable to point to your JDK installation.  Often setting JAVA_HOME is considered optional, but I have seen many strange situations resolved after this variable has been properly set.

You should obtain and run the WPILib one-step installer (available at the beginning of the 2019 season).  Even if you’ll be developing with Eclipse,  you’re likely to need the tools and project templates included in this package.

It is recommended (though not strictly required) that you also install git, instructions for which are at: https://git-scm.com/ .

Step 1: Download and install Eclipse

Eclipse is available for Windows, Macintosh, and Linux. Download the installer from https://www.eclipse.org/downloads .  As of this writing, the latest version of Eclipse is called Photon.  If possible, run the installer as Administrator.  The installer will offer you several versions of the program.  Pick either “Eclipse IDE for Java Developers” or “Eclipse IDE for C/C++ developers”.

eclipse_install_installer

Eclipse is a big program, and you should consider looking at the online documentation. Here are a few concepts to get you started:

  1. There are a lot of things going on in the main Eclipse window.  Editors appear in the middle of the window.  This is where you modify code. The tabbed panels surrounding the editors are called Views. Views give you information about your whole project and allow you perform important actions, such as build and deploy code.  There are more views available than are currently displayed, and you can add them from the Window > Show View menu.
    For now, important views to know about include:

    1. The Package Explorer view on the left side shows all available projects.  From here you can open projects and then drill down to find files which can then be edited.
    2. The Outline view on the right side shows a table of contents of any file you are editing.
    3. The Problems view on the bottom shows things that are wrong with your code.  If there is a compile error in the code, you will see it here.
  2. The Preferences dialog allows you to change some Eclipse configurations.  On Macintoshes this can be opened from the Eclipse menu.  On all other computers it is under the Windows menu.
    Also, right-clicking on any project within the Package Explorer view will let you open the Properties dialog for that project.  The project Properties dialog lets you reconfigure the project.
  3. You can extend the functionality of Eclipse by adding plugins.  Plugins are managed from the Help menu, starting with the menu items for “Install New Software…” and “Eclipse Marketplace…”

eclipse_install_eclipse

Once Eclipse starts up, you should verify that it will be using your preferred Java installation. Open the Preferences dialog and then click on “Java” and then “Installed JREs”.  Make sure that your preferred JDK installation is present and is checked.

eclipse_install_jre.png

Step 2: Install the Gradle plugin

Now we’ll want to install a plugin to Eclipse that makes it easier to build and deploy your robot programs.  Click on the Help menu and select “Eclipse Marketplace…”  In the dialog’s find box, type “Buildship Gradle”.  Click the Install button for the Gradle plugin.  Eclipse will need to restart to complete installation.

eclipse_install_plugin

After the restart, open the Eclipse Preferences dialog and click on the “Gradle” item.  Make sure that “Gradle wrapper” is selected.  Apply and close.

Click on the Window menu and select “Show View…” and “Other…”.  Find the “Gradle” item and select “Gradle Tasks”.   The Gradle Tasks view is where you will build and deploy your robot programs.

Step 3: Build a simple project

Creating  new robot programs in Eclipse is a lesson I’ll defer to another tutorial.  For now, you can download an existing project and verify that Eclipse can build robot programs.

  1. Go to https://github.com/firebears-frc/testrobot0/releases/ and download testrobot0.zip . Uncompress this ZIP file onto your laptop, probably in your Documents folder.
  2. From the File menu, select Import…
  3. In the Import dialog select General and then Existing Projects.  Select your new testrobot0 directory as the root.  Hit the Finish button.  This will create a new testrobot0 project in your Package Explorer.
  4. You should also see testrobot0 in your Gradle Tasks view.  Open this item and then open “build”.  Double-click on the “assemble” task.  This should successfully compile the program.
  5. Under embeddedtools, double-click on the “deploy” task to deploy the program to your robot.  This will fail if you aren’t connected to a roboRIO.  But, no harm will have been done.

Further Reading: