opendev/gerrit
Code Issues Proposed changes
gerrit/Documentation/dev-buck.txt
David Ostrovsky 2536d06da0 Buck: Support plugin own Maven repositories 
Currently only predefined Maven repositories are supported by Buck maven_jar.
Additional logic exists to redirect to a local repository mirror.

Current implementation relies on the repository name matching between repo
passed to maven_jar and redirect definition defined in local.properties that
is not under Git control.

This change extends that by allowing to pass not only the repo name but the
complete URL to maven_jar. The augmented implementation checks if it is a
known Maven repository: if it is, then the behavious is unchanged, if not,
then the passed URL is used.

As result plugin's can use custom Maven repositories:

  GERRIT_FORGE = 'http://gerritforge.com/snapshot'

  maven_jar(
    name = 'gitblit',
    id = 'com.gitblit:gitblit:1.4.0',
    sha1 = '1b130dbf5578ace37507430a4a523f6594bf34fa',
    license = 'Apache2.0',
    repository = GERRIT_FORGE,
  )

Plugin owned Maven repositories can also be rewritten in local.properties.
To achieve that custom repository name must be passed to the maven_jar()
function, like known repositories, and the URL must be defined in
local.properties.

local.properties excerpt:

  download.GERRIT_FORGE = http://my.company.mirror/gerrit-forge

BUCK excerpt:

  GERRIT_FORGE = 'GERRIT_FORGE:'

  maven_jar(
    name = 'gitblit',
    id = 'com.gitblit:gitblit:1.4.0',
    sha1 = '1b130dbf5578ace37507430a4a523f6594bf34fa',
    license = 'Apache2.0',
    repository = GERRIT_FORGE,
  )

Python unit test can be executed with other Java unit tests:

  buck test tools:python_tests
Change-Id: Ib31d51f0884b1ca1a07b6492f861f404db115946
2013-11-18 01:12:09 +01:00

441 lines
9.5 KiB
Plaintext
Raw Blame History

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>:<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.
Additional plugins with BUCK files can be added to the build
environment by cloning the source repository into the plugins
subdirectory:
----
git clone https://gerrit.googlesource.com/plugins/<name> plugins/<name>
echo /plugins/<name> >>.git/info/exclude
----
Additional plugin sources will be automatically added to Eclipse the
next time project.py is run:
----
tools/eclipse/project.py
----
[[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,
)
----
Building against artifacts from custom Maven repositories
---------------------------------------------------------
To build against custom Maven repositories, two modes of operations are
supported: with rewrite in local.properties and without.
Without rewrite the URL of custom Maven repository can be directly passed
to the maven_jar() function:
[source,python]
----
GERRIT_FORGE = 'http://gerritforge.com/snapshot'
maven_jar(
name = 'gitblit',
id = 'com.gitblit:gitblit:1.4.0',
sha1 = '1b130dbf5578ace37507430a4a523f6594bf34fa',
license = 'Apache2.0',
repository = GERRIT_FORGE,
)
----
When the custom URL has to be rewritten, then the same logic as with Gerrit
known Maven repository is used: Repo name must be defined that matches an entry
in local.properties file:
----
download.GERRIT_FORGE = http://my.company.mirror/gerrit-forge
----
And corresponding BUCK excerpt:
[source,python]
----
GERRIT_FORGE = 'GERRIT_FORGE:'
maven_jar(
name = 'gitblit',
id = 'com.gitblit:gitblit:1.4.0',
sha1 = '1b130dbf5578ace37507430a4a523f6594bf34fa',
license = 'Apache2.0',
repository = GERRIT_FORGE,
)
----
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]
SEARCHBOX
---------
View Git Blame Copy Permalink