From d0525a7ced73a7cc87b202dd10896a6b400e129e Mon Sep 17 00:00:00 2001
From: David Pursehouse <david.pursehouse@sonymobile.com>
Date: Thu, 9 May 2013 17:49:34 +0100
Subject: [PATCH] Add documentation of the buck build

The content of the documentation is copied mostly verbatim from
the commit message of fd6bb9f which is the commit that adds the
buck build configuration.

Change-Id: Id2b29be5325f922024cdbbd6ae299161b7cfb0bf
---
 Documentation/dev-buck.txt   | 138 +++++++++++++++++++++++++++++++++++
 Documentation/dev-readme.txt |   6 +-
 2 files changed, 141 insertions(+), 3 deletions(-)
 create mode 100644 Documentation/dev-buck.txt

diff --git a/Documentation/dev-buck.txt b/Documentation/dev-buck.txt
new file mode 100644
index 0000000000..be72bcc591
--- /dev/null
+++ b/Documentation/dev-buck.txt
@@ -0,0 +1,138 @@
+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
+builds to run without network access.
+
+Force a download of dependency JARs by building the `download` target:
+
+----
+  buck build download
+----
+
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
diff --git a/Documentation/dev-readme.txt b/Documentation/dev-readme.txt
index 1b285c2c4f..b503e1f5b9 100644
--- a/Documentation/dev-readme.txt
+++ b/Documentation/dev-readme.txt
@@ -1,9 +1,9 @@
 Gerrit Code Review - Developer Setup
 ====================================
 
-Apache Maven is needed to compile the code, and a SQL database
-to house the review metadata.  H2 is recommended for development
-databases, as it requires no external server process.
+Apache Maven or Facebook Buck is needed to compile the code, and a
+SQL database to house the review metadata.  H2 is recommended for
+development databases, as it requires no external server process.
 
 
 Getting the Source