diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7aef006..9948142 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -264,8 +264,10 @@ jobs: # never wired on Apple" would answer neither question. Turn the tests on as its own change, once this # leg has run green at least once. # - # UNVERIFIED when written: no macOS toolchain on the machine this was written on, and nothing had run - # it when the change landed. Do not read it as coverage until a run says so. + # UNVERIFIED WHEN WRITTEN; IT HAS SINCE RUN (2026-11-21): the leg's first push was run 44859037261 + # (commit 9938d3d, the merge of #15) and step 10 of this job is green there -- as it is in #15's own + # run 44858155866. That is also the first independent confirmation that #14 is what fixed Apple's + # archive step: this build reaches that step and passes no `D`. - name: Build the static configuration (Apple's ar has no `D` modifier -- see PR #14) run: | cmake -S . -B build-static \ diff --git a/CMakeLists.txt b/CMakeLists.txt index 1a7ab64..6a37477 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -653,12 +653,19 @@ endif () if (CPP_PINYIN2_INSTALL) set(version ${PROJECT_VERSION}) - # Cflags has to say what the CMake target says (2026-10-20 audit, G11). Two gaps were measured: - # `CPP_PINYIN2_STATIC` is a PUBLIC compile definition (it selects the no-dllimport branch of - # PinyinGlobal.h), so a pkg-config consumer of a STATIC install that does not get it compiles - # against the dllimport branch -- harmless on ELF where both spell the same, wrong on MSVC/MinGW; - # and the library needs C++17, which pkg-config consumers were never told. Neither is inherited - # from the .pc the way they are from the CMake target, so both are written out here. + # Cflags has to say what the CMake target says, with ONE exception that an outside report got right + # (issue #13, 2026-11-21). `CPP_PINYIN2_STATIC` is a PUBLIC compile definition (it selects the + # no-dllimport branch of PinyinGlobal.h), so a pkg-config consumer of a STATIC install that does not get + # it compiles against the dllimport branch -- harmless on ELF where both spell the same, wrong on + # MSVC/MinGW. That one stays in Cflags. + # + # THE C++17 REQUIREMENT DOES NOT. `Cflags` reaches whatever compiler the consumer runs, and this package + # serves a C header as well (`ext/c_api.h`): clang rejects a C++ standard option outright in C mode and + # gcc only warns, so a C consumer's fate depended on which compiler it used. Nor can pkg-config express + # "at least 17" -- a consumer that chose C++20 would have the option appended after its own `-std=` and + # be dropped back to 17, because the last one wins. The requirement is exported as the `cxx_std` variable + # in cpp-pinyin2.pc.in instead (ask for it with `pkg-config --variable=cxx_std`), while the CMake target + # keeps stating it properly as `cxx_std_17`, which means "at least" and is what the headers need. set(CPP_PINYIN2_PC_EXTRA_CFLAGS "") if (NOT BUILD_SHARED_LIBS) set(CPP_PINYIN2_PC_EXTRA_CFLAGS " -DCPP_PINYIN2_STATIC") diff --git a/README.md b/README.md index 6e0a70b..5d9f486 100644 --- a/README.md +++ b/README.md @@ -191,6 +191,25 @@ add_custom_command(TARGET your_app POST_BUILD The package refuses a **cross-major** request on purpose (`COMPATIBILITY SameMajorVersion`), so a 1.x `find_package(cpp-pinyin2 1.x)` does not silently resolve to a 2.x install. +**pkg-config.** The install also carries `lib/pkgconfig/cpp-pinyin2.pc`, for consumers that do not use CMake: + +```sh +pkg-config --cflags --libs cpp-pinyin2 # -I…/include -L…/lib -lcpp-pinyin2 +pkg-config --variable=dictdir cpp-pinyin2 # where this install put the dictionaries +pkg-config --variable=cxx_std cpp-pinyin2 # the C++ mode these headers need (-std=c++17) +``` + +`cxx_std` is a **variable and not a `Cflags` entry** on purpose (issue #13): `Cflags` reaches whatever +compiler you run — this package also installs a C header (`include/cpp-pinyin2/ext/c_api.h`), and clang +refuses a C++ standard option in C mode — and pkg-config cannot say "at least 17", so an entry there would +override your own `-std=c++20` with `-std=c++17` (the last one on the command line wins). Apply the variable +yourself only if your compiler defaults to something older than C++17: + +```sh +g++ $(pkg-config --cflags cpp-pinyin2) $(pkg-config --variable=cxx_std cpp-pinyin2) \ + your_app.cpp $(pkg-config --libs cpp-pinyin2) +``` + **Per-character alignment.** Downstream morphology/TTS code usually needs "which reading belongs to which input character". One row of a `Result` covers **one input span**, and the spans are a partition of your input — the contract is that **concatenating every row's `text` in order reproduces diff --git a/cpp-pinyin2.pc.in b/cpp-pinyin2.pc.in index 2f206ad..d64224b 100644 --- a/cpp-pinyin2.pc.in +++ b/cpp-pinyin2.pc.in @@ -15,13 +15,25 @@ includedir=${prefix}/include # "dict" subdirectory), and libdir/includedir must agree with CMAKE_INSTALL_LIBDIR/INCLUDEDIR. dictdir=${prefix}/@CMAKE_INSTALL_DATADIR@/cpp-pinyin2/dict +# THE C++ STANDARD, OFFERED AND NOT IMPOSED (2026-11-21, issue #13). These headers need C++17, but `Cflags` +# is the wrong channel to say so in, for two reasons that were each measured: +# * pkg-config has no per-language flag channel, so anything put there reaches a C compiler too -- and this +# package serves a C header (`ext/c_api.h`). clang rejects a C++ standard option outright in C mode +# ("invalid argument ... not allowed with 'C'") while gcc only warns, so a C consumer's fate depended on +# which compiler it used; +# * pkg-config cannot say "at least 17": a consumer that chose C++20 would get the option appended after +# its own and be dropped back to 17, because the last one on the command line wins. +# So the requirement is exported as a variable instead. `pkg-config --variable=cxx_std cpp-pinyin2` answers +# with the flag, and nothing applies it unless the consumer copies it onto its own command line. +cxx_std=-std=c++17 + Name: cpp-pinyin2 Description: A lightweight Chinese/Cantonese to Pinyin library. Version: @version@ Requires: Conflicts: -Cflags: -I${includedir} -std=c++17@CPP_PINYIN2_PC_EXTRA_CFLAGS@ +Cflags: -I${includedir}@CPP_PINYIN2_PC_EXTRA_CFLAGS@ Libs: -L${libdir} -lcpp-pinyin2 # Read by `pkg-config --static` only. `dl` is part of libc from glibc 2.34, so a static consumer on an # older glibc is the case this line exists for; CMakeLists.txt computes it from ${CMAKE_DL_LIBS}, which is diff --git a/docs/RELEASE_CHECKLIST.md b/docs/RELEASE_CHECKLIST.md index 7a5bccd..748be04 100644 --- a/docs/RELEASE_CHECKLIST.md +++ b/docs/RELEASE_CHECKLIST.md @@ -340,7 +340,7 @@ foreach ($d in @('.tmp\repro-a', '.tmp\repro-b')) { |---|---|---|---|---| | **PyPI** | 构建产物:`python/dist/` 下的 `cpp_pinyin2-2.0.0` wheel(**不入库、文件名随平台变**;2026-10-23 重建自压缩后的 `v2` 树) | `python/tools/check_wheel.py` **PASS**(成员逐字节);`check_bindings.py --wheel` **PASS**;`Requires-Python: >=3.9`;classifiers 与 5 条 project_urls;许可证表达式改为三项,`THIRD_PARTY_NOTICES.md` 随包进 `/`(2026-10-21 补) | manylinux / macOS 轮子(要 CI);`twine check` **本机没跑**(本机没装 `twine`);上传是**人的动作** | **`release_prep` 从未运行**(manylinux 轮子无来源);`twine check` 未跑;上传按 6.7.12 第三条 | | **NuGet** | `.tmp/pkgs/CppPinyin.2.0.0.nupkg`(单 RID `win-x64`,本机打;2026-10-23 重建自压缩后的 `v2` 树) | `check_bindings.py --nupkg` **PASS**(含 8+8 词典文件、`runtimes/win-x64/native`、三 TFM 的 `lib/` 与 `ref/`);nuspec 的 `projectUrl`/`repository`/`tags`/`releaseNotes`;**许可证文件** = 随包 `THIRD_PARTY_NOTICES.md`(2026-10-30 起;此前是三项表达式,nuget.org 拒收 `CC-BY-SA-3.0`) | 另外两个 RID 的包与池化(要 CI 的三个平台腿);上传是人的动作 | **`release_prep` 从未运行**(`linux-x64`/`osx-arm64` 与池化包无来源,见 §7.5) | -| **pkg-config** | 安装树里的 `lib/pkgconfig/cpp-pinyin2.pc` | 2026-10-21 读安装树逐字段核对:`prefix` 相对、`Version: 2.0.0`、`Cflags`/`Libs`/`dictdir` 齐全;由 `InstallConsumerSmoke` 这条 ctest 每次构建都验——**但 Windows 腿不跑该用例**(`ci.yml` 的 `-E '^InstallConsumerSmoke$'`,判词见 `docs/DECISIONS.md` 的 D45),所以这条覆盖在 Windows 侧是空的 | 无(随 CMake install 一起发);**静态消费面另有一处已知缺口**:`.pc` 没有 `Libs.private: -ldl`,而 `CMakeLists.txt` 说 glibc<2.34 上 `dladdr` 必须显式带 `dl` ⇒ `pkg-config --static` 在旧 glibc 上会链接失败,且该组合无门禁 | Windows 侧:`InstallConsumerSmoke` 的排除未撤;静态面:未验 | +| **pkg-config** | 安装树里的 `lib/pkgconfig/cpp-pinyin2.pc` | 2026-10-21 读安装树逐字段核对:`prefix` 相对、`Version: 2.0.0`、`Cflags`/`Libs`/`dictdir` 齐全;由 `InstallConsumerSmoke` 这条 ctest 每次构建都验。**2026-11-21 两处更正**:① Windows 腿对该用例的排除**已于 2026-10-27 撤除**(`c3a728c`,判词见 `docs/DECISIONS.md` D45),现在只剩 `linux-sanitizers` 腿为 ASan 运行时原因排除它(`ci.yml:176-181`);该腿 2026-11-21 的整轮运行为 success〔依据:job 绿 + 排除项已不在 windows 腿;未逐例看日志〕。② 静态消费面**不再是缺口**:`Libs.private` 已由 `${CMAKE_DL_LIBS}` 写进 `.pc`,并由 `ci_manylinux_aarch64.sh` 步骤 10 实测 `pkg-config --static`(2026-10-27 起)。③ 同一轮起 `Cflags` **不再带 `-std=`**(issue #13),C++17 要求改由 `.pc` 的 `cxx_std` 变量承载,门禁双向断言(`check_install_consumer.cmake`) | 无(随 CMake install 一起发);`.pc` 的三条读数可在本机实测:`--cflags` 不含 `-std=`、`--variable=cxx_std` = `-std=c++17`、`--variable=dictdir` 指向安装树(2026-11-21 实测于 Win64/MinGW + pkgconf 3.0.11) | Windows 侧:排除已撤且最近一轮整轮绿;静态面:容器步骤 10 实测;**仍缺**:一个"真用 `pkg-config` 编 C++ 消费端"的门禁(现有 C++ 侧只读 `.pc` 文本 + manylinux 步骤 10 的编译探针) | 三个渠道各自的**发版命令**在 [`RELEASE_RUNBOOK.md`](./RELEASE_RUNBOOK.md)——这份清单管"发之前验收什么",那份管"发布当天怎么敲"。vcpkg 不是渠道:仓库不提供端口(2026-10-23 移除)。 diff --git a/docs/RELEASE_RUNBOOK.md b/docs/RELEASE_RUNBOOK.md index 647b4f9..c0589ee 100644 --- a/docs/RELEASE_RUNBOOK.md +++ b/docs/RELEASE_RUNBOOK.md @@ -128,7 +128,8 @@ vcpkg 的"接受任意哈希",端口在那个状态下是不能发布的。 | 步骤 | 命令 | 判据 | |---|---|---| | 4.1 安装到临时前缀 | `cmake --install .tmp/build-default --prefix .tmp/prefix` | 生成 `lib/pkgconfig/cpp-pinyin2.pc` | -| 4.2 读 `.pc` | `$env:PKG_CONFIG_PATH=".tmp/prefix/lib/pkgconfig"; pkg-config --cflags --libs cpp-pinyin2` | 输出含 `-I…/include`、`-L…/lib`、`-lcpp-pinyin2` | +| 4.2 读 `.pc` | `$env:PKG_CONFIG_PATH=".tmp/prefix/lib/pkgconfig"; pkg-config --cflags --libs cpp-pinyin2` | 输出含 `-I…/include`、`-L…/lib`、`-lcpp-pinyin2`,**且 `Cflags` 里不得出现 `-std=`**(2026-11-21 起,判词见 issue #13) | +| 4.2b 读语言模式要求 | `pkg-config --variable=cxx_std cpp-pinyin2` | 输出 `-std=c++17`。这是"C++17 要求"的唯一可读出口,它**不进 `Cflags`**:pkg-config 没有 per-language 通道(本包同时装 C 头 `ext/c_api.h`,clang 在 C 模式下直接拒绝 C++ 标准选项),也无法表达"至少 17",进了 `Cflags` 就会覆盖消费方自己的 `-std=c++20` | | 4.3 消费者冒烟 | `ctest --preset default -R InstallConsumerSmoke` | PASS(这条 ctest 每次构建都在跑) | --- diff --git a/python/tools/ci_manylinux_aarch64.sh b/python/tools/ci_manylinux_aarch64.sh index aa540d5..80e370c 100644 --- a/python/tools/ci_manylinux_aarch64.sh +++ b/python/tools/ci_manylinux_aarch64.sh @@ -225,11 +225,15 @@ C_EOF # libstdc++: driving it with `gcc` failed with "undefined reference to std::__cxx11::basic_string<...>" and # "operator new" (measured here, manylinux aarch64, 2026-10-29). Adding -lstdc++ to the .pc would encode one # platform's runtime into a file that also ships for MSVC and Apple, so the link uses `g++` instead -- the - # same thing any consumer of a C++ library does, and `Cflags` already says `-std=c++17`. + # same thing any consumer of a C++ library does. # Word-splitting is the point here: the flags have to reach the compiler as separate arguments. # shellcheck disable=SC2046 gcc -c /tmp/static-consumer.c -o /tmp/static-consumer.o \ $(PKG_CONFIG_PATH="$pc_dir" pkg-config --static --cflags cpp-pinyin2) >> /tmp/static.txt 2>&1 + static_compile_rc=$? + echo "C consumer compile exit: $static_compile_rc" + check "a C consumer compiles through pkg-config's Cflags" \ + "$([ "$static_compile_rc" = 0 ] && echo 1 || echo 0)" "see /tmp/static.txt" # shellcheck disable=SC2046 g++ /tmp/static-consumer.o -o /tmp/static-consumer \ $(PKG_CONFIG_PATH="$pc_dir" pkg-config --static --libs cpp-pinyin2) >> /tmp/static.txt 2>&1 @@ -242,6 +246,42 @@ C_EOF else /tmp/static-consumer fi + # THE TWO DEFECTS THE OLD `Cflags` CAUSED, measured instead of argued (issue #13, 2026-11-21). The .pc used + # to name a C++ standard mode; each check below is exactly one of the two complaints it produced, and both + # compile with the same flags `pkg-config --cflags` prints. + # + # 1. A consumer that asked for C++20 FIRST and the package's flags SECOND. That order used to lose, because + # the last `-std=` on a command line wins. The TU asserts the mode itself instead of trusting some later + # construct to fail, so a regression reads as this #error and not as unrelated C++20 syntax. + cat > /tmp/static-consumer-cxx20.cpp <<'CPP_EOF' +#if __cplusplus < 202002L +#error "not in C++20 mode: something appended a language standard after the consumer's own choice" +#endif +int main() { return 0; } +CPP_EOF + # shellcheck disable=SC2046 + g++ -std=c++20 -c /tmp/static-consumer-cxx20.cpp -o /tmp/static-consumer-cxx20.o \ + $(PKG_CONFIG_PATH="$pc_dir" pkg-config --static --cflags cpp-pinyin2) >> /tmp/static.txt 2>&1 + cxx20_rc=$? + echo "C++20 consumer compile exit: $cxx20_rc" + check "the .pc's flags do not drop a C++20 consumer back to an older mode" \ + "$([ "$cxx20_rc" = 0 ] && echo 1 || echo 0)" "see /tmp/static.txt" + # 2. The C header compiled by a compiler that is STRICT about language modes. The gcc compile above cannot + # prove this -- gcc only warns. clang errors ("invalid argument ... not allowed with 'C'"), and clang is + # what a macOS or Android consumer of the C ABI builds with. When the image ships no clang the half stays + # unmeasured and says so out loud; that is not a failure, because an image not carrying clang is not a + # defect in this tree (the same distinction the ninja probe above draws). + if command -v clang >/dev/null 2>&1; then + # shellcheck disable=SC2046 + clang -c /tmp/static-consumer.c -o /tmp/static-consumer-clang.o \ + $(PKG_CONFIG_PATH="$pc_dir" pkg-config --static --cflags cpp-pinyin2) >> /tmp/static.txt 2>&1 + clang_rc=$? + echo "clang C consumer compile exit: $clang_rc" + check "a clang C consumer accepts the .pc's Cflags" \ + "$([ "$clang_rc" = 0 ] && echo 1 || echo 0)" "see /tmp/static.txt" + else + echo "NOT MEASURED: this image has no clang, so the strict-C-compiler half of issue #13 is unmeasured here" + fi else # NOT A SILENT SKIP (the reasoning check_format's `--require` spells out): this step exists only to # measure Libs.private, so an image without the tool means the -ldl claim stays unmeasured -- and a step diff --git a/tests/install/check_install_consumer.cmake b/tests/install/check_install_consumer.cmake index b49386a..45da6c5 100644 --- a/tests/install/check_install_consumer.cmake +++ b/tests/install/check_install_consumer.cmake @@ -137,10 +137,21 @@ message(STATUS "pkg-config dictdir points at the installed data: ${_pc_dict_dir} if (NOT _pc MATCHES "Version: ${VERSION}") message(FATAL_ERROR "cpp-pinyin2.pc does not carry Version: ${VERSION}.\n--- pc file ---\n${_pc}") endif () -# The Cflags line must say what the CMake target says (2026-10-20 audit, G11): the library requires -# C++17 and, in a static install, the consumer needs `CPP_PINYIN2_STATIC` too (it selects the -# no-dllimport branch of core/PinyinGlobal.h). Neither is inherited through the .pc the way it is -# through the exported CMake target, so a consumer that only uses pkg-config is the one who finds out. +# The Cflags line must say what the CMake target says, with ONE exception that an outside report got right +# (issue #13, 2026-11-21). `CPP_PINYIN2_STATIC` is a PUBLIC compile definition and, in a static install, a +# pkg-config consumer that does not get it compiles against the dllimport branch of core/PinyinGlobal.h +# (harmless on ELF where both spell the same, wrong on MSVC/MinGW). It is not inherited through the .pc the +# way it is through the exported CMake target, so a consumer that only uses pkg-config is the one who finds +# out -- and this gate keeps asserting it. +# +# A LANGUAGE MODE IS NOT ON THAT LIST, and asserting one here is what this gate used to do. `Cflags` reaches +# whatever compiler the consumer runs, and this package serves a C header too (`ext/c_api.h`): clang rejects +# a C++ standard option outright in C mode while gcc only warns, so a C consumer's fate depended on which +# compiler it used. A consumer that chose C++20 was silently dropped back to 17 as well, because the last +# `-std=` on the command line wins. The requirement moved to the `cxx_std` variable, which nothing applies +# unless the consumer asks for it -- so this gate now asserts BOTH halves: no standard mode in Cflags, and +# the requirement still readable from this file alone. +# # `BUILD_SHARED` is what tests/CMakeLists.txt passes; `BUILD_SHARED_LIBS` is unset inside a `-P` script # (a `-P` run has no cache), so testing the latter read as "static" in every configuration. Absent means # "not told", and the shared expectation is the lenient one: this leg must not invent a failure. @@ -148,8 +159,15 @@ set(_pc_expect_static OFF) if (DEFINED BUILD_SHARED AND NOT BUILD_SHARED) set(_pc_expect_static ON) endif () -if (NOT _pc MATCHES "Cflags:.*-std=c\\+\\+17") - message(FATAL_ERROR "cpp-pinyin2.pc's Cflags does not name -std=c++17.\n--- pc file ---\n${_pc}") +if (_pc MATCHES "Cflags:[^\r\n]*-std=") + message(FATAL_ERROR + "cpp-pinyin2.pc's Cflags names a language standard mode. pkg-config cannot scope that to C++, and " + "appended after a consumer's own choice it overrides it.\n--- pc file ---\n${_pc}") +endif () +if (NOT _pc MATCHES "cxx_std=-std=c\\+\\+17") + message(FATAL_ERROR + "cpp-pinyin2.pc does not export cxx_std with the C++17 requirement, so a consumer that reads only " + "this file cannot learn it.\n--- pc file ---\n${_pc}") endif () if (_pc_expect_static AND NOT _pc MATCHES "Cflags:.*-DCPP_PINYIN2_STATIC") message(FATAL_ERROR