6062b6599d
Per discussion on Ic0b01959 the process for including external dependencies was less than clear. Most plugins suggest overwriting core's external_plugin_deps.bzl with the plugin's version. This works until you want to add a second plugin or you expect your dependencies to automatically be picked up when building the release war. So instead suggest importing the dependencies! Change-Id: Iab7fe269b7d6ca6c499e5dc61fad7057e0a52725
158 lines
3.8 KiB
Plaintext
158 lines
3.8 KiB
Plaintext
= Gerrit Code Review - Building plugins
|
|
|
|
|
|
From build process perspective there are three types of plugins:
|
|
|
|
* Maven driven
|
|
* Bazel tree driven
|
|
* Bazel standalone
|
|
|
|
These types can be combined: if both files in plugin's root directory exist:
|
|
|
|
* `BUILD`
|
|
* `pom.xml`
|
|
|
|
the plugin can be built with both Bazel and Maven.
|
|
|
|
|
|
== Maven driven build
|
|
|
|
If plugin contains `pom.xml` file, it can be built with Maven as usually:
|
|
|
|
----
|
|
mvn clean package
|
|
----
|
|
|
|
Exceptions from the rule above:
|
|
|
|
=== Exception 1:
|
|
|
|
|
|
Plugin's `pom.xml` references snapshot version of plugin API:
|
|
`2.8-SNAPSHOT`. In this case there are two possibilities:
|
|
|
|
* switch to release API. Change plugin API version in `pom.xml` from
|
|
`2.8-SNAPSHOT` to `2.8.1` and repeat step 1 above.
|
|
* build and install `SNAPSHOT` version of plugin API in local Maven repository:
|
|
|
|
----
|
|
./tools/maven/api.sh install
|
|
----
|
|
|
|
=== Exception 2:
|
|
|
|
Plugin's `pom.xml` references other own or foreign (unpublished) libraries or
|
|
even other Gerrit plugins. These libraries and/or plugins must be built and
|
|
installed in local Maven repository. Clone the related projects and issue
|
|
|
|
----
|
|
mvn install
|
|
----
|
|
|
|
Repeat step 1. above.
|
|
|
|
|
|
== Bazel in tree driven
|
|
|
|
|
|
The fact that plugin contains `BUILD` file doesn't mean that building this
|
|
plugin from the plugin directory works.
|
|
|
|
Bazel in tree driven means it can only be built from within Gerrit tree. Clone
|
|
or link the plugin into gerrit/plugins directory:
|
|
|
|
----
|
|
cd gerrit
|
|
bazel build plugins/<plugin-name>:<plugin-name>
|
|
----
|
|
|
|
The output can be normally found in the following directory:
|
|
|
|
----
|
|
bazel-genfiles/plugins/<plugin-name>/<plugin-name>.jar
|
|
----
|
|
|
|
Some plugins describe their build process in `src/main/resources/Documentation/build.md`
|
|
file. It may worth checking.
|
|
|
|
=== Plugins with external dependencies ===
|
|
|
|
If the plugin has external dependencies, then they must be included from Gerrit's
|
|
own WORKSPACE file. This can be achieved by including them in `external_plugin_deps.bzl`.
|
|
During the build in Gerrit tree, this file must be copied over the dummy one in
|
|
`plugins` directory.
|
|
|
|
Example for content of `external_plugin_deps.bzl` file:
|
|
|
|
----
|
|
load("//tools/bzl:maven_jar.bzl", "maven_jar")
|
|
|
|
def external_plugin_deps():
|
|
maven_jar(
|
|
name = 'org_apache_tika_tika_core',
|
|
artifact = 'org.apache.tika:tika-core:1.12',
|
|
sha1 = '5ab95580d22fe1dee79cffbcd98bb509a32da09b',
|
|
)
|
|
----
|
|
|
|
=== Bundle custom plugin in release.war ===
|
|
|
|
To bundle custom plugin(s) in the link:dev-bazel.html#release[release.war] artifact,
|
|
add them to the CUSTOM_PLUGINS list in `tools/bzl/plugins.bzl`.
|
|
|
|
Example of `tools/bzl/plugins.bzl` with custom plugin `my-plugin`:
|
|
|
|
----
|
|
CORE_PLUGINS = [
|
|
"commit-message-length-validator",
|
|
"download-commands",
|
|
"hooks",
|
|
"replication",
|
|
"reviewnotes",
|
|
"singleusergroup",
|
|
]
|
|
|
|
CUSTOM_PLUGINS = [
|
|
"my-plugin",
|
|
]
|
|
|
|
CUSTOM_PLUGINS_TEST_DEPS = [
|
|
# Add custom core plugins with tests deps here
|
|
]
|
|
----
|
|
|
|
If the plugin(s) being bundled in the release have external dependencies, include them
|
|
in `plugins/external_plugin_deps`. You should alias `external_plugin_deps()` so it
|
|
can be imported for multiple plugins. For example:
|
|
|
|
----
|
|
load(":my-plugin/external_plugin_deps.bzl", my_plugin="external_plugin_deps")
|
|
load(":my-other-plugin/external_plugin_deps.bzl", my_other_plugin="external_plugin_deps")
|
|
|
|
def external_plugin_deps():
|
|
my_plugin()
|
|
my_other_plugin()
|
|
----
|
|
|
|
[NOTE]
|
|
Since `tools/bzl/plugins.bzl` and `plugins/external_plugin_deps.bzl` are part of
|
|
Gerrit's source code and the version of the war is based on the state of the git
|
|
repository that is built; you should commit this change before building, otherwise
|
|
the version will be marked as 'dirty'.
|
|
|
|
== Bazel standalone driven
|
|
|
|
Only few plugins support that mode for now:
|
|
|
|
----
|
|
cd reviewers
|
|
bazel build reviewers
|
|
----
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|
|
|
|
SEARCHBOX
|
|
---------
|