# Development and testing

Bongo uses CMake throughout the source tree. Individual libraries, agents,
applications, tests, manual pages, and packaging rules keep their own
`CMakeLists.txt`; the root file coordinates them.

## Build

Use an out-of-tree build:

```sh
cmake -S . -B build \
    -DCMAKE_BUILD_TYPE=Debug \
    -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build -j
ctest --test-dir build --output-on-failure
```

GCC and Clang are supported. To keep warnings actionable, fix their cause in
the code instead of adding flags which hide them. Portable code must not
assume that pointers, `long`, or `size_t` are 64-bit or that the host is
x86-64; 32-bit and ARM cross-builds are release validation targets.

Important cache variables include `BONGO_USER`, `BONGO_STATE_DIR`,
`BONGO_CONFIG_DIR`, `SYSCONF_INSTALL_DIR`, `BONGO_TZDATA_DIR`, and
`CONN_TRACE`. Connection tracing may expose plaintext or already-decrypted
credentials and message data; enable it only in an isolated test environment.

## Sanitizers and debuggers

An AddressSanitizer/UndefinedBehaviorSanitizer build can be configured with:

```sh
cmake -S . -B build-asan \
    -DCMAKE_BUILD_TYPE=Debug \
    -DCMAKE_C_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer" \
    -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined" \
    -DCMAKE_SHARED_LINKER_FLAGS="-fsanitize=address,undefined"
cmake --build build-asan -j
ctest --test-dir build-asan --output-on-failure
```

Run long-lived agents under GDB or a sanitizer only on an isolated instance
with disposable mail and credentials. ThreadSanitizer requires its own build;
do not combine it with AddressSanitizer. Leak checks need realistic protocol
sessions in addition to the unit tests.

## Staged installation and packages

Test installation paths without modifying the host:

```sh
DESTDIR=/tmp/bongo-stage cmake --install build
find /tmp/bongo-stage -print
```

For a `/usr` prefix, reject any staged `/usr/etc` or `/usr/var` path. Runtime
directories belong to tmpfiles or setup, not the package image.

Generate binary and source packages separately:

```sh
cpack --config build/CPackConfig.cmake
cpack --config build/CPackSourceConfig.cmake
```

Source packages are named `bongo-<version>` without a platform suffix such as
`-linux`. They contain the maintained Markdown documentation and exclude VCS
metadata and build trees.

## Timezone snapshot

Normal builds are reproducible and never download data. To refresh the
checked-in zone snapshot, unpack a reviewed IANA tzdata release, configure its
directory, and call the explicit target:

```sh
cmake -S . -B build-zoneinfo -DBONGO_TZDATA_DIR=/path/to/tzdata
cmake --build build-zoneinfo --target update-zoneinfo
```

Review the generated diff and calendar tests before committing it. The
`tzcache` administration command rebuilds the runtime cache from the installed
snapshot; it does not fetch a new upstream release.

## Source conventions

New C and C header files use the same licence/copyright header style as the
surrounding subsystem. Generated data and suffixless JSON configuration
templates do not need a C source header. Add focused tests beside the
subsystem's existing `tests` directory and register them with CTest.

## Collector protocol integration tests

The normal test suite has no Java dependency.  An optional integration test
uses the archived Apache-2.0-licensed `vtestmail-core` 1.0.0 artifact as an
in-memory POP3 and IMAP peer.  The artifact is test-only, its SHA-256 is
pinned by CMake, and it is never linked into or installed with Bongo.

Download the immutable Maven Central artifact and enable the fixture explicitly:

```sh
curl -fL \
  https://repo.maven.apache.org/maven2/net/markwalder/vtestmail-core/1.0.0/vtestmail-core-1.0.0.jar \
  -o /tmp/vtestmail-core-1.0.0.jar
cmake -S . -B build-vtestmail \
  -DBUILD_TESTING=ON \
  -DBONGO_VTESTMAIL_JAR=/tmp/vtestmail-core-1.0.0.jar
cmake --build build-vtestmail
ctest --test-dir build-vtestmail -R collector-vtestmail --output-on-failure
```

The test exercises authenticated POP3 and IMAP listing, fetching and deletion
over STLS/STARTTLS with certificate and hostname verification enabled.
vtestmail 1.0.0 does not implement the IMAP `UID SEARCH`, `UID FETCH` and
`UID STORE` subset needed by the Collector, so Bongo registers those three
minimal commands inside its isolated Java fixture.  The upstream jar remains
unchanged.