kmpkg_extract_source_archive

提取归档文件（源码包）。

用法

kmpkg_extract_source_archive(
    <out-var>
    ARCHIVE <path>
    [NO_REMOVE_ONE_LEVEL]
    [SKIP_PATCH_CHECK]
    [PATCHES <patch>...]
    [SOURCE_BASE <base>]
    [BASE_DIRECTORY <relative-path> | WORKING_DIRECTORY <absolute-path>]
)

参数

`<out-var>`

用于存储提取后内容所在目录路径的变量名称。

NO_REMOVE_ONE_LEVEL

跳过移除归档文件的顶层目录。

大多数归档文件会包含一个单独的顶层目录，例如：

zlib-1.2.11/
    doc/
        ...
    examples/
        ...
    ChangeLog
    CMakeLists.txt
    README
    zlib.h
    ...

默认情况下，kmpkg_extract_source_archive 会移除该顶层目录，并将所有内容移动到 <out-var> 指向的目录中。若归档文件无顶层目录，此行为会触发错误。

启用此标志后，顶层目录会被保留；即使归档文件没有顶层目录，也不会触发错误。

SKIP_PATCH_CHECK

忽略补丁应用过程中的错误，且不输出相关提示。

此选项仅应在 --head 等非稳定模式下使用。若源码版本是固定的，补丁应用失败应被视为致命错误。

PATCHES

要应用到提取后源码上的补丁文件列表。

补丁会按列表顺序依次应用（应用时机为顶层目录移除操作之后，参见 NO_REMOVE_ONE_LEVEL）。相对路径会被解析为相对于当前端口目录的路径。

若需根据目标平台信息条件性应用补丁，可先构造补丁列表再展开传入：

set(patches "")
if(KMPKG_TARGET_IS_WINDOWS)
    list(APPEND patches only-windows.patch)
endif()
kmpkg_extract_source_archive(src
    ARCHIVE "${archive}"
    PATCHES
        always-applied.patch
        ${patches}
)

SOURCE_BASE

提取后目录的易识别名称（友好名称）。

不得包含路径分隔符（/ 或 \\）。

更多细节请参见 WORKING_DIRECTORY。

BASE_DIRECTORY

提取后目录的根级子文件夹。

默认值为 src，必须是相对路径。

更多细节请参见 WORKING_DIRECTORY。

WORKING_DIRECTORY

提取后目录的根文件夹。

默认值为 ${CURRENT_BUILDTREES_DIR}/<BASE_DIRECTORY>，必须是绝对路径。

kmpkg_extract_source_archive 会将归档文件提取到 <WORKING_DIRECTORY>/<SOURCE_BASE>-<short-hash>.clean 目录中。若该目录已存在，会先删除再执行提取。若未指定 SOURCE_BASE、BASE_DIRECTORY 或 WORKING_DIRECTORY，默认路径为 ${CURRENT_BUILDTREES_DIR}/src/<archive-stem>-<short-hash>.clean（archive-stem 指归档文件的主文件名，不含扩展名）。

在 --editable 模式下：

提取后的目录不会添加 .clean 后缀；
提取后的目录不会被删除。若目录已存在，kmpkg_extract_source_archive 不会执行任何操作。

<short-hash> 是用于唯一标识归档文件和补丁文件内容的短哈希值。调用此函数后，对工作目录内容的任何修改都应无条件执行，以避免在 editable 模式下出现意外行为。

示例

kmpkg_download_distfile(
    archive # "archive" 变量会被赋值为下载文件的完整路径
    URLS "https://nmap.org/dist/nmap-7.70.tar.bz2"
    FILENAME "nmap-7.70.tar.bz2"
    SHA512 084c148b022ff6550e269d976d0077f7932a10e2ef218236fe13aa3a70b4eb6506df03329868fc68cb3ce78e4360b200f5a7a491d3145028fed679ef1c9ecae5
)
kmpkg_extract_source_archive(
    src # "src" 变量会被赋值为提取后源码目录的路径
    ARCHIVE "${archive}"
    SOURCE_BASE nmap.org-nmap-7.70
    PATCHES
        0001-disable-werror.patch
)
kmpkg_cmake_configure(SOURCE_PATH "${src}")

GitHub 示例搜索

备注

已废弃的语法

该命令还支持一种已废弃的重载形式（不推荐使用）：

kmpkg_extract_source_archive(<archive> [<working_directory>])

此废弃语法存在设计缺陷：若目标目录不存在，会将 <archive> 提取到 ${working_directory}/<archive-filename>.extracted 目录。该行为会导致补丁和其他修改在不同构建任务间泄露，进而引发难以调试的错误。

所有使用此废弃重载的场景，都应替换为用法中定义的标准语法——添加显式的 ARCHIVE 参数，并将对提取路径的直接引用替换为对 <out-var> 变量的使用。

替代关系

该命令替代了已废弃的 kmpkg_extract_source_archive_ex()。

源码

scripts/cmake/kmpkg_extract_source_archive.cmake

用法​

参数​

<out-var>​

ARCHIVE​

NO_REMOVE_ONE_LEVEL​

SKIP_PATCH_CHECK​

PATCHES​

SOURCE_BASE​

BASE_DIRECTORY​

WORKING_DIRECTORY​

示例​

备注​

已废弃的语法​

替代关系​

源码​

用法

参数