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.

Clone the git and build it:

----
  git clone https://gerrit.googlesource.com/buck
  cd buck
  ant
----

Add the buck executable's location to the system path:


Linux
~~~~~

----
  PATH="`pwd`/bin:$PATH"
----


Mac OS
~~~~~~

----
  PATH="`pwd`/bin:/System/Library/Frameworks/JavaVM.framework/Versions/Current/Commands:$PATH"
----


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

If the code doesn't compile and an updated classpath is needed, the configs
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
----


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

Currently there is no way to download dependencies other than over an HTTP
connection from the source sites (Maven Central and the Gerrit storage
bucket).  It is not yet possible to use, for example, a corporate Nexus
proxy.

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


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]