CPython curses 模块构建改进:用 configure 能力探测替代 ncurses 假设,适配窄字符库与 NetBSD curses

原创2026-09-09 21:58:271,695 阅读
文章标签:编程语言语言运行时解释器标准库并发编程

CPython curses 模块构建改进:用 configure 能力探测替代 ncurses 假设,适配窄字符库与 NetBSD curses

导读

CPython 的 curses 模块(及其面板扩展 _curses_panel)在历史上默认假设底层实现是 ncurses,并按 ncurses 的特性集编译模块。这一假设在遇到窄字符(non-wide)ncurses、NetBSD 系统 curses 等实现时会失效。本仓库的新变更(见 Misc/NEWS.d/next/Build/2026-06-28-16-17-55.gh-issue-152502.6SNqMg.rst)改为在 configure 阶段用能力探测(capability probe)逐项检测 curses 的可选函数,使模块能够针对窄字符 ncurses 及其他 curses 实现(如 NetBSD curses)正常构建,并只暴露这些实现实际提供的函数。读完本文,你将理解该机制在 configure.ac 中的实现原理、探测宏的工作方式、--with-curses 后端选择规则,以及模块源码如何按 HAVE_CURSES_* 宏做条件编译。

变更背景:为什么“假设 ncurses”不可靠

curses 是一个存在大量变体的 C 库家族。除了最流行的 ncurses(又分为普通版与 --enable-widec 宽字符版),还有 NetBSD、OpenBSD、Solaris/illumos 自带的系统 curses,以及 PDCurses 等移植实现。不同实现的 API 面并不一致:

  • 宽字符接口(cchar_t、setcchar、add_wch 等)只存在于宽字符构建;
  • 可选函数(如 immedok、syncok、resize_term、has_key、slk_attr_on 等)并非每个实现都有;
  • 同名函数签名可能不同,例如 PDCurses 声明的是 getmouse(void),而 X/Open 标准签名是 getmouse(MEVENT *)。

旧逻辑“假设 ncurses”意味着:要么在缺少某些函数的实现上编译失败,要么暴露出底层库并不支持、调用即出错的接口。新方案的核心思路在 NEWS 条目中一句话即可概括:以 configure 能力探测替代假设,暴露底层实现恰好提供的函数集合。

核心机制:PY_CHECK_CURSES_FUNC / PY_CHECK_CURSES_VAR 探测宏

新逻辑定义在 configure.ac 中,由两个 autoconf 宏驱动:

函数探测 PY_CHECK_CURSES_FUNC(FUNCTION)

对传入的函数名 $1,构造一段依赖 _CURSES_INCLUDES 的编译测试:

AC_DEFUN([PY_CHECK_CURSES_FUNC],
[ AS_VAR_PUSHDEF([py_var], [ac_cv_lib_curses_$1])
  AS_VAR_PUSHDEF([py_define], [HAVE_CURSES_]m4_toupper($1))
  AC_CACHE_CHECK(
    [for curses function $1],
    [py_var],
    [AC_COMPILE_IFELSE(
      [AC_LANG_PROGRAM(_CURSES_INCLUDES, [
        #ifndef $1
        void *x=$1
        #endif
      ])],
      [AS_VAR_SET([py_var], [yes])],
      [AS_VAR_SET([py_var], [no])])]
  )
  AS_VAR_IF(
    [py_var],
    [yes],
    [AC_DEFINE([py_define], [1], [Define if you have the '$1' function.])])
  AS_VAR_POPDEF([py_var])
  AS_VAR_POPDEF([py_define])
])

要点:

  • 使用 AC_COMPILE_IFELSE(仅编译、不链接),因此不要求目标库以链接库形式存在,也避免了运行期探测在交叉编译下的不可用性;
  • 测试代码取函数地址 void *x = $1,若该函数未被底层头文件声明,编译即失败,探测结果为 no;
  • 结果以缓存变量 ac_cv_lib_curses_$1 缓存,命中时定义 HAVE_CURSES_<函数名大写> 宏;
  • _CURSES_INCLUDES 负责按 HAVE_NCURSESW_NCURSES_H → HAVE_NCURSESW_CURSES_H → HAVE_NCURSES_NCURSES_H → HAVE_NCURSES_CURSES_H → HAVE_NCURSES_H → HAVE_CURSES_H 的优先级选择头文件,并在包含前预定义 NCURSES_OPAQUE 0,确保 ncurses ≥ 5.7 暴露结构体字段(见 configure.ac)。

变量/宏探测 PY_CHECK_CURSES_VAR(VARIABLE)

函数探测无法覆盖整数变量或宏(如 ESCDELAY、TABSIZE),因此新增了变量探测变体,测试代码为 int x = $1; (void)x;,命中时同样定义 HAVE_CURSES_<名称大写>(见 configure.ac)。

完整的探测清单

configure.ac 依次探测以下函数与变量,结果分别对应 _cursesmodule.c 中的一个 #ifdef HAVE_CURSES_* 条件块:

类别 探测目标 对应宏
窗口与尺寸 is_pad、is_term_resized、resize_term、resizeterm HAVE_CURSES_IS_PAD 等
刷新与同步 immedok、syncok HAVE_CURSES_IMMEDOK、HAVE_CURSES_SYNCOK
属性 wchgat、wattr_get、wattr_set、wattr_on、wattr_off、wcolor_set HAVE_CURSES_WCHGAT、HAVE_CURSES_WATTR_GET 等
过滤与输入 filter、nofilter、typeahead、use_env HAVE_CURSES_FILTER、HAVE_CURSES_NOFILTER 等
键盘与鼠标 has_key、has_mouse、is_keypad、is_leaveok、key_defined、define_key、keyok HAVE_CURSES_HAS_KEY、HAVE_CURSES_HAS_MOUSE 等
终端控制 set_escdelay、set_tabsize、term_attrs、ESCDELAY、TABSIZE HAVE_CURSES_SET_ESCDELAY、HAVE_CURSES_TERM_ATTRS 等
多屏/软标签 new_prescr、use_screen、use_window、slk_attr_on、slk_attr_off、slk_attr_set、slk_color HAVE_CURSES_NEW_PRESCR、HAVE_CURSES_SLK_* 等
屏幕转储 scr_dump、scr_set HAVE_CURSES_SCR_DUMP、HAVE_CURSES_SCR_SET

其中 wattr_*/slk_* 系列被注释明确为 X/Open attr_t 接口,旧的 SVr4 curses(如 illumos 自带的)并不提供,这正是不再假设 ncurses 后需要逐项探测的典型场景。

两个特殊探测

除了上述通用宏,还有两处签名级探测:

  1. getmouse 的 X/Open 签名:PDCurses 在未启用 ncurses 鼠标 API 时声明 getmouse(void),与标准 getmouse(MEVENT *) 不兼容。因此单独编译测试 MEVENT event; (void)getmouse(&event);,成功才定义 HAVE_CURSES_GETMOUSE(见 configure.ac)。
  2. scr_dump 与 scr_set 分开探测:scr_dump 同时是 scr_dump/scr_restore/scr_init 的门槛,而 scr_set 独立探测,因为旧 SVr4 curses 有前者却没有后者(见 configure.ac)。

宽字符支持:不再依赖“库名带 w”

除了可选函数,宽字符能力的判定也同步去除了“假设”。注释明确指出(见 configure.ac):

一个不叫 “ncursesw” 的 curses 仍然可能是宽字符的:NetBSD 的系统 curses,或一个以 --enable-widec 构建但保留普通名字的 ncurses(pkgsrc、macOS)。

因此在非 ncursesw 后端下,configure 会用调整后的 CURSES_CFLAGS(例如 macOS 追加的 -D_XOPEN_SOURCE_EXTENDED=1,见 configure.ac)编译一段调用 cchar_t、setcchar、add_wch 的链接测试:

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

命中即定义 HAVE_NCURSESW,把该库“当作宽字符版”构建模块。这也是 NEWS 条目所讲“能针对窄字符 ncurses 构建”的镜像:宽窄判定由探测结果决定,而不是由库名或默认假设决定。

后端选择:--with-curses 与自动回退

能力探测运行在指定的 curses 后端之上。新增的 --with-curses 选项(见 configure.ac)显式选择后端:

--with-curses[=ncursesw|ncurses|curses|no]
  • auto(默认):优先用 pkg-config 找 ncursesw,失败再回退 ncurses,但永不选择原生 curses;
  • ncursesw / ncurses:分别通过 PKG_CHECK_MODULES 检查 ncursesw+panelw、ncurses+panel(面板还有 gnupanel 别名,因为 pkgsrc 为避免与系统 libpanel 冲突而重命名,见 configure.ac);
  • curses:链接系统原生 curses(NetBSD、Solaris 等),这类库通常没有 .pc 文件,因此交给头文件与链接探测(AC_SEARCH_LIBS 回退到 initscr/update_panels,见 configure.ac);
  • no:禁用 curses 与 _curses_panel 两个模块。

头文件探测也按后端区分:原生 curses 后端只探测 curses.h/panel.h,避免系统同时存在 ncurses 头文件时,把 ncurses 的声明(如 tparm())与原生库混链造成 ABI 错配(见 configure.ac)。

模块侧:暴露“恰好提供的函数”

configure 产出的 HAVE_CURSES_* 宏写入 pyconfig.h(模板见 pyconfig.h.in,包含全部 #undef 声明),随后在模块源码中驱动条件编译。以 _cursesmodule.c 为例:

  • immedok/syncok 的窗口方法被 #ifdef HAVE_CURSES_IMMEDOK / HAVE_CURSES_SYNCOK 包裹(见 Modules/_cursesmodule.c),底层库不提供时,对应 Python 方法也不会注册;
  • attr_get/attr_set/attr_on/attr_off/color_set 分别由 HAVE_CURSES_WATTR_GET 等宏控制(见 Modules/_cursesmodule.c);
  • scr_dump/scr_set、has_key/define_key/key_defined/keyok、new_prescr、ESCDELAY/set_escdelay、is_term_resized/resize_term/resizeterm、term_attrs、typeahead、use_env、slk_attr_*/slk_color 等均按同样模式条件编译(对应行号参见 Modules/_cursesmodule.c 区间的 #ifdef HAVE_CURSES_*)。

因此“暴露的 Python 级 API”与底层库的能力一一对应:探测到才定义宏,定义宏才编译进模块。这与标准库文档中反复出现的措辞一致——例如 alloc_pair/free_pair/find_pair 明确标注“仅在以支持扩展颜色的宽字符 curses 构建时可用”(见 Doc/library/curses.rst),Doc 中也有多处 “available on a narrow build” 的差异化说明,体现同一套“按实际能力暴露 API”的设计哲学。

对构建者与打包者的影响

对普通用户而言,构建流程没有变化:

./configure && make

能力探测是 configure 阶段自动完成的,无需额外参数即可获得正确结果。以下场景受益最明显:

  • 窄字符 ncurses(未启用 widec):旧假设会导致构建失败或导出无意义的宽字符接口,现在模块会按窄库能力编译;
  • NetBSD 等系统原生 curses:通过 --with-curses=curses 显式选择后,可选函数按探测结果暴露;
  • 交叉编译/打包:AC_CACHE_CHECK 缓存变量(ac_cv_lib_curses_*)可预置,保证探测可复现;
  • 需要禁用时,--without-curses 等价于 --with-curses=no。

总结

这条变更的本质,是把 curses 模块的构建从“面向 ncurses 的假设式编译”重构为“面向任意 curses 实现的能力探测式编译”:

  1. configure.ac 新增 PY_CHECK_CURSES_FUNC / PY_CHECK_CURSES_VAR 宏,逐项编译探测 30 余个可选函数与变量;
  2. getmouse 签名、scr_dump/scr_set 分离、宽字符 API 三个特殊场景单独探测;
  3. --with-curses[=ncursesw|ncurses|curses|no] 让后端选择显式可控;
  4. _cursesmodule.c 依据 pyconfig.h 中的 HAVE_CURSES_* 宏条件编译,保证 Python 侧 API 与底层库能力严格一致。

对构建者和嵌入式/BSD 平台的用户来说,这意味着 curses 模块的可移植性显著提升:同一份 CPython 源码,可以在更广泛的 curses 实现上干净地构建,且不会暴露底层库根本不支持的接口。

登录后查看全文
cpython