source-stack/AGENTS.md

Project Instructions

Source Dependencies

• Do not download or initialize Git submodules during source builds unless an explicit exception is listed below.
• Rely on the default non-recursive behavior of git clone; do not add submodule initialization or update steps.
• Declare and pin every source dependency version in the Dockerfile or another tracked project file.
• Do not use floating branches, unversioned archives, or implicit dependency downloads.
• Add each dependency as a separate, reviewable build step so its source and version remain visible.
• Append new dependency build steps after all existing dependency build steps. Do not insert or reorder steps in the existing build sequence, so previously successful build layers remain unchanged.
• The DuckDB ui extension (duckdb-ui) is built in the same step as DuckDB instead of a separate step. It is statically linked into the DuckDB shell and can only be compiled as part of the DuckDB source tree (via -DDUCKDB_EXTENSION_CONFIGS), against the matching DuckDB version. Keep its pinned commit in the same RUN as DuckDB and update the two together. Because DuckDB is built from a tarball, pass -DOVERRIDE_GIT_DESCRIBE with the DuckDB version so the extension selects the correct API.
• The log4cplus build also takes its required ThreadPool dependency in the same step, as a second source archive extracted into src/threadpool. log4cplus REL_2_0_5 pins ThreadPool to commit cc0b6371d3963f7028c2da5fc007733f9f3bf205; keep the two in sync and do not fetch unused log4cplus submodules.
• Sources that ship one archive per architecture (such as Rust) go in their own sources/<name>/ directory, keeping the architecture in the file name. fetch-sources.sh downloads the archive for uname -m, and the Dockerfile mounts the whole directory (source=<name>) and selects the file with $(uname -m) in the same RUN. Do not create architecture-neutral hard links or symlinks, and do not mount the whole sources root, because that would invalidate the cache of existing layers whenever any source is added.

System Development Packages

• Do not install distribution-provided -dev packages for third-party libraries.

• Build third-party development dependencies from source at explicitly pinned versions.

• System -dev packages are allowed only for foundational platform infrastructure, such as glibc and Linux kernel headers.

• Document any new foundational -dev package exception in this file before adding it to the image.

• On Rocky Linux 9, glibc-devel, kernel-headers, and libstdc++-devel may be installed directly or as compiler dependencies because they are foundational C/C++ platform and toolchain components.

• On Alpine Linux, musl-dev and linux-headers may be installed directly or as compiler dependencies because they are foundational C/C++ platform and toolchain components.

• The rocky9-system image is the exception to the rules above: it deliberately installs third-party libraries and their -devel packages from the Rocky Linux 9, CRB and EPEL repositories instead of building them from source, with Protobuf (v3.21.12, installed under /usr/local) as the only library built from source. Other libraries use distribution versions and are not pinned. Libraries missing from those repositories (for example magic_enum) are skipped, not built from source.

Meta Libraries

• Pin all Meta/Facebook ecosystem libraries to the same date-based release tag.
• The current Meta release tag is v2026.08.03.00; use this exact tag for Folly and every subsequently added Meta library.
• Update the shared Meta release tag only when all Meta libraries in this project can be updated together.