674078ad63
Change-Id: I66199e35ea824af85b877bff94c065da3ad16ab4 Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
337 lines
8.3 KiB
Plaintext
337 lines
8.3 KiB
Plaintext
Gerrit Code Review - Building with Buck
|
|
=======================================
|
|
|
|
|
|
Installation
|
|
------------
|
|
|
|
There is currently no binary distribution of Buck, so it has to be manually
|
|
built and installed. Apache Ant is required. Currently only Linux and Mac
|
|
OS are supported.
|
|
|
|
Clone the git and build it:
|
|
|
|
----
|
|
git clone https://gerrit.googlesource.com/buck
|
|
cd buck
|
|
ant
|
|
----
|
|
|
|
Make sure you have a `bin/` directory in your home directory and that
|
|
it is included in your path:
|
|
|
|
----
|
|
mkdir ~/bin
|
|
PATH=~/bin:$PATH
|
|
----
|
|
|
|
Add a symbolic link in `~/bin` to the buck executable:
|
|
|
|
----
|
|
ln -s `pwd`/bin/buck ~/bin/
|
|
----
|
|
|
|
Verify that `buck` is accessible:
|
|
|
|
----
|
|
which buck
|
|
----
|
|
|
|
|
|
[[eclipse]]
|
|
Eclipse Integration
|
|
-------------------
|
|
|
|
|
|
Generating the Eclipse Project
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Create the Eclipse project by building the `eclipse` target:
|
|
|
|
----
|
|
buck build eclipse
|
|
----
|
|
|
|
In Eclipse, choose 'Import existing project' and select the `gerrit` project
|
|
from the current working directory.
|
|
|
|
Expand the `gerrit` project, right-click on the `buck-out` folder, select
|
|
'Properties', and then under 'Attributes' check 'Derived'.
|
|
|
|
Note that if you make any changes in the project configuration that get
|
|
saved to the `.project` file, for example adding Resource Filters on a
|
|
folder, they will be overwritten the next time you run `buck build eclipse`.
|
|
|
|
|
|
Refreshing the Classpath
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Normally `buck build eclipse` does everything necessary to generate a working Eclipse
|
|
environment, but if the code doesn't compile and an updated classpath is needed, the
|
|
Eclipse project can be refreshed and missing dependency JARs can be downloaded by
|
|
building the `eclipse_project` and `download` targets:
|
|
|
|
----
|
|
buck build eclipse_project download
|
|
----
|
|
|
|
|
|
Attaching Sources
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
To save time and bandwidth source JARs are only downloaded by the buck
|
|
build where necessary to compile Java source into JavaScript using the
|
|
GWT compiler. Additional sources may be obtained, allowing Eclipse to
|
|
show documentation or dive into the implementation of a library JAR:
|
|
|
|
----
|
|
buck build download_sources
|
|
----
|
|
|
|
|
|
[[build]]
|
|
Building on the Command Line
|
|
----------------------------
|
|
|
|
|
|
Gerrit Development WAR File
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To build the Gerrit web application:
|
|
|
|
----
|
|
buck build gerrit
|
|
----
|
|
|
|
The output executable WAR will be placed in:
|
|
|
|
----
|
|
buck-out/gen/gerrit.war
|
|
----
|
|
|
|
|
|
Extension and Plugin API JAR Files
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To build the extension and plugin API JAR files:
|
|
|
|
----
|
|
buck build api
|
|
----
|
|
|
|
The output JAR files will be placed in:
|
|
|
|
----
|
|
buck-out/gen/{extension,plugin}-api.jar
|
|
----
|
|
|
|
Install {extension,plugin}-api to the local maven repository:
|
|
|
|
----
|
|
buck build api_install
|
|
----
|
|
|
|
Deploy {extension,plugin}-api to the remote maven repository
|
|
|
|
----
|
|
buck build api_deploy
|
|
----
|
|
|
|
The type of the repo is induced from the Gerrit version name, i.e.
|
|
* 2.8-SNAPSHOT: shapshot repo
|
|
* 2.8: release repo
|
|
|
|
Plugins
|
|
~~~~~~~
|
|
|
|
To build all core plugins:
|
|
|
|
----
|
|
buck build plugins:core
|
|
----
|
|
|
|
The output JAR files for individual plugins will be placed in:
|
|
|
|
----
|
|
buck-out/gen/plugins/<name>/<name>.jar
|
|
----
|
|
|
|
The JAR files will also be packaged in:
|
|
|
|
----
|
|
buck-out/gen/plugins/core.zip
|
|
----
|
|
|
|
To build a specific plugin:
|
|
|
|
----
|
|
buck build plugins/<name>
|
|
----
|
|
|
|
The output JAR file will be be placed in:
|
|
|
|
----
|
|
buck-out/gen/plugins/<name>/<name>.jar
|
|
----
|
|
|
|
Note that when building an individual plugin, the `core.zip` package
|
|
is not regenerated.
|
|
|
|
|
|
[[tests]]
|
|
Running Unit Tests
|
|
------------------
|
|
|
|
To run all tests including acceptance tests:
|
|
|
|
----
|
|
buck test --all
|
|
----
|
|
|
|
To exclude slow tests:
|
|
|
|
----
|
|
buck test --all --exclude slow
|
|
----
|
|
|
|
To run a specific test, e.g. the acceptance test
|
|
`com.google.gerrit.acceptance.git.HttpPushForReviewIT`:
|
|
|
|
----
|
|
buck test //gerrit-acceptance-tests/src/test/java/com/google/gerrit/acceptance/git:HttpPushForReviewIT
|
|
----
|
|
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
Dependency JARs are normally downloaded automatically, but Buck can inspect
|
|
its graph and download any missing JAR files. This is useful to enable
|
|
subsequent builds to run without network access.
|
|
|
|
Force a download of dependency JARs by building the `download` target:
|
|
|
|
----
|
|
buck build download
|
|
----
|
|
|
|
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:
|
|
|
|
----
|
|
maven_jar(
|
|
name = 'gwtorm',
|
|
id = 'gwtorm:gwtorm:42',
|
|
license = 'Apache2.0',
|
|
repository = MAVEN_LOCAL,
|
|
)
|
|
----
|
|
|
|
|
|
Caching Build Results
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Build results can be locally cached, saving rebuild time when
|
|
switching between Git branches. Buck's documentation covers
|
|
caching in link:http://facebook.github.io/buck/concept/buckconfig.html[buckconfig].
|
|
The trivial case using a local directory is:
|
|
|
|
----
|
|
cat >.buckconfig.local <<EOF
|
|
[cache]
|
|
mode = dir
|
|
dir = buck-cache
|
|
EOF
|
|
----
|
|
|
|
|
|
Build Process Switch Exit Criteria
|
|
----------------------------------
|
|
|
|
The switch to Buck is an experimental process. Buck will become the
|
|
primary build for Gerrit only when the following conditions are met.
|
|
|
|
1. Windows support.
|
|
+
|
|
Facebook has an intern who will be working on this (summer 2013).
|
|
|
|
2. Bootstrap and stable version support.
|
|
+
|
|
From a fresh Gerrit clone on a machine without Buck (but with some
|
|
reasonable subset of Buck's dependencies, e.g. Python 2.7), a new
|
|
Gerrit developer should be able to set up and start building with
|
|
Buck by running approximately one command. There should also be some
|
|
idea of a "stable" version of Buck, even if we just tie our build
|
|
to specific known-good SHAs. Binary distributions are another plus,
|
|
which I believe the Buck team has planned.
|
|
|
|
3. Shawn's Buck fork merged upstream.
|
|
+
|
|
Shawn has a link:https://gerrit.googlesource.com/buck/+log/github-master..master[fork of Buck]
|
|
with some patches necessary to build Gerrit and run its unit tests.
|
|
These patches (or their equivalents) must be in the upstream Buck tree.
|
|
|
|
4. Fix all incidental issues.
|
|
+
|
|
Things come up that don't work. Martin just ran out of file
|
|
descriptors, which sounds like an upstream bug.
|
|
+
|
|
There should be a consensus that new bugs like this in upstream
|
|
Buck are not constantly being introduced.
|
|
|
|
5. Support development of custom plugins.
|
|
+
|
|
There are three different alternatives for custom plugins:
|
|
+
|
|
The first is to build with BUCK in tree; your plugin builds against
|
|
whatever version of Gerrit you have the sources checked out for. This
|
|
is the simplest method on master right now. The BUCK definition is
|
|
only a few lines of code and the rest "just works". But you are
|
|
working from a Gerrit source tree, which is maybe not the ideal way to
|
|
develop.
|
|
+
|
|
Another is to continue to use Maven. We just have to package the
|
|
archetypes to support creating a new plugin, but existing plugins can
|
|
develop against the API JAR(s) if they are installed into a Maven
|
|
repository. tools/deploy_api.sh is how we did this for release
|
|
versions of Gerrit. Something similar probably still be used with BUCK
|
|
to publish the precompiled JARs. (Note: this is partially done with the
|
|
target: `buck build api_install`; after issuing this command the new API
|
|
version can be consumed by Maven driven custom plugins).
|
|
+
|
|
The third option is to support a BUCK based plugin build outside of
|
|
the Gerrit tree. This is harder because there is functionality
|
|
developed as macros in the Gerrit tree that plugins would want to use
|
|
(e.g. gerrit_plugin rule).
|
|
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|