| :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 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 | |
| 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 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 | |
| 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 | |
| --------- |