Documentation/dev-buck.txt

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


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.  Do not import any of the other Maven
based projects.

Expand the `gerrit` project, right-click on the `buck-out` folder, select
'Properties', and then under 'Attributes' check 'Derived'.


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


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


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.


Running Unit Tests
------------------

To run all tests including acceptance tests:

----
  buck test --all
----

To exclude slow tests:

----
  buck test --all -e slow
----


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


Build Process Switch Exit Criteria
----------------------------------

The switch to Buck is an experimental process. Buck will become the
primary build for Gerrit (and link:dev-maven.html[Maven support]
removed) 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. Eclipse support.
+
Much of this is already there. The build needs to be at least as
reliable as it is under Maven. (This is kind of a low bar, due to
issues like Maven not handling generated Prolog source files or
recompiling the GWT source.)

4. Build without Internet access.
+
Currently dependencies are downloaded directly from Maven Central
and Gerrit's Google Cloud Storage bucket. In some environments
build systems do not have direct network access. It must be possible
for a developer to swap out the upstream Maven Central URL with an
internal Maven mirror, or to supply all of the JARs themselves.

5. 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.

6. 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.


GERRIT
------
Part of link:index.html[Gerrit Code Review]