---
url: /zh/api/description/builtin-policies.md
---
# 内置策略  {#builtin-policies}

Xmake 有很多的默认行为，比如：自动检测和映射编译、链接标志、跨工程目标并行构建等，虽然提供了一定的智能化处理，但重口难调，不一定能满足所有的用户的使用习惯和需求。
因此， xmake 提供了**针对默认策略的修改设置**，在一定程度上给予了用户**修改策略**的权限。这个功能主要通过 [set\_policy](/zh/api/description/project-target#set-policy) 接口来实现，我们通常可以使用这个接口来配置修改 target, package 以及工程整体的一些行为策略。

策略通过 [set\_policy()](/zh/api/description/project-target#set-policy) 接口设置，可在 [target()](/zh/api/description/project-target#target)、[package()](/zh/api/description/package-dependencies#package) 或全局域中使用。

## 使用方式 {#usage}

::: tip 注意
如果设置的策略名是无效的， xmake 会有警告提示。
:::

### 1. 获取当前版本所支持的所有策略 {#\_1-get-all-the-policies-supported-by-the-current-version}

执行下面的命令可以返回所有的配置及其描述、值类型和默认值：

```sh
$ xmake l core.project.policy.policies
```

### 2. 在 `xmake.lua` 中直接调用接口进行策略的配置 {#\_2-configuring-policies-in-xmake-lua}

::: code-group

```lua [全局设置]
-- 在项目根域设置这个配置，就可以全局禁用 flags 的自动检测和忽略机制
set_policy("check.auto_ignore_flags", false)
```

```lua [局部设置]
target("test")
    -- 针对特定的 target `test` 生效
    set_policy("check.auto_ignore_flags", false)
```

:::

### 3. 通过命令行进行策略的配置 {#\_3-configuring-policies-via-the-command-line}

当我们构建工程时，可能需要暂时性地启用或是禁用一些策略。在这种情况下，使用命令行就更加贴合需求了。使用命令行设置策略时，默认该策略为启用状态：

```sh
$ xmake f --policies=package.fetch_only
```

当然，我们也可以指定其他值以达到禁用等效果：

```sh
$ xmake f --policies=package.precompiled:n
```

值得注意的是，同时配置多个策略需要用逗号进行分割：

```sh
$ xmake f --policies=package.precompiled:n,package.install_only
```

## check.auto\_ignore\_flags 

::: danger 潜在风险
强行禁用自动检测和忽略标志的默认策略可能会导致其他用户在编译时由于编译器的支持力度不同，从而出现一定程度的编译失败。
:::

### 默认策略 {#default-policy}

xmake 默认会对所有通过 `add_cxflags`, `add_ldflags` 等接口添加的原始编译和链接标志进行自动检测。如果检测出当前编译器和链接器不支持某些标志，就会自动忽略并弹出警告信息。

这种自动忽略的策略通常是很有用的，尤其是在处理一些可选的编译标志时，即使编译器不支持也能正常编译。

### 潜在需求 {#use-cases}

由于自动检测在某些情况下会有一定程度的误判（尤其是针对交叉编译工具链，更容易出现检测失败，导致编译失败），而且自动忽略的同时会产生警告提示，所以某些用户并不喜欢这个设定。

例如，如果标志检测失败，就会有警告提示用户：

```sh
warning: add_ldflags("-static") is ignored, please pass `{force = true}` or call `set_policy("check.auto_ignore_flags", false)` if you want to set it.
```

根据警告提示，我们可以自己分析判断是否需要强制添加这个标志。我们可以根据 flag 的数量来选择以下两种方案：

#### 1. 添加 force 参数 {#\_1-add-the-force-parameter}

```lua
add_ldflags("-static", {force = true})
```

`{force = true}` 参数可以显式地强制添加标志并跳过自动检测，这对于**个别**的检测失败是**有效快捷**的处理方式，但是对于交叉编译，**大量**的标志检测不通过的情况下，每个都设置 force 参数过于**繁琐**。

#### 2. 配置策略 {#\_2-set-the-policy}

针对方案一中的局限性，我们可以使用 `set_policy` 直接禁用对某个目标或者整个项目默认的标志自动检测和忽略行为，从而达到没有额外警告信息出现的效果：

```lua
set_policy("check.auto_ignore_flags", false)
target("test")
    add_ldflags("-static")
```

## check.auto\_map\_flags 

::: tip 注意
目前的自动映射实现还不是很完整，没有 100% 覆盖所有 gcc 的标志，所以还是有部分标志是无法去映射的。
:::

### 默认策略 {#default-policy-1}

这是 xmake 的另外一个对标志的智能分析处理。通常情况下，通过 `add_links`, `add_defines` 这种 xmake 内置的 API 去设置的配置是具有跨平台特性的。针对不同的编译器平台， xmake 会自动处理成对应的原始标志。

但是有些情况下，用户还是会通过 `add_cxflags`, `add_ldflags` 等接口设置原始的编译链接标志。这些 API 接收原始标志为参数，但部分标志本身并不是被所有的编译器支持的。

例如 `-O0` 这个编译优化标志。虽然有 `set_optimize` 来实现跨编译器配置，但如果用户可能会直接使用 `add_cxflags("-O0")` 。这种情况下， gcc/clang 下可以正常处理，但是 msvc 下就不支持它了。

因此， xmake 内置了标志的自动映射功能：基于 gcc 编译标志的普及性， xmake 采用 gcc 的标志命名规范，针对不同的编译器对其进行自动映射，例如：

```lua
add_cxflags("-O0")
```

这一行设置，在 gcc/clang 编译器下还是 `-O0` ，但针对 msvc 编译器， xmake 就会自动将其映射为 msvc 中对应的 `-Od` 编译标志来禁用优化。整个过程，用户是完全无感知的，直接执行 xmake 就可以跨编译器完成标志的映射和编译。

### 用法 {#usage-1}

也有部分用户并不喜欢这种自动映射行为，那么我们可以通过下面的设置完全禁用这个默认的行为：

```lua
set_policy("check.auto_map_flags", false)
```

## check.target\_package\_licenses 

### 默认策略 {#default-policy-2}

在软件开发过程中引入开源软件作为第三方依赖，可以有效避免“重造轮子”。我们应当**尊重并认可**其他开发者的劳动成果，**遵守**相应的开源许可证。为了帮助开发者发现潜在的**许可证冲突等风险**， xmake 默认会对项目和引入依赖的许可证进行**兼容性检查**。

### 用法 {#usage-2}

这个策略主要用于辅助用户发现潜在的许可证合规问题，起一个提醒的作用。在某些学习或特定场景下，如果用户希望暂时屏蔽检测产生的冲突警告，可以通过以下设置禁用许可证兼容性检测并去除警告信息：

```lua
set_policy("check.target_package_licenses", false)
```

## build.across\_targets\_in\_parallel 

这个策略也是默认开启的，主要用于跨target间执行并行构建，v2.3.3之前的版本，并行构建只能针对单个target内部的所有源文件，
跨target的编译，必须要要等先前的target完全link成功，才能执行下一个target的编译，这在一定程度上会影响编译速度。

然而每个target的源文件是可以完全并行化处理的，最终在一起执行link过程，v2.3.3之后的版本通过这个优化，构建速度提升了30%。

当然，如果有些特殊的target里面的构建源文件要依赖先前的target（尤其是一些自定义rules的情况，虽然很少遇到），我们也可以通过下面的设置禁用这个优化行为：

```sh
set_policy("build.across_targets_in_parallel", false)
```

## build.fence 

由于配置 `set_policy("build.across_targets_in_parallel", false)` 存在局限性，它会限制父 target 和它的所有依赖的子 target 之间的并行度，影响的范围有点大。

而我们做 codegen 时候，有时候仅仅只是想对其中某个依赖的 target 限制并行度，作为 codegen 程序，提前让它完成编译。

这个时候，`build.across_targets_in_parallel` 就无法精细控制了，编译速度也无法达到最优。

因此，我们新增了 `build.fence` 策略，它可以仅仅只针对特定的子 target 限制并行编译链接。

相关的背景细节，可以看下：[#5003](https://github.com/xmake-io/xmake/issues/5003)

例如：

```lua
target("autogen")
    set_default(false)
    set_kind("binary")
    set_plat(os.host())
    set_arch(os.arch())
    add_files("src/autogen.cpp")
    set_languages("c++11")
    set_policy("build.fence", true)

target("test")
    set_kind("binary")
    add_deps("autogen")
    add_rules("autogen")
    add_files("src/main.cpp")
    add_files("src/*.in")
```

其中 autogen 目标程序需要在 test 程序的源码被编译前，就要完成编译链接，因为 test 目标需要运行 autogen 程序，去动态生成一些源码参与编译。

而针对 autogen 配置 `set_policy("build.fence", true)` 就可以实现这个目的。

## build.merge\_archive 

如果设置了这个策略，那么使用 `add_deps()` 依赖的目标库不再作为链接存在，而是直接把它们合并到父目标库中去。

例如：

```lua
add_rules("mode.debug", "mode.release")

target("add")
    set_kind("static")
    add_files("src/add.c")
    add_files("src/subdir/add.c")

target("sub")
    set_kind("static")
    add_files("src/sub.c")
    add_files("src/subdir/sub.c")

target("mul")
    set_kind("static")
    add_deps("add", "sub")
    add_files("src/mul.c")
    set_policy("build.merge_archive", true)

target("test")
    add_deps("mul")
    add_files("src/main.c")
```

libmul.a 静态库会自动合并 libadd.a 和 libsub.a 两个子依赖的静态库。

自 v3.0.9 起，该策略同时会把 `add_packages(...)` 引入的静态库一起合并到父目标中。例如：

```lua
add_requires("libpng", {system = false})
add_requireconfs("libpng.*", {system = false, override = true})

target("foo")
    set_kind("static")
    add_files("src/png.c")
    add_packages("libpng")
    set_policy("build.merge_archive", true)
```

构建完成后，`libfoo.a` 里会包含 `png.c.o` 以及 `libpng.a` 与其传递依赖 `zlib.a` 中的全部目标文件，下游目标只需要链接 `foo` 即可。

## build.release.strip 

在 `mode.release` 和 `mode.releasedbg` 模式下，自动裁剪二进制文件中的调试符号。此策略默认启用。

当该策略启用且目标未显式调用 `set_strip()` 时，会自动设置 `set_strip("all")`。

```lua
-- 默认已启用，如需关闭
set_policy("build.release.strip", false)
```

## build.ccache 

Xmake 默认是开启内置的编译缓存的，通过设置这个策略，可以显式禁用缓存。

```lua
set_policy("build.ccache", false)
```

当然，我们也可以命令行去禁用它。

```sh
$ xmake f --ccache=n
```

或者

```sh
$ xmake f --policies=build.ccache:n
```

## build.warning 

默认编译通常不会实时回显警告输出，我们通常需要使用 `xmake -w` 开启，或者通过 `xmake g --build_warning=y` 来全局开启它。

现在，我们也可以在 xmake.lua 配置中去默认启用警告回显输出。

```lua
set_policy("build.warning", true)
set_warnings("all", "extra")
```

这个时候，即使我们执行 `xmake` 命令，也能直接回显警告输出。

## build.optimization.lto 

2.6.9 版本 xmake 改进了对 LTO 链接时优化的支持，对 gcc/clang/msvc 等不同平台下都进行了适配，只需要启用这个策略，就能对特定 target 开启 LTO。

```lua
set_policy("build.optimization.lto", true)
```

我们也可以通过命令行选项快速开启。

```sh
$ xmake f --policies=build.optimization.lto
```

## build.c++.dynamic\_debugging 

启用 MSVC 的 C++ 动态调试功能（需要 MSVC 工具集 14.44+，仅 x64，与 LTCG/PGO/OPT-ICF 不兼容）。

```lua
set_policy("build.c++.dynamic_debugging", true)
```

## build.cuda.devlink 

2.7.7 版本可以通过这个配置，显示开启对特定目标的设备链接。

这通常用于 Cuda 项目的构建，以及非 Cuda binary/shared 依赖 Cuda static 目标的情况，这个时候，Cuda static 目标就需要显示配置这个，开启设备链接。

```lua
target("test")
    set_kind("static")
    set_policy("build.cuda.devlink", true)
```

而默认 Cuda binary/shared 是开启 devlink 的，我们也可以通过策略显示禁用它。

关于这个的详细背景说明，见：[#1976](https://github.com/xmake-io/xmake/issues/1976)

## run.windows\_error\_dialog 

默认情况下，当 `xmake run` 在 Windows 上执行程序时，如果程序崩溃（例如段错误），Windows 可能会弹出错误对话框。这可能会阻塞自动化脚本或 CI/CD 流水线。

此策略控制在运行目标时是否启用 Windows 错误对话框。默认是启用的。

### 用法

如果你想禁用错误对话框（屏蔽它），可以将此策略设置为 `false`。

```lua
set_policy("run.windows_error_dialog", false)
```

## build.distcc.remote\_only 

这个策略用于配置分布式编译的行为。默认情况下，在启用分布式编译后，本机既充当调度节点，也会参与实际的编译工作。

如果启用这个策略，则强制仅让远程机器执行分布式编译任务，本机不参与实际编译，仅仅作为调度节点使用。这在本机资源有限，或者希望将所有编译工作都分配到远程服务器集群时非常有用。

```lua
set_policy("build.distcc.remote_only", true)
```

或者通过命令行启用：

```sh
$ xmake f --policies=build.distcc.remote_only
```

关于分布式编译的更多详细信息，请参阅：[分布式编译](/zh/guide/extras/distributed-compilation)

## build.sanitizer.address 

Address Sanitizer（ASan）是一个快速的内存错误检测工具，由编译器内置支持，通常我们需要在编译和链接的 flags 中同时配置 `-fsanitize-address` 才能正确开启。

而我们可以通过开启这个策略，就可以快速全局启用它，这会使得编译出来的程序，直接支持 ASan 检测。

例如，我们可以通过命令行的方式去启用：

```sh
$ xmake f --policies=build.sanitizer.address
```

也可以通过接口配置去全局启用：

```lua
set_policy("build.sanitizer.address", true)
```

当然，我们也可以单独对某个特定的 target 去配置开启。

另外，如果全局配置它，我们就可以同时对所有依赖包也生效。

```lua
set_policy("build.sanitizer.address", true)

add_requires("zlib")
add_requires("libpng")
```

它等价于，对每个包依次设置 asan 配置。

```lua
add_requires("zlib", {configs = {asan = true}})
add_requires("libpng", {configs = {asan = true}})
```

::: tip 注意
`add_rules("mode.asan", "mode.tsan", "mode.ubsan", "mode.msan")` 将被废弃，尽可能使用这些新的策略，因为这些构建模式无法同步对依赖包生效。
:::

另外，我们也可以同时生效多个 sanitizer 检测，例如：

```lua
set_policy("build.sanitizer.address", true)
set_policy("build.sanitizer.undefined", true)
```

或者

```
$ xmake f --policies=build.sanitizer.address,build.sanitizer.undefined
```

## build.sanitizer.thread 

与 [build.sanitizer.address](#build-sanitizer-address) 类似，用于检测线程安全问题。

## build.sanitizer.memory 

与 [build.sanitizer.address](#build-sanitizer-address) 类似，用于检测内存问题。

## build.sanitizer.leak 

与 [build.sanitizer.address](#build-sanitizer-address) 类似，用于检测内存泄漏问题。

## build.sanitizer.undefined 

与 [build.sanitizer.address](#build-sanitizer-address) 类似，用于检测 undefined 问题。

## build.always\_update\_configfiles 

这个策略用于对 `add_configfiles` 配置文件的自动生成行为。默认情况下，xmake 仅仅只会在首次 `xmake config` 时候，或者 xmake.lua 配置有改动的是否，才会触发 configfiles 的重新生成。

之后的每次构建，只要配置没有变化，就不会重新生成 configfiles。

但是，如果我们的 configfiles 中有使用 GIT\_COMMIT 等变量，想要每次构建时候，总是重新生成最新的配置，那么可以配置它。

具体使用背景，可以看下：[#4747](https://github.com/xmake-io/xmake/issues/4747)

## build.intermediate\_directory 

配置启用或禁用构建的内部子目录。

默认情况下，执行 `xmake` 编译项目会自动在 build 目录下根据平台。架构，编译模式生成子目录，分别存储对象文件，目标文件。例如：

```sh
build/
└── macosx
    └── x86_64
        └── release
            └─test
```

如果配置禁用此策略，那么生成的产物将会直接生成到 build 根目录下。变成：

```sh
build/
└─ test
```

## build.rpath 

配置启用或者禁用构建时的 target rpath 设置。

默认情况下，如果 `target(foo)` 依赖动态库 bar，那么生成的 foo 可执行文件会自动加上 bar 的 rpath，这能保证用户直接执行 foo 程序，也能正确找到 bar。

如果你想禁用这个行为，可以显式配置禁用它。

## install.rpath 

尽管构建后的程序，会被设置 rpath，但是当 `xmake install` 安装后，它构建时候的 rpath 就不一定完全适用了，因此 xmake 会自动修改调整 rpath，使得安装后的程序，同样可以找到它的依赖库。

不过前提是，用户自己先得通过 `add_rpathdirs("/xxx", {installonly = true})` 去配置独立的安装 rpath。

而我们也可以通过这个 policy 去禁用默认的安装阶段 rpath 设置行为。

## run.autobuild 

这个策略用于调整 `xmake run` 的行为，默认情况下，执行 `xmake run` 并不会自动构建目标程序，如果程序还没被编译，就是提示用户手动构建一下。

而开启这个策略，我们就可以在运行程序前，先自动构建对应的目标程序。

```sh
$ xmake f --policies=run.autobuild
$ xmake run
```

如果想要全局生效这个策略，可以全局开启它。

```sh
$ xmake g --policies=run.autobuild
```

## preprocessor.linemarkers 

通常用户编译缓存中，预处理器的生成策略，默认开启，如果配置关闭这个策略，那么缓存生成的预处理文件内容将不包含 linemarkers 信息，这会极大减少预处理文件大小。
也会提升缓存的处理效率，但是缺点就是会丢失源码行信息，如果遇到编译错误，将无法看到准确的出错代码行。

## preprocessor.gcc.directives\_only 

这也是用于预处理器的策略，默认开启，这会提升 gcc 下编译缓存预处理的效率，但是如果源文件中包含 `__DATE__`, `__TIME__` 等宏，就会导致缓存出现不一致。

因此，可以根据自身工程代码，按需关闭此策略，确保生成的结果一致。

## package.requires\_lock 

可用于开启 `add_requires()` 引入的依赖包的版本锁定。

具体看下：[依赖包的锁定和升级](/zh/guide/package-management/using-official-packages#lock-and-upgrade-package)。

## package.precompiled 

可用于禁用 windows 下预编译依赖包的获取。

## package.fetch\_only 

如果开启这个策略，那么所有的依赖包仅仅只会从系统获取，不会从远程下载安装。

## package.install\_only 

如果开启这个策略，那么所有的依赖包仅仅只会走远程下载安装，不会从系统查找获取。

## package.librarydeps.strict\_compatibility 

默认禁用，如果启用它，那么当前包和它的所有库依赖包之间会保持严格的兼容性，任何依赖包的版本更新，都会强制触发当前包的重新编译安装。

以确保所有的包都是二进制兼容的，不会因为某个依赖包接口改动，导致和其他已被安装的其他包一起链接时候，发生链接和运行错误。

```lua
package("foo")
    add_deps("bar", "zoo")
    set_policy("package.librarydeps.strict_compatibility", true)
```

例如，如果 bar 或者 zoo 的版本有更新，那么 foo 也会重新编译安装。

## package.strict\_compatibility 

默认禁用，如果启用它，那么当前包和其他所有依赖它的包之间会保持严格的兼容性，这个包的版本更新，都会强制触发其他父包的重新编译安装。

以确保所有的包都是二进制兼容的，不会因为某个依赖包接口改动，导致和其他已被安装的其他包一起链接时候，发生链接和运行错误。

```lua
package("foo")
    set_policy("package.strict_compatibility", true)

package("bar")
    add_deps("foo")

package("zoo")
    add_deps("foo")
```

例如，如果 foo 的版本有更新，那么 bar 和 zoo 都会被强制重新编译安装。

## package.install\_always 

每次运行 `xmake f -c` 重新配置的时候，总是会重新安装包，这对于本地第三方源码包集成时候比较有用。

因为，用户可能随时需要修改第三方源码，然后重新编译集成它们。

之前只能通过每次修改包版本号，来触发重新编译，但是有了这个策略，就能每次都会触发重编。

```lua
add_rules("mode.debug", "mode.release")

package("foo")
    add_deps("cmake")
    set_sourcedir(path.join(os.scriptdir(), "foo"))
    set_policy("package.install_always", true)
    on_install(function (package)
        local configs = {}
        table.insert(configs, "-DCMAKE_BUILD_TYPE=" .. (package:debug() and "Debug" or "Release"))
        table.insert(configs, "-DBUILD_SHARED_LIBS=" .. (package:config("shared") and "ON" or "OFF"))
        import("package.tools.cmake").install(package, configs)
    end)
    on_test(function (package)
        assert(package:has_cfuncs("add", {includes = "foo.h"}))
    end)
package_end()

add_requires("foo")

target("demo")
    set_kind("binary")
    add_files("src/main.c")
    add_packages("foo")
```

## package.download.http\_headers 

设置包下载的 http headers

如果有些包的 url 下载，需要设置特定 http headers，才能通过下载，可以通过这个策略来指定。

```lua
package("xxx")
    set_policy("package.download.http_headers", "TEST1: foo", "TEST2: bar")
```

我们也可以设置指定的 urls 的 http headers：

```lua
add_urls("https://github.com/madler/zlib/archive/$(version).tar.gz", {
    http_headers = {"TEST1: foo", "TEST2: bar"}
})
```

## windows.manifest.uac 

通过这个策略，我们可以快速方便的设置并启用 Windows UAC。

它支持以下几个 Level：

| Level | Flag |
| --- | --- |
| invoker | asInvoker |
| admin | requireAdministrator |
| highest | highestAvailable |

例如：

```lua
set_policy("windows.manifest.uac", "admin")
```

它等价于设置

```lua
if is_plat("windows") then
    add_ldflags("/manifest:embed", {"/manifestuac:level='requireAdministrator' uiAccess='false'"}, {force = true, expand = false})
end
```

但是更加方便简洁，并且不需要判断平台，其他平台自动忽略。

## windows.manifest.uac.ui 

设置 Windows UAC 的 uiAccess，如果没有设置它，默认是 false。

```lua
set_policy("windows.manifest.uac.ui", true)
```

## build.progress\_style 

设置构建进度输出的样式。支持两种样式：

* `"single"`（默认）：单行进度输出，只更新一行进度信息
* `"multirow"`：多行进度输出，显示多个并发构建任务及其各自的进度

多行进度输出在长时间运行的构建过程中提供更好的视觉体验，使得监控并行编译变得更加容易。

您可以通过两种方式启用多行进度输出：

1. **通过主题配置**：使用 `soong` 主题，它默认包含多行进度：
   ```bash
   $ xmake g --theme=soong
   ```

2. **通过项目策略**：在 `xmake.lua` 中直接启用：
   ```lua
   set_policy("build.progress_style", "multirow")
   ```

这提供了更好的并行构建进度可见性，更容易识别编译缓慢的单元，并为包含大量源文件或具有多个编译单元的并行构建的大型项目改善了整体用户体验。

## build.ccache.global\_storage 

开启 `build.ccache` 后，使用全局存储来存放编译缓存。

```lua
set_policy("build.ccache.global_storage", true)
```

## build.c++.modules 

即使没有 `.mpp` 文件参与编译，也强制启用 C++ Modules 支持。

```lua
set_policy("build.c++.modules", true)
```

## build.c++.modules.std 

启用 std 模块导入支持，默认启用。

```lua
set_policy("build.c++.modules.std", false) -- 禁用
```

## build.c++.modules.culling 

启用未引用和非公开命名模块的裁剪，默认启用。

```lua
set_policy("build.c++.modules.culling", false)
```

## build.c++.modules.reuse 

尽可能复用已编译的模块 BMI 文件，默认启用。

```lua
set_policy("build.c++.modules.reuse", false)
```

## build.c++.modules.reuse.nocheck 

复用模块时禁用编译标志兼容性检查。

```lua
set_policy("build.c++.modules.reuse.nocheck", true)
```

## build.c++.modules.reuse.strict 

复用模块时，如果依赖目标的宏定义不同则不复用。

```lua
set_policy("build.c++.modules.reuse.strict", true)
```

## build.c++.modules.fallbackscanner 

强制所有编译器使用回退模块依赖扫描器。

```lua
set_policy("build.c++.modules.fallbackscanner", true)
```

## build.c++.modules.clang.fallbackscanner 

强制 clang 使用回退模块依赖扫描器。

```lua
set_policy("build.c++.modules.clang.fallbackscanner", true)
```

## build.c++.modules.msvc.fallbackscanner 

强制 msvc 使用回退模块依赖扫描器。

```lua
set_policy("build.c++.modules.msvc.fallbackscanner", true)
```

## build.c++.modules.gcc.fallbackscanner 

强制 gcc 使用回退模块依赖扫描器。

```lua
set_policy("build.c++.modules.gcc.fallbackscanner", true)
```

## build.c++.modules.gcc.cxx11abi 

强制在 gcc 的 C++ Modules 中启用新的 cxx11 ABI。

```lua
set_policy("build.c++.modules.gcc.cxx11abi", true)
```

## build.c++.modules.non\_cascading\_changes 

启用非级联变更支持（实验性），默认关闭。

```lua
set_policy("build.c++.modules.non_cascading_changes", true)
```

## build.c++.modules.hide\_dependencies 

隐藏 C++ Modules 编译时命令行中的依赖文件，减少噪音（可能降低构建性能）。

```lua
set_policy("build.c++.modules.hide_dependencies", true)
```

## build.c++.modules.two\_phases 

如果编译器支持，启用两阶段编译，默认启用。

```lua
set_policy("build.c++.modules.two_phases", false)
```

## build.c++.msvc.runtime 

设置默认的 MSVC 运行时，可选值为 `MT` 或 `MD`。

```lua
set_policy("build.c++.msvc.runtime", "MT")
```

## build.linker.output 

启用链接器输出信息，例如显示 gcc/g++ 的 `-Wl,--print-memory-usage` 输出。

```lua
set_policy("build.linker.output", true)
```

## build.jobgraph 

启用构建 jobgraph，默认启用。

```lua
set_policy("build.jobgraph", false) -- 禁用
```

## build.progress\_show\_target 

在构建进度输出中显示目标名称，默认启用。

```lua
set_policy("build.progress_show_target", false)
```

## install.strip\_packagelibs 

安装时裁剪包库文件中的符号，默认启用。

```lua
set_policy("install.strip_packagelibs", false)
```

## platform.longpaths 

在 Windows 上构建目标或安装包时启用长路径支持。

```lua
set_policy("platform.longpaths", true)
```

## package.install\_locally 

将包安装到本地项目目录而非全局目录。

```lua
set_policy("package.install_locally", true)
```

它只影响平台侧的包。主机包 —— 也就是用来构建其它包的工具，例如交叉工具链 —— 不依赖工程配置，而且跨工程复用，所以仍然装在全局目录，并有自己的策略，@see `package.host.install_locally`。

## package.host.install\_locally 

让主机包（例如工具链）也安装到本地项目目录。

```lua
set_policy("package.install_locally", true)
set_policy("package.host.install_locally", true)
```

适用于工程需要完全自包含的场景，比如要求连工具链都放在 `build/.packages` 下的可复现构建。不开启时，只有你的程序真正链接的那些包会装在本地。

## package.keep\_source 

安装包后保留源码，不清理源码目录。

```lua
set_policy("package.keep_source", true)
```

## package.include\_external\_headers 

将包的头文件作为外部头文件引用（如使用 `-isystem`），减少警告。

```lua
set_policy("package.include_external_headers", false)
```

## package.inherit\_external\_configs 

从外部命令行参数继承配置（如工具链），默认启用。

```lua
set_policy("package.inherit_external_configs", false)
```

## package.resolve\_depconflict 

自动解决包依赖冲突，默认启用。

```lua
set_policy("package.resolve_depconflict", false)
```

## package.sync\_requires\_to\_deps 

将顶层 `add_requires` 配置同步到所有包依赖项。

```lua
set_policy("package.sync_requires_to_deps", true)
```

## package.xmake.pass\_depconfs 

自动将依赖配置传递给内部 xmake 包，默认启用。

```lua
set_policy("package.xmake.pass_depconfs", false)
```

## package.cmake\_generator.ninja 

强制 cmake 包使用 ninja 进行构建。

```lua
set_policy("package.cmake_generator.ninja", true)
```

## package.msbuild.multi\_tool\_task 

启用 msbuild 的 MultiToolTask 并行编译。

```lua
set_policy("package.msbuild.multi_tool_task", true)
```

## package.merge\_staticlibs 

安装包后合并所有静态库。

```lua
set_policy("package.merge_staticlibs", true)
```

## package.build.ccache 

启用 C/C++ 包构建缓存，默认关闭。

```lua
set_policy("package.build.ccache", true)
```

## test.stop\_on\_first\_failure 

在第一个测试失败时停止运行后续测试。

```lua
set_policy("test.stop_on_first_failure", true)
```

## test.return\_zero\_on\_failure 

测试失败时返回 0 作为退出码。

```lua
set_policy("test.return_zero_on_failure", true)
```

## diagnosis.check\_build\_deps 

显示构建依赖检查的诊断信息。

```lua
set_policy("diagnosis.check_build_deps", true)
```

## network.mode 

设置网络模式，设为 `private` 时将禁用远程包仓库获取。

```lua
set_policy("network.mode", "private")
```

## compatibility.version 

设置兼容性版本，可选值为 `2.0` 或 `3.0`，默认 `3.0`。

```lua
set_policy("compatibility.version", "2.0")
```

## generator.compile\_commands 

启用 compile\_commands.json 生成，默认启用。

```lua
set_policy("generator.compile_commands", false)
```

## generator.vsxmake.root\_sln 

在根输出目录生成解决方案文件。

```lua
set_policy("generator.vsxmake.root_sln", true)
```