gerrit/Documentation/dev-bazel.txt
Han-Wen Nienhuys fe81f93215 Simplify local JGit development
Put all the logic in jgit.bzl, where a single edit suffices to get
the local flavor.

Given that all sha1 for jgit dependencies are in jgit.bzl, we can
remove the constants and use sha1 values directly.

Change-Id: Icabf651e02f226e5c025457d54588074a11ae283
2017-03-24 08:36:18 +09:00

387 lines
8.0 KiB
Plaintext

= Gerrit Code Review - Building with Bazel
[[installation]]
== 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
----
[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 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.
[[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
---------