47b79bd20f
Since [1] two action cache option were merged, and the experimental prefix was removed. Also update the section about repository cache. This cache is now activated per default and we can only change the location of that cache. [1] https://github.com/bazelbuild/bazel/pull/4874 Change-Id: Iec4557a28987665182e9fe3f476d035421b751fe
404 lines
8.3 KiB
Plaintext
404 lines
8.3 KiB
Plaintext
= Gerrit Code Review - Building with Bazel
|
|
|
|
[[installation]]
|
|
== Prerequisites
|
|
|
|
To build Gerrit from source, you need:
|
|
|
|
* A Linux or macOS system (Windows is not supported at this time)
|
|
* A JDK for Java 8
|
|
* Python 2 or 3
|
|
* Node.js
|
|
* link:https://www.bazel.io/versions/master/docs/install.html[Bazel]
|
|
* Maven
|
|
* zip, unzip
|
|
* gcc
|
|
|
|
[[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 //javatests/com/google/gerrit/acceptance/api/change:api_change
|
|
----
|
|
|
|
To run a specific test group, e.g. the rest-account test group:
|
|
|
|
----
|
|
bazel test //javatests/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 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
|
|
* edit
|
|
* git
|
|
* notedb
|
|
* pgm
|
|
* rest
|
|
* server
|
|
* ssh
|
|
|
|
== 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.
|
|
|
|
[[local-action-cache]]
|
|
|
|
To accelerate builds, local action cache can be activated.
|
|
To activate the local action cache add these lines to your `~/.bazelrc` file:
|
|
|
|
----
|
|
build --disk_cache=~/.gerritcodereview/bazel-cache/cas
|
|
build --experimental_strict_action_env
|
|
build --action_env=PATH
|
|
----
|
|
|
|
[[repository_cache]]
|
|
|
|
To accelerate fetches, local repository cache is activated per default in Bazel.
|
|
This cache is only used for rules_closure external repository and transitive
|
|
dependendcies. That's because rules_closure uses standard Bazel download facility.
|
|
For all other gerrit dependencies, the download_artifacts repository cache is used
|
|
already.
|
|
|
|
To change the default local repository cache directry, create accessible cache
|
|
directory:
|
|
|
|
----
|
|
mkdir -p ~/.gerritcodereview/bazel-cache/repository
|
|
----
|
|
|
|
and add this line to your `~/.bazelrc` file:
|
|
|
|
----
|
|
build --repository_cache=/home/<user>/.gerritcodereview/bazel-cache/repository
|
|
----
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|
|
|
|
SEARCHBOX
|
|
---------
|