317 lines
5.5 KiB
Markdown
317 lines
5.5 KiB
Markdown
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:
|
||
|
||
```c
|
||
/* Enable PTY support only if requested */
|
||
#ifdef ASL_ENABLE_PTY
|
||
#define _GNU_SOURCE
|
||
#include <pty.h>
|
||
#endif
|
||
```
|
||
|
||
Then guard PTY-specific code:
|
||
|
||
```c
|
||
#ifdef ASL_ENABLE_PTY
|
||
static pid_t spawn_pty(...);
|
||
static void pump_pty(...);
|
||
#endif
|
||
```
|
||
|
||
In `asl_capture_run`:
|
||
|
||
```c
|
||
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)
|
||
|
||
```make
|
||
CFLAGS += -Wall -Wextra -O2
|
||
LIBS +=
|
||
|
||
ifdef ENABLE_PTY
|
||
CFLAGS += -DASL_ENABLE_PTY
|
||
LIBS += -lutil
|
||
endif
|
||
```
|
||
|
||
Usage:
|
||
|
||
```sh
|
||
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)
|
||
|
||
```text
|
||
/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`
|
||
|
||
```debcontrol
|
||
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`:
|
||
|
||
```debcontrol
|
||
Build-Depends:
|
||
libc6-dev,
|
||
pkg-config,
|
||
libutil-dev <!no-pty>
|
||
```
|
||
|
||
Then build with:
|
||
|
||
```sh
|
||
dpkg-buildpackage -Pno-pty
|
||
```
|
||
|
||
This is **exactly how Debian likes optional features**.
|
||
|
||
---
|
||
|
||
## 3.3 `debian/rules` (snippet)
|
||
|
||
```make
|
||
#!/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`
|
||
|
||
```text
|
||
usr/lib/*/libasl-capture.so.*
|
||
```
|
||
|
||
## 3.5 `debian/libasl-capture-dev.install`
|
||
|
||
```text
|
||
usr/include/asl/asl_capture.h
|
||
usr/lib/*/libasl-capture.so
|
||
```
|
||
|
||
## 3.6 `debian/asl-tools.install`
|
||
|
||
```text
|
||
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.
|
||
|