ebeb15460c
Asciidoc may fail to render link attributes for external links supposed to open in a new window correctly. This change adds :linkattrs: to the beginning of such files to force parsing link attributes correctly. Bug: Issue 12068 Change-Id: If18be60de646ff78f672239dd4fa435fd4fd92ab
240 lines
6.5 KiB
Plaintext
240 lines
6.5 KiB
Plaintext
:linkattrs:
|
|
= Gerrit Code Review: Developer Setup
|
|
|
|
To build a developer instance, you'll need link:https://bazel.build/[Bazel,role=external,window=_blank] to
|
|
compile the code.
|
|
|
|
== Git Setup
|
|
|
|
[[clone]]
|
|
=== Getting the Source
|
|
|
|
Create a new client workspace:
|
|
|
|
----
|
|
git clone --recurse-submodules https://gerrit.googlesource.com/gerrit
|
|
cd gerrit
|
|
----
|
|
|
|
The `--recurse-submodules` option is needed on `git clone` to ensure that the
|
|
core plugins, which are included as git submodules, are also cloned.
|
|
|
|
=== Switching between branches
|
|
|
|
When using `git checkout` without `--recurse-submodules` to switch between
|
|
branches, submodule revisions are not altered, which can result in:
|
|
|
|
* Incorrect or unneeded plugin revisions.
|
|
* Missing plugins.
|
|
|
|
After you switch branches, ensure that you have the correct versions of
|
|
the submodules.
|
|
|
|
CAUTION: If you store Eclipse or IntelliJ project files in the Gerrit source
|
|
directories, do *_not_* run `git clean -fdx`. Doing so may remove untracked files and damage your project. For more information, see
|
|
link:https://git-scm.com/docs/git-clean[git-clean,role=external,window=_blank].
|
|
|
|
Run the following:
|
|
|
|
----
|
|
git submodule update
|
|
git clean -ffd
|
|
----
|
|
|
|
[[compile_project]]
|
|
== Compiling
|
|
|
|
For details, see <<dev-bazel#,Building with Bazel>>.
|
|
|
|
|
|
== Testing
|
|
|
|
[[tests]]
|
|
=== Running the acceptance tests
|
|
|
|
Gerrit contains acceptance tests that validate the Gerrit daemon via REST, SSH,
|
|
and the Git protocol.
|
|
|
|
A new review site is created for each test and the Gerrit daemon is
|
|
then started on that site. When the test is completed, the Gerrit daemon is
|
|
shut down.
|
|
|
|
For instructions on running the acceptance tests with Bazel,
|
|
see <<dev-bazel#tests,Running Unit Tests with Bazel>>.
|
|
|
|
|
|
== Local server
|
|
|
|
[[init]]
|
|
=== Site Initialization
|
|
|
|
After you compile the project <<compile_project,(above)>>, run the Gerrit
|
|
`init`
|
|
command to create a test site:
|
|
|
|
----
|
|
export GERRIT_SITE=~/gerrit_testsite
|
|
$(bazel info output_base)/external/local_jdk/bin/java \
|
|
-jar bazel-bin/gerrit.war init --batch --dev -d $GERRIT_SITE
|
|
----
|
|
|
|
[[special_bazel_java_version]]
|
|
NOTE: You must use the same Java version that Bazel used for the build, which
|
|
is available at `$(bazel info output_base)/external/local_jdk/bin/java`.
|
|
|
|
This command takes two parameters:
|
|
|
|
* `--batch` assigns default values to several Gerrit configuration
|
|
options. To learn more about these options, see
|
|
link:config-gerrit.html[Configuration].
|
|
* `--dev` configures the Gerrit server to use the authentication
|
|
option, `DEVELOPMENT_BECOME_ANY_ACCOUNT`, which enables you to
|
|
switch between different users to explore how Gerrit works. To learn more
|
|
about setting up Gerrit for development, see
|
|
link:dev-readme.html[Gerrit Code Review: Developer Setup].
|
|
|
|
After initializing the test site, Gerrit starts serving in the background. A
|
|
web browser displays the Start page.
|
|
|
|
On the Start page, you can:
|
|
|
|
. Log in as the account you created during the initialization process.
|
|
. Register additional accounts.
|
|
. Create projects.
|
|
|
|
To shut down the daemon, run:
|
|
|
|
----
|
|
$GERRIT_SITE/bin/gerrit.sh stop
|
|
----
|
|
|
|
|
|
[[localdev]]
|
|
=== Working with the Local Server
|
|
|
|
To create more accounts on your development instance:
|
|
|
|
. Click 'become' in the upper right corner.
|
|
. Select 'Switch User'.
|
|
. Register a new account.
|
|
. link:user-upload.html#ssh[Configure your SSH key].
|
|
|
|
Use the `ssh` protocol to clone from and push to the local server. For
|
|
example, to clone a repository that you've created through the admin
|
|
interface, run:
|
|
|
|
----
|
|
git clone ssh://username@localhost:29418/projectname
|
|
----
|
|
|
|
To use the `HTTP` protocol, run:
|
|
|
|
----
|
|
git clone http://username@localhost:8080/projectname
|
|
----
|
|
|
|
The default password for user `admin` is `secret`. You can regenerate a
|
|
password in the UI under User Settings -- HTTP credentials. The password can be
|
|
stored locally to avoid retyping it:
|
|
|
|
----
|
|
git config --global credential.helper store
|
|
git pull
|
|
----
|
|
|
|
To create changes as users of Gerrit would, run:
|
|
|
|
----
|
|
git push origin HEAD:refs/for/master
|
|
----
|
|
|
|
[[run_daemon]]
|
|
=== Running the Daemon
|
|
|
|
The daemon can be launched directly from the build area, without
|
|
copying to the test site:
|
|
|
|
----
|
|
$(bazel info output_base)/external/local_jdk/bin/java \
|
|
-jar bazel-bin/gerrit.war daemon -d $GERRIT_SITE \
|
|
--console-log
|
|
----
|
|
|
|
NOTE: To learn why using `java -jar` isn't sufficient, see
|
|
<<special_bazel_java_version,this explanation>>.
|
|
|
|
To debug the Gerrit server of this test site:
|
|
|
|
. Open a debug port (such as port 5005). To do so, insert the following code
|
|
immediately after `-jar` in the previous command. To learn how to attach
|
|
IntelliJ, see <<dev-intellij#remote-debug,Debugging a remote Gerrit server>>.
|
|
|
|
----
|
|
-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005
|
|
----
|
|
|
|
=== Running the Daemon with Gerrit Inspector
|
|
|
|
link:dev-inspector.html[Gerrit Inspector] is an interactive scriptable
|
|
environment you can use to inspect and modify the internal state of the system.
|
|
|
|
Gerrit Inspector appears on the system console whenever the system starts.
|
|
Leaving the Inspector shuts down the Gerrit instance.
|
|
|
|
To troubleshoot, the Inspector enables interactive work as well as running of
|
|
Python scripts.
|
|
|
|
To start the Inspector, add the '-s' option to the daemon start command:
|
|
|
|
----
|
|
$(bazel info output_base)/external/local_jdk/bin/java \
|
|
-jar bazel-bin/gerrit.war daemon -d $GERRIT_SITE -s
|
|
----
|
|
|
|
NOTE: To learn why using `java -jar` isn't sufficient, see
|
|
<<special_bazel_java_version,this explanation>>.
|
|
|
|
Inspector examines Java libraries, loads the initialization scripts, and
|
|
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
|
|
>>>
|
|
----
|
|
|
|
When the Inspector is enabled, you can use Gerrit as usual and all
|
|
interfaces (including HTTP and SSH) are available.
|
|
|
|
CAUTION: When using the Inspector, be careful not to modify the internal state
|
|
of the system.
|
|
|
|
|
|
== Setup for backend developers
|
|
|
|
=== Configuring Eclipse
|
|
|
|
To use the Eclipse IDE for development, see
|
|
link:dev-eclipse.html[Eclipse Setup].
|
|
|
|
To configure the Eclipse workspace with Bazel, see
|
|
link:dev-bazel.html#eclipse[Eclipse integration with Bazel].
|
|
|
|
=== Configuring IntelliJ IDEA
|
|
|
|
See <<dev-intellij#,IntelliJ Setup>> for details.
|
|
|
|
== Setup for frontend developers
|
|
See link:https://gerrit.googlesource.com/gerrit/+/master/polygerrit-ui/README.md[Frontend Developer Setup].
|
|
|
|
|
|
GERRIT
|
|
------
|
|
Part of link:index.html[Gerrit Code Review]
|
|
|
|
SEARCHBOX
|
|
---------
|