Apache Serf 配置参数详解

目标：系统梳理 Apache Serf 1.3.10 的全部配置参数——scons 构建变量（安装路径、依赖定位、编译器与优化模式）、编译期宏、链接参数与 pkg-config 元数据的查看与使用方式。所有命令与回显均在 Ubuntu 22.04.5 + SCons 4.0.1 环境实测。Serf 是 C 链接库，没有运行时配置文件与服务端口，本文所讲参数即「构建期 + 编译链接期」两套。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS
• 架构：x86_64
• 构建工具：SCons 4.0.1（scons --version 回显）
• Serf 源码：serf-1.3.10.tar.bz2，解压于 /opt/serf-1.3.10
• 安装前缀：/usr/local/serf
• 演示账号：root

二、前置条件

• 已安装 build-essential libapr1-dev libaprutil1-dev libssl-dev zlib1g-dev scons。
• 已按《Apache Serf 安装指南》篇完成下载解压与 scons 构建、安装。
• 已安装 pkg-config（apt-get install -y pkg-config），用于读取 serf-1.pc。

三、参数查看与修改方式

Serf 1.3.10 没有 ./configure，构建参数全部通过 SCons 的命令行变量传入，查看与修改有三个入口：

入口 1：scons -h 查询全部构建变量及其当前值

cd /opt/serf-1.3.10 && scons -h

实测回显（变量部分）：

PREFIX: Directory to install under ( /path/to/PREFIX )
    default: /usr/local
    actual: /usr/local/serf

LIBDIR: Directory to install architecture dependent libraries under ( /path/to/LIBDIR )
    default: $PREFIX/lib
    actual: /usr/local/serf/lib

APR: Path to apr-1-config, or to APR's install area ( /path/to/APR )
    default: /usr
    actual: /usr/bin/apr-1-config

APU: Path to apu-1-config, or to APR's install area ( /path/to/APU )
    default: /usr
    actual: /usr/bin/apu-1-config

OPENSSL: Path to OpenSSL's install area ( /path/to/OPENSSL )
    default: /usr
    actual: /usr

ZLIB: Path to zlib's install area ( /path/to/ZLIB )
    default: /usr
    actual: /usr

GSSAPI: Path to GSSAPI's install area ( /path/to/GSSAPI )
    default: None
    actual: None

DEBUG: Enable debugging info and strict compile warnings (yes|no)
    default: False
    actual: False

APR_STATIC: Enable using a static compiled APR (yes|no)
    default: False
    actual: False

CC: Command name or path of the C compiler
    default: None
    actual: gcc

CFLAGS: Extra flags for the C compiler (space-separated)
    default: None
    actual:

LIBS: Extra libraries passed to the linker, e.g. "-l<library1> -l<library2>" (space separated)
    default: None
    actual: None

LINKFLAGS: Extra flags for the linker (space-separated)
    default: None
    actual:

CPPFLAGS: Extra flags for the C preprocessor (space separated)
    default: None
    actual: None

Use scons -H for help about command-line options.

（actual 列为实测机已选值：曾以 scons APR=/usr/bin/apr-1-config APU=/usr/bin/apu-1-config PREFIX=/usr/local/serf 构建，值已被记住。）

入口 2：.saved_config 持久化缓存

scons 会把命令行传入的变量保存到源码目录的 .saved_config 文件，下次构建自动加载，无需重复输入：

cat /opt/serf-1.3.10/.saved_config

实测回显：

PREFIX = '/usr/local/serf'
APR = '/usr/bin/apr-1-config'
APU = '/usr/bin/apu-1-config'
CC = ['gcc']
CFLAGS = ['']
LINKFLAGS = ['']

修改方式：要么用 scons 变量=值 覆盖（会更新该文件），要么直接 vi /opt/serf-1.3.10/.saved_config 手工编辑；删除该文件则回到纯命令行模式。

入口 3：安装后的 pkg-config 元数据 serf-1.pc

PKG_CONFIG_PATH=/usr/local/serf/lib/pkgconfig pkg-config --cflags --libs serf-1

-I/usr/local/serf/include/serf-1 -L/usr/local/serf/lib -lserf-1

serf-1.pc 内容（构建时自动生成，与所选前缀一致）：

SERF_MAJOR_VERSION=1
prefix=/usr/local/serf
exec_prefix=${prefix}
libdir=/usr/local/serf/lib
includedir=${prefix}/include/serf-1

Name: serf
Description: HTTP client library
Version: 1.3.10
Requires.private: libssl libcrypto
Libs: -L${libdir} -lserf-${SERF_MAJOR_VERSION}
Libs.private: /usr/lib/x86_64-linux-gnu/libaprutil-1.la /usr/lib/x86_64-linux-gnu/libapr-1.la  -lz
Cflags: -I${includedir}

四、参数总览

💡 注意：1.3.10 的 SConstruct 没有 RELEASE/OPT 变量——默认构建即「发布模式」（-O2 -DNDEBUG），开 DEBUG 变量即进入调试模式，二者互斥，详见 5.4 节。

五、参数分类详解

5.1 安装路径参数

PREFIX（安装根目录）

• 作用：决定 include/、lib/、lib/pkgconfig/ 的落点，并写进自动生成的 serf-1.pc。
• 推荐值：/usr/local/serf（前缀隔离，避免污染 /usr、便于整目录卸载；对比 apt 包落点 /usr/include/serf-1、/usr/lib/x86_64-linux-gnu）。
• 实测安装布局：

find /usr/local/serf -type f -o -type l | sort

/usr/local/serf/include/serf-1/serf.h
/usr/local/serf/include/serf-1/serf_bucket_types.h
/usr/local/serf/include/serf-1/serf_bucket_util.h
/usr/local/serf/lib/libserf-1.a
/usr/local/serf/lib/libserf-1.so
/usr/local/serf/lib/libserf-1.so.1
/usr/local/serf/lib/libserf-1.so.1.3.0
/usr/local/serf/lib/pkgconfig/serf-1.pc

LIBDIR（库目录）

• 作用：动态库安装子目录，默认 $PREFIX/lib；64 位系统想统一进 lib64 或多架构共存的场景才会改它。本机实测保持默认。

5.2 依赖定位参数

APR / APU（APR 与 APR-util 定位）

• 作用：SConstruct 通过这两个 config 脚本取编译旗标与库路径；取值可以是 config 路径，也可以是安装区目录。
• 查看可选路径：apr-1-config --version（1.7.0）、apu-1-config --version（1.6.1）。
• 默认 /usr 即可命中系统包；自编译 APR 场景传对应前缀，如 APR=/opt/apr/bin/apr-1-config。

OPENSSL / ZLIB（OpenSSL 与 zlib 定位）

• 作用：非标准前缀（如自编译在 /opt/openssl-3）时指定安装区，SConstruct 会在其 include/、lib/ 下找头文件与库。默认 /usr。
• 依赖强度：serf-1.pc 中 Requires.private: libssl libcrypto，zlib 在 Libs.private 末尾以 -lz 体现；缺 zlib 开发头文件会直接构建失败（zlib.h: No such file or directory，见《Apache Serf 安装指南》FAQ Q1）。

GSSAPI（SPNEGO/GSSAPI 认证）

• 作用：指定 GSSAPI 安装区即启用 SPNEGO/Kerberos 认证支持（auth_spnego 模块）；默认 None 表示不启用。
• 实测环境未装 GSSAPI，保持 None。

5.3 构建模式参数

DEBUG（调试构建开关，yes|no）

• DEBUG=no（默认）：实测编译行带 -O2 -DNDEBUG，即发布模式：

gcc -o context.o -c -std=c89 -Wdeclaration-after-statement -Wmissing-prototypes -Wall -O2 -DNDEBUG -DOPENSSL_NO_STDIO -DLINUX -D_REENTRANT -D_GNU_SOURCE -I. -I/usr/include/apr-1.0 ... context.c

• DEBUG=yes：SConstruct 逻辑为追加 -g 与 CPPDEFINES=['DEBUG', '_DEBUG']（源码 SConstruct 片段：env.Append(CCFLAGS=['-g'])、env.Append(CPPDEFINES=['DEBUG', '_DEBUG'])），并开启更严格的编译告警；适合排查库内问题时构建带符号版本。

APR_STATIC（静态链接 APR，yes|no）

• 作用：让 Serf 链接静态 APR 库（主要为 Windows 平台场景），Linux 下自编译 APR 静态库时才需要，默认 False。

5.4 编译器与编译参数

CC（C 编译器）

• 实测值：gcc（scons 探测回显 Checking for GNU-compatible C compiler...yes）。
• 可改为 clang 等：scons CC=clang。

CFLAGS / CPPFLAGS / LINKFLAGS / LIBS（附加旗标与库）

• 作用：向编译/预处理/链接注入额外内容，均以空格分隔。
• 典型用法：
  • 追加优化或去掉严格告警：scons CFLAGS='-O0 -fno-omit-frame-pointer'
  • 追加宏定义走 CPPFLAGS：scons CPPFLAGS='-DSERF_EXPERIMENTAL'
  • 追加私有库：scons LIBS='-lm'
• 实测环境四项均为空，采用 SConstruct 默认旗标：-std=c89 -Wdeclaration-after-statement -Wmissing-prototypes -Wall -O2 -DNDEBUG -DOPENSSL_NO_STDIO -DLINUX -D_REENTRANT -D_GNU_SOURCE。

5.5 链接参数与编译期宏

编译你的 Serf 应用程序时，链接参数固定三件套 + 可选路径项：

gcc /opt/serf-demo.c -o /opt/serf-demo \
  -I/usr/local/serf/include/serf-1 \
  $(apr-1-config --cflags --includes) \
  $(apu-1-config --includes) \
  -L/usr/local/serf/lib -lserf-1 -lapr-1 -laprutil-1

链接结果核对：

ldd /opt/serf-demo | grep -E "serf|apr"

        libserf-1.so.1 => /usr/local/serf/lib/libserf-1.so.1 (0x00007ef621ee4000)
        libapr-1.so.0 => /lib/x86_64-linux-gnu/libapr-1.so.0 (0x00007ef621ea7000)
        libaprutil-1.so.0 => /usr/lib/x86_64-linux-gnu/libaprutil-1.so.0 (0x00007ef621749000)

编译期宏（SConstruct 注入，见 5.3 实测编译行）：

• NDEBUG：发布模式断言裁剪（DEBUG 关闭时）
• OPENSSL_NO_STDIO：禁用 OpenSSL 的 STDIO 接口
• LINUX -D_REENTRANT -D_GNU_SOURCE：平台与线程安全宏
• 应用代码侧常用版本宏（头文件定义，可做条件编译）：

#define SERF_MAJOR_VERSION 1
#define SERF_MINOR_VERSION 3
#define SERF_PATCH_VERSION 10

5.6 动态库运行时配置

构建期之外，唯一需要「配置」的是动态链接器缓存：

echo /usr/local/serf/lib > /etc/ld.so.conf.d/serf-1.conf
ldconfig
ldconfig -p | grep serf

        libserf-1.so.1 (libc6,x86-64) => /usr/local/serf/lib/libserf-1.so.1
        libserf-1.so (libc6,x86-64) => /usr/local/serf/lib/libserf-1.so

多版本共存时的优先级：-Wl,-rpath > LD_LIBRARY_PATH > ldconfig 缓存顺序（/etc/ld.so.conf.d/ 下文件按字母序并入）。

六、生产配置模板

按典型场景给出「可直接执行」的构建参数组合：

模板套用要点：

• 一台服务器只装一套 Serf：PREFIX=/usr/local/serf + ld.so.conf.d 注册即可。
• 需要升级版本：换新源码目录、沿用同一 PREFIX 覆盖安装，再 ldconfig。
• 生产排查内存/崩溃问题：同一前缀用 DEBUG=yes 重装一份带符号库，gdb 可直入 serf 符号。

七、注意事项

⚠️ 注意：

1. 变更构建变量后必须先 scons 再 scons install；只跑 install 会沿用 .saved_config 里的旧值。
2. PREFIX 变更后旧前缀不会自动清理，升级前缀时记得删除旧目录并更新 /etc/ld.so.conf.d/。
3. DEBUG=yes 构建的库性能明显低于默认 -O2 版本，只用于问题定位，勿长期驻留生产。

八、常见问题（FAQ）

Q1：scons -h 里 actual 与我传的不一致？ 看 .saved_config——它会持久化最近一次命令行变量并在后续构建中生效。以 scons 变量=新值 覆盖或删除该文件重建。

Q2：没有 RELEASE/OPT 变量，怎么控制优化级别？ 1.3.10 的优化由 DEBUG 开关二选一：默认 -O2 -DNDEBUG（发布），DEBUG=yes 则 -g + DEBUG/_DEBUG 宏（调试）。需要自定义级别时用 CFLAGS/CPPFLAGS 追加覆盖。

Q3：pkg-config 找不到 serf-1？ serf-1.pc 在非标准前缀下需显式指路径：export PKG_CONFIG_PATH=/usr/local/serf/lib/pkgconfig:$PKG_CONFIG_PATH，或临时 PKG_CONFIG_PATH=... pkg-config --cflags --libs serf-1。

Q4：链接时 OpenSSL/zlib 符号报 undefined？ 静态链接 libserf-1.a 时传递依赖不会自动带上，需显式补 -lssl -lcrypto -lz；动态链接 libserf-1.so 则无需（见 5.5 节表格）。

Q5：如何确认程序运行时加载的是源码版 1.3.10 而非 apt 版 1.3.9？ ldd <程序> | grep serf 看解析路径；ldconfig -p | grep serf 看缓存顺序（/usr/local 条目在前则优先）。需要强制版本时用 -Wl,-rpath,/usr/local/serf/lib 固化。

九、参考链接

• Serf 构建脚本（变量定义权威）：源码包 SConstruct（/opt/serf-1.3.10/SConstruct）
• pkg-config 元数据：/usr/local/serf/lib/pkgconfig/serf-1.pc
• 版本宏：/usr/local/serf/include/serf-1/serf.h
• 关联篇目：《Apache Serf 安装指南》《Apache Serf 构建并运行示例应用指南》《Apache Serf 常用工具与 API 详解》