gerrit/Documentation/dev-intellij.txt

:linkattrs:
= Gerrit Code Review - IntelliJ IDEA Setup

== Prerequisites

=== Bazel

Bazel must be installed as described by
<<dev-bazel#installation,Building with Bazel - Installation>>.

It's strongly recommended to verify you can build your Gerrit tree with Bazel
for Java 8 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
link:https://plugins.jetbrains.com/plugin/8609-bazel/versions[JetBrains plugin repository page of the Bazel plugin,role=external,window=_blank]
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 8 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 8.

=== Installation of IntelliJ IDEA

Please refer to the
link:https://www.jetbrains.com/help/idea/installation-guide.html[installation guide provided by Jetbrains,role=external,window=_blank]
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
link:https://github.com/bazelbuild/intellij[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).
+
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 link:https://plugins.jetbrains.com/plugin/8609-bazel/versions[the JetBrains plugin page,role=external,window=_blank].
. 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:

. Go to *Preferences -> Other Settings -> Bazel Settings*.
. Set the *Bazel binary location*.
====

== 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,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 <<dev-crafting-changes#style,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
https://raw.githubusercontent.com/google/styleguide/gh-pages/intellij-java-google-style.xml[
intellij-java-google-style.xml,role=external,window=_blank].
. 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
<<dev-crafting-changes#commit-message,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
<<dev-crafting-changes#git-commit-settings,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*.

[[runconfigurations-daemon]]
=== 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 <<dev-readme#run_daemon,Running the Daemon>> in
combination with <<remote-debug,Debugging a remote Gerrit server>>.

(link:https://bugs.chromium.org/p/gerrit/issues/detail?id=11360[Issue 11360,role=external,window=_blank])
====

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

This run configuration starts the Gerrit daemon similarly as
<<dev-readme#run_daemon,Running the Daemon>>.

NOTE: The <<dev-readme#init,Site Initialization>> has to be completed
before this run configuration works properly.

[[unit-tests]]
=== 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.

[[remote-debug]]
=== 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 <<runconfigurations-daemon,local run configuration issue>>.

GERRIT
------
Part of link:index.html[Gerrit Code Review]

SEARCHBOX
---------