# Gerrit Code Review - Building with Buck

version v2.8.3-1-g15771a8

## 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

If you don’t have a `bin/` directory in your home directory, create one:

      mkdir ~/bin

Add the `~/bin` folder to the path:

      PATH=~/bin:$PATH

Note that the buck executable needs to be available in all shell sessions, so also make sure it is appended to the path globally.

Add a symbolic link in `~/bin` to the buck executable:

      ln -s `pwd`/bin/buck ~/bin/

Verify that `buck` is accessible:

      which buck

If you plan to use the Buck daemon add a symbolic link in `~/bin` to the buckd executable:

      ln -s `pwd`/bin/buckd ~/bin/

To enable autocompletion of buck commands, install the autocompletion script from `./scripts/bash_completion` in the buck project. Refer to the script’s header comments for installation instructions.

## Eclipse Integration

### Generating the Eclipse Project

Create the Eclipse project:

      tools/eclipse/project.py

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 `tools/eclipse/project.py`.

### Refreshing the Classpath

If an updated classpath is needed, the Eclipse project can be refreshed and missing dependency JARs can be downloaded:

      tools/eclipse/project.py

### 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:

      tools/eclipse/project.py --src

## 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`: snapshot 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.

### Documentation

To build the documentation:

      buck build docs

The generated html files will be placed in:

      buck-out/gen/Documentation/html__tmp/Documentation

The html files will also be bundled into `html.zip` in this location:

      buck-out/gen/Documentation/html.zip

### Gerrit Release WAR File

To build the release of the Gerrit web application, including documentation and all core plugins:

      buck build release

The output release WAR will be placed in:

      buck-out/gen/release.war

## 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:

      tools/download_all.py

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 buckconfig. The trivial case using a local directory is:

      cat >.buckconfig.local <<EOF
      [cache]
        mode = dir
        dir = buck-cache
      EOF

### Using Buck daemon

Buck ships with a daemon command `buckd`, which uses the Nailgun protocol for running Java programs from the command line without incurring the JVM startup overhead.

Using a Buck daemon can save significant amounts of time as it avoids the overhead of starting a Java virtual machine, loading the buck class files and parsing the build files for each command.

It is safe to run several buck daemons started from different project directories and they will not interfere with each other. Buck’s documentation covers daemon in buckd.

The trivial use case is to run `buckd` from the project’s root directory and run `buck` as usual:

      buckd
      buck build gerrit
      Using buckd.
      [-] PARSING BUILD FILES...FINISHED 0.6s
      [-] BUILDING...FINISHED 0.2s

### Override Buck’s settings

User-specific configuration can be placed in one of the following files: `/etc/buck.conf`, `$HOME/.buck/buck.conf` or `$HOME/.buckrc`.

For example to override Buck’s default 1GB heap size:

      cat > $HOME/.buckrc <<EOF
      export BUCK_EXTRA_JAVA_ARGS="\
      -XX:MaxPermSize=512m \
      -Xms8000m \
      -Xmx16000m"
      EOF

Or to debug BUCK, set `BUCK_DEBUG_MODE` to anything non-empty, then connect to port 8888:

      cat > $HOME/.buckrc <<EOF
      export BUCK_DEBUG_MODE="yes"
      EOF

Part of Gerrit Code Review