This is the canonical operating guide for contributors and coding agents. CFL is a compact C library of data structures and low-level utilities embedded by Fluent Bit and companion telemetry libraries. Keep it portable, allocation-safe, and usable both as a bundled dependency and as an installed library.
include/cfl/: public API. Each header must compile on its own.src/: implementations and private headers;src/cfl_arena_internal.his not public API.tests/: acutest unit tests, public-header tests, and an installed-consumer fixture.benchmarks/: arena and mutable-variant performance tools; see benchmarks/README.md.cmake/,CMakeLists.txt: CMake 3.20+ build and packaging definitions.lib/xxhash/: bundled third-party xxHash sources. Do not apply CFL style or unrelated edits there..github/workflows/: authoritative cross-platform, sanitizer, Valgrind, installed-consumer, packaging, lint, and downstream validation.
Start architecture work with README.md, the relevant public header, and its matching source and test file. Arena ownership and tuning are detailed in ARENA.md.
CMake generates these ignored files; edit their .in sources instead:
include/cfl/cfl_info.hfrominclude/cfl/cfl_info.h.ininclude/cfl/cfl_version.hfrominclude/cfl/cfl_version.h.intests/cfl_tests_internal.hfromtests/cfl_tests_internal.h.in
Do not edit build directories or generated package output. Treat lib/xxhash/
and tests/lib/acutest/ as vendored code unless the task explicitly updates the
dependency.
The verified local path is:
cmake -S . -B build -DCFL_TESTS=On
cmake --build build -j8
ctest --test-dir build --output-on-failureConvenience wrappers run from any directory:
scripts/agent-build.sh
scripts/agent-test.sh
scripts/agent-test.sh cfl-test-arena
scripts/agent-verify.shscripts/agent-test.sh accepts a CTest regular expression. The verification
wrapper configures, builds, runs all tests, and checks tracked diffs for
whitespace errors. Set BUILD_DIR or BUILD_JOBS to override its defaults.
For a focused test without the wrapper:
ctest --test-dir build -R cfl-test-<name> --output-on-failureBuild benchmarks separately in release mode:
cmake -S . -B build/bench -DCMAKE_BUILD_TYPE=Release -DCFL_BENCHMARKS=On
cmake --build build/bench -j8There is no repository-owned formatter or standalone local sanitizer command.
Always run git diff --check. GitHub CI is the canonical extended validation
for GNU99/GNU17, GCC/Clang, Windows/MSYS2, ARM64, sanitizers, Valgrind, shell
lint, installed consumers, and downstream consumers.
- Follow the existing Apache-style C: four-space indentation, braces for all control blocks, and function opening braces on the next line.
- Declare variables at the start of functions, not inside executable blocks.
- Use descriptive
snake_case; public symbols use thecfl_prefix. - Use
CFL_TRUEandCFL_FALSEfor CFL boolean-style results. - Keep public headers self-contained and include the standard headers they use.
- Put public declarations in
include/cfl/, implementation insrc/, and behavioral coverage intests/. - Check allocation failure and partial initialization. Preserve cleanup paths and ownership on every error return.
- Verify container ownership transfer, arena lifetime, and mutation behavior before changing variants, arrays, kvlists, or SDS storage.
- Avoid unrelated formatting, refactoring, generated output, or vendor churn.
Public headers and installed library symbols are compatibility-sensitive. Before changing a public signature, return value, ownership rule, layout, or allocation behavior, inspect all in-repository callers and tests. Maintain C99 portability and do not introduce compiler-specific behavior without an existing compatibility abstraction and cross-platform coverage.
Fluent Bit, cmetrics, ctraces, and cprofiles bundle CFL under lib/cfl. CI tests
the current CFL tree by replacing each consumer's bundled copy. CFL owns its
generic data structures and APIs; consumer-specific behavior remains in the
consumer repository. For changes that can affect callers, follow
docs/ai/cross-repository.md, inspect production
callers separately from bundled source copies, and report any unavailable
checkout or validation.
- Investigation: docs/ai/investigate.md
- Bug fixes: docs/ai/bug-fix.md
- Reviews: docs/ai/code-review.md
- Cross-repository changes: docs/ai/cross-repository.md
Follow local commit history: component: short imperative description. Keep
commits scoped to one component or interface. Do not amend history, create or
delete remote branches, or open pull requests unless explicitly requested.
- The change is minimal and belongs in this repository.
- New behavior has success, failure, and boundary tests where applicable.
- Relevant focused tests pass, followed by
scripts/agent-verify.shfor shared code, public APIs, ownership, CMake, or installation changes. - Public API and downstream impact are assessed and documented.
- Generated and vendored files remain untouched unless explicitly in scope.
git diff --checkpasses and unrelated user changes remain intact.- The final report lists commands run, compatibility impact, and validation gaps or unresolved risks.
Do not modify repositories outside this checkout without explicit permission. Preserve unrelated tracked and untracked work in the shared worktree.