App-karr
view release on metacpan or search on metacpan
misc/agent-context/.claude/skills/karr-single-binary/references/pp-recipe.md view on Meta::CPAN
```
## 2. Build
```bash
# Run from the checkout root (bin/karr, lib/ visible), with $DISTDIR from step 1.
# The [verified] lines below the block explain PAR_VERBATIM, the JSON list, and ::**.
PAR_VERBATIM=1 \
pp -o karr \
-M 'App::karr::**' -M 'App::karr::Cmd::**' \
-M YAML::XS \
-M JSON::MaybeXS -M Cpanel::JSON::XS -M JSON::PP \
-M Module::Runtime \
-M MooX::Cmd -M 'MooX::Cmd::**' \
-M MooX::Options -M 'MooX::Options::**' \
-M Git::Native -M 'Git::Native::**' \
-M Git::Libgit2 -M 'Git::Libgit2::**' \
-M Alien::Libgit2 \
-M FFI::Platypus -M 'FFI::Platypus::**' -M FFI::CheckLib \
-a "$DISTDIR;lib/auto/share/dist/Alien-Libgit2" \
-a "share;lib/auto/share/dist/App-karr" \
bin/karr
```
- **`PAR_VERBATIM=1` [verified].** Without it, pp's default `PAR::Filter::PodStrip`
runs and **corrupts** karr's sources â see "Two build-breakers" below. This is
the difference between a binary that dies on every command and one that works.
- **JSON: `-M` only the backend that is actually installed [verified].** `-M` on an
absent module makes pp abort (`Cannot find module JSON/XS.pm`), so do not list all
three speculatively. `JSON::MaybeXS` picks whatever is present (here
`Cpanel::JSON::XS`); check with
`perl -MJSON::MaybeXS -e 'print ref(JSON::MaybeXS->new)'` and name that one.
- **`-M 'MooX::Cmd::**'` and `-M 'MooX::Options::**'` [verified]** â same dynamic-load
trap as karr's own Cmd classes, one layer deeper: `MooX::Cmd` string-loads
`MooX::Cmd::Role` via `Module::Runtime`, which the scanner never sees. Without the
glob: `Can't locate MooX/Cmd/Role.pm` at startup.
- **libgit2 gets no `-l`** â it is found at runtime via the bundled share dir
(`dist_dir` resolves against `@INC`, which under PAR points into
`$PAR_TEMP/inc/lib/auto/share/dist/Alien-Libgit2`).
- **Bundle karr's own `share/` too, same mechanism.** `App::karr::Role::SkillFile`
(behind `karr skill` and `karr init --claude-skill`) looks the shipped skills
up with `File::ShareDir::dist_dir('App-karr')`, falling back to `share/` next
to the `lib/` it loaded from when the dist isn't installed â a fallback with
no checkout to find inside a PAR binary. `pp` does not pack a second dist's
share tree for you any more than it did Alien-Libgit2's, so it needs its own
`-a` pair, at the same `auto/share/dist/<Dist-Name>` target layout. Skipped,
the binary still builds and passes `--help`; only the first `karr skill`
action or `karr init --claude-skill` dies, with `Could not find
<skill>/SKILL.md. Is App::karr properly installed?` (k308, shipped in 0.601).
- To flush out any runtime dep the scanner missed: add `-c` (compile-check) or,
only if safe, `-x karr <args>` (really runs karr â may touch/write git; never in
the karr checkout, whose `refs/karr/*` is the live board).
## 3. Verify
```bash
PAR_GLOBAL_TEMP="$(mktemp -d)" ./karr --help # fresh cache, first-run extract
# then exercise EVERY subcommand against a throwaway board (trap 1 dies at runtime)
```
Exercise the subcommands in a **separate `mktemp -d` + `git init` repo**, never in
the karr checkout â a worktree shares `refs/karr/*` with the real board, so a
verification `create`/`move`/`destroy` there mutates live state. `karr <cmd> --help`
for each of the 32 commands is the cheap trap-1 probe (forces the class to load,
no side effects); pair it with one real initâcreateâlistâmoveâhandoffâbackupâ
restoreâdestroy flow to prove libgit2/FFI end-to-end.
Also run `karr skill install --agent claude-code` in a fresh `mktemp -d` project
and byte-compare what it wrote against the checkout's own `share/*/SKILL.md`
(and `references/*.md`) â the missing-`share/` `-a` trap above is invisible to
every check so far, since nothing above it reads the skill files, only loads
the class. `scripts/verify-binary.sh`'s trap 3 is exactly this install-and-diff.
Finally `scripts/check-binary-libs.sh ./karr`: none of the runs above can see a
lib the target lacks, because they run where it is installed. This one reads
what every packed object needs and fails on anything outside the documented
runtime set (failure mode 11). A dev-box build may fail it for a lib the box
links and CI's bookworm image does not; that binary is not one to hand out.
## Building in a fresh container (CI), not the dev box
On the dev box the build works because `~/perl5` already has karr and all its
deps installed. A CI container (e.g. `perl:5.40-bookworm`) is a clean slate,
which exposes three traps the dev box hides â all found by karr's
`release-binaries.yml` dry-run, all now baked into `scripts/build-binary.sh` and
that workflow:
1. **`pp` needs `-I lib`.** `bin/karr` does `use App::karr::SyncGuard` with no
`use lib`, and the `-M 'App::karr::**'` glob resolves against `@INC`. In a
container that installed only the *deps* (karr itself is not installed), the
glob finds nothing and the packed binary dies at startup: `Can't locate
App/karr/SyncGuard.pm`. Add `-I lib` so the checkout's `lib/` is on `@INC`
for the scan.
2. **The container has no `-dev` headers.** `Alien::Libgit2`'s share build is
`-DUSE_SSH=ON -DUSE_HTTPS=OpenSSL`, so libgit2's cmake needs libssh2 + openssl
+ zlib + zstd *dev* headers, which `perl:*-bookworm` (buildpack-deps) does not
carry for libssh2. Missing them, cmake aborts `LIBSSH2 not found` and nothing
is built. `apt-get install -y pkg-config libssh2-1-dev libssl-dev zlib1g-dev
libzstd-dev`.
3. **`ALIEN_INSTALL_TYPE=share` must scope to libgit2 only.** Setting it for the
whole dep install forces *build-tool* aliens like `Alien::cmake3` to build
cmake from source (and fail) instead of using the apt cmake. Install
`Alien::cmake3` first (no env var â `system`, uses apt cmake), then set
`ALIEN_INSTALL_TYPE=share` inline for just the `Alien::Libgit2 Git::Libgit2
Git::Native` cpanm call so it does not leak.
Cosmetic, not a blocker: some CPAN tarballs (Cpanel::JSON::XS, Alien::Build,
FFI::Platypus) are packed on macOS and carry a `com.apple.provenance` xattr in a
LIBARCHIVE pax header; GNU tar warns `Ignoring unknown extended header keyword`.
`TAR_OPTIONS=--warning=no-unknown-keyword` silences it. (During bring-up those
warnings masked a *transient CPAN mirror outage* â 404s on the dep tarballs â
that looked like a tar bug but was not; if unpack fails with `gzip: unexpected
end of file`, suspect the mirror, not tar.)
The base image matters beyond glibc: the bare `perl:5.40` tag has moved on to
a trixie base, whose buildpack layer carries `libthai-dev`, so
`Unicode::LineBreak` links `libthai.so.0` there â and the binary dies at
startup on any target without `libthai0`. `perl:5.40-bookworm` doesn't link
it, which is why `release-binaries.yml` pins that tag (the comment at the
`image:` line says so). The pin is backed by a check (k315):
`scripts/check-binary-libs.sh <binary>` unzips the PAR archive, runs `ldd` on
the loader and every `.so` in it, and fails on any lib outside the documented
runtime set, naming the object that needs it. It compares names rather than
( run in 1.006 second using v1.01-cache-2.11-cpan-99fa8243a42 )