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