Add AGENTS.md

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 <http://beezinga.org/>).
+
+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 <pkg>
+
+# 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 <file-or-URL>        # 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 ~/<somewhere>/….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 <pypi-name> <version>` generates a
+`python-<name>.be0`. Also `bee init <url>` 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/<md5>/<file>`. 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 <dir>`, `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/<pkg>-<ver>.x86_64.bee.tar.bz2` into `${D}`. The rest
+recompile an old upstream version normally.
+
+### Kernel and NVIDIA packages
+
+`linux-<version>-<revision>.bee` builds the mariux kernel; `<revision>` 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-<kernelver>-<krev>-<nvidiaver>-<rev>.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.