How boostorg/boost works
This repository is the Boost C++ Libraries superproject: a large, multi-library source distribution rather than a single application. Its architecture is centered on reusable C++ components, with shared build, documentation, validation, and release tooling around them.
1. Core product layer: libs/
The main payload lives under libs/*. Each subdirectory is an individual Boost library or related module, typically with its own headers, tests, docs, and build metadata. Examples include asio, filesystem, json, thread, python, program_options, variant, and many others.
2. Library boundary model
Most Boost libraries are designed as independently consumable components, often header-only or with a small compiled part. The repository structure reflects that: the library directories are the source-of-truth boundaries, not a single shared application layer.
3. Common build and integration layer
Build orchestration is shared across the repo through Jamroot, Jamfile.v2, boost-build.jam, boostcpp.jam, and the root CMakeLists.txt. This gives the project dual build support: Boost.Build/B2 remains central, while CMake is supported for broader ecosystem integration.
4. Tooling layer: tools/
tools/ contains developer and release utilities such as boostdep, boostbook, quickbook, inspect, bcp, check_build, and cmake helpers. These tools support dependency analysis, documentation generation, packaging, and build validation across the library collection.
5. Documentation system: doc/
The doc/ tree contains the project-wide documentation pipeline, including source inputs, HTML/PDF outputs, test fixtures, and styling assets. Documentation is generated from BoostBook/Quickbook sources into publishable formats, with a separate documentation build flow from library compilation.
6. Documentation as a first-class artifact
The repo includes prebuilt docs under doc/html and doc/pdf, plus test cases in doc/test. This indicates documentation is treated as a build artifact with regression checks, not just static text checked into the repo.
7. Status, quality, and release gating: status/
The status/ directory holds automated conformance and regression infrastructure, including expected results, failure markup, and inspection scripts. This layer is used to track library health and detect breakage across the broad library set.
8. Continuous integration and release automation
CI is externalized through .github/workflows/*, .circleci/*, .travis.yml, and appveyor.yml. These pipelines validate builds across platforms and toolchains, and the release workflow (release-cmake.yml) suggests packaging and release verification are part of the repo’s operational flow.
9. Cross-platform support as an architectural constraint
The presence of Windows, Linux, and macOS-oriented CI plus Boost’s portable C++ mission means portability is a structural concern. Build scripts, tests, and library code are organized to keep platform-specific differences isolated.
10. Repository bootstrap and distribution support
Scripts like bootstrap.sh, bootstrap.bat, INSTALL, and the top-level README.md support first-time setup and consumption. This is a source distribution designed to be built from checkout, with standardized entry points for users and contributors.
11. External dependency management
The repository uses .gitmodules, indicating some parts may be maintained as submodules or have external source dependencies. In architectural terms, that means some workflows rely on synchronized external components rather than everything living in one flat source tree.
12. Overall data flow
Source code in libs/ and tooling in tools/ feed the build system (Jamroot/CMake). The build produces library artifacts and test results, while the documentation pipeline transforms docs sources in doc/ into HTML/PDF outputs. CI runs these flows on multiple platforms and publishes verification signals used for release readiness.
13. How to diagram it
A good architecture diagram should show:
- a central “Boost library collection” block containing many independent library modules,
- shared build orchestration around it,
- documentation generation as a parallel pipeline,
- status/testing as a quality gate,
- and CI/release automation as external execution environments.
In short, this repo is a platform for distributing and validating many independent C++ libraries, with strong shared infrastructure for building, documenting, and continuously verifying them across platforms.
Main entry points: libs Library set · doc Docs pipeline · ci.yml CI workflows · tools Tooling set
Components 19
Core libraries
Independent Boost library modules under libs/.
- Library set · The main Boost source distribution of independently consumable C++ libraries.
libs - Core libs · Common building blocks and portability primitives used by many other Boost components.
libs/core - Runtime libs · Execution, threading, networking, and system-facing libraries.
libs/asio - Data libs · Containers, parsing, numeric, and data structure oriented libraries.
libs/array - Meta libs · Template metaprogramming and type-introspection libraries.
libs/type_traits - Text libs · String processing, lexical conversion, and formatting libraries.
libs/format - Dist libs · Serialization, filesystem, Python, and other broader integration libraries.
libs/filesystem
Shared infrastructure
Repo-wide build and bootstrap entry points.
- Build root · Top-level Boost.Build and CMake entry points that coordinate repo-wide builds.
Jamroot - CMake entry · Repository-level CMake configuration for external build ecosystem integration.
CMakeLists.txt - Bootstrap · Initial setup and distribution scripts for configuring the repository build.
bootstrap.sh
Documentation
Documentation sources, generated outputs, and doc tooling.
- Docs pipeline · Project-wide documentation sources, tests, and generated outputs.
doc - Doc sources · Primary BoostBook and stylesheet sources for documentation generation.
doc/src - Doc tests · Documentation formatting and gold-file regression tests.
doc/test
Quality gates
Status, regression, and validation infrastructure.
- Status checks · Automated conformance, expected-results, and inspection infrastructure.
status
CI / release
External automation and platform validation.
- CI workflows · External continuous integration and release automation across platforms.
.github/workflows/ci.yml
Tools
Developer and release utilities.
- Tooling set · Utilities for dependency analysis, documentation, inspection, and packaging.
tools - Boostdep · Analyzes library dependencies across the Boost source tree.
tools/boostdep - Quickbook · Transforms Boost documentation sources into publishable doc inputs.
tools/quickbook - BoostBook · Documentation generation and formatting support for BoostBook sources.
tools/boostbook
Connections 23
- Build root → Library set: builds · Boost.Build orchestrates the library collection.
- CMake entry → Library set: configures · CMake provides an alternate repo-wide build entry.
- Bootstrap → Build root: prepares · Bootstrap scripts initialize the build environment.
- Library set → Core libs: includes · The library set contains core foundational modules.
- Library set → Runtime libs: includes · The library set contains runtime and concurrency modules.
- Library set → Data libs: includes · The library set contains data-structure and container modules.
- Library set → Meta libs: includes · The library set contains metaprogramming modules.
- Library set → Text libs: includes · The library set contains string and formatting modules.
- Library set → Dist libs: includes · The library set contains integration and distribution modules.
- Tooling set → Boostdep: provides · Dependency analysis is one of the central repo tools.
- Tooling set → Quickbook: provides · Quickbook is a major documentation source tool.
- Tooling set → BoostBook: provides · BoostBook supports documentation generation.
- Tooling set → Status checks: supports · Tooling feeds validation and inspection workflows.
- Docs pipeline → Doc sources: contains · Documentation sources live under doc/src.
- Docs pipeline → Doc tests: contains · Documentation regression tests live under doc/test.
- Docs pipeline → BoostBook: uses · The doc pipeline depends on BoostBook generation support.
- Docs pipeline → Quickbook: uses · The doc pipeline depends on Quickbook source processing.
- Status checks → Library set: checks · Status tooling validates the library collection.
- Status checks → Build root: verifies · Status checks exercise the shared build system.
- CI workflows → Build root: runs · CI executes the primary build orchestration.
- CI workflows → Docs pipeline: publishes · CI builds and validates documentation artifacts.
- CI workflows → Status checks: gates · CI consumes status results for readiness checks.
- CI workflows → Bootstrap: tests · Automation validates repo bootstrap and setup flows.