Prerequisites

Bazel

Bazel must be installed as described by Building with Bazel - Installation.

It’s strongly recommended to verify you can build your Gerrit tree with Bazel for Java 11 from the command line first. Ensure that at least bazel build gerrit runs successfully before you proceed.

IntelliJ version and Bazel plugin

Before downloading IntelliJ, look at the JetBrains plugin repository page of the Bazel plugin to see what version of the IntelliJ IDEA it is actually compatible with.

Also note that the version of the Bazel plugin used in turn may or may not be compatible with the Bazel version used.

In addition, Java 11 must be specified on your path or via JAVA_HOME so that building with Bazel via the Bazel plugin is possible.

Tip
 If the synchronization of the project with the BUILD files using the Bazel plugin fails and IntelliJ reports the error Could not get Bazel roots, this indicates that the Bazel plugin couldn’t find Java 11.

Installation of IntelliJ IDEA

Please refer to the installation guide provided by Jetbrains to install it on your platform. Make sure to install a version compatible with the Bazel plugin as mentioned above.

Installation of the Bazel plugin

The plugin is usually installed using the Jetbrains plugin repository as shown in the steps below, but it’s also possible to build it from source.

  1. Go to File → Settings → Plugins.

    (Or, from the welcome screen, Configure → Plugins)

  2. Activate the Marketplace tab.

  3. Search for the plugin Bazel (by Google).

    Tip
    		 In case the Bazel plugin is not listed, or if it shows an outdated version, verify the compatibility between the Bazel plugin and IntelliJ IDEA on the JetBrains plugin page.

  4. Install it.

  5. Restart IntelliJ IDEA.

Tip

If your project’s Bazel build fails with Cannot run program "bazel": No such file or directory, then you may have to set the binary location in the Bazel plugin settings:

  1. Go to Preferences → Other Settings → Bazel Settings.

  2. Set the Bazel binary location.

Creation of the project

  1. Go to File → Import Bazel Project.

    (Or, from the welcome screen, Import Bazel Project should already be shown in there.)

  2. For Use existing bazel workspace → Workspace, select the directory containing the Gerrit source code.

  3. Choose Import from workspace and select the .bazelproject file which is located in the top directory of the Gerrit source code.

  4. Adjust the path of the project data directory and the name of the project if desired.

  5. Finish the creation of the project.

  6. Verify that you can now build the project. Hit the button with the Bazel icon (located on the top-right by default) to synchronize the project. Note that warnings may be present in the build.

At this point all the basic functionality should be working such as Java class inspection and running unit tests.

Tip
 The project data directory can be separate from the source code. One advantage of this is that project files don’t need to be excluded from version control.

Recommended settings

Code style

google-java-format plugin

Install the google-java-format plugin by following these steps:

  1. Go to File → Settings → Plugins.

  2. Activate the Marketplace tab.

  3. Search for the plugin google-java-format by Google.

  4. Install it.

  5. Restart IntelliJ IDEA.

Every time you start IntelliJ IDEA, make sure to use Code → Reformat with google-java-format on an arbitrary line of code. This replaces the default CodeStyleManager with a custom one. Thus, uses of Reformat Code either via Code → Reformat Code, keyboard shortcuts, or the commit dialog will use the custom style defined by the google-java-format plugin.

Please refer to the documentation on the code style for which version of google-java-format is used with Gerrit.

Code style settings

The google-java-format plugin is the preferred way to format the code. As it only kicks in on demand, it’s also recommended to have code style settings which help to create properly formatted code as-you-go. Those settings can’t completely mimic the format enforced by the google-java-format plugin but try to be as close as possible. So before submitting code, please make sure to run Reformat Code.

  1. Download intellij-java-google-style.xml.

  2. Go to File → Settings → Editor → Code Style.

  3. Click on the wrench icon with the tooltip Show Scheme Actions.

  4. Click on Import Scheme.

  5. Select the previously downloaded file intellij-java-google-style.xml.

  6. Make sure that GoogleStyle is chosen as the current Scheme.

In addition, the EditorConfig settings (which ensure a consistent style between Eclipse, IntelliJ, and other editors) should be applied on top of that. Those settings are in the file .editorconfig of the Gerrit source code. IntelliJ will automatically pick up those settings if the EditorConfig plugin is enabled and configured correctly as can be verified by:

  1. Go to File → Settings → Plugins.

  2. Ensure that the EditorConfig plugin (by JetBrains) is enabled.

  3. Go to File → Settings → Editor → Code Style.

  4. Ensure that Enable EditorConfig support is checked.

Note
 If IntelliJ notifies you later on that the EditorConfig settings override the code style settings, simply confirm that.

Copyright

  1. Copy the folder $(gerrit_source_code)/tools/intellij/copyright (not just the contents) to $(project_data_directory)/.idea. If it already exists, replace it. If you didn’t select a custom data directory the command could look like this, as run from the Gerrit source tree checkout as working directory:

    cp -r tools/intellij/copyright .ijwb/.idea/

  2. Go to File → Settings → Editor → Copyright → Copyright Profiles.

  3. Verify that the Gerrit Copyright is now present there.

    Only in case it hasn’t picked up the copyright profile automatically, import the Gerrit_Copyright.xml from that folder manually.

Git integration

This section is only relevant in case you want to use the Git integration plugin in IntelliJ IDEA.

To simplify the creation of commit messages which are compliant with the Commit Message format, do the following:

  1. Go to File → Settings → Version Control → Commit Dialog.

  2. In the Commit message inspections, activate the three inspections:

    • Blank line between subject and body,

    • Limit body line and

    • Limit subject line.

  3. For the limit line inspections, make sure that 72 is specified as value.

  4. For Limit body line, tick Show right margin and Wrap when typing reaches right margin.

In addition, you should follow the instructions of this section (if you haven’t done so already):

  • Install the Git commit message hook for the Change-Id line.

  • Set up the HTTP access.

Setting up the HTTP access will allow you to commit changes via IntelliJ without specifying your credentials. The Git hook won’t be noticeable during a commit as it’s executed after the commit dialog of IntelliJ was closed.

Run configurations

Run configurations can be accessed on the toolbar. To edit them or add new ones, choose Edit Configurations on the drop-down list of the run configurations or go to Run → Edit Configurations.

Gerrit Daemon

Warning

At the moment running this (local) configuration results in a java.io.FileNotFoundException. To debug a local Gerrit server with IntelliJ, use the instructions of Running the Daemon in combination with Debugging a remote Gerrit server.

(Issue 40011100)

Copy $(gerrit_source_code)/tools/intellij/gerrit_daemon.xml to $(project_data_directory)/.idea/runConfigurations/.

This run configuration starts the Gerrit daemon similarly as Running the Daemon.

Note
 The Site Initialization has to be completed before this run configuration works properly.

Unit tests

To create run configurations for unit tests, run or debug them via a right-click on a method, class, file, or package. The created run configuration is a temporary one and can be saved to make it permanent by selecting Create 'Bazel test […​]'…​ from the context menu.

Normally, this approach generates JUnit run configurations. When the Bazel plugin manages a project, it intercepts the creation and creates a Bazel test run configuration instead, which can be used just like the standard ones.

Debugging a remote Gerrit server

If a remote Gerrit server is running and has opened a debug port, you can attach IntelliJ via a Remote debug configuration.

  1. Go to Run → Edit Configurations.

  2. Click on the + to add a new configuration.

  3. Choose Remote from the Templates.

  4. Adjust Configuration → Settings → Host and Port.

  5. Start this configuration in Debug mode.

Tip
 This run configuration dialog also shows the line for the JVM as startup flag that you can copy to include in your $(gerrit_test_site)/etc/gerrit.config in the [container] section in order to work-around the local run configuration issue.

Part of Gerrit Code Review