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

 If you plan to use the link:#buck-daemon[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]]
 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
 ----


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

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

 [[tests]]
 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:

 [source,python]
 ----
  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 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
 ----

 [[buck-daemon]]
 Using Buck daemon
 ~~~~~~~~~~~~~~~~~

 Buck ships with a daemon command `buckd`, which uses the
 link:https://github.com/martylamb/nailgun[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 http://facebook.github.io/buck/command/buckd.html[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
 ----

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

	If you plan to use the link:#buck-daemon[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]]
	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
	----


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

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

	[[tests]]
	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:

	[source,python]
	----
	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 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
	----

	[[buck-daemon]]
	Using Buck daemon
	~~~~~~~~~~~~~~~~~

	Buck ships with a daemon command `buckd`, which uses the
	link:https://github.com/martylamb/nailgun[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 http://facebook.github.io/buck/command/buckd.html[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
	----

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