Documentation/dev-eclipse.txt - gerrit - Git at Google

 :linkattrs:
 = Gerrit Code Review - Eclipse Setup

 This document is about configuring Gerrit Code Review into an
 Eclipse workspace for development.

 Java 11 or later SDK is required.
 Otherwise, java 8 can still be used for now as described below.

 [[setup]]
 == Project Setup

 In your Eclipse installation's link:https://wiki.eclipse.org/Eclipse.ini[`eclipse.ini`,role=external,window=_blank] 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
 link:https://docs.bazel.build/versions/master/output_directories.html[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 threshold for the cleanup of temporary files
 The default threshold for the cleanup can be overridden 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 link:https://superuser.com/a/187105[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
 link:dev-build-plugins.html#_bundle_custom_plugin_in_release_war[bundling in release.war]
 and run `tools/eclipse/project.py`.

 If a plugin requires additional test dependencies (not available in the Gerrit),
 then in order to execute tests directly from Eclipse, that plugin must be also
 added to `CUSTOM_PLUGINS_TEST_DEPS` list in `tools/bzl/plugins.bzl` and Eclipse
 project configuration needs to be updated by running `tools/eclipse/project.py`.

 == Java Versions

 Java 11 is supported as a default, but some adjustments must be done for other JDKs:

 * 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

 Moreover, the actual java 11 language features are not supported yet.

 [[Formatting]]
 == Code Formatter Settings

 To format source code, Gerrit uses the
 link:https://github.com/google/google-java-format[`google-java-format`,role=external,window=_blank]
 tool (version 1.24.0), which automatically formats code to follow the
 style guide. See link:dev-crafting-changes.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,role=external,window=_blank]
 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

 === The Gerrit web app UI is served by `Web Dev Server`. To launch it,
 run this command:

 ----
   $ npm run start
 ----

 === 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.

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

 SEARCHBOX
 ---------
	:linkattrs:
	= Gerrit Code Review - Eclipse Setup

	This document is about configuring Gerrit Code Review into an
	Eclipse workspace for development.

	Java 11 or later SDK is required.
	Otherwise, java 8 can still be used for now as described below.

	[[setup]]
	== Project Setup

	In your Eclipse installation's link:https://wiki.eclipse.org/Eclipse.ini[`eclipse.ini`,role=external,window=_blank] 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
	link:https://docs.bazel.build/versions/master/output_directories.html[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 threshold for the cleanup of temporary files
	The default threshold for the cleanup can be overridden 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 link:https://superuser.com/a/187105[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
	link:dev-build-plugins.html#_bundle_custom_plugin_in_release_war[bundling in release.war]
	and run `tools/eclipse/project.py`.

	If a plugin requires additional test dependencies (not available in the Gerrit),
	then in order to execute tests directly from Eclipse, that plugin must be also
	added to `CUSTOM_PLUGINS_TEST_DEPS` list in `tools/bzl/plugins.bzl` and Eclipse
	project configuration needs to be updated by running `tools/eclipse/project.py`.

	== Java Versions

	Java 11 is supported as a default, but some adjustments must be done for other JDKs:

	* 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

	Moreover, the actual java 11 language features are not supported yet.

	[[Formatting]]
	== Code Formatter Settings

	To format source code, Gerrit uses the
	link:https://github.com/google/google-java-format[`google-java-format`,role=external,window=_blank]
	tool (version 1.24.0), which automatically formats code to follow the
	style guide. See link:dev-crafting-changes.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,role=external,window=_blank]
	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

	=== The Gerrit web app UI is served by `Web Dev Server`. To launch it,
	run this command:

	----
	$ npm run start
	----

	=== 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.

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

	SEARCHBOX
	---------