RPM Spec 文件解析与规范排查：从宏展开到构建环境

在 RPM 打包过程中，spec 文件的解析报错很少源于单一原因。宏展开时序、路径表达方式、文件包含关系以及构建目录结构，任何一环出现偏差，都可能表现为"文件找不到""宏未定义"或"路径不合规"。下面以一次 gdb.spec 的排查过程为线索，梳理一套从解析错误到规范检查的完整处理思路。

一、先区分问题的性质

排查 spec 文件时，建议先将问题归入以下三类，避免把不同层面的故障混在一起处理。

第一类：解析与预处理错误。 spec 文件无法被 rpm/rpmbuild 正确读取或展开，典型表现是 rpmspec 直接报错退出，例如宏未定义、%include 目标文件缺失、条件块不配对等。

第二类：规范与静态检查警告。 spec 在语法上可以通过解析，但 rpmlint 指出其写法不符合打包规范，例如硬编码库路径、注释中出现宏、补丁声明与实际应用方式不匹配等。

第三类：构建环境配置问题。 _topdir、_sourcedir、buildroot 等路径宏的实际展开值与 spec 的预期不一致，导致文件在构建阶段找不到或安装到错误位置。

这三类问题的处理顺序有实际意义：解析错误必须先行排除。如果 spec 本身无法被正确展开和读取，后续 rpmlint 给出的部分提示可能建立在残缺的展开结果之上，可信度会打折扣。

二、rpmspec 与 rpmlint 的分工

理解这两个工具的定位差异，是建立排查顺序的前提。

rpmspec -P 执行的是宏展开与 spec 预处理 。它会把 spec 中的宏替换为实际值，处理条件分支，解析 %include，然后将展开后的结果输出到标准输出。如果宏未定义、包含文件缺失或条件结构不完整，这一步会直接暴露。它适合用来快速判断"spec 本身能不能被 rpm 读懂"。

rpmlint 的职责是规范与静态检查 。它在读取 spec 时同样会触发一定程度的宏展开和解析，但它的侧重点是识别不符合打包约定的写法。rpmlint 的部分"错误"在特定上下文中可能是预期行为，因此它更适合作为规范层面的参考，而不是解析层面的最终仲裁者。

推荐的执行顺序是：

rpmspec -P SPECS/foo.spec > /dev/null   # 先获得干净的展开结果，定位解析问题
rpmlint SPECS/foo.spec                  # 再做规范层面的检查

需要特别留意的是：rpmspec -P 只做预处理，并不执行 %prep、%build、%install 中的任何命令 。因此它无法验证补丁是否真的能应用、文件是否真的安装到了预期位置。解析通过只是构建的第一步，最终仍需通过 rpmbuild 的实际执行来确认。

三、硬编码库路径：区分"通用库目录"与"调试信息目录"

rpmlint 常见的报错之一是：

E: hardcoded-library-path in $RPM_BUILD_ROOT/usr/lib/debug%{_bindir}

这条规则针对的是 /lib 和 /usr/lib 这类硬编码的库路径。rpmlint 的建议是使用 %{_libdir} 代替。但"使用 %{_libdir}"这一建议需要放在具体语境中理解，不能机械地全局替换。

当目标确实是通用库目录时 ，%{_libdir} 是正确的选择。它在 64 位系统上通常展开为 /usr/lib64，在 32 位系统上为 /usr/lib，这正是规范希望达成的架构无关性。

%{buildroot}%{_libdir}/%{name}

当目标涉及 debuginfo 路径时，情况不同。 在 RHEL/CentOS/Fedora 系的传统布局中，debuginfo 文件位于 /usr/lib/debug ，而不是 /usr/lib64/debug。%{_libdir} 在 x86_64 上展开为 /usr/lib64，因此写成 %{_libdir}/debug 会指向 /usr/lib64/debug，与实际 debuginfo 路径并不一致。

更重要的是，debuginfo 的拆分通常由 rpmbuild 自动完成。find-debuginfo.sh 会在构建过程中从 ELF 二进制中提取调试符号，放入 debuginfo 子包，spec 本身一般不需要手动写入 debug 目录的安装路径。如果 spec 中出现了 /usr/lib/debug 或 %{_libdir}/debug 这类写法，首先应判断它是否确实必要。确需引用发行版特定的 debug 目录时，应当使用该发行版提供的宏，而不是自行拼接 %{_libdir}/debug。

四、%{buildroot} 只属于 %install 阶段

%{buildroot} 是构建环境中的临时安装根目录，仅在 %install 阶段用于把文件"安装"到构建沙箱中。它绝不能写入目标系统路径。

这一区分在某些工具调用中尤为关键。以 Python 字节编译为例：

compileall.compile_dir("%{buildroot}%{_libdir}/foo", 1, "%{_libdir}/foo")

第一个参数是 buildroot 下的实际文件路径，需要带 %{buildroot}；第二个参数是目标系统上的安装路径，不能带 %{buildroot}。混用两者会导致生成的文件记录错误的路径。

五、注释中的宏：%dnl 优先于转义

RPM 的一个基本行为是：宏在注释行中同样会被展开。这意味着下面这样的注释是有实际风险的：

# %elif condition
# %{some_undefined_macro}

如果 %elif 或 %{some_undefined_macro} 在当前上下文中不可用，注释本身就可能触发解析问题。rpmlint 的 W: macro-in-comment 警告正是在提示这一情况。

处理方式有两种，但推荐程度不同。

一种方式是将 % 转义为 %%：

# %%elif condition

这在大多数情况下有效，但需要逐处检查，多行注释或含多个 % 的注释容易遗漏。

更可靠的方式是使用 %dnl 。%dnl 是 rpm 4.15 引入的注释原语，它会丢弃该行中 %dnl 之后的所有内容，并且不做任何宏展开 。它相当于一个"真正惰性"的注释，不依赖 % 转义，也不受宏展开机制影响：

%dnl 下面这行中的 %elif 不会被展开
%dnl make unversioned %__python an error

对于需要在注释中保留含 % 文本的场景，%dnl 比 # 加 %% 转义更不易出错，应当作为默认选择。

六、%include 的路径是显式的，不自动搜索 SOURCES

spec 中常见这样的写法：

Patch9998: _gdb.spec.Patch.include
Patch9999: _gdb.spec.patch.include
%include %{PATCH9998}

这里存在一个容易误解的地方：Patch9998: 声明的是补丁文件的逻辑名称，并不会自动建立"该文件位于 SOURCES 目录"的查找关系 。%include 的目标路径按其自身字符串解析，rpmbuild 不会因为某个文件被声明为 Patch，就自动到 %{_sourcedir} 下去寻找它。

如果 %{PATCH9998} 展开为一个单纯的文件名（例如 _gdb.spec.Patch.include），%include 会相对于当时的工作目录 来解析这个相对路径，而不是相对于 SOURCES。因此，当文件明明存在于 SOURCES 中却仍然报"No such file or directory"时，原因往往就是 %include 的路径语义与预期不一致。

更可靠的写法是给出显式路径：

%include %{_topdir}/SOURCES/_gdb.spec.Patch.include

或者确保 %{PATCH9998} 展开为完整的绝对路径。排查时应先确认展开结果：

rpm --eval '%{PATCH9998}'
rpm --eval '%{_sourcedir}'

然后判断该字符串是绝对路径、相对于工作目录的路径，还是仅仅一个裸文件名。不要假定 rpmbuild 会自动到 SOURCES 中搜索 %include 目标。

另外，如果 %include 目标确实缺失，简单地在其前面加 # 注释掉不一定有效 。%include 是在预处理阶段处理的，注释行中的宏仍可能被展开，简单的 # 并不保证阻止这一行为。稳妥的做法是删除该行，或确保目标文件存在，而不是依赖注释来绕过缺失。

七、_topdir 与构建目录的一致性

_topdir 是 RPM 构建树的根目录，它间接决定了 %{_sourcedir}、%{_builddir}、%{_specdir}、%{_rpmdir} 等一系列路径宏的值。如果用户在 ~/.rpmmacros 中自定义了 _topdir，但实际的目录结构与 spec 的预期不一致，就会出现文件找不到、补丁无法包含、%include 路径偏离等问题。

排查时应先确认一组关键宏的实际展开值，而不仅是 _topdir 本身：

rpm --eval '%{_topdir}'
rpm --eval '%{_sourcedir}'
rpm --eval '%{_libdir}'
rpm --eval '%{buildroot}'

如果确认 _topdir 的自定义是问题来源，可以移除 ~/.rpmmacros 中的相关定义，使 _topdir 恢复为默认路径（通常是 %{getenv:HOME}/rpmbuild）。但修改宏配置后，应当重新验证所有受其影响的路径宏，因为某些自定义宏可能间接依赖 _topdir 来定义其他路径。

八、跨发行版的差异不可忽略

不同 RPM 版本和发行版在宏体系、debuginfo 处理方式、条件语法支持程度上存在实际差异。把某个发行版上的 spec 直接复制到另一个发行版构建，是许多解析和环境问题的来源。

RHEL/CentOS 7 的 debuginfo 机制较为传统，_topdir 通常为 ~/rpmbuild。RHEL/CentOS 8 及之后 对 debugsource 与 debuginfo 的拆分更加规范化，宏体系也更严格。Fedora 与新版 RPM 对宏展开、路径规范和补丁检查更为敏感。衍生发行版（openEuler、Kylin 等）可能对库目录、debug 目录或补丁包含方式做了自定义。

迁移 spec 时，至少应重新确认上述关键宏的展开值，并根据目标发行版的实际行为判断 %include、debuginfo 路径和补丁声明是否需要调整。

九、排查清单

遇到 spec 解析或规范问题时，可以按以下顺序推进：

1. 运行 rpmspec -P SPECS/foo.spec > /dev/null，确认宏展开与预处理不报错。
2. 检查 %include 的路径是否显式且可解析 ；不要假定 rpmbuild 会自动到 SOURCES 中查找。
3. 如果 %include 目标缺失，删除该行或补全文件；不要依赖 # 注释来阻止其被处理。
4. 确认 _topdir、_sourcedir、_libdir、buildroot 的实际展开值。
5. 区分场景使用路径宏：通用库目录用 %{_libdir}；debuginfo 路径不要机械拼接 %{_libdir}/debug，优先让 find-debuginfo.sh 自动处理。
6. 注释中含 % 的内容，优先使用 %dnl；需要保留 # 形式时，用 %% 转义。
7. 检查 %if/%endif、%ifarch/%endif 等条件块是否配对，条件语法是否与当前 rpm 版本兼容。
8. 确认 spec 文件使用 Unix 换行符。
9. 最后运行 rpmlint，并结合 -i 选项理解具体规则的含义；部分警告在特定包中可能是预期行为，不应一律"修复"。

十、注意事项

• 不要直接修改 /usr/lib/rpm/macros 中的系统级宏。用户级自定义应放在 ~/.rpmmacros 中，修改后及时验证受影响的路径宏。
• %{buildroot} 仅用于 %install 阶段的构建环境路径，不要将其写入目标系统路径。
• rpmspec -P 通过不等于 构建通过：它不执行各阶段的脚本，补丁能否应用、文件能否正确安装仍需 rpmbuild 实际验证。
• %{_libdir}/debug 不是 debuginfo 路径的通用替代。在 64 位 RHEL 系中，/usr/lib/debug 与 %{_libdir}（/usr/lib64）是不同路径，debuginfo 拆分通常由构建机制自动完成。
• %include 的路径解析是显式的。使用 %{_topdir} 或完整绝对路径，可以避免大量"文件存在却找不到"的困惑。
• 注释中的宏同样参与展开，%dnl 是比转义更可靠的惰性注释方式。
• 跨发行版迁移 spec 时，除宏展开值外，还应确认 debuginfo 拆分机制和 %include 处理行为是否与目标环境一致。

总结 ：spec 排错的核心不在于记住某一条 rpmlint 提示的"标准改法"，而在于理解宏展开的时序、路径的语义边界以及构建目录的实际解析规则。先让 rpmspec -P 给出干净的展开结果，再逐层排查包含关系与路径宏，最后用 rpmlint 收束规范问题，是一条可重复、可解释的处理路径。