This document is about configuring Gerrit Code Review into an Eclipse workspace for development and debugging with GWT.

Java 8 or later SDK is also required to run GWT’s compiler and runtime debugging environment.

Project Setup

In your Eclipse installation’s eclipse.ini file, add the following line in the vmargs section:

  -DmaxCompiledUnitsAtOnce=10000

Without this setting, annotation processing does not work reliably and the build is likely to fail with errors like:

  Could not write generated class ... javax.annotation.processing.FilerException: Source file already created

and

  AutoAnnotation_Commands_named cannot be resolved to a type

First, generate the Eclipse project by running the tools/eclipse/project.py script. Then, in Eclipse, choose 'Import existing project' and select the gerrit project from the current working directory.

Expand the gerrit project, right-click on the eclipse-out folder, select 'Properties', and then under 'Attributes' check 'Derived'.

Note that if you make any changes in the project configuration that get saved to the .project file, for example adding Resource Filters on a folder, they will be overwritten the next time you run tools/eclipse/project.py.

Eclipse project on MacOS

By default, bazel uses /private/var/tmp as the outputRoot on MacOS. This means that the eclipse project will reference libraries stored under that directory. However, MacOS runs periodic cleanup task which deletes the content under /private/var/tmp which wasn’t accessed or modified for some days, by default 3 days. This can lead to a broken Eclipse project as referenced libraries get deleted.

There are two possibilities to mitigate this issue.

Change the location of the bazel output directory

On Linux, the output directory defaults to $HOME/.cache/bazel and the same can be configured on Mac too. Edit, or create, the $HOME/.bazelrc file and add the following line:

startup --output_user_root=/Users/johndoe/.cache/bazel

Increase the treshold for the cleanup of temporary files

The default treshold for the cleanup can be overriden by creating a configuration file under /etc/periodic.conf and setting a larger value for the daily_clean_tmps_days.

An example /etc/periodic.conf file:

# This file overrides the settings from /etc/defaults/periodic.conf
daily_clean_tmps_days="45"                              # If not accessed for

For more details about the proposed workaround see this post

Eclipse project with custom plugins

To add custom plugins to the eclipse project add them to tools/bzl/plugins.bzl the same way you would when bundling in release.war and run tools/eclipse/project.py.

[[Newer Java versions]]

Java 9 and later are supported, but some adjustments must be done, because Java 8 is still the default:

  • Add JRE, e.g.: directory: /usr/lib64/jvm/java-9-openjdk, name: java-9-openjdk-9

  • Change execution environment for gerrit project to: JavaSE-9 (java-9-openjdk-9)

  • Check that compiler compliance level in gerrit project is set to: 9

  • Add this parameter to VM argument for gerrit_daemin launcher:

  --add-modules java.activation \
  --add-opens=jdk.management/com.sun.management.internal=ALL-UNNAMED

Code Formatter Settings

To format source code, Gerrit uses the google-java-format tool (version 1.7), which automatically formats code to follow the style guide. See Code Style for the instruction how to set up command line tool that uses this formatter. The Eclipse plugin is provided that allows to format with the same formatter from within the Eclipse IDE. See Eclipse plugin for details how to install it. It’s important to use the same plugin version as the google-java-format script.

Site Initialization

Build once on the command line with Bazel and then follow Site Initialization in the Developer Setup guide to configure a local site for testing.

Testing

Running the Daemon

Duplicate the existing launch configuration:

  • In Eclipse select Run → Debug Configurations …​

  • Java Application → gerrit_daemon

  • Right click, Duplicate

  • Modify the name to be unique.

  • Switch to Arguments tab.

  • Edit the -d program argument flag to match the path used during 'init'. The template launch configuration resolves to ../gerrit_testsite since that is what the documentation recommends.

  • Switch to Common tab.

  • Change Save as to be Local file.

  • Close the Debug Configurations dialog and save the changes when prompted.

Running GWT Debug Mode

The gerrit_gwt_debug launch configuration uses GWT’s Super Dev Mode.

  • Make a local copy of the gerrit_gwt_debug configuration, using the process described for gerrit_daemon above.

  • Launch the local copy of gerrit_gwt_debug from the Eclipse debug menu.

  • If debugging GWT for the first time:

    • Open the codeserver URL and add the Dev Mode On and Dev Mode Off bookmarklet to your bookmark bar.

    • Activate the source maps feature in your browser. Refer to the Chrome and Firefox developer documentation.

  • Load the Gerrit page.

  • Open the source tab in developer tools.

  • Click the Dev Mode On bookmark to incrementally recompile changed files.

  • Select the gerrit_ui module to compile (the Compile button can also be used as a bookmarklet).

  • In the developer tools source tab, open a file and set a breakpoint.

  • Navigate to the UI and confirm that the breakpoint is hit.

  • To end the debugging session, click the Dev Mode Off bookmark.

After changing the client side code:

  • Hitting F5 in the browser only reloads the last compile output, without recompiling.

  • To reflect your changes in the debug session, click Dev Mode On then Compile.

Running GWT Debug Mode for Gerrit plugins

A Gerrit plugin can expose GWT module and its implementation can be inspected in the SDM debug session.

codeserver needs two additional inputs to expose the plugin module in the SDM debug session: the module name and the source folder location. For example the module name and source folder of any GWT plugin should be added in the local copy of the gerrit_gwt_debug configuration:

  com.googlesource.gerrit.plugins.myplugin.HelloForm \
  -src ${resource_loc:/gerrit}/plugins/myplugin/src/main/java \
  -- --console-log [...]

After doing that, both the Gerrit core and plugin GWT modules can be activated during SDM (debug session).

Part of Gerrit Code Review