CPython 为 `curses` 模块自动探测宽字符 ncurses:构建系统修复详解
CPython 为 curses 模块自动探测宽字符 ncurses:构建系统修复详解
导读
在 CPython 源码仓库中,Misc/NEWS.d/next/Build/2026-07-19-12-16-31.gh-issue-154070.f5da07.rst 记录了一次针对构建系统的功能修复:当系统中存在宽字符(wide-character)能力完备的 ncurses 库、但其库名并不叫 ncursesw 时(典型如 pkgsrc 为 NetBSD/illumos 提供的 ncurses,以及 macOS 的系统 ncurses),CPython 的配置脚本现在也能正确识别并把它当作宽字符版本来构建 curses 模块。本文以此变更日志为骨架,深入 CPython 的 configure.ac 与 Modules/_cursesmodule.c 源码,说明窄/宽字符构建的差异、新探测逻辑的工作原理、相关配置参数与验证方式,帮助你在各平台上获得具备完整 Unicode 支持的 curses 模块。
背景:为什么"名字带不带 w"很重要
窄字符与宽字符 ncurses 的区别
ncurses 有两个常见形态:
- 窄字符版本(narrow build):
chtype的字符位只有 8 位,addch()/inch()等 API 只能处理单字节字符,遇到中文、日文、Emoji 等多字节 UTF-8 序列会被截断或乱码。 - 宽字符版本(wide build):通过
--enable-widec编译,提供cchar_t、setcchar()、add_wch()、win_wch()等宽字符 API,字符以码点(code point)为单位处理,才能正确显示多字节 Unicode 文本。
在绝大多数 Linux 发行版上,宽字符版本被安装为单独的 libncursesw(对应头文件 ncursesw/curses.h、pkg-config 名 ncursesw),所以"宽字符能力"几乎与"库名 ncursesw"画等号。但并非所有平台都遵循这一约定:
- pkgsrc(NetBSD/illumos 等):
--enable-widec编译出的 ncurses 仍保留普通名字ncurses,只有ncursesw头文件/库的符号名;严格说,其头文件位于ncursesw/下,但库本身可能只叫ncurses。 - macOS:系统自带的 ncurses 将宽字符支持合并在
libncurses/libpanel中,系统里没有独立的/usr/lib/libncursesw或libpanelw。
在这些系统上,如果 CPython 配置脚本仅仅因为找不到 ncursesw 就退回"窄字符构建",用户得到的 curses 模块将无法正确处理宽字符文本——这正是本变更要修复的问题:"库名不带 w,不代表它不具备宽字符能力"。
变更核心:按能力探测,而非按名字假设
本变更的核心逻辑位于 configure.ac(约 7364~7390 行)。在选定后端、并确定 have_curses != "no" 之后,配置脚本不再信任库名,而是直接做一次链接级能力探测:
dnl A curses that is not named "ncursesw" can still be wide-character capable:
dnl the system curses of NetBSD, or an ncurses built with --enable-widec that
dnl keeps the plain name (pkgsrc, macOS). Probe for the wide API and, if
dnl present, build the module wide by defining HAVE_NCURSESW. The "ncursesw"
dnl backend already defines it, so only the other backends are probed.
AS_CASE([$with_curses], [ncursesw|no], [], [
save_curses_cppflags=$CPPFLAGS
AS_VAR_APPEND([CPPFLAGS], [" $CURSES_CFLAGS"])
AC_CACHE_CHECK([whether curses supports wide characters],
[ac_cv_curses_wide],
[AC_LINK_IFELSE(
[AC_LANG_PROGRAM([_CURSES_INCLUDES], [[
cchar_t wcval;
setcchar(&wcval, L"x", A_NORMAL, 0, NULL);
add_wch(&wcval);
]])],
[ac_cv_curses_wide=yes],
[ac_cv_curses_wide=no])])
CPPFLAGS=$save_curses_cppflags
dnl HAVE_NCURSESW marks the wide (cchar_t) curses API; its template comes
dnl from the ncursesw pkg-config check above, so no description here.
AS_VAR_IF([ac_cv_curses_wide], [yes], [AC_DEFINE([HAVE_NCURSESW], [1])])
])
几个关键设计点:
- 探测范围:只有
ncurses与curses后端(即--with-curses=ncurses或--with-curses=curses)会被探测;ncursesw后端本来就保证宽字符,无需探测;no后端则完全跳过。 - 探测方法:使用
AC_LINK_IFELSE做真正的编译+链接验证——测试程序通过_CURSES_INCLUDES引入正确头文件(见 configure.ac,该宏会按HAVE_NCURSESW_NCURSES_H、HAVE_NCURSESW_CURSES_H、HAVE_NCURSES_NCURSES_H等探测结果依次选择ncursesw/ncurses.h、ncursesw/curses.h、ncurses/curses.h……直至curses.h),然后声明cchar_t变量、调用setcchar()与add_wch()。只要这三者能链接成功,就认定该库具备宽字符 API。 - CFLAGS 联动:探测时把调整后的
CURSES_CFLAGS(macOS 会追加-D_XOPEN_SOURCE_EXTENDED=1,见 configure.ac,因为宽字符声明依赖该宏)拼进CPPFLAGS,确保宽字符声明在探测期间可见;探测结束后用专用变量save_curses_cppflags恢复现场(注释说明外层WITH_SAVE_ENV的CPPFLAGS槽位不可重入)。 - 结果落点:探测通过则定义
HAVE_NCURSESW宏。该宏贯穿Modules/_cursesmodule.c全程(出现约 60 处),是"按宽字符 API 编译"的总开关,同时也会写入生成的 pyconfig.h。
探测前的平台铺垫
在探测之前,配置脚本还做了两件配套工作,可从 configure.ac 看到:
- 剥离冲突宏:
CURSES_CFLAGS/PANEL_CFLAGS中由 pkg-config 带来的-D_XOPEN_SOURCE=600会被移除,因为pyconfig.h已经统一把_XOPEN_SOURCE设为 700,避免重复定义冲突。 - macOS 特判:当
ac_sys_system为Darwin时,向CURSES_CFLAGS追加-D_XOPEN_SOURCE_EXTENDED=1。macOS 没有单独的libncursesw/libpanelw,系统 ncurses 把宽字符支持合并在libncurses/libpanel中,这条宏正是让宽字符声明在 macOS 系统 ncurses 头文件中可见的关键。
后端选择参数:--with-curses
本变更所属的 curses 构建体系支持通过配置参数显式选择后端,完整的取值说明在 configure.ac:
AC_ARG_WITH(
[curses],
[AS_HELP_STRING([--with(out)-curses@<:@=ncursesw|ncurses|curses|no@:>@],
[select the curses backend for the curses and _curses_panel
modules, or disable them (default: auto)])],
...)
各取值含义如下:
| 取值 | 行为 |
|---|---|
auto(默认) |
先尝试 pkg-config 找 ncursesw + panelw,失败则回退找 ncurses + panel;永远不会选择原生 curses。对应 configure.ac 中的 PY_CHECK_CURSES([ncursesw], [panelw]) 及失败后的 PY_CHECK_CURSES([ncurses], [panel]) |
ncursesw |
强制宽字符 ncurses 后端,curses_libs="ncursesw"、panel_libs="panelw gnupanel" |
ncurses |
强制普通 ncurses 后端(不一定宽字符,由本次新探测决定),curses_libs="ncurses"、panel_libs="panel gnupanel" |
curses |
强制链接系统原生 curses(如 NetBSD、Solaris 的 libcurses)。原生 curses 没有 pkg-config 文件,auto 模式永远不会选中它;头文件探测也仅限 curses.h/panel.h,避免与 ncurses 头文件混用产生不兼容声明(configure.ac) |
no / --without-curses |
彻底禁用 curses 与 _curses_panel 模块,curses_libs/panel_libs 置空 |
PY_CHECK_CURSES 宏(configure.ac)通过 PKG_CHECK_MODULES 查找库并定义 HAVE_NCURSESW/HAVE_NCURSES 及对应的 HAVE_PANELW/HAVE_PANEL 宏;它还专门处理了 pkgsrc 把面板库改名为 gnupanel 的情况(configure.ac),避免与系统 libpanel 冲突。
链接兜底
即使 pkg-config 探测失败,配置脚本仍会尝试直接用链接器搜索来兜底(configure.ac):用 AC_SEARCH_LIBS 依次在 $curses_libs 中找 initscr、在 $panel_libs 中找 update_panels。扩展模块不链接 LIBS,因此这里显式构造 LIBS="$CURSES_LIBS $PANEL_LIBS",保证找到的库会被真正用于链接。
模块启用与 Setup.stdlib.in
探测结果最终决定是否构建 _curses 与 _curses_panel 扩展模块。configure.ac 中:
PY_STDLIB_MOD([_curses],
[], [test "$have_curses" = "yes"],
...)
PY_STDLIB_MOD([_curses_panel],
[], [test "$have_curses" = "yes" && test "$have_panel" = "yes"],
...)
PY_STDLIB_MOD 会把符合条件的模块写入 Modules/Setup.stdlib.in,从而纳入构建;同时 configure 生成的脚本里也能看到 with_curses 变量与 --with(out)-curses[=ncursesw|ncurses|curses|no] 帮助文本(configure)。
HAVE_NCURSESW 宏如何在模块源码中生效
宽字符 API 的分支编译
Modules/_cursesmodule.c 中几乎所有宽字符功能都被 #ifdef HAVE_NCURSESW 包裹。以字符转换逻辑为例(Modules/_cursesmodule.c):宽构建下,PyCurses_ConvertToWideCell() 把 Python str(一个可显示字符后跟至多 CCHARW_MAX - 1 个组合字符)转成 wchar_t 数组,再经 setcchar() 写入 cchar_t;若字符串含内嵌 \0 或首字符不是可显示字符,则抛出 TypeError/ValueError。非宽构建则退化为 PyCurses_ConvertToChtype(),按字节处理。这是"宽字符支持"在 Python 层的直接体现。
inch() 同样有分支(Modules/_cursesmodule.c):注释明确指出,ncursesw 的 winch() 返回整个码点,会溢出 chtype 的 8 位字符字段、污染颜色与属性位,因此宽构建改用 win_wch()/mvwin_wch() 读取 cchar_t 单元,再经 curses_getcchar() 还原为宽字符与属性。
扩展颜色支持
HAVE_NCURSESW 还参与"扩展颜色"能力的判定(Modules/_cursesmodule.c):
#if defined(HAVE_NCURSESW) && NCURSES_EXT_FUNCS+0 >= 20170401 && NCURSES_EXT_COLORS+0 >= 20170401
#define _NCURSES_EXTENDED_COLOR_FUNCS 1
#else
#define _NCURSES_EXTENDED_COLOR_FUNCS 0
#endif
开启后,_curses 会使用 init_extended_color()/init_extended_pair()/extended_color_content() 等扩展函数,并把颜色值类型从 short 提升为 int,突破传统 16/256 色的限制。
变更验证
CPython 的 curses 测试套件在 Lib/test/test_curses.py 中:
test_has_key(Lib/test/test_curses.py)验证has_key()返回bool;has_key在_curses缺失时由 Lib/curses/init.py 回退到纯 Python 的Lib/curses/has_key.py实现;test_use_default_colors(Lib/test/test_curses.py)验证默认配色支持;test_has_extended_color_support(Lib/test/test_curses.py)与 1081、2216、2221 行附近对has_extended_color_support()的检查,验证扩展颜色在宽构建下的可用性。
这些测试是"宽字符探测正确生效"的行为级验证——若构建系统把宽能力库误判为窄构建,相关测试就会失败。
影响与验证建议
本变更直接改善了以下场景的用户体验:
- pkgsrc/NetBSD/illumos:即使 ncurses 保持
ncurses名字(且面板库叫gnupanel),curses模块也能以宽字符构建; - macOS:系统 ncurses 无
libncursesw,但模块仍能获得完整 Unicode 支持; - 其他
--enable-widec且保留原名的发行版:同样受益。
配置时可用以下方式验证宽字符能力是否生效:
# 查看 configure 最终采用的配置与探测结果
./configure --with-curses=auto
grep -E "HAVE_NCURSESW|HAVE_NCURSES" pyconfig.h
# 构建后在交互式解释器中确认宽字符行为
./python -c "import curses; print(curses.COLORS, curses.COLOR_PAIRS)"
./python -c "import curses; curses.setupterm(); print('wide OK')"
若 pyconfig.h 中出现 #define HAVE_NCURSESW 1,即说明探测成功、模块将以宽字符 API 编译;配合 Lib/test/test_curses.py 运行 ./python -m test test_curses 可做端到端验证。
小结
CPython 通过本次变更,把"curses 是否宽字符"的判定从库名约定(ncursesw)升级为链接级能力探测(cchar_t + setcchar + add_wch),并统一以 HAVE_NCURSESW 宏驱动模块源码的分支编译。对 pkgsrc、macOS 这类"宽库不带 w 名"的平台,这是一个低侵入、高收益的构建系统修复,也再次体现了 CPython 在可移植性上一贯的务实做法:不假设平台命名习惯,只相信编译器的链接结果。