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

 = Gerrit Code Review - Building with Bazel

 [[installation]]
 == Installation

 You need to use Python (2 or 3), Java 8, and Node.js for building gerrit.

 You can install Bazel from the bazel.io:
 https://www.bazel.io/versions/master/docs/install.html


 [[build]]
 == Building on the Command Line

 === Gerrit Development WAR File

 To build the Gerrit web application that includes the GWT UI and the
 PolyGerrit UI:

 ----
   bazel build gerrit
 ----

 [NOTE]
 PolyGerrit UI may require additional tools (such as npm). Please read
 the polygerrit-ui/README.md for more info.

 The output executable WAR will be placed in:

 ----
   bazel-bin/gerrit.war
 ----

 [[release]]
 === Gerrit Release WAR File

 To build the Gerrit web application that includes the GWT UI, the
 PolyGerrit UI, core plugins and documentation:

 ----
   bazel build release
 ----

 The output executable WAR will be placed in:

 ----
   bazel-bin/release.war
 ----

 === Headless Mode

 To build Gerrit in headless mode, i.e. without the GWT Web UI:

 ----
   bazel build headless
 ----

 The output executable WAR will be placed in:

 ----
   bazel-bin/headless.war
 ----

 === Extension and Plugin API JAR Files

 To build the extension, plugin and GWT API JAR files:

 ----
   bazel build api
 ----

 The output archive that contains Java binaries, Java sources and
 Java docs will be placed in:

 ----
   bazel-genfiles/api.zip
 ----

 Install {extension,plugin,gwt}-api to the local maven repository:

 ----
   tools/maven/api.sh install
 ----

 Install gerrit.war to the local maven repository:

 ----
   tools/maven/api.sh war_install
 ----

 === Plugins

 ----
   bazel build plugins:core
 ----

 The output JAR files for individual plugins will be placed in:

 ----
   bazel-genfiles/plugins/<name>/<name>.jar
 ----

 The JAR files will also be packaged in:

 ----
   bazel-genfiles/plugins/core.zip
 ----

 To build a specific plugin:

 ----
   bazel build plugins/<name>
 ----

 The output JAR file will be be placed in:

 ----
   bazel-genfiles/plugins/<name>/<name>.jar
 ----

 Note that when building an individual plugin, the `core.zip` package
 is not regenerated.


 [[IDEs]]
 == Using an IDE.

 === IntelliJ

 The Gerrit build works with Bazel's link:https://ij.bazel.io[IntelliJ plugin].
 Please follow the instructions on <<dev-intellij#,IntelliJ Setup>>.

 === Eclipse

 ==== Generating the Eclipse Project

 Create the Eclipse project:

 ----
   tools/eclipse/project.py
 ----

 and then follow the link:dev-eclipse.html#setup[setup instructions].

 ==== Refreshing the Classpath

 If an updated classpath is needed, the Eclipse project can be
 refreshed and missing dependency JARs can be downloaded by running
 `project.py` again. For IntelliJ, you need to click the `Sync Project
 with BUILD Files` button of link:https://ij.bazel.io[IntelliJ plugin].

 [[documentation]]
 === Documentation

 To build only the documentation for testing or static hosting:

 ----
   bazel build Documentation:searchfree
 ----

 The html files will be bundled into `searchfree.zip` in this location:

 ----
   bazel-bin/Documentation/searchfree.zip
 ----

 To build the executable WAR with the documentation included:

 ----
   bazel build withdocs
 ----

 The WAR file will be placed in:

 ----
   bazel-bin/withdocs.war
 ----

 [[tests]]
 == Running Unit Tests

 ----
   bazel test --build_tests_only //...
 ----

 Debugging tests:

 ----
   bazel test --test_output=streamed --test_filter=com.gerrit.TestClass.testMethod  testTarget
 ----

 Debug test example:

 ----
   bazel test --test_output=streamed --test_filter=com.google.gerrit.acceptance.api.change.ChangeIT.getAmbiguous //gerrit-acceptance-tests/src/test/java/com/google/gerrit/acceptance/api/change:api_change
 ----

 To run a specific test group, e.g. the rest-account test group:

 ----
   bazel test //gerrit-acceptance-tests/src/test/java/com/google/gerrit/acceptance/rest/account:rest_account
 ----

 To run the tests against NoteDb backend with write
 to NoteDb, but not read from it:

 ----
   bazel test --test_env=GERRIT_NOTEDB=WRITE //...
 ----

 Write and read from NoteDb:

 ----
   bazel test --test_env=GERRIT_NOTEDB=READ_WRITE //...
 ----

 Primary storage NoteDb:

 ----
   bazel test --test_env=GERRIT_NOTEDB=PRIMARY //...
 ----

 Primary storage NoteDb and ReviewDb disabled:

 ----
   bazel test --test_env=GERRIT_NOTEDB=ON //...
 ----

 To run only tests that do not use SSH:

 ----
   bazel test --test_env=GERRIT_USE_SSH=NO //...
 ----

 To exclude tests that have been marked as flaky:

 ----
   bazel test --test_tag_filters=-flaky //...
 ----

 To exclude tests that require a Docker host:

 ----
   bazel test --test_tag_filters=-docker //...
 ----

 To ignore cached test results:

 ----
   bazel test --cache_test_results=NO //...
 ----

 To run one or more specific groups of tests:

 ----
   bazel test --test_tag_filters=api,git //...
 ----

 The following values are currently supported for the group name:

 * annotation
 * api
 * docker
 * edit
 * elastic
 * git
 * notedb
 * pgm
 * rest
 * server
 * ssh

 [[elasticsearch]]
 === Elasticsearch

 Successfully running the Elasticsearch tests requires Docker, and
 may require setting the local
 link:https://www.elastic.co/guide/en/elasticsearch/reference/current/vm-max-map-count.html[virtual memory].

 If Docker is not available, the Elasticsearch tests will be skipped.
 Note that Bazel currently does not show
 link:https://github.com/bazelbuild/bazel/issues/3476[the skipped tests].

 == Dependencies

 Dependency JARs are normally downloaded as needed, but you can
 download everything upfront.  This is useful to enable
 subsequent builds to run without network access:

 ----
   bazel fetch //...
 ----

 When downloading from behind a proxy (which is common in some corporate
 environments), it might be necessary to explicitly specify the proxy that
 is then used by `curl`:

 ----
   export http_proxy=http://<proxy_user_id>:<proxy_password>@<proxy_server>:<proxy_port>
 ----

 Redirection to local mirrors of Maven Central and the Gerrit storage
 bucket is supported by defining specific properties in
 `local.properties`, a file that is not tracked by Git:

 ----
   echo download.GERRIT = http://nexus.my-company.com/ >>local.properties
   echo download.MAVEN_CENTRAL = http://nexus.my-company.com/ >>local.properties
 ----

 The `local.properties` file may be placed in the root of the gerrit repository
 being built, or in `~/.gerritcodereview/`.  The file in the root of the gerrit
 repository has precedence.

 == Building against unpublished Maven JARs

 To build against unpublished Maven JARs, like gwtorm or PrologCafe, the custom
 JARs must be installed in the local Maven repository (`mvn clean install`) and
 `maven_jar()` must be updated to point to the `MAVEN_LOCAL` Maven repository for
 that artifact:

 [source,python]
 ----
  maven_jar(
    name = 'gwtorm',
    artifact = 'gwtorm:gwtorm:42',
    repository = MAVEN_LOCAL,
  )
 ----

 == Building against artifacts from custom Maven repositories

 To build against custom Maven repositories, two modes of operations are
 supported: with rewrite in local.properties and without.

 Without rewrite the URL of custom Maven repository can be directly passed
 to the maven_jar() function:

 [source,python]
 ----
   GERRIT_FORGE = 'http://gerritforge.com/snapshot'

   maven_jar(
     name = 'gitblit',
     artifact = 'com.gitblit:gitblit:1.4.0',
     sha1 = '1b130dbf5578ace37507430a4a523f6594bf34fa',
     repository = GERRIT_FORGE,
  )
 ----

 When the custom URL has to be rewritten, then the same logic as with Gerrit
 known Maven repository is used: Repo name must be defined that matches an entry
 in local.properties file:

 ----
   download.GERRIT_FORGE = http://my.company.mirror/gerrit-forge
 ----

 And corresponding WORKSPACE excerpt:

 [source,python]
 ----
   GERRIT_FORGE = 'GERRIT_FORGE:'

   maven_jar(
     name = 'gitblit',
     artifact = 'com.gitblit:gitblit:1.4.0',
     sha1 = '1b130dbf5578ace37507430a4a523f6594bf34fa',
     repository = GERRIT_FORGE,
  )
 ----

 [[consume-jgit-from-development-tree]]

 To consume the JGit dependency from the development tree, edit
 `lib/jgit/jgit.bzl` setting LOCAL_JGIT_REPO to a directory holding a
 JGit repository.

 [[bazel-local-caches]]

 To accelerate builds, several caches are activated per default:

 * ~/.gerritcodereview/bazel-cache/downloaded-artifacts
 * ~/.gerritcodereview/bazel-cache/repository
 * ~/.gerritcodereview/bazel-cache/cas

 Currently none of these caches have a maximum size limit. See
 link:https://github.com/bazelbuild/bazel/issues/5139[this bazel issue] for
 details. Users should watch the cache sizes and clean them manually if
 necessary.

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

 SEARCHBOX
 ---------
	= Gerrit Code Review - Building with Bazel

	[[installation]]
	== Installation

	You need to use Python (2 or 3), Java 8, and Node.js for building gerrit.

	You can install Bazel from the bazel.io:
	https://www.bazel.io/versions/master/docs/install.html


	[[build]]
	== Building on the Command Line

	=== Gerrit Development WAR File

	To build the Gerrit web application that includes the GWT UI and the
	PolyGerrit UI:

	----
	bazel build gerrit
	----

	[NOTE]
	PolyGerrit UI may require additional tools (such as npm). Please read
	the polygerrit-ui/README.md for more info.

	The output executable WAR will be placed in:

	----
	bazel-bin/gerrit.war
	----

	[[release]]
	=== Gerrit Release WAR File

	To build the Gerrit web application that includes the GWT UI, the
	PolyGerrit UI, core plugins and documentation:

	----
	bazel build release
	----

	The output executable WAR will be placed in:

	----
	bazel-bin/release.war
	----

	=== Headless Mode

	To build Gerrit in headless mode, i.e. without the GWT Web UI:

	----
	bazel build headless
	----

	The output executable WAR will be placed in:

	----
	bazel-bin/headless.war
	----

	=== Extension and Plugin API JAR Files

	To build the extension, plugin and GWT API JAR files:

	----
	bazel build api
	----

	The output archive that contains Java binaries, Java sources and
	Java docs will be placed in:

	----
	bazel-genfiles/api.zip
	----

	Install {extension,plugin,gwt}-api to the local maven repository:

	----
	tools/maven/api.sh install
	----

	Install gerrit.war to the local maven repository:

	----
	tools/maven/api.sh war_install
	----

	=== Plugins

	----
	bazel build plugins:core
	----

	The output JAR files for individual plugins will be placed in:

	----
	bazel-genfiles/plugins/<name>/<name>.jar
	----

	The JAR files will also be packaged in:

	----
	bazel-genfiles/plugins/core.zip
	----

	To build a specific plugin:

	----
	bazel build plugins/<name>
	----

	The output JAR file will be be placed in:

	----
	bazel-genfiles/plugins/<name>/<name>.jar
	----

	Note that when building an individual plugin, the `core.zip` package
	is not regenerated.



	[[IDEs]]
	== Using an IDE.

	=== IntelliJ

	The Gerrit build works with Bazel's link:https://ij.bazel.io[IntelliJ plugin].
	Please follow the instructions on <<dev-intellij#,IntelliJ Setup>>.

	=== Eclipse

	==== Generating the Eclipse Project

	Create the Eclipse project:

	----
	tools/eclipse/project.py
	----

	and then follow the link:dev-eclipse.html#setup[setup instructions].

	==== Refreshing the Classpath

	If an updated classpath is needed, the Eclipse project can be
	refreshed and missing dependency JARs can be downloaded by running
	`project.py` again. For IntelliJ, you need to click the `Sync Project
	with BUILD Files` button of link:https://ij.bazel.io[IntelliJ plugin].

	[[documentation]]
	=== Documentation

	To build only the documentation for testing or static hosting:

	----
	bazel build Documentation:searchfree
	----

	The html files will be bundled into `searchfree.zip` in this location:

	----
	bazel-bin/Documentation/searchfree.zip
	----

	To build the executable WAR with the documentation included:

	----
	bazel build withdocs
	----

	The WAR file will be placed in:

	----
	bazel-bin/withdocs.war
	----

	[[tests]]
	== Running Unit Tests

	----
	bazel test --build_tests_only //...
	----

	Debugging tests:

	----
	bazel test --test_output=streamed --test_filter=com.gerrit.TestClass.testMethod testTarget
	----

	Debug test example:

	----
	bazel test --test_output=streamed --test_filter=com.google.gerrit.acceptance.api.change.ChangeIT.getAmbiguous //gerrit-acceptance-tests/src/test/java/com/google/gerrit/acceptance/api/change:api_change
	----

	To run a specific test group, e.g. the rest-account test group:

	----
	bazel test //gerrit-acceptance-tests/src/test/java/com/google/gerrit/acceptance/rest/account:rest_account
	----

	To run the tests against NoteDb backend with write
	to NoteDb, but not read from it:

	----
	bazel test --test_env=GERRIT_NOTEDB=WRITE //...
	----

	Write and read from NoteDb:

	----
	bazel test --test_env=GERRIT_NOTEDB=READ_WRITE //...
	----

	Primary storage NoteDb:

	----
	bazel test --test_env=GERRIT_NOTEDB=PRIMARY //...
	----

	Primary storage NoteDb and ReviewDb disabled:

	----
	bazel test --test_env=GERRIT_NOTEDB=ON //...
	----

	To run only tests that do not use SSH:

	----
	bazel test --test_env=GERRIT_USE_SSH=NO //...
	----

	To exclude tests that have been marked as flaky:

	----
	bazel test --test_tag_filters=-flaky //...
	----

	To exclude tests that require a Docker host:

	----
	bazel test --test_tag_filters=-docker //...
	----

	To ignore cached test results:

	----
	bazel test --cache_test_results=NO //...
	----

	To run one or more specific groups of tests:

	----
	bazel test --test_tag_filters=api,git //...
	----

	The following values are currently supported for the group name:

	* annotation
	* api
	* docker
	* edit
	* elastic
	* git
	* notedb
	* pgm
	* rest
	* server
	* ssh

	[[elasticsearch]]
	=== Elasticsearch

	Successfully running the Elasticsearch tests requires Docker, and
	may require setting the local
	link:https://www.elastic.co/guide/en/elasticsearch/reference/current/vm-max-map-count.html[virtual memory].

	If Docker is not available, the Elasticsearch tests will be skipped.
	Note that Bazel currently does not show
	link:https://github.com/bazelbuild/bazel/issues/3476[the skipped tests].

	== Dependencies

	Dependency JARs are normally downloaded as needed, but you can
	download everything upfront. This is useful to enable
	subsequent builds to run without network access:

	----
	bazel fetch //...
	----

	When downloading from behind a proxy (which is common in some corporate
	environments), it might be necessary to explicitly specify the proxy that
	is then used by `curl`:

	----
	export http_proxy=http://<proxy_user_id>:<proxy_password>@<proxy_server>:<proxy_port>
	----

	Redirection to local mirrors of Maven Central and the Gerrit storage
	bucket is supported by defining specific properties in
	`local.properties`, a file that is not tracked by Git:

	----
	echo download.GERRIT = http://nexus.my-company.com/ >>local.properties
	echo download.MAVEN_CENTRAL = http://nexus.my-company.com/ >>local.properties
	----

	The `local.properties` file may be placed in the root of the gerrit repository
	being built, or in `~/.gerritcodereview/`. The file in the root of the gerrit
	repository has precedence.

	== Building against unpublished Maven JARs

	To build against unpublished Maven JARs, like gwtorm or PrologCafe, the custom
	JARs must be installed in the local Maven repository (`mvn clean install`) and
	`maven_jar()` must be updated to point to the `MAVEN_LOCAL` Maven repository for
	that artifact:

	[source,python]
	----
	maven_jar(
	name = 'gwtorm',
	artifact = 'gwtorm:gwtorm:42',
	repository = MAVEN_LOCAL,
	)
	----

	== Building against artifacts from custom Maven repositories

	To build against custom Maven repositories, two modes of operations are
	supported: with rewrite in local.properties and without.

	Without rewrite the URL of custom Maven repository can be directly passed
	to the maven_jar() function:

	[source,python]
	----
	GERRIT_FORGE = 'http://gerritforge.com/snapshot'

	maven_jar(
	name = 'gitblit',
	artifact = 'com.gitblit:gitblit:1.4.0',
	sha1 = '1b130dbf5578ace37507430a4a523f6594bf34fa',
	repository = GERRIT_FORGE,
	)
	----

	When the custom URL has to be rewritten, then the same logic as with Gerrit
	known Maven repository is used: Repo name must be defined that matches an entry
	in local.properties file:

	----
	download.GERRIT_FORGE = http://my.company.mirror/gerrit-forge
	----

	And corresponding WORKSPACE excerpt:

	[source,python]
	----
	GERRIT_FORGE = 'GERRIT_FORGE:'

	maven_jar(
	name = 'gitblit',
	artifact = 'com.gitblit:gitblit:1.4.0',
	sha1 = '1b130dbf5578ace37507430a4a523f6594bf34fa',
	repository = GERRIT_FORGE,
	)
	----

	[[consume-jgit-from-development-tree]]

	To consume the JGit dependency from the development tree, edit
	`lib/jgit/jgit.bzl` setting LOCAL_JGIT_REPO to a directory holding a
	JGit repository.

	[[bazel-local-caches]]

	To accelerate builds, several caches are activated per default:

	* ~/.gerritcodereview/bazel-cache/downloaded-artifacts
	* ~/.gerritcodereview/bazel-cache/repository
	* ~/.gerritcodereview/bazel-cache/cas

	Currently none of these caches have a maximum size limit. See
	link:https://github.com/bazelbuild/bazel/issues/5139[this bazel issue] for
	details. Users should watch the cache sizes and clean them manually if
	necessary.

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

	SEARCHBOX
	---------