Mario Fetka
121 lines
4.4 KiB
Markdown
121 lines
4.4 KiB
Markdown
# 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. The replacement is atomic,
|
|
so an invalid or incomplete installed snapshot leaves the previous cache in
|
|
place and makes the command fail.
|
|
|
|
## 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.
|