src/main/resources/Documentation/build.md

# Build

The @PLUGIN@ plugin can be built in-tree in Gerrit's `/plugins` path.

The `plugins/external_plugin_deps.bzl` file will need to be updated to match
or contain `@PLUGIN@/external_plugin_deps.bzl`.

```
git clone --recursive https://gerrit.googlesource.com/gerrit
cd gerrit
git clone "https://gerrit.googlesource.com/plugins/@PLUGIN@" plugins/@PLUGIN@
ln -sf plugins/@PLUGIN@/external_plugin_deps.bzl plugins/.
bazelisk build plugins/@PLUGIN@
```

The output is created in

```
gerrit/bazel-bin/plugins/@PLUGIN@/@PLUGIN@.jar
```

The @PLUGIN@ plugin requires the global-refdb libModule to be available in
the site/lib directory. Instructions for building the global-refdb libModule
can be found [here](https://gerrit.googlesource.com/modules/global-refdb/).

## Eclipse project setup

This project can be imported into the Eclipse IDE:

- Add the plugin name to the `CUSTOM_PLUGINS_TEST_DEPS`
set in Gerrit core in `tools/bzl/plugins.bzl`,
- execute:

```
./tools/eclipse/project.py
```

## Run tests

The tests require a spanner service where the refdb will be created. The spanner
service may be a real spanner service in GCP or a locally running docker based
emulator.

### Running tests using a real spanner service

In this case we have to provide an GCP service account key and the instance name
under which the test refdb will be found or created. This is done by passing two
environment variables `GOOGLE_APPLICATION_CREDENTIALS` and `SPANNER_INSTANCE`.

If `SPANNER_DATABASE` environment variable is also specified, then a database
with that name will be used for testing. If a database with that name does not
exist it will be created. This database will not be dropped when the test run
finishes, leaving it ready for a next test run.
Using this option is recommended as database creation and especially schema
initialization is known to take a very long time.

If `SPANNER_DATABASE` environment variable is not specified then a new database
will be created for this test run and will be dropped when the test run
finishes.

```
bazelisk test \
  --test_env='GOOGLE_APPLICATION_CREDENTIALS=/path/to/the/key.json' \
  --test_env='SPANNER_INSTANCE=test-instance' \
  [--test_env='SPANNER_DATABASE=test-global-refdb'] \
  --test_tag_filters=@PLUGIN@ //...
```

Note that instead of using the `--test_tag_filters=@PLUGIN@ //...` we can also
pass a different test target `//plugins/@PLUGIN@/...`:

```
bazelisk test \
  --test_env='GOOGLE_APPLICATION_CREDENTIALS=/path/to/the/key.json' \
  --test_env='SPANNER_INSTANCE=test-instance' \
  [--test_env='SPANNER_DATABASE=test-global-refdb'] \
  //plugins/@PLUGIN@/...
```

### Running tests using a local docker based spanner emulator

This use case requires docker to be installed and running on the machine running
the tests. A container running spanner will be created automatically by the
tests.

The absence of the `GOOGLE_APPLICATION_CREDENTIALS` env variable means that the tests
will create local spanner emulator.

```
bazelisk test //plugins/@PLUGIN@/...
```

### MacOS specifics when using docker based spanner emulator

On MacOS you may need to access the docker daemon via TCP.

Run [socat](https://linux.die.net/man/1/socat) to expose the docker daemon socket via TCP

```
socat TCP-LISTEN:2375,fork UNIX-CONNECT:/var/run/docker.sock
```

Execute the tests over TCP

```
bazelisk test --test_env='DOCKER_HOST=tcp://127.0.0.1:2375' //plugins/@PLUGIN@/...
```

### Debugging tests

```
bazelisk test --test_output=streamed //plugins/@PLUGIN@/...
```

If necessary increase log levels in `src/test/resources/log4j.properties`
to trace testcontainers and docker java API.

### Tracing traffic to docker daemon

If you face issue you can trace traffic to the docker daemon using
[socat](https://linux.die.net/man/1/socat) exposing the docker daemon via TCP.

Run socat to log diagnostics and show the traffic to the docker daemon

```
socat -dd -v TCP-LISTEN:2375,fork UNIX-CONNECT:/var/run/docker.sock
```

Execute the tests over TCP

```
bazelisk test --test_env='DOCKER_HOST=tcp://127.0.0.1:2375' //plugins/@PLUGIN@/...
```

[Back to @PLUGIN@ documentation index][index]

[index]: index.html