From 24597d9ea38b794b73f0bea1779c6af16af14dc4 Mon Sep 17 00:00:00 2001 From: Willaaaaaaa Date: Thu, 2 Oct 2025 13:59:49 +0800 Subject: [PATCH 1/9] fix anchors --- docs/api/description/builtin-policies.md | 62 ++++++++++----------- docs/zh/api/description/builtin-policies.md | 62 ++++++++++----------- 2 files changed, 62 insertions(+), 62 deletions(-) diff --git a/docs/api/description/builtin-policies.md b/docs/api/description/builtin-policies.md index e229dd0bc..3526327ee 100644 --- a/docs/api/description/builtin-policies.md +++ b/docs/api/description/builtin-policies.md @@ -64,7 +64,7 @@ Or configure multiple policy values at the same time, separated by commas. $ xmake f --policies=package.precompiled:n,package.install_only ``` -### check.auto_ignore_flags +## check.auto_ignore_flags By default, xmake will automatically detect all the original flags set by the `add_cxflags` and` add_ldflags` interfaces. If the current compiler and linker do not support them, they will be automatically ignored. @@ -96,7 +96,7 @@ target("test") Then we can set various original flags at will, xmake will not automatically detect and ignore them. -### check.auto_map_flags +## check.auto_map_flags This is another intelligent analysis and processing of flags by xmake. Usually, the configuration set by xmake built-in APIs like `add_links`,` add_defines` is cross-platform, and different compiler platforms will automatically process them into corresponding Original flags. @@ -126,7 +126,7 @@ Some users do not like this automatic mapping behavior, so we can completely dis set_policy("check.auto_map_flags", false) ``` -### build.across_targets_in_parallel +## build.across_targets_in_parallel This strategy is also enabled by default and is mainly used to perform parallel builds between targets. In versions prior to v2.3.3, parallel builds can only target all source files within a single target. For cross-target compilation, you must wait until the previous target is fully linked before you can execute the compilation of the next target, which will affect the compilation speed to a certain extent. @@ -139,7 +139,7 @@ Of course, if the build source files in some special targets depend on previous set_policy("build.across_targets_in_parallel", false) ``` -### build.fence +## build.fence Due to the limitation of `set_policy(‘build.across_targets_in_parallel’, false)`, it will limit the parallelism between the parent target and all of its dependent subtargets, which is a bit wide. @@ -175,7 +175,7 @@ The autogen target needs to be compiled and linked before the source code of the The autogen configuration `set_policy(‘build.fence’, true)` does this. -### build.merge_archive +## build.merge_archive If this policy is set, then the target libraries that are dependent on using `add_deps()` no longer exist as links, but are merged directly into the parent target library. @@ -208,7 +208,7 @@ target("test") The libmul.a static library automatically merges the libadd.a and libsub.a sub-dependent static libraries. -### build.ccache +## build.ccache Xmake has a built-in build cache enabled by default, which can be explicitly disabled by setting this policy. @@ -228,7 +228,7 @@ or $ xmake f --policies=build.ccache:n ``` -### build.warning +## build.warning The default compilation usually does not echo the warning output in real time, we usually need to use `xmake -w` to turn it on, or to turn it on globally with `xmake g --build_warning=y`. @@ -241,7 +241,7 @@ set_warnings("all", "extra") At this time, even if we execute the `xmake` command, the warning output can be echoed directly. -### build.optimization.lto +## build.optimization.lto xmake v2.6.9 has improved support for link-time optimisation (LTO), with adaptations for different platforms such as gcc/clang/msvc, simply by enabling this policy to enable LTO for specific targets. @@ -255,7 +255,7 @@ We can also turn it on quickly via the command line option. $ xmake f --policies=build.optimization.lto ``` -### build.cuda.devlink +## build.cuda.devlink Version 2.7.7 can be configured to show that device links to specific targets are turned on. @@ -271,7 +271,7 @@ Whereas by default Cuda binary/shared is devlink enabled, we can also disable it For a detailed background on this, see: [#1976](https://github.com/xmake-io/xmake/issues/1976) -### build.sanitizer.address +## build.sanitizer.address Address Sanitizer (ASan) is a fast memory error detection tool that is built-in by the compiler, and usually requires `-fsanitize-address` to be configured in both the build and link flags to enable it correctly. @@ -325,23 +325,23 @@ or $ xmake f --policies=build.sanitizer.address,build.sanitizer.undefined ``` -### build.sanitizer.thread +## build.sanitizer.thread Similar to [build.sanitizer.address](#build-sanitizer-address) for detecting thread safety issues. -### build.sanitizer.memory +## build.sanitizer.memory Similar to [build.sanitizer.address](#build-sanitizer-address) for detecting memory issues. -### build.sanitizer.leak +## build.sanitizer.leak Similar to [build.sanitizer.address](#build-sanitizer-address) for detecting memory leaks. -### build.sanitizer.undefined +## build.sanitizer.undefined Similar to [build.sanitizer.address](#build-sanitizer-address) for detecting undefined issues. -### build.always_update_configfiles +## build.always_update_configfiles This policy is used for the automatic generation of `add_configfiles` configuration files. By default, xmake only triggers the regeneration of configfiles the first time `xmake config` is done, or if the xmake.lua configuration is changed. @@ -351,7 +351,7 @@ However, if we use a variable such as GIT_COMMIT in our configfiles and want to For background on how to use it, see: [#4747](https://github.com/xmake-io/xmake/issues/4747) -### build.intermediate_directory +## build.intermediate_directory Configures whether to enable or disable internal subdirectories of the build. @@ -372,7 +372,7 @@ build/ └─ test ``` -### build.rpath +## build.rpath Configures to enable or disable the target rpath setting during build. @@ -380,7 +380,7 @@ By default, if `target(foo)` depends on the dynamic library bar, the generated f If you want to disable this behavior, you can explicitly configure it. -### install.rpath +## install.rpath Although the rpath will be set for the built program, the rpath when it is built may not be completely applicable after `xmake install` is installed, so xmake will automatically modify and adjust the rpath so that the installed program can also find its dependent libraries. @@ -388,7 +388,7 @@ However, the premise is that the user must first configure an independent instal And we can also use this policy to disable the default installation phase rpath setting behavior. -### run.autobuild +## run.autobuild This policy is used to adjust the behaviour of `xmake run`. By default, running `xmake run` does not build the target program automatically, but prompts the user to build it manually if it has not been compiled yet. @@ -405,36 +405,36 @@ If you want this policy to take effect globally, you can turn it on globally. $ xmake g --policies=run.autobuild ``` -### preprocessor.linemarkers +## preprocessor.linemarkers If this policy is turned off, then the cache will generate preprocessor files without linemarkers, which will greatly reduce the size of the preprocessor files. This will greatly reduce the size of the preprocessor file and improve the efficiency of the cache, but the downside is that the source line information will be lost and if you encounter a compilation error, you will not be able to see the exact line of code that went wrong. -### preprocessor.gcc.directives_only +## preprocessor.gcc.directives_only This is also used as a preprocessor policy and is enabled by default. This will improve the efficiency of compile cache preprocessing under gcc, but can lead to cache inconsistencies if the source file contains macros such as `__DATE__`, `__TIME__`, etc. Therefore, you can turn this policy off as needed to ensure consistent results, depending on your project code. -### package.requires_lock +## package.requires_lock Can be used to enable version locking of dependency packages introduced by `add_requires()`. See [Dependent package lock and upgrade](/guide/package-management/using-official-packages#dependent-package-lock-and-upgrade). -### package.precompiled +## package.precompiled Can be used to disable fetching of precompiled dependency packages under windows. -### package.fetch_only +## package.fetch_only If this policy is enabled, then all dependencies will only be fetched from the system and not downloaded and installed from a remote location. -### package.install_only +## package.install_only If this policy is enabled, then all dependencies will only be downloaded and installed remotely, not fetched from the system. -### package.librarydeps.strict_compatibility +## package.librarydeps.strict_compatibility Disabled by default, if enabled then strict compatibility is maintained between the current package and all its library dependencies, any version update of a dependent package will force a recompile install of the current package. @@ -448,7 +448,7 @@ package("foo") For example, if there is an updated version of bar or zoo, then foo will also be recompiled and installed. -### package.strict_compatibility +## package.strict_compatibility is disabled by default, if it is enabled then strict compatibility is maintained between the current package and all other packages that depend on it, and any version update of this package will force a recompile and install of the other parent packages. @@ -468,7 +468,7 @@ package("zoo") For example, if there is an updated version of foo, then both bar and zoo will be forced to be recompiled and installed. -### package.install_always +## package.install_always This is useful for local integration of third-party source packages, as the package will always be reinstalled each time `xmake f -c` is run to reconfigure it. @@ -504,7 +504,7 @@ target("demo") add_packages("foo") ``` -### package.download.http_headers +## package.download.http_headers Setting http headers for package downloads @@ -523,7 +523,7 @@ add_urls("https://github.com/madler/zlib/archive/$(version).tar.gz", { }) ``` -### windows.manifest.uac +## windows.manifest.uac This policy allows us to quickly and easily setup and enable Windows UAC. @@ -551,7 +551,7 @@ end But it's easier and cleaner, and doesn't need to judge the platform, other platforms are automatically ignored. -### windows.manifest.uac.ui +## windows.manifest.uac.ui Sets uiAccess for Windows UAC, defaults to false if it is not set. diff --git a/docs/zh/api/description/builtin-policies.md b/docs/zh/api/description/builtin-policies.md index 89e0a68e6..2c1a1bcd1 100644 --- a/docs/zh/api/description/builtin-policies.md +++ b/docs/zh/api/description/builtin-policies.md @@ -66,7 +66,7 @@ $ xmake f --policies=package.precompiled:n $ xmake f --policies=package.precompiled:n,package.install_only ``` -### check.auto_ignore_flags +## check.auto_ignore_flags xmake默认会对所有`add_cxflags`, `add_ldflags`接口设置的原始flags进行自动检测，如果检测当前编译器和链接器不支持它们，就会自动忽略。 @@ -98,7 +98,7 @@ target("test") 然后我们就可以随意设置各种原始flags，xmake不会去自动检测和忽略他们了。 -### check.auto_map_flags +## check.auto_map_flags 这是xmake的另外一个对flags的智能分析处理，通常像`add_links`, `add_defines`这种xmake内置的api去设置的配置，是具有跨平台特性的，不同编译器平台会自动处理成对应的原始flags。 @@ -128,7 +128,7 @@ add_cxflags("-O0") set_policy("check.auto_map_flags", false) ``` -### build.across_targets_in_parallel +## build.across_targets_in_parallel 这个策略也是默认开启的，主要用于跨target间执行并行构建，v2.3.3之前的版本，并行构建只能针对单个target内部的所有源文件， 跨target的编译，必须要要等先前的target完全link成功，才能执行下一个target的编译，这在一定程度上会影响编译速度。 @@ -141,7 +141,7 @@ set_policy("check.auto_map_flags", false) set_policy("build.across_targets_in_parallel", false) ``` -### build.fence +## build.fence 由于配置 `set_policy("build.across_targets_in_parallel", false)` 存在局限性，它会限制父 target 和它的所有依赖的子 target 之间的并行度，影响的范围有点大。 @@ -177,7 +177,7 @@ target("test") 而针对 autogen 配置 `set_policy("build.fence", true)` 就可以实现这个目的。 -### build.merge_archive +## build.merge_archive 如果设置了这个策略，那么使用 `add_deps()` 依赖的目标库不再作为链接存在，而是直接把它们合并到父目标库中去。 @@ -210,7 +210,7 @@ target("test") libmul.a 静态库会自动合并 libadd.a 和 libsub.a 两个子依赖的静态库。 -### build.ccache +## build.ccache Xmake 默认是开启内置的编译缓存的，通过设置这个策略，可以显式禁用缓存。 @@ -230,7 +230,7 @@ $ xmake f --ccache=n $ xmake f --policies=build.ccache:n ``` -### build.warning +## build.warning 默认编译通常不会实时回显警告输出，我们通常需要使用 `xmake -w` 开启，或者通过 `xmake g --build_warning=y` 来全局开启它。 @@ -243,7 +243,7 @@ set_warnings("all", "extra") 这个时候，即使我们执行 `xmake` 命令，也能直接回显警告输出。 -### build.optimization.lto +## build.optimization.lto 2.6.9 版本 xmake 改进了对 LTO 链接时优化的支持，对 gcc/clang/msvc 等不同平台下都进行了适配，只需要启用这个策略，就能对特定 target 开启 LTO。 @@ -257,7 +257,7 @@ set_policy("build.optimization.lto", true) $ xmake f --policies=build.optimization.lto ``` -### build.cuda.devlink +## build.cuda.devlink 2.7.7 版本可以通过这个配置，显示开启对特定目标的设备链接。 @@ -273,7 +273,7 @@ target("test") 关于这个的详细背景说明，见：[#1976](https://github.com/xmake-io/xmake/issues/1976) -### build.sanitizer.address +## build.sanitizer.address Address Sanitizer（ASan）是一个快速的内存错误检测工具，由编译器内置支持，通常我们需要在编译和链接的 flags 中同时配置 `-fsanitize-address` 才能正确开启。 @@ -327,23 +327,23 @@ set_policy("build.sanitizer.undefined", true) $ xmake f --policies=build.sanitizer.address,build.sanitizer.undefined ``` -### build.sanitizer.thread +## build.sanitizer.thread 与 [build.sanitizer.address](#build-sanitizer-address) 类似，用于检测线程安全问题。 -### build.sanitizer.memory +## build.sanitizer.memory 与 [build.sanitizer.address](#build-sanitizer-address) 类似，用于检测内存问题。 -### build.sanitizer.leak +## build.sanitizer.leak 与 [build.sanitizer.address](#build-sanitizer-address) 类似，用于检测内存泄漏问题。 -### build.sanitizer.undefined +## build.sanitizer.undefined 与 [build.sanitizer.address](#build-sanitizer-address) 类似，用于检测 undefined 问题。 -### build.always_update_configfiles +## build.always_update_configfiles 这个策略用于对 `add_configfiles` 配置文件的自动生成行为。默认情况下，xmake 仅仅只会在首次 `xmake config` 时候，或者 xmake.lua 配置有改动的是否，才会触发 configfiles 的重新生成。 @@ -353,7 +353,7 @@ $ xmake f --policies=build.sanitizer.address,build.sanitizer.undefined 具体使用背景，可以看下：[#4747](https://github.com/xmake-io/xmake/issues/4747) -### build.intermediate_directory +## build.intermediate_directory 配置启用或禁用构建的内部子目录。 @@ -374,7 +374,7 @@ build/ └─ test ``` -### build.rpath +## build.rpath 配置启用或者禁用构建时的 target rpath 设置。 @@ -382,7 +382,7 @@ build/ 如果你想禁用这个行为，可以显式配置禁用它。 -### install.rpath +## install.rpath 尽管构建后的程序，会被设置 rpath，但是当 `xmake install` 安装后，它构建时候的 rpath 就不一定完全适用了，因此 xmake 会自动修改调整 rpath，使得安装后的程序，同样可以找到它的依赖库。 @@ -390,7 +390,7 @@ build/ 而我们也可以通过这个 policy 去禁用默认的安装阶段 rpath 设置行为。 -### run.autobuild +## run.autobuild 这个策略用于调整 `xmake run` 的行为，默认情况下，执行 `xmake run` 并不会自动构建目标程序，如果程序还没被编译，就是提示用户手动构建一下。 @@ -407,36 +407,36 @@ $ xmake run $ xmake g --policies=run.autobuild ``` -### preprocessor.linemarkers +## preprocessor.linemarkers 通常用户编译缓存中，预处理器的生成策略，默认开启，如果配置关闭这个策略，那么缓存生成的预处理文件内容将不包含 linemarkers 信息，这会极大减少预处理文件大小。 也会提升缓存的处理效率，但是缺点就是会丢失源码行信息，如果遇到编译错误，将无法看到准确的出错代码行。 -### preprocessor.gcc.directives_only +## preprocessor.gcc.directives_only 这也是用于预处理器的策略，默认开启，这会提升 gcc 下编译缓存预处理的效率，但是如果源文件中包含 `__DATE__`, `__TIME__` 等宏，就会导致缓存出现不一致。 因此，可以根据自身工程代码，按需关闭此策略，确保生成的结果一致。 -### package.requires_lock +## package.requires_lock 可用于开启 `add_requires()` 引入的依赖包的版本锁定。 具体看下：[依赖包的锁定和升级](/zh/guide/package-management/using-official-packages#lock-and-upgrade-package)。 -### package.precompiled +## package.precompiled 可用于禁用 windows 下预编译依赖包的获取。 -### package.fetch_only +## package.fetch_only 如果开启这个策略，那么所有的依赖包仅仅只会从系统获取，不会从远程下载安装。 -### package.install_only +## package.install_only 如果开启这个策略，那么所有的依赖包仅仅只会走远程下载安装，不会从系统查找获取。 -### package.librarydeps.strict_compatibility +## package.librarydeps.strict_compatibility 默认禁用，如果启用它，那么当前包和它的所有库依赖包之间会保持严格的兼容性，任何依赖包的版本更新，都会强制触发当前包的重新编译安装。 @@ -450,7 +450,7 @@ package("foo") 例如，如果 bar 或者 zoo 的版本有更新，那么 foo 也会重新编译安装。 -### package.strict_compatibility +## package.strict_compatibility 默认禁用，如果启用它，那么当前包和其他所有依赖它的包之间会保持严格的兼容性，这个包的版本更新，都会强制触发其他父包的重新编译安装。 @@ -470,7 +470,7 @@ package("zoo") 例如，如果 foo 的版本有更新，那么 bar 和 zoo 都会被强制重新编译安装。 -### package.install_always +## package.install_always 每次运行 `xmake f -c` 重新配置的时候，总是会重新安装包，这对于本地第三方源码包集成时候比较有用。 @@ -504,7 +504,7 @@ target("demo") add_packages("foo") ``` -### package.download.http_headers +## package.download.http_headers 设置包下载的 http headers @@ -523,7 +523,7 @@ add_urls("https://github.com/madler/zlib/archive/$(version).tar.gz", { }) ``` -### windows.manifest.uac +## windows.manifest.uac 通过这个策略，我们可以快速方便的设置并启用 Windows UAC。 @@ -551,7 +551,7 @@ end 但是更加方便简洁，并且不需要判断平台，其他平台自动忽略。 -### windows.manifest.uac.ui +## windows.manifest.uac.ui 设置 Windows UAC 的 uiAccess，如果没有设置它，默认是 false。 From bd92058b7474c038573572916d5b0193ade1400e Mon Sep 17 00:00:00 2001 From: Willaaaaaaa Date: Thu, 2 Oct 2025 20:06:42 +0800 Subject: [PATCH 2/9] add supported version info --- docs/api/description/builtin-policies.md | 64 ++++++++++----------- docs/zh/api/description/builtin-policies.md | 64 ++++++++++----------- 2 files changed, 64 insertions(+), 64 deletions(-) diff --git a/docs/api/description/builtin-policies.md b/docs/api/description/builtin-policies.md index 3526327ee..420070922 100644 --- a/docs/api/description/builtin-policies.md +++ b/docs/api/description/builtin-policies.md @@ -1,4 +1,4 @@ -# Build Policies +# Built-in Policies Xmake has many default behaviors, such as: automatic detection and mapping of flags, cross-target parallel construction, etc. Although it provides a certain amount of intelligent processing, it is difficult to adjust and may not meet all users' habits and needs. @@ -64,7 +64,7 @@ Or configure multiple policy values at the same time, separated by commas. $ xmake f --policies=package.precompiled:n,package.install_only ``` -## check.auto_ignore_flags +## check.auto_ignore_flags By default, xmake will automatically detect all the original flags set by the `add_cxflags` and` add_ldflags` interfaces. If the current compiler and linker do not support them, they will be automatically ignored. @@ -96,7 +96,7 @@ target("test") Then we can set various original flags at will, xmake will not automatically detect and ignore them. -## check.auto_map_flags +## check.auto_map_flags This is another intelligent analysis and processing of flags by xmake. Usually, the configuration set by xmake built-in APIs like `add_links`,` add_defines` is cross-platform, and different compiler platforms will automatically process them into corresponding Original flags. @@ -126,7 +126,7 @@ Some users do not like this automatic mapping behavior, so we can completely dis set_policy("check.auto_map_flags", false) ``` -## build.across_targets_in_parallel +## build.across_targets_in_parallel This strategy is also enabled by default and is mainly used to perform parallel builds between targets. In versions prior to v2.3.3, parallel builds can only target all source files within a single target. For cross-target compilation, you must wait until the previous target is fully linked before you can execute the compilation of the next target, which will affect the compilation speed to a certain extent. @@ -139,7 +139,7 @@ Of course, if the build source files in some special targets depend on previous set_policy("build.across_targets_in_parallel", false) ``` -## build.fence +## build.fence Due to the limitation of `set_policy(‘build.across_targets_in_parallel’, false)`, it will limit the parallelism between the parent target and all of its dependent subtargets, which is a bit wide. @@ -175,7 +175,7 @@ The autogen target needs to be compiled and linked before the source code of the The autogen configuration `set_policy(‘build.fence’, true)` does this. -## build.merge_archive +## build.merge_archive If this policy is set, then the target libraries that are dependent on using `add_deps()` no longer exist as links, but are merged directly into the parent target library. @@ -208,7 +208,7 @@ target("test") The libmul.a static library automatically merges the libadd.a and libsub.a sub-dependent static libraries. -## build.ccache +## build.ccache Xmake has a built-in build cache enabled by default, which can be explicitly disabled by setting this policy. @@ -228,7 +228,7 @@ or $ xmake f --policies=build.ccache:n ``` -## build.warning +## build.warning The default compilation usually does not echo the warning output in real time, we usually need to use `xmake -w` to turn it on, or to turn it on globally with `xmake g --build_warning=y`. @@ -241,7 +241,7 @@ set_warnings("all", "extra") At this time, even if we execute the `xmake` command, the warning output can be echoed directly. -## build.optimization.lto +## build.optimization.lto xmake v2.6.9 has improved support for link-time optimisation (LTO), with adaptations for different platforms such as gcc/clang/msvc, simply by enabling this policy to enable LTO for specific targets. @@ -255,7 +255,7 @@ We can also turn it on quickly via the command line option. $ xmake f --policies=build.optimization.lto ``` -## build.cuda.devlink +## build.cuda.devlink Version 2.7.7 can be configured to show that device links to specific targets are turned on. @@ -271,7 +271,7 @@ Whereas by default Cuda binary/shared is devlink enabled, we can also disable it For a detailed background on this, see: [#1976](https://github.com/xmake-io/xmake/issues/1976) -## build.sanitizer.address +## build.sanitizer.address Address Sanitizer (ASan) is a fast memory error detection tool that is built-in by the compiler, and usually requires `-fsanitize-address` to be configured in both the build and link flags to enable it correctly. @@ -325,23 +325,23 @@ or $ xmake f --policies=build.sanitizer.address,build.sanitizer.undefined ``` -## build.sanitizer.thread +## build.sanitizer.thread Similar to [build.sanitizer.address](#build-sanitizer-address) for detecting thread safety issues. -## build.sanitizer.memory +## build.sanitizer.memory Similar to [build.sanitizer.address](#build-sanitizer-address) for detecting memory issues. -## build.sanitizer.leak +## build.sanitizer.leak Similar to [build.sanitizer.address](#build-sanitizer-address) for detecting memory leaks. -## build.sanitizer.undefined +## build.sanitizer.undefined Similar to [build.sanitizer.address](#build-sanitizer-address) for detecting undefined issues. -## build.always_update_configfiles +## build.always_update_configfiles This policy is used for the automatic generation of `add_configfiles` configuration files. By default, xmake only triggers the regeneration of configfiles the first time `xmake config` is done, or if the xmake.lua configuration is changed. @@ -351,7 +351,7 @@ However, if we use a variable such as GIT_COMMIT in our configfiles and want to For background on how to use it, see: [#4747](https://github.com/xmake-io/xmake/issues/4747) -## build.intermediate_directory +## build.intermediate_directory Configures whether to enable or disable internal subdirectories of the build. @@ -372,7 +372,7 @@ build/ └─ test ``` -## build.rpath +## build.rpath Configures to enable or disable the target rpath setting during build. @@ -380,7 +380,7 @@ By default, if `target(foo)` depends on the dynamic library bar, the generated f If you want to disable this behavior, you can explicitly configure it. -## install.rpath +## install.rpath Although the rpath will be set for the built program, the rpath when it is built may not be completely applicable after `xmake install` is installed, so xmake will automatically modify and adjust the rpath so that the installed program can also find its dependent libraries. @@ -388,7 +388,7 @@ However, the premise is that the user must first configure an independent instal And we can also use this policy to disable the default installation phase rpath setting behavior. -## run.autobuild +## run.autobuild This policy is used to adjust the behaviour of `xmake run`. By default, running `xmake run` does not build the target program automatically, but prompts the user to build it manually if it has not been compiled yet. @@ -405,36 +405,36 @@ If you want this policy to take effect globally, you can turn it on globally. $ xmake g --policies=run.autobuild ``` -## preprocessor.linemarkers +## preprocessor.linemarkers If this policy is turned off, then the cache will generate preprocessor files without linemarkers, which will greatly reduce the size of the preprocessor files. This will greatly reduce the size of the preprocessor file and improve the efficiency of the cache, but the downside is that the source line information will be lost and if you encounter a compilation error, you will not be able to see the exact line of code that went wrong. -## preprocessor.gcc.directives_only +## preprocessor.gcc.directives_only This is also used as a preprocessor policy and is enabled by default. This will improve the efficiency of compile cache preprocessing under gcc, but can lead to cache inconsistencies if the source file contains macros such as `__DATE__`, `__TIME__`, etc. Therefore, you can turn this policy off as needed to ensure consistent results, depending on your project code. -## package.requires_lock +## package.requires_lock Can be used to enable version locking of dependency packages introduced by `add_requires()`. See [Dependent package lock and upgrade](/guide/package-management/using-official-packages#dependent-package-lock-and-upgrade). -## package.precompiled +## package.precompiled Can be used to disable fetching of precompiled dependency packages under windows. -## package.fetch_only +## package.fetch_only If this policy is enabled, then all dependencies will only be fetched from the system and not downloaded and installed from a remote location. -## package.install_only +## package.install_only If this policy is enabled, then all dependencies will only be downloaded and installed remotely, not fetched from the system. -## package.librarydeps.strict_compatibility +## package.librarydeps.strict_compatibility Disabled by default, if enabled then strict compatibility is maintained between the current package and all its library dependencies, any version update of a dependent package will force a recompile install of the current package. @@ -448,7 +448,7 @@ package("foo") For example, if there is an updated version of bar or zoo, then foo will also be recompiled and installed. -## package.strict_compatibility +## package.strict_compatibility is disabled by default, if it is enabled then strict compatibility is maintained between the current package and all other packages that depend on it, and any version update of this package will force a recompile and install of the other parent packages. @@ -468,7 +468,7 @@ package("zoo") For example, if there is an updated version of foo, then both bar and zoo will be forced to be recompiled and installed. -## package.install_always +## package.install_always This is useful for local integration of third-party source packages, as the package will always be reinstalled each time `xmake f -c` is run to reconfigure it. @@ -504,7 +504,7 @@ target("demo") add_packages("foo") ``` -## package.download.http_headers +## package.download.http_headers Setting http headers for package downloads @@ -523,7 +523,7 @@ add_urls("https://github.com/madler/zlib/archive/$(version).tar.gz", { }) ``` -## windows.manifest.uac +## windows.manifest.uac This policy allows us to quickly and easily setup and enable Windows UAC. @@ -551,7 +551,7 @@ end But it's easier and cleaner, and doesn't need to judge the platform, other platforms are automatically ignored. -## windows.manifest.uac.ui +## windows.manifest.uac.ui Sets uiAccess for Windows UAC, defaults to false if it is not set. diff --git a/docs/zh/api/description/builtin-policies.md b/docs/zh/api/description/builtin-policies.md index 2c1a1bcd1..fc6508abe 100644 --- a/docs/zh/api/description/builtin-policies.md +++ b/docs/zh/api/description/builtin-policies.md @@ -1,4 +1,4 @@ -# 内置策略 {#builtin-policies} +# 内置策略 {#builtin-policies} Xmake 有很多的默认行为，比如：自动检测和映射flags、跨target并行构建等，虽然提供了一定的智能化处理，但重口难调，不一定满足所有的用户的使用习惯和需求。 @@ -66,7 +66,7 @@ $ xmake f --policies=package.precompiled:n $ xmake f --policies=package.precompiled:n,package.install_only ``` -## check.auto_ignore_flags +## check.auto_ignore_flags xmake默认会对所有`add_cxflags`, `add_ldflags`接口设置的原始flags进行自动检测，如果检测当前编译器和链接器不支持它们，就会自动忽略。 @@ -98,7 +98,7 @@ target("test") 然后我们就可以随意设置各种原始flags，xmake不会去自动检测和忽略他们了。 -## check.auto_map_flags +## check.auto_map_flags 这是xmake的另外一个对flags的智能分析处理，通常像`add_links`, `add_defines`这种xmake内置的api去设置的配置，是具有跨平台特性的，不同编译器平台会自动处理成对应的原始flags。 @@ -128,7 +128,7 @@ add_cxflags("-O0") set_policy("check.auto_map_flags", false) ``` -## build.across_targets_in_parallel +## build.across_targets_in_parallel 这个策略也是默认开启的，主要用于跨target间执行并行构建，v2.3.3之前的版本，并行构建只能针对单个target内部的所有源文件， 跨target的编译，必须要要等先前的target完全link成功，才能执行下一个target的编译，这在一定程度上会影响编译速度。 @@ -141,7 +141,7 @@ set_policy("check.auto_map_flags", false) set_policy("build.across_targets_in_parallel", false) ``` -## build.fence +## build.fence 由于配置 `set_policy("build.across_targets_in_parallel", false)` 存在局限性，它会限制父 target 和它的所有依赖的子 target 之间的并行度，影响的范围有点大。 @@ -177,7 +177,7 @@ target("test") 而针对 autogen 配置 `set_policy("build.fence", true)` 就可以实现这个目的。 -## build.merge_archive +## build.merge_archive 如果设置了这个策略，那么使用 `add_deps()` 依赖的目标库不再作为链接存在，而是直接把它们合并到父目标库中去。 @@ -210,7 +210,7 @@ target("test") libmul.a 静态库会自动合并 libadd.a 和 libsub.a 两个子依赖的静态库。 -## build.ccache +## build.ccache Xmake 默认是开启内置的编译缓存的，通过设置这个策略，可以显式禁用缓存。 @@ -230,7 +230,7 @@ $ xmake f --ccache=n $ xmake f --policies=build.ccache:n ``` -## build.warning +## build.warning 默认编译通常不会实时回显警告输出，我们通常需要使用 `xmake -w` 开启，或者通过 `xmake g --build_warning=y` 来全局开启它。 @@ -243,7 +243,7 @@ set_warnings("all", "extra") 这个时候，即使我们执行 `xmake` 命令，也能直接回显警告输出。 -## build.optimization.lto +## build.optimization.lto 2.6.9 版本 xmake 改进了对 LTO 链接时优化的支持，对 gcc/clang/msvc 等不同平台下都进行了适配，只需要启用这个策略，就能对特定 target 开启 LTO。 @@ -257,7 +257,7 @@ set_policy("build.optimization.lto", true) $ xmake f --policies=build.optimization.lto ``` -## build.cuda.devlink +## build.cuda.devlink 2.7.7 版本可以通过这个配置，显示开启对特定目标的设备链接。 @@ -273,7 +273,7 @@ target("test") 关于这个的详细背景说明，见：[#1976](https://github.com/xmake-io/xmake/issues/1976) -## build.sanitizer.address +## build.sanitizer.address Address Sanitizer（ASan）是一个快速的内存错误检测工具，由编译器内置支持，通常我们需要在编译和链接的 flags 中同时配置 `-fsanitize-address` 才能正确开启。 @@ -327,23 +327,23 @@ set_policy("build.sanitizer.undefined", true) $ xmake f --policies=build.sanitizer.address,build.sanitizer.undefined ``` -## build.sanitizer.thread +## build.sanitizer.thread 与 [build.sanitizer.address](#build-sanitizer-address) 类似，用于检测线程安全问题。 -## build.sanitizer.memory +## build.sanitizer.memory 与 [build.sanitizer.address](#build-sanitizer-address) 类似，用于检测内存问题。 -## build.sanitizer.leak +## build.sanitizer.leak 与 [build.sanitizer.address](#build-sanitizer-address) 类似，用于检测内存泄漏问题。 -## build.sanitizer.undefined +## build.sanitizer.undefined 与 [build.sanitizer.address](#build-sanitizer-address) 类似，用于检测 undefined 问题。 -## build.always_update_configfiles +## build.always_update_configfiles 这个策略用于对 `add_configfiles` 配置文件的自动生成行为。默认情况下，xmake 仅仅只会在首次 `xmake config` 时候，或者 xmake.lua 配置有改动的是否，才会触发 configfiles 的重新生成。 @@ -353,7 +353,7 @@ $ xmake f --policies=build.sanitizer.address,build.sanitizer.undefined 具体使用背景，可以看下：[#4747](https://github.com/xmake-io/xmake/issues/4747) -## build.intermediate_directory +## build.intermediate_directory 配置启用或禁用构建的内部子目录。 @@ -374,7 +374,7 @@ build/ └─ test ``` -## build.rpath +## build.rpath 配置启用或者禁用构建时的 target rpath 设置。 @@ -382,7 +382,7 @@ build/ 如果你想禁用这个行为，可以显式配置禁用它。 -## install.rpath +## install.rpath 尽管构建后的程序，会被设置 rpath，但是当 `xmake install` 安装后，它构建时候的 rpath 就不一定完全适用了，因此 xmake 会自动修改调整 rpath，使得安装后的程序，同样可以找到它的依赖库。 @@ -390,7 +390,7 @@ build/ 而我们也可以通过这个 policy 去禁用默认的安装阶段 rpath 设置行为。 -## run.autobuild +## run.autobuild 这个策略用于调整 `xmake run` 的行为，默认情况下，执行 `xmake run` 并不会自动构建目标程序，如果程序还没被编译，就是提示用户手动构建一下。 @@ -407,36 +407,36 @@ $ xmake run $ xmake g --policies=run.autobuild ``` -## preprocessor.linemarkers +## preprocessor.linemarkers 通常用户编译缓存中，预处理器的生成策略，默认开启，如果配置关闭这个策略，那么缓存生成的预处理文件内容将不包含 linemarkers 信息，这会极大减少预处理文件大小。 也会提升缓存的处理效率，但是缺点就是会丢失源码行信息，如果遇到编译错误，将无法看到准确的出错代码行。 -## preprocessor.gcc.directives_only +## preprocessor.gcc.directives_only 这也是用于预处理器的策略，默认开启，这会提升 gcc 下编译缓存预处理的效率，但是如果源文件中包含 `__DATE__`, `__TIME__` 等宏，就会导致缓存出现不一致。 因此，可以根据自身工程代码，按需关闭此策略，确保生成的结果一致。 -## package.requires_lock +## package.requires_lock 可用于开启 `add_requires()` 引入的依赖包的版本锁定。 具体看下：[依赖包的锁定和升级](/zh/guide/package-management/using-official-packages#lock-and-upgrade-package)。 -## package.precompiled +## package.precompiled 可用于禁用 windows 下预编译依赖包的获取。 -## package.fetch_only +## package.fetch_only 如果开启这个策略，那么所有的依赖包仅仅只会从系统获取，不会从远程下载安装。 -## package.install_only +## package.install_only 如果开启这个策略，那么所有的依赖包仅仅只会走远程下载安装，不会从系统查找获取。 -## package.librarydeps.strict_compatibility +## package.librarydeps.strict_compatibility 默认禁用，如果启用它，那么当前包和它的所有库依赖包之间会保持严格的兼容性，任何依赖包的版本更新，都会强制触发当前包的重新编译安装。 @@ -450,7 +450,7 @@ package("foo") 例如，如果 bar 或者 zoo 的版本有更新，那么 foo 也会重新编译安装。 -## package.strict_compatibility +## package.strict_compatibility 默认禁用，如果启用它，那么当前包和其他所有依赖它的包之间会保持严格的兼容性，这个包的版本更新，都会强制触发其他父包的重新编译安装。 @@ -470,7 +470,7 @@ package("zoo") 例如，如果 foo 的版本有更新，那么 bar 和 zoo 都会被强制重新编译安装。 -## package.install_always +## package.install_always 每次运行 `xmake f -c` 重新配置的时候，总是会重新安装包，这对于本地第三方源码包集成时候比较有用。 @@ -504,7 +504,7 @@ target("demo") add_packages("foo") ``` -## package.download.http_headers +## package.download.http_headers 设置包下载的 http headers @@ -523,7 +523,7 @@ add_urls("https://github.com/madler/zlib/archive/$(version).tar.gz", { }) ``` -## windows.manifest.uac +## windows.manifest.uac 通过这个策略，我们可以快速方便的设置并启用 Windows UAC。 @@ -551,7 +551,7 @@ end 但是更加方便简洁，并且不需要判断平台，其他平台自动忽略。 -## windows.manifest.uac.ui +## windows.manifest.uac.ui 设置 Windows UAC 的 uiAccess，如果没有设置它，默认是 false。 From 0201f1f4606fc0a339348d6e7ca8592503414510 Mon Sep 17 00:00:00 2001 From: Willaaaaaaa Date: Thu, 2 Oct 2025 14:05:39 +0800 Subject: [PATCH 3/9] improve set_policy api intro --- docs/api/description/builtin-policies.md | 64 +++++++++------------ docs/zh/api/description/builtin-policies.md | 60 ++++++++----------- 2 files changed, 50 insertions(+), 74 deletions(-) diff --git a/docs/api/description/builtin-policies.md b/docs/api/description/builtin-policies.md index 420070922..510f94aee 100644 --- a/docs/api/description/builtin-policies.md +++ b/docs/api/description/builtin-policies.md @@ -1,64 +1,54 @@ # Built-in Policies -Xmake has many default behaviors, such as: automatic detection and mapping of flags, cross-target parallel construction, etc. Although it provides a certain amount of intelligent processing, it is difficult to adjust and may not meet all users' habits and needs. +Xmake incorporates many default behaviors, such as automatically detecting and mapping for flags and enabling parallel builds across different targets. Although it provides intelligent processing to some extent, it is difficult to satisfy all users' habits, needs and preferences. -Therefore, starting with v2.3.4, xmake provides modified settings for the default build strategy, -which is open to users to a certain degree of configurability. It is mainly configured through the [set_policy](/api/description/project-target#set-policy) interface. +Therefore, xmake provides a way to override its default build policies, giving users a higher degree of control. +This is primarily achieved through the [set_policy](/api/description/project-target#set-policy) API, which can be used to modify the default behavior of targets, packages, or the entire project. -The usage is as follows: +## Usage -```lua -set_policy("check.auto_ignore_flags", false) +::: tip NOTE +If the policy name you provide is invalid, xmake will show a warning. +::: + +### 1. Get All the Policies Supported by the Current Version + +We can run the following command to get a list of all the policy configurations, including their descriptions, types, and default values: + +```sh +$ xmake l core.project.policy.policies ``` -You only need to set this configuration in the project root domain to disable the automatic detection and ignore mechanism of flags. -In addition, set_policy can also take effect locally for a specific target. +### 2. Configuring Policies in `xmake.lua` -```lua +::: code-group +```lua [globally] +-- Set this in the root domain to globally disable the automatic detection and ignore mechanism of flags +set_policy("check.auto_ignore_flags", false) +``` + +```lua [locally] target ("test") + -- This applies only to the `test` target.     set_policy ("check.auto_ignore_flags", false) ``` - -::: tip NOTE -In addition, if the set policy name is invalid, xmake will also have a warning prompt. ::: -If you want to get a list and description of all the policy configurations supported by the current xmake, you can execute the following command: +### 3. Configuring Policies via the Command Line -```sh -$ xmake l core.project.policy.policies -{ - "check.auto_map_flags" = { - type = "boolean", - description = "Enable map gcc flags to the current compiler and linker automatically.", - default = true - }, - "build.across_targets_in_parallel" = { - type = "boolean", - description = "Enable compile the source files for each target in parallel.", - default = true - }, - "check.auto_ignore_flags" = { - type = "boolean", - description = "Enable check and ignore unsupported flags automatically.", - default = true - } -} -``` - -We can also set up internal policy changes via the command line: +When building projects, we may need to temporarily enable or disable certain policies. In such cases, it's more suitable to use the command line. And when a policy is set from the command line, it is enabled by default: ```sh $ xmake f --policies=package.fetch_only ``` -The policy name is set by default, which is the enabled state, but we can of course specify to set other values to disable it. +Also, we can specify other values to disable the policy or achieve other effects: ```sh $ xmake f --policies=package.precompiled:n ``` -Or configure multiple policy values at the same time, separated by commas. +Please note that when specifying multiple policies, you should use commas to separate them: ```sh $ xmake f --policies=package.precompiled:n,package.install_only diff --git a/docs/zh/api/description/builtin-policies.md b/docs/zh/api/description/builtin-policies.md index fc6508abe..20d9681b4 100644 --- a/docs/zh/api/description/builtin-policies.md +++ b/docs/zh/api/description/builtin-policies.md @@ -1,66 +1,52 @@ # 内置策略 {#builtin-policies} -Xmake 有很多的默认行为，比如：自动检测和映射flags、跨target并行构建等，虽然提供了一定的智能化处理，但重口难调，不一定满足所有的用户的使用习惯和需求。 +Xmake 有很多的默认行为，比如：自动检测和映射编译、链接标志、跨工程目标并行构建等，虽然提供了一定的智能化处理，但重口难调，不一定能满足所有的用户的使用习惯和需求。 +因此， xmake 提供了**针对默认策略的修改设置**，在一定程度上给予了用户**修改策略**的权限。这个功能主要通过 [set_policy](/zh/api/description/project-target#set-policy) 接口来实现，我们通常可以使用这个接口来配置修改 target, package 以及工程整体的一些行为策略。 -因此，从v2.3.4开始，xmake 提供默认构建策略的修改设置，开放给用户一定程度上的可配置性。 +## 使用方式 -它主要通过 [set_policy](/zh/api/description/project-target#set-policy) 接口来配置。 +::: tip 注意 +如果设置的策略名是无效的， xmake 会有警告提示。 +::: -我们通常可以用它来配置修改 target，package 以及工程整体的一些行为策略。 +### 1. 获取当前版本所支持的所有策略 -使用方式如下： +执行下面的命令可以返回所有的配置及其描述、值类型和默认值： -```lua -set_policy("check.auto_ignore_flags", false) +```sh +$ xmake l core.project.policy.policies ``` -只需要在项目根域设置这个配置，就可以禁用flags的自动检测和忽略机制，另外`set_policy`也可以针对某个特定的target局部生效。 +### 2. 在 `xmake.lua` 中直接调用接口进行策略的配置 -```lua +::: code-group +```lua [全局设置] +-- 在项目根域设置这个配置，就可以全局禁用 flags 的自动检测和忽略机制 +set_policy("check.auto_ignore_flags", false) +``` + +```lua [局部设置] target("test") + -- 针对特定的 target `test` 生效 set_policy("check.auto_ignore_flags", false) ``` - -::: tip 注意 -另外，如果设置的策略名是无效的，xmake也会有警告提示。 ::: -如果要获取当前xmake支持的所有策略配置列表和描述，可以执行下面的命令： +### 3. 通过命令行进行策略的配置 -```sh -$ xmake l core.project.policy.policies -{ - "check.auto_map_flags" = { - type = "boolean", - description = "Enable map gcc flags to the current compiler and linker automatically.", - default = true - }, - "build.across_targets_in_parallel" = { - type = "boolean", - description = "Enable compile the source files for each target in parallel.", - default = true - }, - "check.auto_ignore_flags" = { - type = "boolean", - description = "Enable check and ignore unsupported flags automatically.", - default = true - } -} -``` - -我们也可以通过命令行的方式去设置修改内部的策略: +当我们构建工程时，可能需要暂时性地启用或是禁用一些策略。在这种情况下，使用命令行就更加贴合需求了。使用命令行设置策略时，默认该策略为启用状态： ```sh $ xmake f --policies=package.fetch_only ``` -默认设置策略名，就是启用状态，当然我们也可以指定设置其他值，禁用它。 +当然，我们也可以指定其他值以达到禁用等效果： ```sh $ xmake f --policies=package.precompiled:n ``` -或者同时配置多个策略值，用逗号分割。 +值得注意的是，同时配置多个策略需要用逗号进行分割： ```sh $ xmake f --policies=package.precompiled:n,package.install_only From e9f74968ab0b708121ae770fdd6b9f79cf69f629 Mon Sep 17 00:00:00 2001 From: Willaaaaaaa Date: Thu, 2 Oct 2025 15:29:17 +0800 Subject: [PATCH 4/9] check.auto_ignore_flags --- docs/api/description/builtin-policies.md | 27 ++++++++++++++------- docs/zh/api/description/builtin-policies.md | 25 ++++++++++++------- 2 files changed, 34 insertions(+), 18 deletions(-) diff --git a/docs/api/description/builtin-policies.md b/docs/api/description/builtin-policies.md index 510f94aee..30f964542 100644 --- a/docs/api/description/builtin-policies.md +++ b/docs/api/description/builtin-policies.md @@ -56,27 +56,38 @@ $ xmake f --policies=package.precompiled:n,package.install_only ## check.auto_ignore_flags -By default, xmake will automatically detect all the original flags set by the `add_cxflags` and` add_ldflags` interfaces. If the current compiler and linker do not support them, they will be automatically ignored. +::: danger Potential Risk +Disabling the default policy for auto-detecting and ignoring flags without careful consideration may cause unexpected compiling errors for others, as compilers' support for specific flags varies. +::: + +### Default policy + +By default, xmake will automatically detect all the compilation and linking flags set by the `add_cxflags` and `add_ldflags` interfaces. If the current compiler or linker does not support a certain flag, xmake will automatically ignore it and show a warning. -This is usually very useful. Like some optional compilation flags, it can be compiled normally even if it is not supported, but it is forced to set up. When compiling, other users may have a certain degree of difference due to the different support of the compiler. The compilation failed. +This can be extremely useful especially when dealing with optional compilation flags. It can still be compiled normally even if the flag in question is not supported. -However, because automatic detection does not guarantee 100% reliability, sometimes there will be a certain degree of misjudgment, so some users do not like this setting (especially for cross-compilation tool chains, which are more likely to fail). +### Use Cases -At present, if the detection fails in v2.3.4, there will be a warning prompt to prevent users from lying inexplicably, for example: +However, in some circumstances, this default policy can result in false positives, especially during cross-compilation. What's more, the resulting warnings can be annoying and create a lot of noise in the build output. + +For example: ``` 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. ``` -According to the prompt, we can analyze and judge ourselves whether it is necessary to set this flags. One way is to pass: +Based on this warning, we can determine if we need to add this flag. Depending on the number of flags involved, you can choose one of the following two solutions: +#### 1. Add the `force` parameter ```lua add_ldflags("-static", {force = true}) ``` -To display the mandatory settings, skip automatic detection, which is an effective and fast way to deal with occasional flags failure, but for cross-compilation, if a bunch of flags settings cannot be detected, each set force Too tedious. +The `{force = true}` parameter can explicitly force the flag(s) to be added, skipping the automatic check. This is an effective and fast way to deal with a few flags. However, when dealing with complex projects like cross-compilation, where a large number of flags might fail the detection, setting this parameter for each one becomes tedious. + +#### 2. Set the Policy -At this time, we can use `set_policy` to directly disable the default automatic detection behavior for a target or the entire project: +To avoid the limitation of the first approach, we can use `set_policy` to directly disable the default automatic detection behavior for a specified target or the entire project. Meanwhile, this will suppress all related warnings. ```lua set_policy("check.auto_ignore_flags", false) @@ -84,8 +95,6 @@ target("test") add_ldflags("-static") ``` -Then we can set various original flags at will, xmake will not automatically detect and ignore them. - ## check.auto_map_flags This is another intelligent analysis and processing of flags by xmake. Usually, the configuration set by xmake built-in APIs like `add_links`,` add_defines` is cross-platform, and different compiler platforms will automatically process them into corresponding Original flags. diff --git a/docs/zh/api/description/builtin-policies.md b/docs/zh/api/description/builtin-policies.md index 20d9681b4..815691526 100644 --- a/docs/zh/api/description/builtin-policies.md +++ b/docs/zh/api/description/builtin-policies.md @@ -54,27 +54,36 @@ $ xmake f --policies=package.precompiled:n,package.install_only ## check.auto_ignore_flags -xmake默认会对所有`add_cxflags`, `add_ldflags`接口设置的原始flags进行自动检测，如果检测当前编译器和链接器不支持它们，就会自动忽略。 +::: danger 潜在风险 +强行禁用自动检测和忽略标志的默认策略可能会导致其他用户在编译时由于编译器的支持力度不同，从而出现一定程度的编译失败。 +::: + +### 默认策略 +xmake 默认会对所有通过 `add_cxflags`, `add_ldflags` 等接口添加的原始编译和链接标志进行自动检测。如果检测出当前编译器和链接器不支持某些标志，就会自动忽略并弹出警告信息。 -这通常是很有用的，像一些可选的编译flags，即使不支持也能正常编译，但是强行设置上去，其他用户在编译的时候，有可能会因为编译器的支持力度不同，出现一定程度的编译失败。 +这种自动忽略的策略通常是很有用的，尤其是在处理一些可选的编译标志时，即使编译器不支持也能正常编译。 -但，由于自动检测并不保证100%可靠，有时候会有一定程度的误判，所以某些用户并不喜欢这个设定（尤其是针对交叉编译工具链，更容易出现失败）。 +### 潜在需求 -目前，v2.3.4版本如果检测失败，会有警告提示避免用户莫名躺坑，例如： +由于自动检测在某些情况下会有一定程度的误判（尤其是针对交叉编译工具链，更容易出现检测失败，导致编译失败），而且自动忽略的同时会产生警告提示，所以某些用户并不喜欢这个设定。 + +例如，如果标志检测失败，就会有警告提示用户： ```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. ``` -根据提示，我们可以自己分析判断，是否需要强制设置这个flags，一种就是通过： +根据警告提示，我们可以自己分析判断是否需要强制添加这个标志 。我们可以根据 flag 的数量来选择以下两种方案： +#### 1. 添加 force 参数 ```lua add_ldflags("-static", {force = true}) ``` -来显示的强制设置上它，跳过自动检测，这对于偶尔的flags失败，是很有效快捷的处理方式，但是对于交叉编译时候，一堆的flags设置检测不过的情况下，每个都设置force太过于繁琐。 +`{force = true}` 参数可以显式地强制添加标志并跳过自动检测，这对于**个别**的检测失败是**有效快捷**的处理方式，但是对于交叉编译，**大量**的标志检测不通过的情况下，每个都设置 force 参数过于**繁琐**。 -这个时候，我们就可以通过`set_policy`来对某个target或者整个project直接禁用默认的自动检测行为： +#### 2. 配置策略 +针对方案一中的局限性，我们可以使用 `set_policy` 直接禁用对某个目标或者整个项目默认的标志自动检测和忽略行为，从而达到没有额外警告信息出现的效果： ```lua set_policy("check.auto_ignore_flags", false) @@ -82,8 +91,6 @@ target("test") add_ldflags("-static") ``` -然后我们就可以随意设置各种原始flags，xmake不会去自动检测和忽略他们了。 - ## check.auto_map_flags 这是xmake的另外一个对flags的智能分析处理，通常像`add_links`, `add_defines`这种xmake内置的api去设置的配置，是具有跨平台特性的，不同编译器平台会自动处理成对应的原始flags。 From d171c184f7231fa5b1a2366a41d677d151ef103d Mon Sep 17 00:00:00 2001 From: Willaaaaaaa Date: Thu, 2 Oct 2025 15:33:54 +0800 Subject: [PATCH 5/9] add usage anchors --- docs/zh/api/description/builtin-policies.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/zh/api/description/builtin-policies.md b/docs/zh/api/description/builtin-policies.md index 815691526..3a16abeb4 100644 --- a/docs/zh/api/description/builtin-policies.md +++ b/docs/zh/api/description/builtin-policies.md @@ -3,13 +3,13 @@ Xmake 有很多的默认行为，比如：自动检测和映射编译、链接标志、跨工程目标并行构建等，虽然提供了一定的智能化处理，但重口难调，不一定能满足所有的用户的使用习惯和需求。 因此， xmake 提供了**针对默认策略的修改设置**，在一定程度上给予了用户**修改策略**的权限。这个功能主要通过 [set_policy](/zh/api/description/project-target#set-policy) 接口来实现，我们通常可以使用这个接口来配置修改 target, package 以及工程整体的一些行为策略。 -## 使用方式 +## 使用方式 {#usage} ::: tip 注意 如果设置的策略名是无效的， xmake 会有警告提示。 ::: -### 1. 获取当前版本所支持的所有策略 +### 1. 获取当前版本所支持的所有策略 {#_1-get-all-the-policies-supported-by-the-current-version} 执行下面的命令可以返回所有的配置及其描述、值类型和默认值： @@ -17,7 +17,7 @@ Xmake 有很多的默认行为，比如：自动检测和映射编译、链接 $ xmake l core.project.policy.policies ``` -### 2. 在 `xmake.lua` 中直接调用接口进行策略的配置 +### 2. 在 `xmake.lua` 中直接调用接口进行策略的配置 {#_2-configuring-policies-in-xmake-lua} ::: code-group ```lua [全局设置] @@ -32,7 +32,7 @@ target("test") ``` ::: -### 3. 通过命令行进行策略的配置 +### 3. 通过命令行进行策略的配置 {#_3-configuring-policies-via-the-command-line} 当我们构建工程时，可能需要暂时性地启用或是禁用一些策略。在这种情况下，使用命令行就更加贴合需求了。使用命令行设置策略时，默认该策略为启用状态： From aaab32ece058eae9ad7de6fc8680a795cc96bb73 Mon Sep 17 00:00:00 2001 From: Willaaaaaaa Date: Thu, 2 Oct 2025 15:37:19 +0800 Subject: [PATCH 6/9] add check.auto_ignore_flags anchors --- docs/zh/api/description/builtin-policies.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/zh/api/description/builtin-policies.md b/docs/zh/api/description/builtin-policies.md index 3a16abeb4..16fb25b57 100644 --- a/docs/zh/api/description/builtin-policies.md +++ b/docs/zh/api/description/builtin-policies.md @@ -58,12 +58,12 @@ $ xmake f --policies=package.precompiled:n,package.install_only 强行禁用自动检测和忽略标志的默认策略可能会导致其他用户在编译时由于编译器的支持力度不同，从而出现一定程度的编译失败。 ::: -### 默认策略 +### 默认策略 {#default-policy} xmake 默认会对所有通过 `add_cxflags`, `add_ldflags` 等接口添加的原始编译和链接标志进行自动检测。如果检测出当前编译器和链接器不支持某些标志，就会自动忽略并弹出警告信息。 这种自动忽略的策略通常是很有用的，尤其是在处理一些可选的编译标志时，即使编译器不支持也能正常编译。 -### 潜在需求 +### 潜在需求 {#use-cases} 由于自动检测在某些情况下会有一定程度的误判（尤其是针对交叉编译工具链，更容易出现检测失败，导致编译失败），而且自动忽略的同时会产生警告提示，所以某些用户并不喜欢这个设定。 @@ -75,14 +75,14 @@ warning: add_ldflags("-static") is ignored, please pass `{force = true}` or call 根据警告提示，我们可以自己分析判断是否需要强制添加这个标志 。我们可以根据 flag 的数量来选择以下两种方案： -#### 1. 添加 force 参数 +#### 1. 添加 force 参数 {#_1-add-the-force-parameter} ```lua add_ldflags("-static", {force = true}) ``` `{force = true}` 参数可以显式地强制添加标志并跳过自动检测，这对于**个别**的检测失败是**有效快捷**的处理方式，但是对于交叉编译，**大量**的标志检测不通过的情况下，每个都设置 force 参数过于**繁琐**。 -#### 2. 配置策略 +#### 2. 配置策略 {#_2-set-the-policy} 针对方案一中的局限性，我们可以使用 `set_policy` 直接禁用对某个目标或者整个项目默认的标志自动检测和忽略行为，从而达到没有额外警告信息出现的效果： ```lua From 36d94d20a4ceab8a8de6c475f0929942a3914935 Mon Sep 17 00:00:00 2001 From: Willaaaaaaa Date: Thu, 2 Oct 2025 18:26:50 +0800 Subject: [PATCH 7/9] check.auto_map_flags --- docs/api/description/builtin-policies.md | 26 +++++++++++---------- docs/zh/api/description/builtin-policies.md | 23 +++++++++--------- 2 files changed, 25 insertions(+), 24 deletions(-) diff --git a/docs/api/description/builtin-policies.md b/docs/api/description/builtin-policies.md index 30f964542..db342fe6c 100644 --- a/docs/api/description/builtin-policies.md +++ b/docs/api/description/builtin-policies.md @@ -97,31 +97,33 @@ target("test") ## check.auto_map_flags -This is another intelligent analysis and processing of flags by xmake. Usually, the configuration set by xmake built-in APIs like `add_links`,` add_defines` is cross-platform, and different compiler platforms will automatically process them into corresponding Original flags. +::: tip NOTE +The current implementation of auto-mapping is not yet complete and doesn't cover 100% of all gcc flags, so there are still some flags that may not be mapped. +::: -However, in some cases, users still need to set the original compilation link flags by add_cxflags, add_ldflags, these flags are not good cross compiler +### Default Policy -Take `-O0` compiler optimization flags. Although` set_optimize` is used to implement cross-compiler configuration, what if the user directly sets `add_cxflags ("-O0 ")`? It can be processed normally under gcc / clang, but it is not supported under msvc +This policy controls another intelligent feature for flag-handling. Usually, the configurations set by xmake built-in APIs like `add_links`, `add_defines` are cross-platform, which means xmake will automatically translate them into appropriate raw flags for different compilers. -Maybe we can use `if is_plat () then` to process by platform, but it is very cumbersome, so xmake has built-in automatic mapping function of flags. +However, in some cases, users still need to set the raw compilation or linking flags by APIs like `add_cxflags` and `add_ldflags`. These APIs takes raw flags as parameters, and therefore are probably compiler-specified and not portable. -Based on the popularity of gcc flags, xmake uses gcc's flags naming convention to automatically map it according to different compilations, for example: +Take `-O0`, a compiler optimization flag, for example. Although `set_optimize` can be used to implement cross-platform configuration, some users still prefer to use `add_cxflags("-O0")`. `-O0` can be recognized by gcc and clang, but not by msvc. + +To solve this, xmake has a built-in auto-mapping function for flags. Based on the widely-used gcc flags, xmake uses gcc's flags naming convention to automatically map them. For example: ```lua add_cxflags("-O0") ``` -This line setting is still `-O0` under gcc/clang, but if it is currently msvc compiler, it will be automatically mapped to msvc corresponding to` -Od` compilation option to disable optimization. +Xmake will pass `-O0` to gcc and clang as it is, but for msvc, it will be automatically mapped to msvc-specified `-Od` flag to disable optimization. -Throughout the process, users are completely unaware, and can execute xmake directly to compile across compilers. +During this transparent process, simply run xmake, and it will handle the necessary flag translations automatically. -::: tip NOTE -Of course, the current implementation of automatic mapping is not very mature. There is no 100% coverage of all gcc flags, so there are still many flags that are not mapped. -::: +### Usage -Some users do not like this automatic mapping behavior, so we can completely disable this default behavior through the following settings: +Some users do not like this auto-mapping behavior, so we can completely disable this default behavior through the following settings: -```sh +```lua set_policy("check.auto_map_flags", false) ``` diff --git a/docs/zh/api/description/builtin-policies.md b/docs/zh/api/description/builtin-policies.md index 16fb25b57..becea14bf 100644 --- a/docs/zh/api/description/builtin-policies.md +++ b/docs/zh/api/description/builtin-policies.md @@ -93,31 +93,30 @@ target("test") ## check.auto_map_flags -这是xmake的另外一个对flags的智能分析处理，通常像`add_links`, `add_defines`这种xmake内置的api去设置的配置，是具有跨平台特性的，不同编译器平台会自动处理成对应的原始flags。 +::: tip 注意 +目前的自动映射实现还不是很完整，没有 100% 覆盖所有 gcc 的标志，所以还是有部分标志是无法去映射的。 +::: -但是，有些情况，用户还是需要自己通过`add_cxflags`, `add_ldflags`设置原始的编译链接flags，这些flags并不能很好的跨编译器 +### 默认策略 {#default-policy-1} +这是 xmake 的另外一个对标志的智能分析处理。通常情况下，通过 `add_links`, `add_defines` 这种 xmake 内置的 API 去设置的配置是具有跨平台特性的。针对不同的编译器平台， xmake 会自动处理成对应的原始标志。 -就拿`-O0`的编译优化flags来说，虽然有`set_optimize`来实现跨编译器配置，但如果用户直接设置`add_cxflags("-O0")`呢？gcc/clang下可以正常处理，但是msvc下就不支持了 +但是有些情况下，用户还是会通过 `add_cxflags`, `add_ldflags` 等接口设置原始的编译链接标志。这些 API 接收原始标志为参数，但部分标志本身并不是被所有的编译器支持的。 -也许我们能通过`if is_plat() then`来分平台处理，但很繁琐，因此xmake内置了flags的自动映射功能。 +例如 `-O0` 这个编译优化标志。虽然有 `set_optimize` 来实现跨编译器配置，但如果用户可能会直接使用 `add_cxflags("-O0")` 。这种情况下， gcc/clang 下可以正常处理，但是 msvc 下就不支持它了。 -基于gcc flags的普及性，xmake采用gcc的flags命名规范，对其根据不同的编译实现自动映射，例如： +因此， xmake 内置了标志的自动映射功能：基于 gcc 编译标志的普及性， xmake 采用 gcc 的标志命名规范，针对不同的编译器对其进行自动映射，例如： ```lua add_cxflags("-O0") ``` -这一行设置，在gcc/clang下还是`-O0`，但如果当前是msvc编译器，那边会自动映射为msvc对应`-Od`编译选项来禁用优化。 +这一行设置，在 gcc/clang 编译器下还是 `-O0` ，但针对 msvc 编译器 xmake 就会自动将其映射为 msvc 中对应的 `-Od` 编译标志来禁用优化。整个过程，用户是完全无感知的，直接执行 xmake 就可以跨编译器完成标志的映射和编译。 -整个过程，用户是完全无感知的，直接执行xmake就可以跨编译器完成编译。 - -::: tip 注意 -当然，目前的自动映射实现还不是很成熟，没有100%覆盖所有gcc的flags，所以还是有不少flags是没去映射的。 -::: +### 用法 {#usage-1} 也有部分用户并不喜欢这种自动映射行为，那么我们可以通过下面的设置完全禁用这个默认的行为： -```sh +```lua set_policy("check.auto_map_flags", false) ``` From 9577e44643e347ee52c669df64cbad4841e4c8d1 Mon Sep 17 00:00:00 2001 From: Willaaaaaaa Date: Thu, 2 Oct 2025 22:27:12 +0800 Subject: [PATCH 8/9] check.target_package_licenses --- docs/api/description/builtin-policies.md | 12 ++++++++++++ docs/zh/api/description/builtin-policies.md | 12 ++++++++++++ 2 files changed, 24 insertions(+) diff --git a/docs/api/description/builtin-policies.md b/docs/api/description/builtin-policies.md index db342fe6c..a8dd40c77 100644 --- a/docs/api/description/builtin-policies.md +++ b/docs/api/description/builtin-policies.md @@ -127,6 +127,18 @@ Some users do not like this auto-mapping behavior, so we can completely disable set_policy("check.auto_map_flags", false) ``` +## check.target_package_licenses + +### Default Policy +Using open-source software as third-party dependences can avoid "reinventing the wheel" in software development. We should **respect and value** other developers' work by following their licenses. In order to help developers find potential risks, xmake performs a **license compatibility check** on projects and its imported dependences by default. + +### Usage +This policy is intended to help developers identify potential license compliance issues. But in some learning or experimental scenarios, you may want to temporarily silence the conflict warnings generated by this check. To do so, you can confiure your project like this: + +```lua +set_policy("check.target_package_licenses", false) +``` + ## build.across_targets_in_parallel This strategy is also enabled by default and is mainly used to perform parallel builds between targets. In versions prior to v2.3.3, parallel builds can only target all source files within a single target. diff --git a/docs/zh/api/description/builtin-policies.md b/docs/zh/api/description/builtin-policies.md index becea14bf..64633afb6 100644 --- a/docs/zh/api/description/builtin-policies.md +++ b/docs/zh/api/description/builtin-policies.md @@ -120,6 +120,18 @@ add_cxflags("-O0") 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内部的所有源文件， From a6b0bf4f6cd35a5da2ec2e60da6d1d18bdadc544 Mon Sep 17 00:00:00 2001 From: Willaaaaaaa Date: Thu, 2 Oct 2025 22:46:50 +0800 Subject: [PATCH 9/9] apply gemini advice --- docs/api/description/builtin-policies.md | 6 +++--- docs/zh/api/description/builtin-policies.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/api/description/builtin-policies.md b/docs/api/description/builtin-policies.md index a8dd40c77..cf1c7085e 100644 --- a/docs/api/description/builtin-policies.md +++ b/docs/api/description/builtin-policies.md @@ -30,7 +30,7 @@ set_policy("check.auto_ignore_flags", false) ```lua [locally] target ("test") -- This applies only to the `test` target. -    set_policy ("check.auto_ignore_flags", false) +    set_policy("check.auto_ignore_flags", false) ``` ::: @@ -130,10 +130,10 @@ set_policy("check.auto_map_flags", false) ## check.target_package_licenses ### Default Policy -Using open-source software as third-party dependences can avoid "reinventing the wheel" in software development. We should **respect and value** other developers' work by following their licenses. In order to help developers find potential risks, xmake performs a **license compatibility check** on projects and its imported dependences by default. +Using open-source software as third-party dependencies can avoid "reinventing the wheel" in software development. We should **respect and value** other developers' work by following their licenses. In order to help developers find potential risks, xmake performs a **license compatibility check** on projects and its imported dependencies by default. ### Usage -This policy is intended to help developers identify potential license compliance issues. But in some learning or experimental scenarios, you may want to temporarily silence the conflict warnings generated by this check. To do so, you can confiure your project like this: +This policy is intended to help developers identify potential license compliance issues. But in some learning or experimental scenarios, you may want to temporarily silence the conflict warnings generated by this check. To do so, you can configure your project like this: ```lua set_policy("check.target_package_licenses", false) diff --git a/docs/zh/api/description/builtin-policies.md b/docs/zh/api/description/builtin-policies.md index 64633afb6..be4018a34 100644 --- a/docs/zh/api/description/builtin-policies.md +++ b/docs/zh/api/description/builtin-policies.md @@ -73,7 +73,7 @@ xmake 默认会对所有通过 `add_cxflags`, `add_ldflags` 等接口添加的 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 的数量来选择以下两种方案： +根据警告提示，我们可以自己分析判断是否需要强制添加这个标志。我们可以根据 flag 的数量来选择以下两种方案： #### 1. 添加 force 参数 {#_1-add-the-force-parameter} ```lua @@ -110,7 +110,7 @@ target("test") add_cxflags("-O0") ``` -这一行设置，在 gcc/clang 编译器下还是 `-O0` ，但针对 msvc 编译器 xmake 就会自动将其映射为 msvc 中对应的 `-Od` 编译标志来禁用优化。整个过程，用户是完全无感知的，直接执行 xmake 就可以跨编译器完成标志的映射和编译。 +这一行设置，在 gcc/clang 编译器下还是 `-O0` ，但针对 msvc 编译器， xmake 就会自动将其映射为 msvc 中对应的 `-Od` 编译标志来禁用优化。整个过程，用户是完全无感知的，直接执行 xmake 就可以跨编译器完成标志的映射和编译。 ### 用法 {#usage-1}