Documentation/dev-buck.txt - gerrit - Git at Google

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

 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.


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

	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.


	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]