From 0b14b660c451c72faeb0060bb4fa4de3523fd535 Mon Sep 17 00:00:00 2001
From: jamesclement1776 <jamesclement1776@protonmail.com>
Date: Thu, 4 Dec 2025 13:19:27 -0600
Subject: [PATCH] Add Linux build and test steps for instrumentation emitters

---
 INSTRUMENTATION.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/INSTRUMENTATION.md b/INSTRUMENTATION.md
index 253f2ee9fb2c2e..afefb575c6609a 100644
--- a/INSTRUMENTATION.md
+++ b/INSTRUMENTATION.md
@@ -11,3 +11,39 @@ Emitters:
 - Code lifecycle: Objects/codeobject.c → `_firm2_emit_code_create_meta/_destroy_meta` (+ `co_extra` provenance)
 - Frame lifecycle: Python/ceval.c → `_firm2_emit_frame_event`
 - Common envelope everywhere: `event_id`, `pid`, `tid`, `ts_ns`
+
+## Build, install, and test on Linux
+
+The emitters are part of the normal CPython binary. On a Debian/Ubuntu system, install prerequisites and build the tree at the repository root:
+
+```bash
+sudo apt update
+sudo apt install build-essential gdb lcov pkg-config \
+     libbz2-dev libffi-dev libgdbm-dev libgdbm-compat-dev \
+     liblzma-dev libncursesw5-dev libreadline6-dev libsqlite3-dev \
+     libssl-dev tk-dev uuid-dev xz-utils zlib1g-dev
+
+./configure
+make -j$(nproc)
+make test         # optional, runs the standard CPython suite
+sudo make install # installs the instrumented interpreter as python3
+```
+
+To exercise the emitters, set `FIRMAMENT2_ENABLE=1` and run any script. The events print to stdout in NDJSON format.
+
+- **Tokenizer NDJSON** (one line per token):
+  ```bash
+  FIRMAMENT2_ENABLE=1 ./python -c "x = 1 + 2" > tokens.ndjson
+  head tokens.ndjson
+  ```
+
+- **AST NDJSON** (one line per node):
+  ```bash
+  FIRMAMENT2_ENABLE=1 ./python - <<'PY' > ast.ndjson
+  def add(a, b):
+      return a + b
+  PY
+  head ast.ndjson
+  ```
+
+The emitted JSON includes the common envelope (`event_id`, `pid`, `tid`, `ts_ns`) plus the emitter-specific payload fields.