bongo/docs/development.md

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:

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:

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:

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:

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:

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:

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.