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.
-
Go to File → Settings → Plugins.
(Or, from the welcome screen, Configure → Plugins)
-
Activate the Marketplace tab.
-
Search for the plugin
Bazel
(by Google).TipIn 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. -
Install it.
-
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:
|
Creation of the project
-
Go to File → Import Bazel Project.
(Or, from the welcome screen, Import Bazel Project should already be shown in there.)
-
For Use existing bazel workspace → Workspace, select the directory containing the Gerrit source code.
-
Choose Import from workspace and select the
.bazelproject
file which is located in the top directory of the Gerrit source code. -
Adjust the path of the project data directory and the name of the project if desired.
-
Finish the creation of the project.
-
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:
-
Go to File → Settings → Plugins.
-
Activate the Marketplace tab.
-
Search for the plugin
google-java-format
by Google. -
Install it.
-
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.
-
Download intellij-java-google-style.xml.
-
Go to File → Settings → Editor → Code Style.
-
Click on the wrench icon with the tooltip Show Scheme Actions.
-
Click on Import Scheme.
-
Select the previously downloaded file
intellij-java-google-style.xml
. -
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:
-
Go to File → Settings → Plugins.
-
Ensure that the EditorConfig plugin (by JetBrains) is enabled.
-
Go to File → Settings → Editor → Code Style.
-
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
-
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/
-
Go to File → Settings → Editor → Copyright → Copyright Profiles.
-
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:
-
Go to File → Settings → Version Control → Commit Dialog.
-
In the Commit message inspections, activate the three inspections:
-
Blank line between subject and body,
-
Limit body line and
-
Limit subject line.
-
-
For the limit line inspections, make sure that 72 is specified as value.
-
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
|
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
.
-
Go to Run → Edit Configurations.
-
Click on the + to add a new configuration.
-
Choose Remote from the Templates.
-
Adjust Configuration → Settings → Host and Port.
-
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