396 lines
8.4 KiB
Plaintext
396 lines
8.4 KiB
Plaintext
= 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 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=DISABLE_CHANGE_REVIEW_DB //...
|
|
----
|
|
|
|
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
|
|
* 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.
|
|
|
|
[[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.
|
|
|
|
Due to the `--experimental_strict_action_env` option used in `bazelrc`
|
|
it is possible that some commands required by the build are not found
|
|
on the PATH, causing the build to fail. In this case the PATH used in
|
|
the build can be overridden with the `--action_env=PATH` directive in
|
|
the user's `~/.bazelrc` file, for example:
|
|
|
|
----
|
|
build --action_env=PATH=/usr/local/opt/coreutils/libexec/gnubin/:/usr/local/bin/:/usr/bin/
|
|
----
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|
|
|
|
SEARCHBOX
|
|
---------
|