amduat-api/ops/asl-debian-packaging-1.md

ASL/DEBIAN-PACKAGING/1 -- Debian Packaging Notes

Status: Draft Owner: Architecture Version: 0.1.0 SoT: No Last Updated: 2026-01-17 Tags: [ops, debian, packaging, build]

Document ID: ASL/DEBIAN-PACKAGING/1 Layer: O2 -- Packaging guidance

Depends on (normative):

• ASL/HOST/1

Informative references:

• ENC-ASL-HOST/1

---

0. Conventions

The key words MUST, MUST NOT, REQUIRED, SHOULD, and MAY are to be interpreted as in RFC 2119.

ASL/DEBIAN-PACKAGING/1 provides packaging guidance for Debian-based distributions. It does not define runtime semantics.

---

1. Optional PTY Support (Normative)

PTY support MUST be controlled at build time with a compile-time flag.

1.1 Build Flag

#ifdef ASL_ENABLE_PTY
#define _GNU_SOURCE
#include <pty.h>
#endif

If PTY is requested at runtime without being built in, tools MUST fail with a clear error.

1.2 Makefile Mapping

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

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

---

2. Library vs Tool Split (Informative)

Guiding principle: libraries define facts; tools perform actions.

2.1 Libraries

• libasl-core
• libasl-store
• libasl-index
• libasl-capture
• libpel-core

Libraries SHOULD avoid CLI parsing and environment policies.

2.2 Tools

• asl-put
• asl-get
• asl-capture
• pel-run
• asl-admin

Tools SHOULD be thin wrappers around libraries.

---

3. Debian Filesystem Layout (Informative)

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

/usr/lib/x86_64-linux-gnu/
  libasl-*.so

---

4. Dependency Rules (Informative)

• libutil MUST be a dependency only when PTY support is enabled.
• No GNU extensions should be required for the PIPE-only build.