Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 4 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 \
Expand Down
19 changes: 13 additions & 6 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down
19 changes: 19 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
14 changes: 13 additions & 1 deletion cpp-pinyin2.pc.in
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/RELEASE_CHECKLIST.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` 随包进 `<dist-info>/`(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 移除)。

Expand Down
3 changes: 2 additions & 1 deletion docs/RELEASE_RUNBOOK.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 每次构建都在跑) |

---
Expand Down
42 changes: 41 additions & 1 deletion python/tools/ci_manylinux_aarch64.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
30 changes: 24 additions & 6 deletions tests/install/check_install_consumer.cmake
Original file line number Diff line number Diff line change
Expand Up @@ -137,19 +137,37 @@ 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.
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
Expand Down
Loading