= Gerrit Code Review - Building with Bazel

Bazel build is experimental. Major missing parts:

* Custom plugins
* Test suites for SSH, acceptance, etc.
* tag tests as slow, flaky, etc.

Nice to have:

* JGit build from local tree.
* local.properties proxy config.
* coverage

== Installation

You need to use 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
----

The output executable WAR will be placed in:

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

To run a Gerrit site execute:

----
  $(bazel info output_base)/external/local_jdk/bin/java \
     -jar bazel-bin/gerrit.war daemon -d ../gerrit_testsite
----

[NOTE] You must use the same Java version that Bazel used for the build.
This Java version is available at
`$(bazel info output_base)/external/local_jdk/bin/java`.

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

To build the Gerrit web application that includes the GWT UI, the
PolyGerrit UI 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 gerrit-plugin-api:plugin-api_deploy.jar
  bazel build gerrit-extension-api:extension-api_deploy.jar
----

Java binaries, Java sources and Java docs are generated into corresponding
project directories, here as example for plugin API:

----
  bazel-bin/gerrit-plugin-api/plugin-api_deploy.jar
  bazel-bin/gerrit-extension-api/extension-api_deploy.jar
----

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

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

Install gerrit.war to the local maven repository:

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

=== 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 [IntelliJ
plugin](https://ij.bazel.io). Do the following:

  * Install the plugin (requires IJ 2016.2 or newer)
  * Restart IntelliJ
  * Select "Import Bazel Project" from the homescreen
  * Select "Workspace": (directory holding gerrit source)
  * Select "Import from workspace > Project view" : `.bazelproject`
  * Once the project was created, copy `tools/intellij/gerrit_daemon.xml` to
    `.idea/runConfigurations/gerrit_daemon.xml` in your IntelliJ output
  * In Settings > Appearance & Behavior > Path Variables create a new path
    variable called `TESTSITE_PATH` and provide the path to your local testsite
    as value


=== Eclipse

==== Generating the Eclipse Project

Create the Eclipse project:

----
  tools/eclipse/project_bzl.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_bzl.py` again.

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

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

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


== 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',
   id = 'gwtorm:gwtorm:42',
   license = 'Apache2.0',
   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',
    id = 'com.gitblit:gitblit:1.4.0',
    sha1 = '1b130dbf5578ace37507430a4a523f6594bf34fa',
    license = 'Apache2.0',
    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',
    id = 'com.gitblit:gitblit:1.4.0',
    sha1 = '1b130dbf5578ace37507430a4a523f6594bf34fa',
    license = 'Apache2.0',
    repository = GERRIT_FORGE,
 )
----


[[clean-cache]]
=== Cleaning The download cache

The cache for the Gerrit Code Review project is located in
`~/.gerritcodereview/buck-cache/locally-built-artifacts`.

If you really do need to clean the cache manually, then:

----
 rm -rf ~/.gerritcodereview/buck-cache/locally-built-artifacts
----

Note that the root `buck-cache` folder should not be deleted as it also contains
the `downloaded-artifacts` directory, which holds the artifacts that got
downloaded (not built locally).

[NOTE] When building with Bazel the artifacts are still cached in
`~/.gerritcodereview/buck-cache/`. This allows Bazel to make use of
libraries that were previously downloaded by Buck.

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

SEARCHBOX
---------