amduat-api/notes/debian packaging stanzas.md

Great — this is exactly the point where small, disciplined decisions pay off for years.

I’ll answer in three clean sections:

1. Making PTY support optional at build time
2. Clean split: libraries vs tools (ASL style)
3. Concrete debian/ packaging stanzas

No fluff, no overreach.

---

1. Making PTY support optional at build time

Design goal

• Default: PIPE-only, fully POSIX
• Optional: PTY-enabled, Linux/glibc-specific
• No API break
• No runtime surprises

---

1.1 Build-time feature flag

Use a compile-time macro, not runtime probing.

In code (asl_capture.c)

At the top:

/* Enable PTY support only if requested */
#ifdef ASL_ENABLE_PTY
#define _GNU_SOURCE
#include <pty.h>
#endif

Then guard PTY-specific code:

#ifdef ASL_ENABLE_PTY
static pid_t spawn_pty(...);
static void pump_pty(...);
#endif

In asl_capture_run:

if (mode == ASL_CAPTURE_PTY) {
#ifndef ASL_ENABLE_PTY
    fprintf(stderr, "PTY support not built in\n");
    return -1;
#else
    ...
#endif
}

This guarantees:

• no accidental PTY usage
• deterministic behavior per build

---

1.2 Build system (Makefile example)

CFLAGS += -Wall -Wextra -O2
LIBS   +=

ifdef ENABLE_PTY
CFLAGS += -DASL_ENABLE_PTY
LIBS   += -lutil
endif

Usage:

make              # PIPE only
make ENABLE_PTY=1 # PTY enabled

This maps perfectly to Debian build profiles later.

---

1.3 Debian mapping

• libutil dependency only when PTY enabled
• No mandatory GNU extensions
• Debian-friendly

---

2. Clean split: libraries vs tools

This matters a lot for long-term sanity.

2.1 Guiding principle

Libraries describe facts. Tools perform actions.

Your ecosystem already follows this instinct.

---

2.2 Proposed split

Libraries (linkable, stable ABI)

Package	Contents
libasl-core	block IDs, artifact IDs, hashing
libasl-store	block IO, sealing, snapshots
libasl-index	lookup, segment handling
libasl-capture	execution + stream capture
libpel-core	DAG, receipt types

Libraries:

• no CLI parsing
• no environment policy
• no filesystem assumptions

---

Tools (thin wrappers)

Binary	Purpose
asl-put	write artifact
asl-get	read artifact
asl-capture	execute + capture
pel-run	run PEL DAG
asl-admin	store ops

Tools:

• parse argv
• open stores
• call libs
• emit artifacts

---

2.3 Filesystem layout (Debian standard)

/usr/bin/
  asl-put
  asl-get
  asl-capture
  pel-run

/usr/lib/x86_64-linux-gnu/
  libasl-core.so.0
  libasl-store.so.0
  libasl-capture.so.0

/usr/include/asl/
  asl_core.h
  asl_capture.h

/usr/share/doc/asl/
  README.md
  specs/

No custom prefixes. No surprises.

---

3. Debian packaging: concrete stanzas

Below is a minimal but correct Debian packaging layout.

---

3.1 debian/control

Source: asl
Section: utils
Priority: optional
Maintainer: Your Name <you@example.org>
Build-Depends:
 debhelper-compat (= 13),
 libc6-dev,
 pkg-config
Standards-Version: 4.6.2
Rules-Requires-Root: no

Package: libasl-capture0
Section: libs
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: ASL execution capture library
 Library providing deterministic execution capture
 with optional PTY support.

Package: libasl-capture-dev
Section: libdevel
Architecture: any
Depends: libasl-capture0 (= ${binary:Version}), ${misc:Depends}
Description: Development files for ASL capture
 Headers and static metadata for linking against
 libasl-capture.

Package: asl-tools
Section: utils
Architecture: any
Depends:
 ${shlibs:Depends},
 ${misc:Depends}
Recommends: bash
Description: ASL command-line tools
 Tools for artifact storage, execution capture,
 and deterministic receipt generation.

---

3.2 PTY as a build profile (optional, advanced but clean)

In debian/control:

Build-Depends:
 libc6-dev,
 pkg-config,
 libutil-dev <!no-pty>

Then build with:

dpkg-buildpackage -Pno-pty

This is exactly how Debian likes optional features.

---

3.3 debian/rules (snippet)

#!/usr/bin/make -f

%:
	dh $@

override_dh_auto_build:
ifeq ($(filter no-pty,$(DEB_BUILD_PROFILES)),)
	$(MAKE) ENABLE_PTY=1
else
	$(MAKE)
endif

---

3.4 debian/libasl-capture0.install

usr/lib/*/libasl-capture.so.*

3.5 debian/libasl-capture-dev.install

usr/include/asl/asl_capture.h
usr/lib/*/libasl-capture.so

3.6 debian/asl-tools.install

usr/bin/asl-capture
usr/bin/asl-put
usr/bin/asl-get
usr/bin/pel-run

---

4. Why this setup is correct for your system

• PTY support is explicit, not implicit
• PIPE-only builds remain fully deterministic
• Debian can ship both safely
• Offline authority hosts can disable PTY entirely
• SystemRescue builds can enable it
• Libraries remain reusable and clean

This is exactly the level of restraint Debian maintainers respect.

---

Where to go next (suggestion)

Natural next steps:

1. Define libasl-capture ABI versioning rules
2. Write a man page for asl-capture
3. Add PTY vs PIPE semantics to ASL-HOST
4. Wire asl-capture into your ISO builder

If you want, I can take any one of those and do it to Debian quality.

You’re building this the right way.