Documentation/dev-eclipse.txt

= Gerrit Code Review - Eclipse Setup

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.


[[setup]]
== Project Setup

In your Eclipse installation's link:https://wiki.eclipse.org/Eclipse.ini[`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 with custom plugins ===

To add custom plugins to the eclipse project add them to `tools/bzl/plugins.bzl`
the same way you would when
link:dev-build-plugins.html#_bundle_custom_plugin_in_release_war[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 environemnt 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
----

[[Formatting]]
== Code Formatter Settings

To format source code, Gerrit uses the
link:https://github.com/google/google-java-format[`google-java-format`]
tool (version 1.7), which automatically formats code to follow the
style guide. See link:dev-contributing.html#style[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
link:https://github.com/google/google-java-format#eclipse[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
link:dev-bazel.html#build[Bazel] and then follow
link:dev-readme.html#init[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
link:http://www.gwtproject.org/articles/superdevmode.html[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 link:http://localhost:9876/[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
link:https://developer.chrome.com/devtools/docs/javascript-debugging#source-maps[
Chrome] and
link:https://developer.mozilla.org/en-US/docs/Tools/Debugger#Use_a_source_map[
Firefox] developer documentation.

* Load the link:http://localhost:8080[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).

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

SEARCHBOX
---------