CPython 为 `curses` 模块自动探测宽字符 ncurses:构建系统修复详解

原创2026-09-09 19:31:081,762 阅读
文章标签:编程语言语言运行时解释器标准库并发编程

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])])
])

几个关键设计点:

  1. 探测范围:只有 ncurses 与 curses 后端(即 --with-curses=ncurses 或 --with-curses=curses)会被探测;ncursesw 后端本来就保证宽字符,无需探测;no 后端则完全跳过。
  2. 探测方法:使用 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。
  3. CFLAGS 联动:探测时把调整后的 CURSES_CFLAGS(macOS 会追加 -D_XOPEN_SOURCE_EXTENDED=1,见 configure.ac,因为宽字符声明依赖该宏)拼进 CPPFLAGS,确保宽字符声明在探测期间可见;探测结束后用专用变量 save_curses_cppflags 恢复现场(注释说明外层 WITH_SAVE_ENV 的 CPPFLAGS 槽位不可重入)。
  4. 结果落点:探测通过则定义 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 在可移植性上一贯的务实做法:不假设平台命名习惯,只相信编译器的链接结果。

登录后查看全文
cpython