Documentation/dev-readme.txt

Gerrit Code Review - Developer Setup
====================================

Facebook Buck is needed to compile the code, and an SQL database to
house the review metadata. H2 is recommended for development
databases, as it requires no external server process.


Getting the Source
------------------

Create a new client workspace:

----
 git clone --recursive https://gerrit.googlesource.com/gerrit
 cd gerrit
----

The `--recursive` option is needed on `git clone` to ensure that
the core plugins, which are included as git submodules, are also
cloned.


Compiling
---------

For details on how to build the source code with Buck, refer to:
link:dev-buck.html#build[Building on the command line with Buck].


Switching between branches
--------------------------

When switching between branches with `git checkout`, be aware that
submodule revisions are not altered. This may result in the wrong
plugin revisions being present, unneeded plugins being present, or
expected plugins being missing.

After switching branches, make sure the submodules are at the correct
revisions for the new branch with the commands:

----
 git submodule update
 git clean -fdx
----


Configuring Eclipse
-------------------

To use the Eclipse IDE for development, please see
link:dev-eclipse.html[Eclipse Setup].

For details on how to configure the Eclipse workspace with Buck,
refer to: link:dev-buck.html#eclipse[Eclipse integration with Buck].


Mac OS X
--------

On Mac OS X ensure "Java For Mac OS X 10.5 Upate 4" (or later) has
been installed, and that `JAVA_HOME` is set to
"/System/Library/Frameworks/JavaVM.framework/Versions/1.6/Home".
Check the installed version by running `java -version` and looking
for 'build 1.6.0_13-b03-211'. Versions of Java 6 prior to this
version crash during the build due to a bug in the JIT compiler.


[[init]]
Site Initialization
-------------------

After compiling (above), run Gerrit's 'init' command to create a
testing site for development use:

----
 java -jar buck-out/gen/gerrit.war init -d ../test_site
----

Accept defaults by pressing Enter until 'init' completes, or add
the '--batch' command line option to avoid them entirely. It is
recommended to change the listen addresses from '*' to 'localhost' to
prevent outside connections from contacting the development instance.

The daemon will automatically start in the background and a web
browser will launch to the start page, enabling login via OpenID.

Shutdown the daemon after registering the administrator account
through the web interface:

----
 ../test_site/bin/gerrit.sh stop
----


Testing
-------


[[tests]]
Running the Acceptance Tests
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Gerrit has a set of integration tests that test the Gerrit daemon via
REST, SSH and the git protocol.

A new review site is created for each test and the Gerrit daemon is
started on that site. When the test has finished the Gerrit daemon is
shutdown.

For instructions on running the integration tests with Buck,
please refer to:
link:dev-buck.html#tests[Running integration tests with Buck].


Running the Daemon
~~~~~~~~~~~~~~~~~~

The daemon can be directly launched from the build area, without
copying to the test site:

----
 java -jar buck-out/gen/gerrit.war daemon -d ../test_site
----

Running the Daemon with Gerrit Inspector
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

link:dev-inspector.html[Gerrit Inspector] is an interactive scriptable
environment to inspect and modify internal state of the system.

This environment is available on the system console after
the system starts. Leaving the Inspector will shutdown the Gerrit
instance.

The environment allows interactive work as well as running of
Python scripts for troubleshooting.

Gerrit Inspect can be started by adding '-s' option to the
command used to launch the daemon:

----
 java -jar buck-out/gen/gerrit.war daemon -d ../test_site -s
----

Gerrit Inspector examines Java libraries first, then loads
its initialization scripts and then starts a command line
prompt on the console:

----
 Welcome to the Gerrit Inspector
 Enter help() to see the above again, EOF to quit and stop Gerrit
 Jython 2.5.2 (Release_2_5_2:7206, Mar 2 2011, 23:12:06)
 [OpenJDK 64-Bit Server VM (Sun Microsystems Inc.)] on java1.6.0 running for Gerrit 2.3-rc0-163-g01967ef
 >>>
----

With the Inspector enabled Gerrit can be used normally and all
interfaces (HTTP, SSH etc.) are available.

Care must be taken not to modify internal state of the system
when using the Inspector.

Querying the Database
~~~~~~~~~~~~~~~~~~~~~

The embedded H2 database can be queried and updated from the
command line. If the daemon is not currently running:

----
 java -jar buck-out/gen/gerrit.war gsql -d ../test_site
----

Or, if it is running and the database is in use, connect over SSH
using an administrator user account:

----
 ssh -p 29418 user@localhost gerrit gsql
----


[[debug-javascript]]
Debugging JavaScript
~~~~~~~~~~~~~~~~~~~~

When debugging browser specific issues add `?dbg=1` to the URL so the
resulting JavaScript more closely matches the Java sources. The debug
pages use the GWT pretty format, where function and variable names
match the Java sources.

----
 http://localhost:8080/?dbg=1
----

To use the GWT DETAILED style the package must be recompiled and
`?dbg=1` must be omitted from the URL:

----
 mvn package -Dgwt.style=DETAILED
----


Release Builds
--------------

To create a release build for a production server, or deployment
through the download site:

----
 ./tools/release.sh
----

If AsciiDoc isn't installed or is otherwise unavailable, the WAR
can still be built without the embedded documentation by passing
an additional flag:

----
 ./tools/release.sh --without-documentation
----


Client-Server RPC
-----------------

The client-server RPC implementation is gwtjsonrpc, not the stock RPC
system that comes with GWT. This buys us automatic XSRF protection.
It also makes all of the messages readable and writable by any JSON
implementation, facilitating "mashups" and 3rd party clients.

The programming API is virtually identical, except service interfaces
extend RemoteJsonService instead of RemoteService.


Why GWT?
--------

We like it. Plus we can write Java code once and run it both in
the browser and on the server side.


External Links
--------------

Google Web Toolkit:

* http://code.google.com/webtoolkit/download.html[Download]

Apache SSHD:

* http://mina.apache.org/sshd/[SSHD]

H2:

* http://www.h2database.com/[H2]
* http://www.h2database.com/html/grammar.html[SQL Reference]

PostgreSQL:

* http://www.postgresql.org/download/[Download]
* http://www.postgresql.org/docs/[Documentation]


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

SEARCHBOX
---------