docs: split context into layered, agent-oriented files
Replace the single file-structure.md with a stratified layout designed
for AI/agent skill consumption: tables and concrete identifiers over
prose, files loaded on demand, content separated by churn rate.
Layers:
- architecture/ stable structural reference (overview, source-map,
test-map, data-flow)
- patterns/ memory, commands, autocomplete, events, xmpp,
encryption, ui, plugins
- testing/ unit-tests, stubs, functional-tests, bench
- build/ local, docker, ci
- playbooks/ add-command, add-test, add-autocomplete,
add-event-handler, add-encryption
- gotchas.md append-only dated entries (seven seed entries)
- wip/ branch-specific notes; deleted on merge to master
Stable layers describe cproof on master only. In-flight feature
branches (currently feat/ai) get a single file under wip/.
INDEX.md is the entry map with churn labels; SKILL.md is the
always-loaded skill hint pointing to it.
This commit is contained in:
55
build/ci.md
Normal file
55
build/ci.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# CI
|
||||
|
||||
## Workflows
|
||||
|
||||
`.github/workflows/`:
|
||||
|
||||
| Workflow | Purpose |
|
||||
|---|---|
|
||||
| `ci-code.yml` | Build + unit tests across the Linux distro matrix. |
|
||||
| `ci-api-docs.yml` | API/plugin docs build check. |
|
||||
|
||||
Plus an OpenBSD pipeline at `.builds/openbsd.yml` (sourcehut-style builds).
|
||||
|
||||
## Distro matrix
|
||||
|
||||
The code CI runs across the Dockerfiles at repo root: Debian, Ubuntu,
|
||||
Fedora, Tumbleweed, Arch. Each job builds the matching image, mounts the
|
||||
checkout, and runs `autogen.sh && configure && make && make check`.
|
||||
|
||||
## Log naming
|
||||
|
||||
CI logs in this project are named:
|
||||
|
||||
```
|
||||
ci-code-Linux (arch)-NNNN.log
|
||||
```
|
||||
|
||||
— where `arch` is the distro flavour (debian, ubuntu, fedora, tumbleweed,
|
||||
arch) and `NNNN` is the run number. Use the distro name to pick the right
|
||||
log when triaging matrix failures.
|
||||
|
||||
## Known matrix-specific notes
|
||||
|
||||
- **Arch (`Dockerfile.arch`):** Pikaur in the image was hit by a duplicated-flag
|
||||
failure (cf. cproof commit `0722dc9e3`). If `Dockerfile.arch` changes,
|
||||
re-check the Pikaur invocation.
|
||||
- **OpenBSD (`.builds/openbsd.yml`):** runs on sourcehut, not GitHub. Failures
|
||||
there don't appear in the GitHub PR check list.
|
||||
|
||||
## Reproducing a CI failure locally
|
||||
|
||||
1. Identify the failing distro from the log name.
|
||||
2. Build the matching Dockerfile locally — see `build/docker.md`.
|
||||
3. Run the same `autogen && configure && make && make check` chain inside the
|
||||
container.
|
||||
4. Compare versions of any drifting dependency between the image and the CI
|
||||
image (`apt list --installed` or equivalent inside both).
|
||||
|
||||
## What CI does not run
|
||||
|
||||
- Functional tests (`tests/functionaltests/`) — require a test XMPP server.
|
||||
- Benches (`tests/bench/`) — not part of CI.
|
||||
|
||||
If you need either, run them locally inside the Docker image — see
|
||||
`testing/functional-tests.md` and `testing/bench.md`.
|
||||
75
build/docker.md
Normal file
75
build/docker.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# Docker build
|
||||
|
||||
Canonical build environment. **Use this; do not build on the host.**
|
||||
|
||||
## Dockerfiles
|
||||
|
||||
All at repo root:
|
||||
|
||||
| File | Base | Purpose |
|
||||
|---|---|---|
|
||||
| `Dockerfile.debian` | `debian:testing` | **Canonical.** Mirrors CI for Linux. |
|
||||
| `Dockerfile.ubuntu` | `ubuntu` | Alternate Linux for compatibility checks. |
|
||||
| `Dockerfile.fedora` | `fedora` | Fedora compatibility. |
|
||||
| `Dockerfile.tumbleweed` | `opensuse/tumbleweed` | openSUSE compatibility. |
|
||||
| `Dockerfile.arch` | `archlinux` | Arch CI matrix. |
|
||||
|
||||
Default: `Dockerfile.debian` for local dev, build, and `make check`.
|
||||
|
||||
## Build the image
|
||||
|
||||
```sh
|
||||
docker build -t cproof-debian -f Dockerfile.debian .
|
||||
```
|
||||
|
||||
`Dockerfile.debian` installs the autotools toolchain plus all optional
|
||||
dependencies (cmocka, libsignal-protocol-c, libotr5, gpgme, libcurl,
|
||||
libmicrohttpd, libnotify, ncurses, GLib, libgcrypt, libreadline, libssl,
|
||||
Python). Treat its `apt-get install` block as the authoritative dependency
|
||||
list.
|
||||
|
||||
## Build cproof inside the container
|
||||
|
||||
Bind-mount the working tree and run the autotools sequence:
|
||||
|
||||
```sh
|
||||
docker run --rm -it \
|
||||
-v "$PWD":/src -w /src \
|
||||
cproof-debian \
|
||||
bash -c './autogen.sh && ./configure && make -j$(nproc)'
|
||||
```
|
||||
|
||||
For tests:
|
||||
|
||||
```sh
|
||||
docker run --rm -it \
|
||||
-v "$PWD":/src -w /src \
|
||||
cproof-debian \
|
||||
bash -c './autogen.sh && ./configure && make -j$(nproc) check'
|
||||
```
|
||||
|
||||
`ccache` is enabled in the image (`CC="ccache gcc"`) — share a ccache volume
|
||||
between runs for faster rebuilds:
|
||||
|
||||
```sh
|
||||
-v "$HOME/.ccache":/root/.ccache
|
||||
```
|
||||
|
||||
## Why Docker
|
||||
|
||||
- Pinned OS + package set; the same toolchain CI uses.
|
||||
- Host glib / openssl / libstrophe drift cannot mask or invent failures.
|
||||
- Encryption-stack dependencies (libsignal-protocol-c especially) are
|
||||
awkward on host package managers; the image already has them.
|
||||
|
||||
## When to use a non-Debian image
|
||||
|
||||
- Reproducing a CI failure that only triggers on Arch / Fedora / Ubuntu /
|
||||
Tumbleweed. Use the matching Dockerfile, same bind-mount pattern.
|
||||
- Otherwise: stick with Debian.
|
||||
|
||||
## Hard rule
|
||||
|
||||
Do not run `./autogen.sh`, `./configure`, or `make` on the host shell unless
|
||||
you have an explicit reason and have verified the host toolchain matches the
|
||||
image. CI is the source of truth; CI uses Debian.
|
||||
68
build/local.md
Normal file
68
build/local.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# Local build
|
||||
|
||||
Reference for `autogen.sh` / `configure` / `make` flags. **Do not run these
|
||||
on the host as a default workflow** — see `build/docker.md`. This file
|
||||
documents what the canonical Docker build does internally.
|
||||
|
||||
## Toolchain
|
||||
|
||||
- autotools: `autoconf`, `automake`, `libtool`, `autoconf-archive`.
|
||||
- C compiler: `gcc` (CI) or `clang`.
|
||||
- GLib 2, ncursesw, OpenSSL, libstrophe, libreadline.
|
||||
- Optional: libcmocka (tests), libsignal-protocol-c (OMEMO), libotr5 (OTR),
|
||||
gpgme (PGP), libcurl (HTTP), libmicrohttpd (HTTP server features),
|
||||
libnotify, libgcrypt, Python (plugins).
|
||||
|
||||
The full Debian package list is in `Dockerfile.debian` — treat that as the
|
||||
authoritative dependency list.
|
||||
|
||||
## Sequence
|
||||
|
||||
```sh
|
||||
./autogen.sh # generate configure from configure.ac
|
||||
./configure [opts]
|
||||
make -jN
|
||||
```
|
||||
|
||||
`autogen.sh` runs `aclocal`, `autoheader`, `automake`, `autoconf`, `libtoolize`.
|
||||
|
||||
## Useful `./configure` flags
|
||||
|
||||
| Flag | Effect |
|
||||
|---|---|
|
||||
| `--enable-debug` | Debug build (the `configure-debug` script wraps this). |
|
||||
| `--disable-omemo` / `--disable-otr` / `--disable-pgp` | Drop encryption stack. |
|
||||
| `--disable-python-plugins` | C-only plugins. |
|
||||
| `--disable-notifications` | No libnotify. |
|
||||
| `--prefix=<path>` | Install prefix. |
|
||||
|
||||
`./configure --help` prints the full set; flag names track upstream Profanity
|
||||
closely.
|
||||
|
||||
## `configure-debug`
|
||||
|
||||
Convenience script at repo root. Roughly:
|
||||
|
||||
```sh
|
||||
./autogen.sh
|
||||
./configure --enable-debug --prefix=$(pwd)/install
|
||||
```
|
||||
|
||||
Tweak in-script if you want different debug knobs.
|
||||
|
||||
## `make` targets
|
||||
|
||||
| Target | What |
|
||||
|---|---|
|
||||
| `make` | Builds the `profanity` binary (and `cproof` symlink, if rename has progressed to it). |
|
||||
| `make check` | Builds and runs the unit-test suite. |
|
||||
| `make clean` | Wipes object files. |
|
||||
| `make distclean` | Wipes generated configure artefacts too. |
|
||||
|
||||
## Why this is host-unfriendly
|
||||
|
||||
- Library version drift between the host (a workstation) and the canonical
|
||||
Debian build means the host build can succeed while CI fails (or vice
|
||||
versa) — bugs that don't reproduce in either env are very expensive.
|
||||
- `Dockerfile.debian` pins the OS and package set used by CI. Mirror it
|
||||
locally instead of fighting the host.
|
||||
Reference in New Issue
Block a user