Mario Fetka
5897512fd9
Complete the current IMAP, POP3, SMTP and proxy protocol work; add the validated setup and administration UI, packaging examples, tests, and maintained roadmap/documentation for the 0.7 development line.
92 lines
3.2 KiB
Markdown
92 lines
3.2 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.
|
|
|
|
## 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.
|