# How to build and test

Use an authorised xitstash checkout with Java 21 or later, Clojure CLI and Babashka.
Install `cljfmt` and `clj-kondo` for formatting and lint.
The library runs on Java 17, but the test-only Closure Compiler requires Java 21.

## Run the normal checks

```shell
bb ci
```

This compiles Java with warnings treated as errors, runs the unit tests and checks Clojure formatting and lint.
Use `bb qa` to apply formatting before lint and tests.

To run one test namespace:

```shell
bb test --focus ol.xitstash.multiformats-interop-test
```

## Run adapter tests

Supply local xitdb-clj and Yggdrasil checkouts.
The tested revisions are:

| Project | Revision |
| --- | --- |
| xitdb-clj | `b9ba2598f6b3a33198b870921382c8b59ff825c6` |
| Yggdrasil | `0177619468885c3521521c8557f54f0ad6b127f0` |
| xitdb-java | Maven version `0.48.0` |

The Yggdrasil revision contains an unpublished xitdb adapter.
A released Yggdrasil dependency does not supply it.
The checkout must provide `yggdrasil.adapters.xitdb` with `create`, `read!`, `transact!` and `compact!`.

Replace both paths and run:

```shell
bb javac
clojure -Sdeps '{:deps {codeboost/xitdb-clj {:local/root "/path/to/xitdb-clj"}
                        org.replikativ/yggdrasil {:local/root "/path/to/yggdrasil"}}}' \
  -M:kaocha:integration --config-file integration/tests.edn
```

This runs unit and integration suites.
Append `:integration` to select only the integration suite.

The adapter tests cover mixed application and binary writes, rollback, branch isolation, historical reads and compaction/reopen.
They do not cover ClojureScript, generic catalog merging or selective erasure across adapter history.
Default CI and Nix package builds do not run these optional tests.

## Run measurements

```shell
bb bench
```

For a fresh-JVM memory check on Linux:

```shell
bb javac
clojure -J-Xmx128m -M:bench --memory small
clojure -J-Xmx128m -M:bench --memory large
```

See [Performance measurements](measurements.adoc) for conditions and interpretation.

## Generate documentation

```shell
bb gen-docs
```

This copies `README.adoc` into the component index, generates the public API reference from `ol.xitstash` and writes `doc/manifest.edn`.
Edit the README or source docstrings rather than their generated pages.
Edit other reader pages under `doc/modules/ROOT/pages/`.

Keep `AGENTS.md` and `docs/agents/` in Markdown.

## Build a development jar

```shell
bb jar
```

The jar under `target/` contains Clojure source, Java classes and attribution resources.
Do not publish it while the project license is unspecified.