Gerrit Code Review - Building with Bazel

If you have the prerequisites, running

should generate a .war file under bazel-bin/gerrit.war.

To build Gerrit from source, you need:

To build only the documentation for testing or static hosting:

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

To generate HTML files skipping the zip archiving:

And open bazel-bin/Documentation/index.html.

To build the Gerrit executable WAR with the documentation included:

The WAR file will be placed in:

Alternatively, one can generate the documentation as flat files:

The html, css, js files are placed in:

Debugging tests:

Debug test example:

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

To run SSH tests using JSch ssh client:

To run SSH tests using Apache MINA ssh client:

To run only tests that do not use SSH:

To exclude tests that have been marked as flaky:

To exclude tests that require a Docker host:

To exclude tests that require very recent git client version:

To ignore cached test results:

To run one or more specific groups of tests:

The following values are currently supported for the group name:

Bazel itself supports a multitude of ways to specify targets for fine-grained test selection that can be combined with many of the examples above.

In some cases it may be necessary to debug a test while running it in bazel. For example, when we observe a different test result in Eclipse and bazel. Using the --java_debug option will start the JVM in debug mode and await for a remote debugger to attach.

Example:

Now attach with a debugger to the port 5005. For example use "Remote Java Application" launch configuration in Eclipe and specify the port 5005.

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:

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:

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:

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.

To build against unpublished Maven JARs, like 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:

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:

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:

And corresponding WORKSPACE excerpt:

To build against SNAPSHOT Maven JARs, the complete SNAPSHOT version must be used:

To accelerate builds, several caches are activated per default:

The downloaded-artifacts cache can be relocated by setting the GERRIT_CACHE_HOME environment variable. The other two can be adjusted with bazel build options --repository_cache and --disk_cache respectively.

Currently none of these caches have a maximum size limit. See this bazel issue for details. Users should watch the cache sizes and clean them manually if necessary.

Parts of the Gerrit web app build require running NPM-based JavaScript programs as "binaries". We don’t attempt to resolve and download NPM dependencies at build time, but instead use pre-built bundles of the NPM binary along with all its dependencies. Some packages on registry.npmjs.org come with their dependencies bundled, but this is the exception rather than the rule. More commonly, to add a new binary to this list, you will need to bundle the binary yourself.

Start by checking that the license and file types of the bundle are acceptable:

This will output a list of the different licenses used by the package and all its transitive dependencies. We can only legally distribute a bundle via our storage bucket if the licenses allow us to do so. As long as all of the listed license are allowed by Google’s. Any by_exception_only, commercial, prohibited, or unlisted licenses are not allowed; otherwise, it is ok to distribute the source. If in doubt, contact a maintainer who is a Googler.

Next, check the file types:

If you see anything that looks like a native library or binary, then we can’t use the bundle.

If everything looks good, install the package with the following command:

Update the polygerrit-ui/app/node_modules_licenses/licenses.ts file. You should add licenses for the package itself and for all transitive depndencies. If you forgot to add a license, the Documentation:check_licenses test will fail.

After the update, commit all changes to the repository (including yarn.lock).

The Bazel build can be used with Google’s Remote Build Execution.

This needs the following setup steps:

Create a worker pool. The instances should have at least 4 CPUs each for adequate performance.

To use RBE, execute

Part of Gerrit Code Review