diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..69d2b946b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,155 @@ +# AGENT.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this repository is + +`bee-files` is the package recipe collection for the *mariux64* Linux distribution used at +the MPI for Molecular Genetics (MPIMG). It contains no application source code: every file +in the root directory is a build recipe (a "bee file") for the `bee` package manager +(`/usr/bin/bee`, `/usr/bin/beesh`, v1.2.30, see ). + +A bee file is a bash script executed by `beesh`. It declares where to fetch sources and +optionally overrides the auto-detected build steps by defining `mee_*` hook functions. +`beesh` downloads, extracts, patches, configures, builds, installs into an image directory +`${D}`, and packages the result as a `.tgz` plus metadata. + +## Commands + +There is no test suite, linter, or CI. Work is done per package. + +```bash +# Build one package (from the repo root, since SRCURL/patches are resolved relative to it) +beesh ./zlib.be0 # or: ./zlib.be0 (files are executable, shebang = beesh) +beesh -c ./zlib.be0 # -c cleans a stale build dir from a crashed run +beesh -i ./zlib.be0 # install after a successful build +BEE_MAKEFLAGS="-j $(nproc)" ./linux-6.12.100-493.bee + +# Inspect what bee will do / where things go +bee --print-config # BEE_TMP_BUILDROOT, BEE_PKGDIR, PREFIX, ... +beeversion --format '%A' zlib.be0 # resolve pkg name-version-revision of a bee file +bee list / bee query / bee install / bee remove / bee update + +# Compare recipes in this checkout against packages installed on the machine +scripts/check-installed + +# Mirror a source tarball or patch to the beehive and print the SRCURL/PATCHURL line +scripts/srcurl # wraps /src/mariux/md5repo.sh +``` + +Notes on building as a normal user (not root): + +- A `.be0`/`.bee` file is a *beesh* script. Running it with plain `bash` only defines the + `mee_*` functions and exits — it produces no package. +- Under `fakeroot` the UID looks like 0, so `/etc/bee/beerc` points the repository at the + admin-only `/src/mariux/beeroot`. Pin `BEE_REPOSITORY_PREFIX` to a writable directory + when using fakeroot. +- Useful env overrides: `BEE_TMP_TMPDIR`, `BEE_TMP_BUILDROOT` (e.g. `/dev/shm/bee-$USER`), + `BEE_MAKEFLAGS`, `PREFIX`. +- Large packages (mesa, llvm, firefox, libreoffice) are built on the MXQ cluster: + `mxqsub -m 956G -t 90m --processors=256 -o ~//….log ./submit.sh`. + Currently, `submit.sh` is not part of the archive. + +## Recipe file conventions + +Two naming schemes coexist: + +- `name.be0` (920 files, the current format) — the filename carries **no** version. The + version lives in the header comment `# BEE_VERSION name-version-revision`, which + `beeversion` parses. Updating a package therefore means editing that line, **not** + renaming the file, so git history stays attached to the package. +- `name-version-revision.bee` (118 files, legacy) — version in the filename. Still used + deliberately where many versions must coexist as separate packages, notably + `linux-*.bee`, `nvidia_linux-*.bee` and `nvidia_current-*.bee`. + `scripts/beenullify.sh` converts a legacy `.bee` to `.be0` (and strips the boilerplate + comments). + +Start new recipes from `scripts/TEMPLATE.be0` (full boilerplate) or `scripts/mTEMPLATE.be0` +(minimal); `scripts/init-pythonpackage ` generates a +`python-.be0`. Also `bee init ` generates a skeleton. + +Anatomy of a recipe, and what actually varies between them: + +- `SRCURL[0]` / `PATCHURL+=()` — download locations. The upstream URL is kept **commented + out directly above** the effective one, which normally points at the local mirror, + `https://beehive.molgen.mpg.de//`. Mirroring is mandatory in practice + (upstream tarballs disappear); if you have appropriate permissions use + `scripts/srcurl` to publish the file and copy the printed line into the recipe. + `PATCHURL` entries may also be plain paths under `/src/mariux/patches/`. + A second word after the URL renames the downloaded file. +- Version variables available in the script: `PKGNAME`, `PKGVERSION`, `PKGREVISION`, + `PKGEXTRAVERSION_DASH`, plus `${S}` (source dir), `${B}` (build dir), `${D}` (image dir). +- `BEE_BUILDTYPE=autotools|configure|meson|make|autogen|none` (also `cmake`, `perl-module`, + `python-module` — see `bee init --help`) overrides bee's build system + auto-detection — needed when detection guesses wrong (e.g. `argtable2.be0` forces + `autotools` because its ancient `CMakeLists.txt` is rejected by modern CMake). +- `build_in_sourcedir`, `sourcesubdir_append `, `EXCLUDE+=()` (paths to keep out of + the package), `B=${S}`. +- Hook functions, in execution order, each with optional `_pre`/`_post` variants: + `mee_getsources`, `mee_extract`, `mee_patch`, `mee_configure`, `mee_build`, + `mee_install`, `mee_check`. The default bodies are `bee_configure` / `bee_build` / + `bee_install`; the common idiom is to call `bee_configure` with extra flags rather than + replace it. `mee_install_post` is the usual place for symlinks, wrappers and fixups. + +### Toolchains from /pkg + +The base system compiler/interpreters are old or missing. Recipes that need a +newer toolchain source an environment profile inside a hook, e.g. in +`mee_configure`: + +```bash +. /pkg/python-3.14.6-0/profile +p=/pkg/rustc-1.97.0-0/profile; [ -e $p ] && . $p +export CC=clang CXX=clang++ +``` + +These are pinned, versioned paths — bumping one is a deliberate change worth its own +commit (see `git log` on `firefox.be0`, `mesalib.be0`). + +### Compat packages + +`*_compat*` recipes (~50 of them, e.g. `openssl_compat102.be0`, `poppler_compat.be0`, +`ncurses_compat-5.7-1.be0`) ship only the old shared libraries of a superseded version so +existing binaries keep running. Most (~30) build nothing at all: `SRCURL=()` and +`mee_install` untars the specific `.so` files out of the already-built old package under +`/src/mariux/beeroot/packages/-.x86_64.bee.tar.bz2` into `${D}`. The rest +recompile an old upstream version normally. + +### Kernel and NVIDIA packages + +`linux--.bee` builds the mariux kernel; `` is a +distro-wide monotonic counter — get the next one with `scripts/next-kernel-number`. The +recipe refuses to build if a package with the same revision already exists, sets +`CONFIG_LOCALVERSION=.mx64.${PKGREVISION}` and symlinks `/boot/mariux.${PKGREVISION}`. +Each kernel needs a matching `nvidia_linux----.bee` +(kernel module) alongside the userspace `nvidia_current-*.bee`; these are usually added and +removed in pairs. See `scripts/build-nvidia.pl` and `scripts/update-graphic-nvidia.sh`. + +## Commits + +`Documentation/SubmittingPatches.md` is authoritative. In short: one logical change per +commit, subject prefixed with the package identifier and a verb in imperative/present +tense, body explaining *why*. Follow the existing phrasing exactly — history is very +uniform and greppable: + +``` +mesalib: Update version from 24.1.5 to 26.1.4 +linux: Add version 6.12.100 +nvidia_linux: Build version 570.144 for linux 6.12.100-493 +linux: Remove 6.12.96-491 superseded by 6.12.98-492 +mesalib: Build Mesa 26 with clang instead of system GCC +``` + +Version-update bodies usually contain just the upstream release-notes/changelog URL. Work +in a topic branch (`add-*` / `update-*` naming dominates) and open a pull request against +`master` on `github.molgen.mpg.de/mariux64/bee-files`; the repo is merged with merge +commits. Whitespace hygiene matters — run `git diff --check`. + +## Working-tree hygiene (known wart) + +The repository has no `.gitignore`, and builds run from the repo root, so downloaded +tarballs and stray build trees accumulate as untracked files next to the recipes +(`*.tar.gz`, `*.tar.xz`, `build.ninja`, `config.h`, `meson-*/`, `gegl/`, `subprojects/`, +`po/`, `tests/`, ad-hoc `build*.sh`/`submit.sh`). Do not commit these, and check +`git status --short` output carefully before staging — `git add -A` in this repo is +dangerous.