Importing a Gradle Project

Due to changes in the project, it is necessary to update the build files for a previous years Gradle project. It is also necessary to import vendor libraries again, since last year’s vendor libraries must be updated to be compatible with this year’s projects.

Automatic Import

To make it easy for teams to import previous years gradle projects into the current year’s framework, WPILib includes a wizard for importing previous years projects into VS Code. This will generate the necessary gradle components and load the project into VS Code. In place upgrades are not supported. The importer automatically imports the old or new command framework 3rd party library (which ever one was used on the imported project).


The import process copies your project source files from the current directory to a new directory and completely regenerates the gradle files. If you made non-standard updates to the build.gradle, you will need to make those changes again. For this reason, in place upgrades are not supported. It is also necessary to import vendor libraries again, since last year’s vendor libraries must be updated to be compatible with this year’s projects.


The automatic import process is broken in version 2021.3.1. As a workaround, the project may be manually imported.

Launching the Import Wizard


When you open a previous year’s project, you will be prompted to import that project. Click yes.

Alternately, you can chose to import it from the menu. Press Ctrl+Shift+P and type «WPILib» or click the WPILib icon to locate the WPILib commands. Begin typing «Import a WPILib 2020 Gradle project» and select it from the dropdown as shown below.

../../../_images/ImportGradleMenu.png ../../../_images/VSCodeImport.png

You’ll be presented with the WPILib Project Importer window. This is similar to the process of creating a new project and the window and the steps are shown below. This window contains the following elements:

  1. Gradle Project: Selects the project to be imported. Users should select the build.gradle file in the root directory of the gradle project.

  2. Project Location: This determines the folder in which the robot project will be located.

  3. Project Name: The name of the robot project. This also specifies the name that the project folder will be given if the Create New Folder box is checked. This must be a different directory from the original location.

  4. Create a New Folder: If this is checked, a new folder will be created to hold the project within the previously-specified folder. If it is not checked, the project will be located directly in the previously-specified folder. An error will be thrown if the folder is not empty and this is not checked.

  5. Team Number: The team number for the project, which will be used for package names within the project and to locate the robot when deploying code.

  6. Enable Desktop Support: If this is checked, simulation and unit test support is enabled. However, there are some cases where this will do some unexpected things. In addition, all vendor libraries need desktop support which not all libraries do.

Click Import Project to begin the upgrade.

The gradle project will be upgraded and copied into the new project directory. You can then either open the new project immediately (the pop-up shown below should appear in the bottom right) or open it later using the Ctrl+O (or Command+O for macOS) shortcut.


C++ Configurations (C++ Only)

For C++ projects, there is one more step to set up IntelliSense. Whenever you open a project, you should get a pop-up in the bottom right corner asking to refresh C++ configurations. Click Yes to set up IntelliSense.


3rd Party Libraries

It is necessary to update and re-import 3rd party libraries. See 3rd Party Libraries for details.

Manual Import Process (2020 to 2021)

As there were minimal changes to the gradle templates in 2021, it is possible to manually import a project from a 2020 version of GradleRIO to 2021, which may be convenient if you’ve heavily customized your build.gradle file. This method does not work for importing a 2019 project, and will not work for future years. There are two files that need to be updated.


Open .wpilib\wpilib_preferences.json and change the projectYear to 2021.

    "enableCppIntellisense": false,
    "currentLanguage": "java",
    "projectYear": "2021",
    "teamNumber": 330


 1plugins {
 2    id "java"
 3    id "edu.wpi.first.GradleRIO" version "2021.1.2"
 6sourceCompatibility = JavaVersion.VERSION_11
 7targetCompatibility = JavaVersion.VERSION_11
 9def ROBOT_MAIN_CLASS = "frc.robot.Main"
11// Define my targets (RoboRIO) and artifacts (deployable files)
12// This is added by GradleRIO's backing project EmbeddedTools.
13deploy {
14    targets {
15        roboRIO("roborio") {
16            // Team number is loaded either from the .wpilib/wpilib_preferences.json
17            // or from command line. If not found an exception will be thrown.
18            // You can use getTeamOrDefault(team) instead of getTeamNumber if you
19            // want to store a team number in this file.
20            team = frc.getTeamNumber()
21        }
22    }
23    artifacts {
24        frcJavaArtifact('frcJava') {
25            targets << "roborio"
26            // Debug can be overridden by command line, for use with VSCode
27            debug = frc.getDebugOrDefault(false)
28        }
29        // Built in artifact to deploy arbitrary files to the roboRIO.
30        fileTreeArtifact('frcStaticFileDeploy') {
31            // The directory below is the local directory to deploy
32            files = fileTree(dir: 'src/main/deploy')
33            // Deploy to RoboRIO target, into /home/lvuser/deploy
34            targets << "roborio"
35            directory = '/home/lvuser/deploy'
36        }
37    }
40// Set this to true to enable desktop support.
41def includeDesktopSupport = false
43// Defining my dependencies. In this case, WPILib (+ friends), and vendor libraries.
44// Also defines JUnit 4.
45dependencies {
46    implementation wpi.deps.wpilib()
47    nativeZip wpi.deps.wpilibJni(wpi.platforms.roborio)
48    nativeDesktopZip wpi.deps.wpilibJni(wpi.platforms.desktop)
51    implementation
52    nativeZip wpi.deps.vendor.jni(wpi.platforms.roborio)
53    nativeDesktopZip wpi.deps.vendor.jni(wpi.platforms.desktop)
55    testImplementation 'junit:junit:4.12'
57    // Enable simulation gui support. Must check the box in vscode to enable support
58    // upon debugging
59    simulation wpi.deps.sim.gui(wpi.platforms.desktop, false)
60    simulation wpi.deps.sim.driverstation(wpi.platforms.desktop, false)
62    // Websocket extensions require additional configuration.
63    // simulation wpi.deps.sim.ws_server(wpi.platforms.desktop, false)
64    // simulation wpi.deps.sim.ws_client(wpi.platforms.desktop, false)
67// Simulation configuration (e.g. environment variables).
68sim {
69    // Sets the websocket client remote host.
70    // envVar "HALSIMWS_HOST", ""
73// Setting up my Jar File. In this case, adding all libraries into the main jar ('fat jar')
74// in order to make them all available at runtime. Also adding the manifest so WPILib
75// knows where to look for our Robot Class.
76jar {
77    from { configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) } }
78    manifest edu.wpi.first.gradlerio.GradleRIOPlugin.javaManifest(ROBOT_MAIN_CLASS)
  1. Change the GradleRIO version to the latest version (e.g. 2021.1.2 for the kickoff release)

  2. (C++ Only) move wpi.deps.vendor.cpp(it) above wpi.deps.wpilib(it) (2 places)

  3. (Optional) add simulation wpi.deps.sim.driverstation(wpi.platforms.desktop, XXXX) where XXXX is false for Java and true for C++. This allows the driver station to be used in simulation

  4. (Optional) add the websocket and simulation configuration blocks to support websockets simulation (i.e. Romi)


Delete imgui.ini (the Simulator GUI ini file) if it exists. The 2020 file format is not compatible with the 2021 format. The file will be regenerated when the Simulator GUI is run).

Update 3rd Party Libraries

It is necessary to update 3rd party libraries. See 3rd Party Libraries for details.