Tutorial

Installing VS Code

Note that the following document was written while we were still in the 2019 alpha test of WPILib.  When the 2019 software is officially released, it will include a one-step installer that sets up almost everything into a single frc2019 directory, including a customized version of Visual Studio Code. So, some of the following may be unnecessary, but there is still some good information about VS Code.  Also, you could use the following to roll your own environment, or experiment with developmental versions of WPILib.

When the new software is officially released, it is recommended that you use the one-step installer.

Starting in 2019, the officially supported development environment for FRC software development will be Visual Studio Code. That’s not to say that you cannot use Eclipse, IntelliJ, or vim if you want. In fact, if your team is happy with another environment, then you can safely stick with it. However, the excellent support from the WPILib team will be behind Visual Studio Code.

The first thing to know is that Visual Studio Code is not the same as Visual Studio. Visual Studio is a heavyweight Integrated Development Environment, primary for working with Microsoft applications. Visual Studio Code (let’s call it VSCode) is a much lighter text editor with an extension mechanism. The WPILib team will be providing a new extension for FRC development.

FRC robot programs will be built using GradleRIO, which can also be executed from Eclipse, IntelliJ or from the command line.

Step 0: Install prerequisites

You must install Java.  Even if you will be developing in C++, you’ll need Java installed to run GradleRIO.  You must define your JAVA_HOME environment variable, since VSCode uses it to find your Java install.  After installing, you should be able to execute “java -version” at a command prompt and get back the current version of the java runtime.  Execute “javac -version” to get back the version of the java compiler.

You must install git, instructions for which are at: https://git-scm.com/ Even if you aren’t using git, VSCode expects it.  After installing, try executing “git –version” at a command prompt.  If it prints back the git version number, you’ve installed it correctly.

If you will be doing C++ development, you must install the compiler toolchains at: http://first.wpi.edu/FRC/roborio/toolchains/

Step 1 : Download and install VSCode

VSCode is available for Windows, Macintosh, and Linux. Download the installer from https://code.visualstudio.com/download . If possible, run the installer as Administrator.

Once installed, VSCode will start up at the Welcome screen

vsc_install_vsc

VSCode is pretty feature rich, and you should definitely start reading the documentation and memorizing the keyboard shortcuts.  Here are a few concepts to get started:

  1. The icons on the left edge make up the “Activity Bar”.  Clicking on the icons will open up the “Sidebar” which offers more functions.
    The icon on top opens the “Explorer” sidebar which shows all the files that you can edit.
    The squarish icon on bottom opens the “Extension” sidebar, which lets you manage software extensions for VSCode.
    Hitting control-B (or command-B on a Mac) will toggle away the sidebar, so you can make full use of screen space.
  2. Holding the control key down and hitting the back-quote character will open a terminal panel on the lower part of the screen.  (The back-quote character is usually in the upper left corner of your keyboard, just under the Esc key).   You’ll probably need to get comfortable with terminals and command lines when developing with VSCode.
    Hitting control-back-quote again will toggle the terminal away.
  3. The F1 key will open the “Command Palette” at the top of the screen.  Also, you can hit control-shift-P on Windows or Linux.  Macintosh users can hit Command-Shift-P.  The Command Palette lets you invoke special commands inside VSCode.  It’s pretty good about offering you suggestions for what you want to do.  Many of these functions are available from menus or from keyboard shortcuts, but you’ll find yourself using the Command Palette a lot.
    The FRC extension for WPILib adds new commands to the Command Palette for building robot code and reconfiguring your robot development environment.

Step 2 : Install language extensions

Click the square “Extension” icon on the Activity Bar.

If you will be doing Java development, type “Java Extension Pack” into the sidebar window.  Select the entry for “Java Extension Pack” and click the green Install button.  After the install is done, click the blue Reload button to restart VSCode.

vsc_install_java

If you will be doing C++ development, search for the “C/C++” extension.  Install and Reload.

vsc_install_three_dot

Note the three dots on the upper right corner of the sidebar.  VS Code calls this the “More Actions” button, and clicking on it will open a menu.  Select “Show Installed Extensions” from the menu.  If everything was successful, you should see your extensions listed in the sidebar.

Step 3 : Install the WPILib extension

At the time of this writing, you can get the alpha release of the WPILib extension from https://github.com/wpilibsuite/vscode-wpilib/releases .  Download the VSIX file.

Click the “Extension” icon on the Activity Bar to open up the Extension sidebar.  Click on the More Actions button on the upper right corner of the sidebar and select “Install from VSIX…”  Specify your new VSIX file.  Install and then hit the blue Reload button.

If you show installed extensions, you should now see the WPILib extension added.  The Command Palette will now offer WPILib commands.  There will also be a little “W” button in a red hexagon on the title bar of all windows. It pops open the Command Palette and lists all WPILib commands.

vsc_install_wpilib

Further Reading:

Tutorial

Installing Java for FRC programming

Note that the following document was written while we were still in the 2019 alpha test of WPILib.  When the 2019 software is officially released, it will include a one-step installer that sets up almost everything into a single frc2019 directory, including a copy of Java version 11.  This document is still good information, especially if you intend to use more than the standard VS Code environment.  If you intend to use VS Code, it is recommended that you:

  • Use the official installer.
  • Set your JAVA_HOME environment variable to the frc2019/jdk directory, as explained below.
  • Install git, as explained below.

If you intend to program your robot in Java, you will need to  install version 11 of the Java Development Kit onto your computer.

Actually, the first step might be to see if you already have Java installed.  Pull up a command window (the CMD program for windows or the terminal program on a Mac) and type the command

java -version

 

java_install_version1.png

If your terminal responds with a version of 11 or more, you might already be set.  Or, you might want to install the latest version, as described below.

Installing Java is really easy.  Let’s see how complicated I can make it.

Step 1: Downloading and Installing the JDK

You’ll want the JDK download for the latest version of Java SE 11 (which at the time of this writing was Java SE 11.0.1).

You can download Java at http://java.oracle.com.  This page changes occasionally, but you should click into the download section for “Java SE”.  From the “Java SE Downloads” page, look for the Java SE 11 section and click on the Oracle JDK download link.

Note that Java comes in two main distributions: the JRE and the JDK. The Java Runtime Environment (JRE) contains only the software to run Java programs.  The Java Development Kit extends the JRE to also let you compile new programs.  For our purposes, you always need the JDK.  Sometimes you’ll find a computer that has both the JRE and JDK installed.  This is perfectly OK, as long as your environment is configured to use the JDK installation.

java_install_download.png

From the JDK 1 Downloads page, accept the license agreement and then download the installer for your operating system.

Windows

There will be two choices for Windows installs, labeled “x86” and “x64”.  You almost certainly want the “x64” version, since the other version is for older 32-bit machines.

Download the installer and run it.  If possible, run the installer as the Administrator user.  After everything is done, you should see your new Java install under the C:/Program Files/Java directory.

Macintosh

Select the “osx” installer in the “dmg” format.  Download and run. Afterwards, you’ll see the installation under the /Library/Java/JavaVirtualMachines/ directory.

Linux

If you’re running Ubuntu or a similar Debian based linux, try executing:

sudo apt-get install openjdk-11-jre openjdk-11-jdk

For Ubuntu, the java installation will end up in /usr/lib/jvm/jdk-11.

For Fedora based Linux distributions, Oracle provides RPM packages.  You’ll probably want the “linux-x64.rpm” version, unless you have an old 32-bit machine.

Step 2: Setting your JAVA_HOME environment variable

Now that Java is installed, we must tell our software where to find it. We’ll want to put that directory path into a JAVA_HOME directory.

For all operating systems, the Java home directory will be the directory containing Java’s  “bin”, “jre”, and “lib” subdirectories.

Windows

Open up a File Explorer window and select the C drive.  Click into Program Files and then click into the Java directory.  Click into a directory named like your new JDK version.

Now click on the file path area and copy the text of the file path into the clipboard.  A typical Java home directory on Windows might be  C:\Program Files\Java\jdk-11 :

 

java_install_win_1

Next, open the Control Panel.  In the search box, type the words “environment variables”.  Click into the link for “Edit System Environment Variables”, which will pop up the System Properties dialog.  Click on “Environment Variables”.

Create a new System Environment Variable named JAVA_HOME, and paste in the value you just copied.

java_install_win_2.png

Next, click on the User Environment variable named “Path” and edit it.  Change it so the first thing in the Path variable is “%JAVA_HOME%\bin” .

Close out the variable and system dialogs.   Open up a CMD windows.  You should now be able to execute the “java -version” command and get back the current version number.

Macintosh

You’ll need to open a terminal window for this job.  Change directories to /Library/Java/JavaVirtualMachines/ .  In this directory you should see a directory whose name is similar to the Java version you just downloaded.  Change into that directory and then into the Contents/Home subdirectory.  That should be your new Java home directory.  For instance, if you installed jdk-11.0.1.jdk, then your Java home directory might be:  /Library/Java/JavaVirtualMachines/jdk-11.0.1.jdk/Contents/Home

java_install_mac_12.png

Change back to your user home directory and edit the file .bash_profile.   Create this file if it doesn’t already exist.  You’ll want to add the following two lines to the end of the file:

export JAVA__HOME=/Library/Java/JavaVirtualMachines/jdk-11.0.1.jdk/Contents/Home
export PATH=${JAVA_HOME}/bin:${PATH}

java_install_mac_2.png

Open a new Terminal window and test that you can execute “java -version” and get back a response.

Linux

Setting the environment variable in Linux is about the same as on a Mac, although you should add the variable definition to the .bashrc file, rather than the .bash_profile.  As above, run java -version to verify that the setup is correct.

Multiple versions of Java

You may have noticed that there are many versions of Java out there.

For the 2018 robot code, we must stick with version 8.  Newer versions will not work.  However, the WPILIB maintainers are committed to making all the new software work with version 11.   It’s perfectly OK to have multiple versions of Java installed on one computer.  Simply update the JAVA_HOME variable to point to your desired installation.

Visual Studio Code and GradleRIO will use the JAVA_HOME variable to find your desired Java installation.  If you develop using Eclipse, there may be an extra step in the Preferences dialog of defining your “installed JRE”.  You can then specify different JREs for different projects.  If you develop in IntelliJ, you can open the Project Structure to set a specific Software Development Kit for each project.

Note that there is also an open-source version of Java called OpenJDK.  This will work perfectly fine for FRC development.   In fact, the roboRIO executes Java programs using the Zulu JRE, which is derived from OpenJDK.  Right now, there’s not much downside to sticking with Oracle’s commercial JDK.

Install git

OK, this has nothing to do with Java. But, while you’re setting up your laptop, you might as well set up git.  Even if you don’t use git, you’ll need this later.

Git is the software version control system used by WPILib and many FRC teams.  For better or worse, git is the world’s most popular software configuration management system.  GitHub is a FIRST sponsor.  Individuals can get free GitHub accounts, and FIRST teams can get upgraded Team Accounts.

Instructions for installing git are at: https://git-scm.com . You might also take a look at:  https://www.atlassian.com/git/tutorials/install-git .  On Windows, do the installation as Administrator.

Further Reading