CPython curses 模块构建改进:用 configure 能力探测替代 ncurses 假设,适配窄字符库与 NetBSD curses
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 后需要逐项探测的典型场景。
两个特殊探测
除了上述通用宏,还有两处签名级探测:
getmouse的 X/Open 签名:PDCurses 在未启用 ncurses 鼠标 API 时声明getmouse(void),与标准getmouse(MEVENT *)不兼容。因此单独编译测试MEVENT event; (void)getmouse(&event);,成功才定义HAVE_CURSES_GETMOUSE(见 configure.ac)。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 实现的能力探测式编译”:
configure.ac新增PY_CHECK_CURSES_FUNC/PY_CHECK_CURSES_VAR宏,逐项编译探测 30 余个可选函数与变量;getmouse签名、scr_dump/scr_set分离、宽字符 API 三个特殊场景单独探测;--with-curses[=ncursesw|ncurses|curses|no]让后端选择显式可控;_cursesmodule.c依据pyconfig.h中的HAVE_CURSES_*宏条件编译,保证 Python 侧 API 与底层库能力严格一致。
对构建者和嵌入式/BSD 平台的用户来说,这意味着 curses 模块的可移植性显著提升:同一份 CPython 源码,可以在更广泛的 curses 实现上干净地构建,且不会暴露底层库根本不支持的接口。