Skip to content

refactor(asio): make module package canonical #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Sunrisepeak merged 2 commits into from
Jul 24, 2026
Merged

refactor(asio): make module package canonical #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
239531f
refactor(asio): make module package canonical
wellwei Jul 21, 2026
425058c
refactor(asio): keep chriskohlhoff namespace, adopt PR #109 content
wellwei Jul 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion mcpp.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,6 @@
[workspace]
members = [
"tests/examples/archive",
"tests/examples/asio",
"tests/examples/asio-module",
"tests/examples/build-mcpp",
"tests/examples/cjson",
Expand Down
235 changes: 44 additions & 191 deletions pkgs/c/chriskohlhoff.asio.lua
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,190 +1,44 @@
-- chriskohlhoff.asio -- Asio 1.38.1 暴露为 C++23 模块 `asio` (Form B inline)
-- asio -- 将独立版 Asio 1.38.1 暴露为 C++23 模块 `asio`
-- (Form B inline descriptor, separate-compilation mode)。
--
-- 消费者引入:
-- mcpp add chriskohlhoff.asio@1.38.1
-- 注意事项
-- * 使用 `mcpp add chriskohlhoff.asio@1.38.1` 引入；消费者需显式写
-- `import std; import asio;`，因为本包设置 import_std = false。
-- * 本包只支持模块方式消费。同一 translation unit 不要混用
-- `#include <asio.hpp>` 和 `import asio;`，避免 inline 定义与模块 BMI
-- 的 separate-compilation 定义产生 ODR 差异。
-- * 默认 feature 显式传播 ASIO_STANDALONE、ASIO_SEPARATE_COMPILATION、
-- ASIO_DISABLE_BOOST_CONTEXT_FIBER 和 ASIO_HAS_THREADS。Asio 头文件内部
-- 自动检测的其他 ASIO_HAS_* 宏不会由 `import asio;` 导出。
--
-- 注意: 不要使用简写 mcpp add asio@1.38.1。
-- 简写 "asio" 已在默认注册表中匹配多个包 (compat.asio, mcpplibs.asio 等),
-- 会导致解析冲突或解析到错误的包。
-- 与 header-only Asio 的区别/限制
-- * 上游 1.38.x 没有模块接口单元。本描述生成 `asio.cppm`，并只编译一次
-- `*/src/asio.cpp` 中的非模板实现；首次构建需生成 BMI，增量构建可避免
-- 每个消费者 translation unit 重复解析整组 Asio 头文件。
-- * 模块只暴露 wrapper 中明确 export 的声明，不等同于
-- `#include <asio.hpp>` 的完整 API 表面。
-- * asio::error_code 是 std::error_code 的别名；wrapper 导出
-- asio::use_future 变量，但未导出 asio::use_future_t<Alloc> 类模板。
-- * 依赖未导出 ASIO_HAS_* 宏、平台专用头文件或 Boost 扩展的代码，需要
-- 改用标准/操作系统能力检测或另行扩展模块 wrapper。
--
-- 本包是 compat.asio (header-only: #include <asio.hpp>) 的模块伴侣包。
-- 采用 ASIO_SEPARATE_COMPILATION 模式 (编译 */src/asio.cpp),
-- 上层叠加生成的模块接口单元 (.cppm wrapper), 使用者只需:
-- import std; import asio;
--
-- 为何用 generated_files: upstream 1.38.x 未提供模块接口单元,
-- wrapper 在 mcpp-index 内手工编写, 先以 docs/asio.lua 本地验证。
--
-- ========== 基本用法 ==========
-- import std; -- 必须, 模块版不会自动拉入标准库
-- import asio;
--
-- using namespace std::chrono_literals;
-- asio::io_context io;
-- auto strand = asio::make_strand(io);
-- asio::steady_timer timer(io, 100ms);
-- asio::co_spawn(io, my_coro(), asio::detached);
--
-- ========== 必须写 import std; ==========
-- 与 header-only 的 compat.asio 不同, 本模块不会隐式拉入任何标准库头文件。
-- 要使用 std::vector, std::error_code, std::thread, std::mutex,
-- std::chrono 等, 必须写 `import std;`。省略则标准库不可见。
--
-- ========== 与 compat.asio(header-only) 的主要差异 ==========
--
-- 1. 构建模型 (HEADER_ONLY -> SEPARATE_COMPILATION)
-- compat.asio: ASIO_HEADER_ONLY -- asio 模板在每个消费者 TU 中实例化,
-- 编译系统只需一个锚定 .c 文件。
-- chriskohlhoff.asio: ASIO_SEPARATE_COMPILATION -- 每次构建只编译一次
-- */src/asio.cpp; BMI (模块) 缓存模板实例化。
-- 首次构建较慢 (编译 asio 实现), 增量构建更快
-- (消费者 TU 变更时无需重解析 asio 头文件)。
--
-- 2. 宏 (宏定义) 不可见
-- `import asio;` 后, 模块边界隔离了预处理状态。使用者不能写:
-- #ifdef ASIO_HAS_THREADS -- 不可见
-- #ifndef ASIO_HEADER_ONLY -- 不可见
-- #ifdef ASIO_HAS_PTHREADS -- 不可见
-- #ifdef ASIO_HAS_PIPE -- 不可见
-- #ifdef ASIO_HAS_FILE -- 不可见
-- #ifdef ASIO_HAS_SERIAL_PORT -- 不可见
-- #ifdef ASIO_HAS_BOOST_* -- 不可见
-- 只有 ASIO_STANDALONE 和 ASIO_SEPARATE_COMPILATION 通过 feature defines
-- 暴露 (见下方 "features" 块)。需要平台检测时, 请使用 C++ 标准宏或
-- 操作系统级宏 (#ifdef __linux__ 等)。
--
-- 3. error_code 类型一致性
-- asio::error_code = std::error_code。模块导出了类型别名, 两者可互换。
-- 定时器回调签名 (const std::error_code&) 和 asio::error::* 枚举值
-- 均正常工作。
--
-- 4. 完成令牌 (Completion Token) 的模板类型
-- 模块使用者可以写 asio::detached / asio::detached_t / asio::deferred /
-- asio::deferred_t 作为类型。但 asio::use_future_t<Alloc> 是类模板,
-- 未导出。请直接使用 asio::use_future 变量, 无需命名其类型。
--
-- 5. 禁止混合 #include 和 import
-- 不要在同一个 TU 中混用 #include <asio.hpp> 和 import asio; --
-- 头文件的 inline 实例化与模块 BMI 之间可能存在 ODR 差异。选一种。
-- 需要 #include 方式时, 请依赖 compat.asio。同理, 不要在同一 TU 中
-- 混合 #include <vector> 和 import std;。
--
-- 6. import_std = false
-- mcpp schema "0.1" 要求自身提供模块接口的包必须设置 import_std = false
-- (由使用者显式写 `import std; import asio;`)。chriskohlhoff.asio 不会
-- 在包级别自动引入 import std;。
--
-- ========== 本模块不可用的 API 组件 ==========
--
-- 以下组件在 compat.asio (header-only) 中可用, 但本模块未导出:
--
-- 组件 头文件 / 路径 原因 / 替代方案
-- ------------------------+----------------------------+----------------------
-- SSL/TLS asio/ssl/*.hpp 需 OpenSSL/wolfSSL
-- (ssl::context, (外部依赖), 本包不包含
-- ssl::stream,
-- ssl::host_name_verify)
-- Unix 域套接字 asio/local/*.hpp 未导出。改用 TCP loopback,
-- (local::stream_protocol, 或在你的代码中 #include
-- local::datagram_proto)
-- POSIX 流描述符 asio/posix/*.hpp 未导出。
-- (posix::stream_descriptor,
-- posix::descriptor_base)
-- Windows 句柄 asio/windows/*.hpp Windows 专用, 未导出。
-- (stream_handle, object_handle,
-- overlapped_ptr)
-- 串口 asio/serial_port.hpp 平台相关
-- (ASIO_HAS_SERIAL_PORT)。
-- 未导出。
-- Pipe (管道) asio/*able_pipe.hpp 需 ASIO_HAS_PIPE。
-- (readable_pipe, writable_pipe) 未导出。
-- 文件 I/O asio/stream_file.hpp 需 ASIO_HAS_FILE。
-- asio/random_access_file 未导出。
-- spawn() 有栈协程 asio/spawn.hpp 需 Boost.Context
-- (spawn, yield_context) (ASIO_HAS_BOOST_CONTEXT
-- _FIBER)。我们定义了
-- ASIO_DISABLE_BOOST_
-- CONTEXT_FIBER, 因此
-- spawn() 给出编译期
-- #error。
-- -> 改用 co_spawn +
-- awaitable (C++20
-- 无栈协程)
-- Boost.Date_Time 定时器 asio/deadline_timer.hpp 已废弃。改用
-- steady_timer /
-- system_timer
-- (使用 std::chrono)
-- 通用套接字协议 asio/generic/*.hpp 较少使用, 未导出。
-- 执行器属性框架 asio/execution/*.hpp 高级执行器框架, 暂未导出。
-- 自定义点检测特质 asio/traits/*.hpp 检测特质, 最终用户
-- 价值较低, 未导出。
-- 遗留宏式协程 <asio/yield.hpp> 已过时。改用 awaitable。
-- <asio/coroutine.hpp>
-- asio::streambuf asio/streambuf.hpp 改用 mutable_buffer +
-- asio::buffer()。
--
-- ========== Boost 淘汰说明 ==========
--
-- 独立版 asio (定义了 ASIO_STANDALONE) 已从所有核心和网络 API 中移除
-- Boost 依赖:
--
-- * Boost.DateTime -- 已完全移除。ASIO_STANDALONE 在 config.hpp 中设置
-- ASIO_DISABLE_BOOST_DATE_TIME, 导致 deadline_timer (依赖
-- boost::posix_time) 完全不可编译。所有现代 asio 定时器
-- (steady_timer, system_timer, high_resolution_timer) 直接使用
-- std::chrono。
--
-- * Boost.Context -- 已从核心库移除, 但 spawn() 仍需要。
-- spawn() / basic_yield_context API 使用 boost::context::fiber 实现
-- 有栈协程。由于我们定义了 ASIO_DISABLE_BOOST_CONTEXT_FIBER,
-- 任何使用 spawn() 的代码都会产生编译期 #error。
-- -> 改用 C++20 无栈协程, 功能完全等价:
-- // 之前 (Boost.Context 有栈):
-- asio::spawn(io, [](asio::yield_context yield) {
-- timer.async_wait(yield);
-- });
-- // 之后 (C++20 无栈, 零 Boost):
-- asio::co_spawn(io, coro(), asio::detached);
-- asio::awaitable<void> coro() {
-- co_await timer.async_wait(asio::use_awaitable);
-- }
--
-- * Boost.Regex -- ASIO_STANDALONE 禁用了 ASIO_HAS_BOOST_REGEX。
-- * Boost.Config, Boost.Array, Boost.Bind, Boost.Limits, Boost.Chrono,
-- Boost.ThrowException 等 -- 全部已禁用。
--
-- * 陷阱提示: ASIO_HAS_BOOST_CONTEXT_FIBER 会针对任意 C++11 兼容编译器
-- (clang/GCC/MSVC) 自动检测并设置自身, 即使你从未要求过 Boost。
-- 如果 Boost 头文件碰巧在 include path 中, spawn() 看起来能编译,
-- 但会在链接时报错 (除非链接了 libboost_context)。
-- ASIO_DISABLE_BOOST_CONTEXT_FIBER 防护了这一点: 我们主动抑制自动检测,
-- 使结果是明确的编译期错误, 而非运行时崩溃。
--
-- ========== 迁移指南 (header-only -> 模块) ==========
--
-- 将项目从 compat.asio (#include <asio.hpp>) 切换到
-- chriskohlhoff.asio (import asio;) 时, 请检查以下断点:
--
-- [ ] 在每一个使用 asio 的 TU 顶部添加 import std;
-- (标准库类型不再隐式可用)
-- [ ] 删除所有 #include <asio/*.hpp> -- 替换为 import asio;
-- [ ] 删除 #include <asio.hpp> (如果有)
-- [ ] 检查 #ifdef ASIO_HAS_THREADS / ASIO_HAS_PIPE / 等
-- -> 替换为操作系统级宏或 if-constexpr 检测
-- [ ] 检查 asio::spawn() / yield_context 用法
-- -> 重写为 co_spawn + awaitable + use_awaitable
-- [ ] 检查 deadline_timer -> 替换为 steady_timer
-- [ ] 检查 asio::ssl::* -> 需要单独的 OpenSSL 集成包
-- [ ] 检查 asio::local::* / posix::* -> 如确实需要, 添加 #include
-- (但同一 TU 中混用 #include 和 import 有风险; 要么对这类文件
-- 继续使用 compat.asio, 要么在 .cppm 文件的模块前导区
-- 仅添加全局性 #include)
-- [ ] 构建时间: 首次构建较慢 (编译 asio.cpp), 增量构建更快
-- (BMI 缓存)。总体上更大的目标文件被跨 TU 更少的模板实例化抵消。
-- 未导出的组件
-- * SSL/TLS (`asio/ssl/*.hpp`)：需要 OpenSSL/wolfSSL 等外部依赖。
-- * Unix 域套接字、POSIX 描述符和 Windows 句柄：
-- `asio/local/*.hpp`、`asio/posix/*.hpp`、`asio/windows/*.hpp`。
-- * 串口、pipe 和文件 I/O：`asio/serial_port.hpp`、
-- `asio/*able_pipe.hpp`、`asio/stream_file.hpp`、
-- `asio/random_access_file.hpp`。
-- * spawn()/yield_context 有栈协程：需要 Boost.Context；本包禁用其自动
-- 检测，应改用 co_spawn + awaitable + use_awaitable。
-- * deadline_timer、generic protocol、execution、traits、遗留宏式协程和
-- streambuf：对应 `asio/deadline_timer.hpp`、`asio/generic/*.hpp`、
-- `asio/execution/*.hpp`、`asio/traits/*.hpp`、`asio/yield.hpp`、
-- `asio/coroutine.hpp`、`asio/streambuf.hpp`。
package = {
spec = "1",
namespace = "chriskohlhoff",
name = "chriskohlhoff.asio",
name = "asio",
description = "Standalone asio exposed as the C++23 module `asio` (separate compilation)",
licenses = {"BSL-1.0"},
repo = "https://github.com/chriskohlhoff/asio",
Expand All @@ -210,10 +64,10 @@ package = {
},
},
windows = {
-- Same symlink-free repack as compat.asio: upstream's tag archives
-- carry two POSIX symlinks (asio/include -> ../include,
-- asio/src -> ../src) that tar.exe cannot materialize on the
-- Windows runner. Provenance: xlings-res/asio README.
-- Upstream tag archives carry two POSIX symlinks
-- (asio/include -> ../include, asio/src -> ../src) that tar.exe
-- cannot materialize on the Windows runner. This uses the existing
-- symlink-free repack documented by xlings-res/asio.
["1.38.1"] = {
url = {
GLOBAL = "https://github.com/xlings-res/asio/releases/download/1.38.1/asio-1.38.1-nosymlinks.tar.gz",
Expand Down Expand Up @@ -390,12 +244,11 @@ using ::asio::this_coro::reset_cancellation_state;
-- to every consumer TU (the module BMI and the consumer must agree on
-- ASIO_SEPARATE_COMPILATION or the inline/extern split miscompiles).
--
-- ASIO_HAS_THREADS: same rationale as compat.asio -- asio's thread
-- detection keys off CRT macros (_MT/_REENTRANT/_POSIX_THREADS) the
-- workspace's llvm-on-Windows toolchain does not define, silently
-- selecting null_thread; pin the detection result. asio only ever
-- tests defined(ASIO_HAS_THREADS), and on POSIX the pthread selection
-- beneath it still runs, so this is a no-op where detection works.
-- ASIO_HAS_THREADS: asio's detection keys off CRT macros
-- (_MT/_REENTRANT/_POSIX_THREADS) that the workspace's llvm-on-Windows
-- toolchain does not define, otherwise silently selecting null_thread.
-- Pin the known multithreaded package contract; POSIX pthread selection
-- still runs beneath this define where applicable.
features = {
["default"] = { implies = { "separate-compilation" } },
["separate-compilation"] = {
Expand Down
95 changes: 0 additions & 95 deletions pkgs/c/compat.asio.lua
View file
Open in desktop

This file was deleted.

Loading
Loading