From 86c043cc946ac9b249de93d39836b27a5ddbf2e7 Mon Sep 17 00:00:00 2001
From: Johnathan Corgan <johnathan@corganlabs.com>
Date: Sat, 6 Jun 2026 12:16:26 +0000
Subject: [PATCH] docs: document libclang-dev as a mandatory Linux build
 prerequisite

Linux source builds pull in rustables, whose build script runs bindgen
to generate nftables bindings for the LAN gateway. bindgen needs
libclang.so on the build host, so a clean source build fails with
'Unable to find libclang' unless libclang-dev (or llvm) is installed.

The prerequisite text in README.md and CONTRIBUTING.md previously
listed only the optional BLE dependencies, and packaging/README.md had
no source-build prerequisite list at all. Document libclang-dev as a
mandatory Linux build dependency, distinct from the optional BLE deps,
and note that it is build-time only so pre-built .deb installs are
unaffected.
---
 CONTRIBUTING.md     |  9 ++++++---
 README.md           | 12 ++++++++++--
 packaging/README.md | 22 ++++++++++++++++++++++
 3 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2583bfc..4e813a7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -35,9 +35,12 @@ cargo test
 ```
 
 The pinned toolchain in [rust-toolchain.toml](rust-toolchain.toml) is
-used for deterministic builds. On Debian/Ubuntu, BLE-capable builds
-need `bluez`, `libdbus-1-dev`, and `pkg-config` installed; the default
-build picks up BLE if those are present and skips it cleanly if not.
+used for deterministic builds. On Linux, a source build requires
+`libclang` (`sudo apt install libclang-dev` on Debian/Ubuntu): the LAN
+gateway's nftables bindings are generated by `bindgen` at build time
+and fail without it. BLE-capable builds additionally need `bluez`,
+`libdbus-1-dev`, and `pkg-config` installed; the default build picks
+up BLE if those are present and skips it cleanly if not.
 
 For multi-node integration runs, Docker is required. The harness
 under [testing/](testing/) starts containerized topologies and
diff --git a/README.md b/README.md
index 565b836..d752cb4 100644
--- a/README.md
+++ b/README.md
@@ -122,8 +122,16 @@ supported; transport availability varies by platform.
 | Tor       |   ✅  |   ✅  |    ✅   |   ✅    |
 | BLE       |   ✅  |   ❌  |    ❌   |   ❌    |
 
-On Linux, BLE requires BlueZ and libdbus
-(`sudo apt install bluez libdbus-1-dev` on Debian / Ubuntu) and is
+On Linux, a source build requires `libclang` — the LAN gateway's
+nftables bindings are generated by `bindgen` at build time, which
+needs `libclang.so` on the build host. Install it before building
+(`sudo apt install libclang-dev` on Debian / Ubuntu); without it the
+build fails inside the `rustables` crate with an "Unable to find
+libclang" error. This is a build-time prerequisite only — it is not a
+runtime dependency, and the pre-built `.deb` artifacts do not need it.
+
+BLE is optional and, on Linux, requires BlueZ and libdbus
+(`sudo apt install bluez libdbus-1-dev` on Debian / Ubuntu). It is
 gated on a build-script probe — install the dependencies first and
 the `cargo build` line above picks it up. The OpenWrt ipk omits
 BLE because libdbus is not available on the target.
diff --git a/packaging/README.md b/packaging/README.md
index 7147728..d5d9644 100644
--- a/packaging/README.md
+++ b/packaging/README.md
@@ -15,6 +15,28 @@ make zip        # Windows .zip package
 make all        # deb + tarball (default)
 ```
 
+## Build Prerequisites
+
+These targets build FIPS from source, so the host needs a build
+environment in addition to a Rust toolchain (the version pinned in
+`rust-toolchain.toml` is auto-installed by rustup).
+
+On Linux, `libclang` is **required**: the LAN gateway's nftables
+bindings are generated by `bindgen` at build time, which needs
+`libclang.so` on the build host. Without it the build fails inside the
+`rustables` crate with an "Unable to find libclang" error.
+
+```sh
+sudo apt install libclang-dev    # Debian / Ubuntu
+```
+
+This is a build-time prerequisite only — it is not a runtime
+dependency, so hosts installing a pre-built `.deb` do not need it.
+
+BLE support is optional and, when building with it, additionally needs
+`bluez`, `libdbus-1-dev`, and `pkg-config`; the build picks up BLE if
+those are present and skips it cleanly if not.
+
 ## Directory Structure
 
 ```text