Skip to content

Commit 4dcdefb

Browse files
wellweiwellwei
committed
docs(asio): record header-only package validation plan
1 parent e087a40 commit 4dcdefb

1 file changed

Lines changed: 154 additions & 0 deletions

File tree

‎.agents/docs/2026-07-17-add-asio-plan.md‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# Add standalone Asio 1.38.1 as a header-only package
2+
3+
Date: 2026-07-17
4+
5+
This document defines the contribution scope for `compat.asio@1.38.1`. It is
6+
based on the current `origin/main`, its active validation workflow, and mcpp
7+
0.0.94. Dated repository guidance is treated as historical when it conflicts
8+
with those live contracts.
9+
10+
## 1. Scope
11+
12+
This contribution adds only the upstream standalone, header-only Asio package.
13+
Consumers use `#include <asio.hpp>` and related upstream headers.
14+
15+
The following work is intentionally excluded:
16+
17+
- a native C++ module or `import asio;` interface;
18+
- OpenSSL or wolfSSL integration;
19+
- Boost.Context, Boost.Regex, or Boost.Date_Time integration;
20+
- liburing integration;
21+
- changes to repository contribution guidance or README content.
22+
23+
Native module adaptation remains separate because it has a different build and
24+
consumer contract and requires its own compatibility evidence.
25+
26+
## 2. Upstream identity and archive evidence
27+
28+
- Canonical repository: `https://github.com/chriskohlhoff/asio`.
29+
- Release tag: `asio-1-38-1`, the latest numeric Asio tag observed on
30+
2026-07-17.
31+
- Tag commit: `bbecff21a23b97c34641f0f1f08b28c91b9c77cf`.
32+
- License: Boost Software License 1.0 (`BSL-1.0`), confirmed from upstream
33+
`COPYING` and `LICENSE_1_0.txt` at the tag.
34+
- Archive URL:
35+
`https://github.com/chriskohlhoff/asio/archive/refs/tags/asio-1-38-1.tar.gz`.
36+
- Archive SHA-256:
37+
`2827b229972be80cdb14e5497962fa393d1adf036b5869e2b9c99f644daadacc`.
38+
39+
Two independent downloads produced the same SHA-256. The archive is wrapped in
40+
`asio-asio-1-38-1/`, and its public entry header is
41+
`asio-asio-1-38-1/include/asio.hpp`. Therefore `*/include` is the required
42+
consumer include root.
43+
44+
The upstream tag is annotated but not cryptographically signed. Reproducibility
45+
is enforced by the descriptor's pinned archive digest.
46+
47+
## 3. Package shape and descriptor contract
48+
49+
Asio is a third-party project without an mcpp manifest in the selected release,
50+
so the package uses an inline Form B descriptor at
51+
`pkgs/c/compat.asio.lua`:
52+
53+
- namespace: `compat`;
54+
- full package name: `compat.asio`;
55+
- published version: bare version `1.38.1`;
56+
- platforms: Linux, macOS, and Windows use the same portable source archive;
57+
- include root: `*/include`;
58+
- build target: a generated C anchor provides the buildable library target
59+
required by the current package resolver;
60+
- Linux link interface: `-pthread`;
61+
- `import_std = false` because this package is consumed through textual headers.
62+
63+
The intended post-publication CLI token is `compat:asio@1.38.1`, which maps to
64+
the consumer declaration `[dependencies.compat] asio = "1.38.1"`. Before the
65+
replacement PR is opened, that token must be exercised with the current mcpp
66+
CLI in an isolated project rather than inferred only from the descriptor name.
67+
68+
The default `standalone` feature contributes these public preprocessor defines:
69+
70+
- `ASIO_STANDALONE`;
71+
- `ASIO_HEADER_ONLY`;
72+
- `ASIO_DISABLE_BOOST_CONTEXT_FIBER`.
73+
74+
mcpp 0.0.94 accepts feature `defines` in the current xpkg parser and propagates
75+
them to consumers. The Asio surface test rejects builds where any of these
76+
defines is absent, and generated compile commands are inspected during local
77+
verification to confirm that the flags reach every consumer translation unit.
78+
79+
The descriptor uses grammar already accepted by the live index contract. This
80+
contribution does not change `index.toml` (`min_mcpp = "0.0.87"`) or the active
81+
workflow pin (`MCPP_VERSION = "0.0.94"`).
82+
83+
## 4. URL and mirror decision
84+
85+
No authorized, byte-identical `mcpp-res` CN asset is available for this
86+
contribution. The descriptor therefore uses the plain canonical upstream URL,
87+
which is the current repository's supported fallback. It does not fabricate a
88+
CN entry or alias the upstream URL as a CN mirror.
89+
90+
A maintainer may add a legitimate CN mirror later by uploading the exact same
91+
archive bytes and retaining the pinned SHA-256.
92+
93+
## 5. Consumer and test design
94+
95+
The consumer project is `tests/examples/asio`, registered in the root workspace
96+
and resolved through the local `compat` index. The current repository workflow
97+
uses `mcpp test --workspace`, so the example follows the active `tests/*.cpp`
98+
layout instead of the historical `src/main.cpp` runner layout.
99+
100+
Six executable tests provide failure-capable assertions:
101+
102+
- `core`: timers, executor work, dispatch, defer, and post behavior;
103+
- `coroutine`: `co_spawn`, `use_awaitable`, and completion behavior;
104+
- `experimental`: experimental channel send/receive behavior;
105+
- `network`: loopback TCP accept/connect/read/write behavior;
106+
- `platform`: platform-specific public types guarded by target macros;
107+
- `surface`: representative public headers, public types, and required package
108+
defines.
109+
110+
The tests do not include or exercise the separate native module adapter.
111+
112+
## 6. Validation contract
113+
114+
The active workflow pins mcpp 0.0.94. Before opening the replacement PR, the
115+
branch must provide fresh evidence for all locally available checks:
116+
117+
1. run the descriptor syntax and mirror lint with Lua 5.4;
118+
2. parse `pkgs/c/compat.asio.lua` with mcpp 0.0.94;
119+
3. run the targeted Asio consumer tests from isolated build state with
120+
`MCPP_INDEX_MIRROR=GLOBAL`;
121+
4. inspect the generated compile commands for all three public defines;
122+
5. exercise `mcpp add compat:asio@1.38.1` in an isolated consumer project;
123+
6. run `mcpp test --workspace` on the local host;
124+
7. run `git diff --check` and confirm README is identical to `origin/main`.
125+
126+
The replacement PR must then pass every check instantiated by the live
127+
workflow, including the Linux, macOS, and Windows workspace matrix. Local macOS
128+
success is not evidence for the other declared platforms.
129+
130+
## 7. Documentation and change boundary
131+
132+
README remains byte-identical to `origin/main`. This package contribution does
133+
not update historical contribution instructions, even where they describe old
134+
CI job names or old feature limitations. Any correction to those documents
135+
requires a separate, evidence-backed audit and a separately scoped change.
136+
137+
The replacement PR is limited to:
138+
139+
- this design record;
140+
- `pkgs/c/compat.asio.lua`;
141+
- the root workspace registration;
142+
- `tests/examples/asio` consumer configuration and tests.
143+
144+
## 8. Acceptance criteria
145+
146+
- upstream version, license, layout, and repeated archive digest are recorded;
147+
- descriptor grammar and exact Lua 5.4 lint pass;
148+
- the CLI dependency token is verified through an isolated `mcpp add`;
149+
- the six targeted consumer tests pass from isolated build state;
150+
- the local workspace test passes;
151+
- README has no diff;
152+
- the replacement PR contains no native module adaptation;
153+
- all required GitHub Actions jobs pass before maintainer merge;
154+
- publication remains the repository's automatic post-merge responsibility.

0 commit comments

Comments
 (0)