opendev/gerrit
Code Issues Proposed changes
0d5be4f5c5
gerrit/Documentation/dev-bazel.txt
David Pursehouse 05af76fa4b Merge branch 'stable-2.15' 
* stable-2.15:
  ChangeIT: Temporarily disable tests related to group matching
  Align SSH create-project with REST API
  SubmoduleOp: Fix formatting of submodule update commit message
  Fix Postgresql JDBC driver leaking memory
  Document that the build works with Python 2 or 3
  merge_jars.py: Fix for python 3 compatibility
  project.py: decode byte output from check_result
  license and doc: Add support for python3
  Bazel: Make build tool chain python 3 compatible
  ExternalIds NoteDb migration: Avoid intermediate migration state
  Make PrivateStateChanged and WorkInProgressStateChanged singletons
  BatchProgramModule: Bind GitReferenceUpdated.DISABLED
  BatchProgramModule: Don't bind event classes to null
  Document that Python 2 is required by the build
  Make event firing classes singleton
  Fix ConcurrentModificationException when posting reviews
  Revert partially "Trim multi-line arguments for task name and ssh_log"
  BaseCommand: Fix formatting of task description with arguments
  Add analytics to the list of plugins
  config-plugins: Consistently use "/+doc/" for documentation links
  config-plugins: Fix link to ref-protection plugin documentation
  config-plugins: Add readonly plugin to plugin list
  Add documentation for SshCreateCommandInterceptor
  Allow plugins to intercept ssh command creation
  GWT/Poly: Default to "Create initial commit" during project creation
  Revert "Reduce chance of deadlock in account cache"
  commit-msg: Adapt to awk behavior change on Cygwin/MSYS
  Expand docs on how to include external dependencies in core plugins
  Document how to bundle custom plugins in release.war
  Group members can't be added as reviewers if a matched username exists
  Set version to 2.13.11
  StreamEventsApiListener: Prevent NPE when account is null
  Set version to 2.11.11
  Replace links to code.google.com/p/gerrit
  Update issue tracker URL in documentation
  Update issue tracker URL in POM files
  Bump jsch to 0.54
  Update jsch to 0.1.53
  Bump Jsch to 1.52

Change-Id: Icec3dcfe53146da7d66d4d690afdd9e77ee10380
2018-03-12 09:03:47 +09:00

429 lines
9.3 KiB
Plaintext
Raw Blame History

= 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]
[[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.
[[clean-download-cache]]
=== Cleaning The download cache
The cache for downloaded artifacts is located in
`~/.gerritcodereview/bazel-cache/downloaded-artifacts`.
If you really do need to clean the download cache manually, then:
----
rm -rf ~/.gerritcodereview/bazel-cache/downloaded-artifacts
----
[[local-action-cache]]
To accelerate builds, local action cache can be activated. Note, that this
experimental feature is not activated per default and only available since
Bazel version 0.7.
To activate the local action cache, create accessible cache directory:
----
mkdir -p ~/.gerritcodereview/bazel-cache/cas
----
and add these lines to your `~/.bazelrc` file:
----
build --experimental_local_disk_cache_path=/home/<user>/.gerritcodereview/bazel-cache/cas
build --experimental_local_disk_cache
build --experimental_strict_action_env
----
[NOTE] `experimental_local_disk_cache_path` must be absolute path. Expansion of `~` is
unfortunately not supported yet. This is also the reason why we can't activate this
feature by default yet (by adjusting tools/bazel.rc file).
[[repository_cache]]
To accelerate fetches, local repository cache can be activated. 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 activate the local repository cache, create accessible cache directory:
----
mkdir -p ~/.gerritcodereview/bazel-cache/repository
----
and add this line to your `~/.bazelrc` file:
----
build --experimental_repository_cache=/home/<user>/.gerritcodereview/bazel-cache/repository
----
[NOTE] `experimental_repository_cache` must be absolute path. Expansion of `~` is
unfortunately not supported yet. This is also the reason why we can't activate this
feature by default yet (by adjusting tools/bazel.rc file).
GERRIT
------
Part of link:index.html[Gerrit Code Review]
SEARCHBOX
---------
View Git Blame Copy Permalink