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

## 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 created. This is done by passing two
environment variables `GOOGLE_APPLICATION_CREDENTIALS` and `SPANNER_INSTANCE`:

```
bazelisk test \
  --test_env='GOOGLE_APPLICATION_CREDENTIALS=/path/to/the/key.json' \
  --test_env='SPANNER_INSTANCE=test-instance' \
  --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' \
  //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