27.国产构建工具之王xmake——包管理package

通用选项

-q, –quiet

静默模式运行，减少输出信息

-y, –yes

需要用户确认时，默认输入 “yes”

–confirm=CONFIRM

需要用户确认时，输入指定结果，可选值：yes/no/def

-v, –verbose

打印详细的冗余信息供用户查看

–root

允许以 root 权限运行 xmake

-D, –diagnosis

仅面向开发者：打印大量诊断信息（回溯、检查信息等），可追加 -v 获取更完整信息（例：xmake -vD）

-h, –help

打印帮助信息并退出

-F FILE, –file=FILE

读取指定的 xmake.lua 文件

-P PROJECT, –project=PROJECT

切换到指定的项目目录，搜索优先级：1. 命令参数指定 2. 环境变量 XMAKE_PROJECT_DIR 3. 当前目录

包管理命令选项

-o OUTPUTDIR, –outputdir=OUTPUTDIR

设置输出目录

-a, –all

打包所有目标（默认：所有目标）

-f FORMAT, –format=FORMAT

设置打包格式（默认：local），可选值：oldpkg/local/remote

–homepage=HOMEPAGE

设置包的主页地址

–description=DESCRIPTION

设置包的描述信息

–url=URL

设置远程包的地址

–version=VERSION

设置远程包的版本

–shasum=SHASUM

设置远程包的 sha256 校验值或提交哈希

target

指定要打包的目标名称；若未指定，将打包所有默认目标

基础定义

package

package(name:)

定义依赖包的入口，指定包名称

name：包名称字符串

元信息配置

set_homepage

set_homepage(url:)

设置包的官方主页地址

url：主页 URL 字符串

元信息配置

set_description

set_description(description:)

设置包的功能描述（可通过 xmake require –info 查看）

description：描述字符串

包类型配置

set_kind

set_kind(kind:, { headeronly =})

设置包类型（library/binary/toolchain）

kind：包类型；headeronly：library 类型时是否为仅头文件库

源码地址配置

set_urls

set_urls(urls:, …, { excludes =, version =, http_headers =})

覆盖性设置包源地址（源码包 / Git 仓库）

urls：地址字符串 / 数组；excludes：解压排除文件；version：版本转换函数

源码地址配置

add_urls

`add_urls(urls:, …, { alias =, excludes =, version =, http_headers =})`

追加包源地址（支持多镜像自动切换）

alias：地址别名；其他参数同 set_urls

版本管理

add_versions

add_versions(version:, hash:)

配置包版本及对应的 SHA256 校验值

version：版本字符串；hash：SHA256 哈希值

版本管理

add_versionfiles

add_versionfiles(file:)

从外部文件加载版本列表（避免配置臃肿）

file：包含版本 – 哈希对的文件路径

目录配置

set_sourcedir

set_sourcedir(sourcedir:)

指定本地源码目录（用于本地库集成）

sourcedir：源码目录路径

补丁管理

add_patches

add_patches(version:, url:, hash:)

为指定版本添加源码补丁（编译前自动应用）

version：适用版本；url：补丁 URL；hash：补丁 SHA256 值

依赖管理

add_deps

`add_deps(deps:, …)`

配置包的依赖关系（安装时自动递归安装依赖）

deps：依赖包名称字符串 / 数组

组件配置

add_components

`add_components(components:, …, { deps =})`

声明包的可用组件列表

components：组件名称；deps：组件依赖数组

组件配置

on_component

on_component(component:, script:)

配置组件的链接、依赖等详细信息（支持全局配置）

component：组件名称（可选）；script：配置脚本

编译配置

add_configs

add_configs(name:, {

description=,

default=,

values=,

type=,

readonly=

})

对外暴露可配置参数（支持类型限制和默认值）

name：配置名；type：类型（string/boolean/number）；readonly：是否只读

编译配置

add_defines

add_defines(defines:, …)

添加宏定义（编译时传递给编译器）

defines：宏定义字符串 / 数组

路径配置

add_includedirs

`add_includedirs(dirs:, …)`

添加头文件搜索目录

dirs：目录路径字符串 / 数组

路径配置

add_bindirs

`add_bindirs(dirs:, …)`

添加可执行文件目录（自动加入 PATH 环境变量）

dirs：可执行文件目录路径

链接配置

add_links

`add_links(links:, …)`

手动配置库链接名称及顺序

links：库名称字符串 / 数组

链接配置

add_syslinks

`add_syslinks(syslinks:, …)`

配置系统库链接（如 Windows 的 gdi32、Linux 的 pthread）

syslinks：系统库名称字符串 / 数组

链接配置

add_frameworks

`add_frameworks(frameworks:, …)`

配置 macOS/iOS 系统框架链接

frameworks：框架名称字符串 / 数组

扩展源配置

add_extsources

`add_extsources(sources:, …)`

配置系统库查找源（支持 pkgconfig/brew 等包管理器）

sources：外部源（格式：”pkgconfig::name” 或 “brew::name”）

脚本钩子

on_load

on_load(script:)

包加载时执行的动态配置脚本（适配多平台 / 架构）

script：加载脚本（参数为 package 对象）

脚本钩子

on_install

`on_install(platforms:, …, script:)`

配置包的安装逻辑（支持平台 / 架构过滤）

platforms：支持的平台；script：安装脚本

脚本钩子

on_test

on_test(script:)

配置安装后的测试逻辑（测试失败则撤销安装）

script：测试脚本（支持函数检测、代码片段编译等）

脚本钩子

on_fetch

`on_fetch(platforms:, …, script:)`

自定义系统库查找逻辑（适配复杂系统环境）

platforms：适用平台；script：查找脚本

脚本钩子

on_check

`on_check(platforms:, …, script:)`

检测包是否支持当前平台 / 工具链（下载前执行）

script：检测脚本（支持版本校验、编译器特性检测等）

脚本钩子

on_download

on_download(script:)

自定义包下载逻辑（适配私有仓库鉴权等场景）

script：下载脚本（参数包含 url 和目标目录）

方案配置

add_schemes

`add_schemes(schemes:, …)`

定义包的可用方案列表（第一个为默认方案）

schemes：方案名称字符串 / 数组

继承配置

set_base

set_base(package:)

继承已有包的配置并覆盖部分参数（适配官方包修改）

package：基础包名称

add_requires

声明项目依赖的包（可指定版本、配置等），是依赖管理的入口

– packages：包名（支持包名@版本格式，如zlib@1.2.13）

– version：版本约束（如~1.2/>=1.0）

– debug：是否启用调试版本

– configs：传递给包的自定义配置（如{shared = true}）

– system：是否优先使用系统库

– optional：依赖是否可选（缺失不报错）

– plat/arch/mode：限定依赖生效的平台 / 架构 / 编译模式

add_requireconfs

覆盖 / 调整add_requires声明的依赖配置，支持精细化控制依赖行为

– override：是否强制覆盖已有配置

– repos：指定依赖包的仓库来源

– cache：是否启用缓存

– build：构建相关配置（如{jobs = 4}指定编译线程）

– fetch：自定义查找配置（如{force = true}强制重新查找）

add_repositories

注册依赖包仓库（官方 / 私有），xmake 会从这些仓库查找add_requires声明的包

– name：仓库名称（自定义）

– url：仓库地址（支持本地路径 / 远程 Git / 官方仓库）

– priority：仓库优先级（数值越小越优先）

– readonly：是否只读（禁止修改仓库配置）

add_packages

将add_requires声明的依赖关联到目标（target），实现编译链接

– packages：要关联的包名（需先通过add_requires声明）

– public：是否对外暴露依赖（用于静态库链接）

– interface：是否仅作为接口依赖（不参与编译，仅提供头文件）

– configs：针对目标的依赖配置覆盖