cpp-project-template/3rd/README.md

# Third-Party Dependencies

This directory contains vendored third-party artifacts for offline-first builds.

## Directory Layout

```
3rd/
├── archives/        # CPM local archive files (.tar.gz)
│   ├── spdlog-1.15.3.tar.gz
│   ├── fmt-11.0.2.tar.gz
│   ├── nlohmann-json-3.11.3.tar.gz
│   ├── ...  (27 total; see table below)
│   └── rxcpp-4.1.1-yousician.tar.gz
├── patches/         # Per-dependency patch files
│   └── fuzztest/    # FuzzTest patchset
│       └── 2026-02-19/
└── README.md        # This file
```

## Archive Policy

- All archives are committed to the repository for true offline fresh-clone builds.
- Archives are the source of truth for CPM `URL` inputs.
- SHA256 hashes are recorded in `cmake/deps/versions.cmake`.
- CPM `URL_HASH SHA256=...` provides build-time integrity enforcement.
- Do not add archives for dependencies not in the v1 inventory.

## v1 Inventory

The complete v1 dependency inventory is defined in `cmake/deps/versions.cmake`
and summarized in `docs/template-design.md`.

### Archived (v1 inventory complete)

| Archive | Dependency | Version | SHA256 |
|---------|-----------|---------|--------|
| spdlog-1.15.3.tar.gz | spdlog | 1.15.3 | 15a04e69c222eb6c01094b5c7ff8a249b36bb22788d72519646fb85feb267e67 |
| fmt-11.0.2.tar.gz | fmt | 11.0.2 | 6cb1e6d37bdcb756dbbe59be438790db409cdb4868c66e888d5df9f13f7c027f |
| nlohmann-json-3.11.3.tar.gz | nlohmann/json | 3.11.3 | 0d8ef5af7f9794e3263480193c491549b2ba6cc74bb018906202ada498a79406 |
| toml11-4.4.0.tar.gz | toml11 | 4.4.0 | 815bfe6792aa11a13a133b86e7f0f45edc5d71eb78f5fb6686c49c7f792b9049 |
| CLI11-2.4.2.tar.gz | CLI11 | 2.4.2 | f2d893a65c3b1324c50d4e682c0cdc021dd0477ae2c048544f39eed6654b699a |
| asio-1.30.2.tar.gz | asio | 1.30.2 | 755bd7f85a4b269c67ae0ea254907c078d408cce8e1a352ad2ed664d233780e8 |
| concurrentqueue-1.0.4.tar.gz | concurrentqueue | 1.0.4 | 87fbc9884d60d0d4bf3462c18f4c0ee0a9311d0519341cac7cbd361c885e5281 |
| ghc-filesystem-1.5.14.tar.gz | ghc::filesystem | 1.5.14 | e783f672e49de7c5a237a0cea905ed51012da55c04fbacab397161976efc8472 |
| expected-lite-0.8.0.tar.gz | expected-lite | 0.8.0 | 27649f30bd9d4fe7b193ab3eb6f78c64d0f585c24c085f340b4722b3d0b5e701 |
| cpp-httplib-0.18.3.tar.gz | cpp-httplib | 0.18.3 | a0567bcd6c3fe5cef1b329b96245119047f876b49e06cc129a36a7a8dffe173e |
| googletest-1.16.0.tar.gz | GoogleTest | 1.16.0 | 78c676fc63881529bf97bf9d45948d905a66833fbfa5318ea2cd7478cb98f399 |
| benchmark-1.7.1.tar.gz | Google Benchmark | 1.7.1 | 6430e4092653380d9dc4ccb45a1e2dc9259d581f4866dc0759713126056bc1d7 |
| googletest-1.17.0.tar.gz | GoogleTest (fuzz lane) | 1.17.0 | 65fab701d9829d38cb77c14acdc431d2108bfdbf8979e40eb8ae567edf10b27c |
| abseil-cpp-20260107.1.tar.gz | Abseil | 20260107.1 | 4314e2a7cbac89cac25a2f2322870f343d81579756ceff7f431803c2c9090195 |
| re2-2025-11-05.tar.gz | RE2 | 2025-11-05 | 87f6029d2f6de8aa023654240a03ada90e876ce9a4676e258dd01ea4c26ffd67 |
| antlr4-4.13.2.tar.gz | ANTLR4 | 4.13.2 | 9f18272a9b32b622835a3365f850dd1063d60f5045fb1e12ce475ae6e18a35bb |
| fuzztest-2026-02-19.tar.gz | FuzzTest | 2026-02-19 | 1c6e04065eb988e2c99613369db8294aa58429d392bf479740b237f1255204ef |
| sigslot-1.2.0.tar.gz | sigslot | 1.2.0 | 751852bcb1871aa2ca9f30b34614d028bc44379bbd6f91327744724c652e7ce8 |
| ByteBuffer-master.tar.gz | ByteBuffer | master | 07ab9ff7b253eb64f7eb220ad3158f72b9ee1baf8158890d98f9ee69a6c83e73 |
| eigen-3.4.0.tar.gz | Eigen3 | 3.4.0 | 8586084f71f9bde545ee7fa6d00288b264a2b7ac3607b974e54d13e7162c1c72 |
| hash-library-v8.tar.gz | hash-library | v8 | ddf9d398166e08482af1225aed968ac4c370f99648b5359b0a20c9ed56f7b1c7 |
| CRCpp-1.2.1.0.tar.gz | CRCpp | 1.2.1.0 | e2019ed95300f865fe0c1ea326e5502e1ba538bfbc2e31d175a5ee313b31510d |
| optional-1.1.0.tar.gz | tl::optional | 1.1.0 | 88ece79f3de5ccaec4191951a222f95cc80c4381dafd3163bdb1ff87cedf3118 |
| range-v3-0.12.0.tar.gz | range-v3 | 0.12.0 | 015adb2300a98edfceaf0725beec3337f542af4915cec4d0b89fa0886f4ba9cb |
| function2-4.2.5.tar.gz | function2 | 4.2.5 | a1f15327c542fb0d3e5affed352784d1126dc0b109e611fca93df804b8f19241 |
| rxcpp-4.1.1-yousician.tar.gz | RxCpp (YousicianGit fork) | 4.1.1-yousician | c4698086baebb799ca81ed7defb5c70d1cc9dd3df81519d2bdf6b4a75e63dec0 |

All 27 v1 dependencies have concrete SHA256 hashes and archived tarballs.
Use `python3 scripts/fetch_deps.py --check` to verify local archive integrity.

## Patch Policy

- Patches live under `3rd/patches/<dependency>/<version>/`.
- Each patchset includes a README with upstream baseline, patched files, rationale, and rebase checklist.
- Patches must not introduce remote fetch behavior or forbidden transitive dependencies.

## No-Network Guarantee

The default and fuzz build lanes resolve all dependencies from committed local
archives. CPM uses `URL` pointing at `3rd/archives/*.tar.gz` with
`URL_HASH SHA256=...` for integrity. There is no implicit remote fallback: if an
archive is missing or its hash does not match, the build fails at configure time.

This guarantee is verified by the `no-network-default` and
`no-network-fuzztest-lane` checks in `scripts/dev_check.py`, which run CMake
under invalid HTTP/HTTPS proxies with an isolated CPM cache.

Scope:

- **Covered**: `debug`, `release`, `asan`, `fuzz` presets.
- **Not covered**: there is no global offline mode. The build system does not set
  `CMAKE_DISABLE_FIND_PACKAGE` or similar flags. Offline behavior comes from
  CPM archive mode, not from suppressing network access at the CMake level.

## Updating Archives

To refresh or add a dependency archive:

1. Run `python3 scripts/fetch_deps.py --fetch <name>` to download the archive
   into `3rd/archives/`.
2. Run `python3 scripts/fetch_deps.py --update-hashes` to write computed SHA256
   values into `cmake/deps/versions.cmake` (replaces `PENDING_T12` tokens).
3. Run `python3 scripts/fetch_deps.py --check` to verify all archives match their
   recorded hashes.
4. Commit the archive and the updated `versions.cmake`.

The `--check` flag is offline: it only compares local files against known hashes.
The `--fetch` flag downloads from the URLs recorded in `versions.cmake`.

## Troubleshooting

### Hash mismatch

```
CMake Error: hash mismatch for ...
```

The archive in `3rd/archives/` does not match the SHA256 in
`cmake/deps/versions.cmake`. Either the archive is corrupted, or someone updated
the hash without updating the file (or vice versa). Fix by re-downloading:

```bash
python3 scripts/fetch_deps.py --fetch --force <name>
```

### Missing archive

```
Could not find archive: 3rd/archives/<name>.tar.gz
```

The tarball was not committed or was deleted. Download it:

```bash
python3 scripts/fetch_deps.py --fetch <name>
```

### Unsupported compiler

The default build lanes require a C++14 compiler. The `fuzz` preset
requires C++17 and Clang (`clang++`). GCC will not work for the fuzz lane.

### FuzzTest unavailable

The fuzz lane (`--preset fuzz`) requires Clang and the C++17 standard. If you
don't have Clang installed, or you're on a platform where Clang is unavailable,
skip the fuzz preset. All other presets (debug, release, asan)
work with any C++14-capable compiler.