From 818db503857e7c2d221ecf105f56b063300c1b92 Mon Sep 17 00:00:00 2001
From: Maciej Wal <1977132+Xata@users.noreply.github.com>
Date: Thu, 2 Apr 2026 11:22:00 -0600
Subject: [PATCH] Add SBOM generation guide
Signed-off-by: Maciej Wal <1977132+Xata@users.noreply.github.com>
---
docs/guides/sbom.md | 39 +++++++++++++++++++++++++++++++++++++++
mkdocs.yml | 1 +
2 files changed, 40 insertions(+)
create mode 100644 docs/guides/sbom.md
diff --git a/docs/guides/sbom.md b/docs/guides/sbom.md
new file mode 100644
index 000000000..3a3d0f4be
--- /dev/null
+++ b/docs/guides/sbom.md
@@ -0,0 +1,39 @@
+Crow has the ability to generate a SBOM (Software Bill of Materials) at build using [`cmake-sbom`](https://github.com/DEMCON/cmake-sbom) in SPDX format.
+
+## Prerequisites
+
+The CMake module `cmake-sbom` expects the `spdx-tools`, `reuse`, and `ntia-conformance-checker` Python packages as external prerequisites.
+
+## Example Steps
+
+Below you'll find the steps to add SBOM generation.
+
+### Install Python Packages
+
+Create a Python virtual environment first so you're not installing Python packages globally:
+
+1. Create and navigate to the build directory:
`mkdir build && cd build`
+2. Create the venv:
`python3 -m venv .venv`
+3. Activate the venv (macOS/Linux):
`source .venv/bin/activate`
+4. Install the required Python packages:
`pip install spdx-tools reuse ntia-conformance-checker`
+
+### Build Crow with cmake-sbom
+
+Steps to generate a `.spdx` file using CMake for your project:
+
+1. If you didn't create the `build` directory, create and navigate to the build directory:
`mkdir build && cd build`
+2. Enable the build option:
`cmake .. -DCROW_GENERATE_SBOM=ON -DPython3_EXECUTABLE=$(which python3)`
+3. Then run:
`cmake --build .`
+4. Run the install:
`cmake --install . --prefix /tmp/crow-install`
+
+Check for the generated .spdx file in the `build/` directory. The file name follows this pattern:
`crow--.spdx`
+
+!!! note
+ You must pass `-DPython3_EXECUTABLE=$(which python3)` so CMake uses the venv's Python instead of the system Python. Without it,
+ the SBOM verification step will fail because the system Python won't have the required packages installed.
+
+!!! note
+ The .spdx file is generated when you run the `cmake --install . --prefix /tmp/crow-install`
+
+!!! note
+ You can also combine `-DCROW_GENERATE_SBOM=ON` with conditional dependencies:
`cmake .. -DCROW_GENERATE_SBOM=ON -DCROW_ENABLE_SSL=ON -DCROW_ENABLE_COMPRESSION=ON`
diff --git a/mkdocs.yml b/mkdocs.yml
index 6d5665a05..e5013dbb9 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -67,6 +67,7 @@ nav:
- Multipart: guides/multipart.md
- Query Strings: guides/query-string.md
- Middleware: guides/middleware.md
+ - SBOM Generation: guides/sbom.md
- SSL: guides/ssl.md
- Static Files: guides/static.md
- Blueprints: guides/blueprints.md