0.3.1 version

Signed-off-by: roots666 <m0980701299@gmail.com>

Author: roots666

.github/workflows/release.yml

@@ -70,6 +70,8 @@ jobs:
     name: Test arm64 (native runner)
     runs-on: ubuntu-24.04-arm
     timeout-minutes: 15
+    # Run on all PRs, pushes to main, and tags to ensure ARM64 compatibility
+    # This validates the full epoll/signalfd path (not QEMU fallback)
     steps:
       - name: Checkout
         uses: actions/checkout@v4

CHANGELOG.md

@@ -1,5 +1,32 @@
+<!-- markdownlint-disable MD024 -->
 # Changelog
 
+## 0.3.1 - 2026-01-11
+
+### Fixed
+
+- Fix `debian/control` Architecture field: changed from `any` to `amd64 arm64` to prevent FTBFS on unsupported architectures.
+- Add explicit `make` to Build-Depends for reproducible builds across all environments.
+
+### Improved
+
+- Implement VERSION single source of truth: version now controlled by `VERSION` file at repository root.
+- Auto-generate arch-specific version include files (`include/version_amd64.inc`, `include/version_arm64.inc`) during build.
+- Version string length now calculated dynamically (no hardcoded lengths).
+- Version bumps now require changing only 1 file instead of 4 separate locations.
+
+### Tests/Docs
+
+- Add restart-on-crash test to `debian/tests/smoke`: validates `EP_RESTART_ENABLED` and `EP_MAX_RESTARTS` functionality.
+- Add PGID signal fan-out test to `debian/tests/smoke`: verifies signals reach both child and grandchild processes.
+- Autopkgtest now validates 5 critical behaviors (was 3).
+- Document that `EP_ARM64_FALLBACK` mode is NOT suitable for production (CI testing stub only).
+- List features NOT available in fallback mode: signal forwarding, graceful shutdown, restart, custom EP_SIGNALS.
+- Add restart configuration best practices: guidance on backoff delays and restart limits to prevent tight CPU loops.
+- Add Debian packaging guide section with build instructions, autopkgtest usage, lintian checks, and supported architectures.
+- Update man page date and version metadata to match VERSION file.
+- Document that ARM64 native tests run on every PR (validates full epoll/signalfd path).
+
 ## 0.3.0 - 2026-01-06
 
 - Real-time signals: `EP_SIGNALS=RT*` now requires explicit `EP_SIGRTMIN`/`EP_SIGRTMAX` (avoids hardcoded SIGRTMIN/SIGRTMAX assumptions).

Makefile

@@ -1,4 +1,6 @@
 # Build configuration
+VERSION          := $(shell cat VERSION 2>/dev/null || echo "unknown")
+
 BUILD_DIR        ?= build
 INC_DIR          := include
 
@@ -17,14 +19,25 @@ LDFLAGS          := -nostdlib -z noexecstack -z relro -z now --build-id=sha1
 
 ARM64_AS         ?= $(shell command -v aarch64-linux-gnu-as 2>/dev/null || echo as)
 ARM64_LD         ?= $(shell command -v aarch64-linux-gnu-ld 2>/dev/null || echo ld)
-ARM64_ASFLAGS    ?=
+ARM64_ASFLAGS    ?= -I$(INC_DIR)
 ARM64_LDFLAGS    ?= -nostdlib -z noexecstack -z relro -z now --build-id=sha1
 
 ifeq ($(DEBUG),1)
 NASMFLAGS        += -g -F dwarf
 ARM64_ASFLAGS    += -g
 endif
 
+# Generate version include files for both architectures
+$(INC_DIR)/version_amd64.inc: VERSION
+	@echo '; Auto-generated version file' > $@
+	@echo 'version_msg_str: db "mini-init-amd64 $(VERSION)", 10, 0' >> $@
+	@echo 'version_msg_len_val: equ $$ - version_msg_str - 1' >> $@
+
+$(INC_DIR)/version_arm64.inc: VERSION
+	@echo '// Auto-generated version file' > $@
+	@echo 'version_msg_arm64: .asciz "mini-init-arm64 $(VERSION)\n"' >> $@
+	@echo '.equ version_msg_arm64_len, . - version_msg_arm64 - 1' >> $@
+
 AMD64_BUILD_DIR  := $(BUILD_DIR)/amd64
 ARM64_BUILD_DIR  := $(BUILD_DIR)/arm64
 
@@ -70,11 +83,11 @@ $(AMD64_BUILD_DIR):
 $(ARM64_BUILD_DIR):
 	mkdir -p $@
 
-$(AMD64_BUILD_DIR)/%.o: $(AMD64_SRC_DIR)/%.asm $(INC_DIR)/*.inc | $(AMD64_BUILD_DIR)
+$(AMD64_BUILD_DIR)/%.o: $(AMD64_SRC_DIR)/%.asm $(INC_DIR)/*.inc $(INC_DIR)/version_amd64.inc | $(AMD64_BUILD_DIR)
 	$(NASM) $(NASMFLAGS) $< -o $@
 
-$(ARM64_BUILD_DIR)/%.o: $(ARM64_SRC_DIR)/%.S $(INC_DIR)/*.inc | $(ARM64_BUILD_DIR)
-	$(ARM64_AS) $(ARM64_ASFLAGS) -I$(INC_DIR) $< -o $@
+$(ARM64_BUILD_DIR)/%.o: $(ARM64_SRC_DIR)/%.S $(INC_DIR)/*.inc $(INC_DIR)/version_arm64.inc | $(ARM64_BUILD_DIR)
+	$(ARM64_AS) $(ARM64_ASFLAGS) $< -o $@
 
 # Helper objects
 $(ARM64_BUILD_DIR)/helpers/%.o: $(ARM64_SRC_DIR)/helpers/%.S $(INC_DIR)/*.inc | $(ARM64_BUILD_DIR)

README.md

@@ -266,7 +266,18 @@ Numeric env vars are parsed as **non-negative decimal**. If a value is invalid/o
 - `EP_ARM64_FALLBACK` (ARM64/QEMU only)
   If set to `1`, ARM64 builds skip the epoll/signalfd path and use a simpler
   `wait4` loop. Intended as a workaround for QEMU user-mode flakiness in CI smoke tests.
-  This mode does **not** provide the full signal-forwarding/grace-timer behavior; it primarily verifies spawn + exit-code propagation.
+
+  **WARNING:** This mode is a CI testing stub and is **NOT suitable for production use**.
+  It does **NOT** provide:
+  - Signal forwarding to child process group
+  - Graceful shutdown with grace period escalation
+  - Restart-on-crash functionality
+  - Custom signal monitoring (EP_SIGNALS)
+
+  Fallback mode only verifies basic spawn and exit code propagation. Use it **only**
+  for CI smoke testing under QEMU user-mode emulation. For production, run the full
+  binary on native ARM64 hardware or use full-system emulation.
+
   In fallback mode, verbose logs may omit timestamps to avoid QEMU-user emulation issues.
   Default: `0` (CI jobs typically set this).
 
@@ -307,6 +318,34 @@ EP_RESTART_ENABLED=1 EP_MAX_RESTARTS=0 EP_RESTART_BACKOFF_SECONDS=0 \
   ./build/mini-init-amd64 -- ./your-app
 ```
 
+### Best Practices
+
+#### Restart Configuration
+
+When enabling restart-on-crash (`EP_RESTART_ENABLED=1`):
+
+- **Always set a backoff delay** (`EP_RESTART_BACKOFF_SECONDS`) to prevent tight restart loops
+  - Recommended minimum: `1` second (default)
+  - For flaky apps: `5-10` seconds
+
+- **Set a restart limit** (`EP_MAX_RESTARTS`) to prevent infinite loops on persistent failures
+  - Recommended: `3-5` restarts for transient errors
+  - Use `0` (unlimited) only for long-running services with rare crashes
+
+**Example - Good configuration:**
+```bash
+# Bounded restarts with backoff (recommended)
+EP_RESTART_ENABLED=1 EP_MAX_RESTARTS=3 EP_RESTART_BACKOFF_SECONDS=5 \
+  ./build/mini-init-amd64 -- ./my-app
+```
+
+**Example - Dangerous configuration:**
+```bash
+# Unlimited restarts with no delay (tight loop on immediate crash - avoid!)
+EP_RESTART_ENABLED=1 EP_MAX_RESTARTS=0 EP_RESTART_BACKOFF_SECONDS=0 \
+  ./build/mini-init-amd64 -- ./my-app
+```
+
 ### Exit code semantics
 
 - Child exits normally → `mini-init-asm` returns the **child exit code**.
@@ -477,6 +516,52 @@ bash scripts/test_diagnostics.sh build/mini-init-arm64
 
 ---
 
+## Debian Packaging
+
+### Package Information
+
+The Debian package `mini-init-asm` provides a unified binary:
+- **Installed at:** `/usr/bin/mini-init-asm`
+- **Architecture-specific:** Built for `amd64` and `arm64` only
+- **Statically linked:** No runtime dependencies (libc-free)
+
+### Building the Debian Package
+
+```bash
+# Install build dependencies
+sudo apt-get install debhelper-compat binutils nasm make
+
+# Build binary package
+dpkg-buildpackage -us -uc -b
+
+# Install locally
+sudo dpkg -i ../mini-init-asm_*.deb
+```
+
+### Running Autopkgtest
+
+```bash
+# After installing package
+autopkgtest . -- null
+
+# Or from source tree with schroot
+autopkgtest -B . -- schroot unstable-amd64
+```
+
+### Lintian Check
+
+```bash
+lintian --fail-on warning --display-info ../mini-init-asm_*.deb
+```
+
+### Supported Architectures
+
+Currently supported: **amd64**, **arm64**
+
+Other architectures are not supported due to the assembly implementation.
+
+---
+
 ## Security notes
 
 - No privilege dropping, seccomp profiles, or capabilities tuning are implemented here.

VERSION

@@ -0,0 +1 @@
+0.3.1

debian/changelog

@@ -1,3 +1,21 @@
+mini-init-asm (0.3.1-1) unstable; urgency=medium
+
+  * Debian packaging fixes:
+    - Fix Architecture field (any → amd64 arm64) to prevent FTBFS
+    - Add explicit make to Build-Depends for reproducible builds
+  * Implement VERSION single source of truth for version strings
+  * Enhanced autopkgtest coverage:
+    - Add restart-on-crash validation test
+    - Add PGID signal fan-out test
+  * Documentation improvements:
+    - Add EP_ARM64_FALLBACK production usage warning
+    - Add restart configuration best practices
+    - Add Debian packaging guide section
+  * Update man page date and version metadata
+  * All changes verified: make test-all, dpkg-buildpackage, lintian clean
+
+ -- Debian Maintainer <debian-maint@example.org>  Sun, 11 Jan 2026 00:00:00 +0000
+
 mini-init-asm (0.3.0-1) unstable; urgency=medium
 
   * Initial Debian packaging skeleton. (Closes: #1122134)

debian/control

@@ -4,6 +4,7 @@ Priority: optional
 Maintainer: Debian Maintainer <debian-maint@example.org>
 Build-Depends:
  debhelper-compat (= 13),
+ make,
  binutils,
  nasm [amd64]
 Standards-Version: 4.6.2
@@ -13,7 +14,7 @@ Vcs-Browser: https://github.com/roots666/mini-init-asm
 Vcs-Git: https://github.com/roots666/mini-init-asm.git
 
 Package: mini-init-asm
-Architecture: any
+Architecture: amd64 arm64
 Depends: ${misc:Depends}
 Description: tiny PID 1 init for containers (pure assembly)
  mini-init-asm is a tiny init intended for container entrypoints.

debian/tests/smoke

@@ -31,4 +31,62 @@ sleep 0.5
 kill -TRAP "$pid"
 wait "$pid"
 
+echo "[autopkgtest] 4) restart on crash"
+# Create a script that exits on first run, succeeds on second run
+cat > /tmp/crash_once.sh <<'CRASHEOF'
+#!/bin/sh
+if [ -f /tmp/restart_marker ]; then
+    # Second run: exit normally
+    exit 0
+else
+    # First run: create marker and crash
+    touch /tmp/restart_marker
+    exit 1
+fi
+CRASHEOF
+chmod +x /tmp/crash_once.sh
+rm -f /tmp/restart_marker
+rm -f /tmp/restart.log
+set +e
+EP_RESTART_ENABLED=1 EP_MAX_RESTARTS=1 "$BIN" -v -- /tmp/crash_once.sh 2>&1 | tee /tmp/restart.log
+rc=$?
+set -e
+# Should see "DEBUG: restarting child" in logs
+if grep -q "DEBUG: restarting child" /tmp/restart.log; then
+    echo "  ✓ Restart triggered"
+else
+    echo "  ✗ Restart not found in logs" >&2
+    exit 1
+fi
+# Final exit code should be 0 (second run succeeded)
+test "$rc" -eq 0
+rm -f /tmp/crash_once.sh /tmp/restart_marker /tmp/restart.log
+
+echo "[autopkgtest] 5) PGID fan-out (signal reaches grandchild)"
+# Child spawns grandchild, both trap TERM, both should receive signal
+cat > /tmp/pgid_test.sh <<'PGIDEOF'
+#!/bin/sh
+trap 'echo "grandchild got TERM" >> /tmp/pgid_test.log; exit 0' TERM
+sleep 1000 &
+GRANDCHILD_PID=$!
+trap 'echo "child got TERM" >> /tmp/pgid_test.log; wait $GRANDCHILD_PID; exit 0' TERM
+sleep 1000
+PGIDEOF
+chmod +x /tmp/pgid_test.sh
+rm -f /tmp/pgid_test.log
+"$BIN" -- /tmp/pgid_test.sh &
+pid=$!
+sleep 0.5
+kill -TERM "$pid"
+wait "$pid"
+# Both child and grandchild should have logged
+if grep -q "child got TERM" /tmp/pgid_test.log && grep -q "grandchild got TERM" /tmp/pgid_test.log; then
+    echo "  ✓ Both child and grandchild received TERM"
+else
+    echo "  ✗ PGID fan-out failed" >&2
+    cat /tmp/pgid_test.log >&2
+    exit 1
+fi
+rm -f /tmp/pgid_test.sh /tmp/pgid_test.log
+
 echo "[autopkgtest] OK"

include/version_amd64.inc

@@ -0,0 +1,3 @@
+; Auto-generated version file
+version_msg_str: db "mini-init-amd64 0.3.1", 10, 0
+version_msg_len_val: equ $ - version_msg_str - 1

include/version_arm64.inc

@@ -0,0 +1,4 @@
+// Auto-generated version file
+version_msg_arm64: .asciz "mini-init-arm64 0.3.1
+"
+.equ version_msg_arm64_len, . - version_msg_arm64 - 1