opendev/gerrit
Code Issues Proposed changes
Files
43c5ed8045202a1bd726177e3f52485b39b24dbb
gerrit/Documentation/dev-bazel.txt
David Ostrovsky 26f8da8f4d Bazel: Add :api rule to build all API artifacts at once 
This simplifies house keeping for the CI implementations and this was
always supported in Buck driven build. Wenn new API is added, only one
rule needs to be updated, and all CI implementation would reflect
building of new API without any changes on their side.

Change-Id: I050cef1e1545431d8806bd3a15a267842e3ed809
2016-12-24 09:33:27 +01:00

331 lines
6.6 KiB
Plaintext
Raw Blame History

= 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]]
== 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
----
[[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 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 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_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 //...
----
To run only tests that do not use SSH:
----
bazel test --test_env=GERRIT_USE_SSH=NO //...
----
== 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
---------
View Git Blame Copy Permalink