全部配置 / APP-FREECOMPILERARGS

freeCompilerArgs

freeCompilerArgs · APP-FREECOMPILERARGS · Gradle DSL

重要：极高 · 决定产物/平台 默认：未设置（不传则空） 场合：开发必用 来源：上游原样

默认值：未设置。默认为空列表，由工程追加。使用场合：开发必用。开发必用：日常开发/调试几乎都会用到。

它是做什么的

用途。Gradle 向编译器透传额外参数的入口（如 -g、-opt、-Xbinary=…）。应按 Debug/Release 分流，避免在公共配置写入仅排障用参数。

影响。错误参数导致失败或意外行为。

适用场景。所有需透传编译器参数的场景；按 Debug/Release 分流，避免公共污染。

取值说明

列表

  • A list of additional compiler arguments Default value: emptyList<String>()

可写。<元素列表> （Gradle 列表属性：org.gradle.api.provider.ListProperty<kotlin.String>）

定义依据：dsl/KotlinCommonCompilerToolOptions.kt 在仓库中打开

怎么用

  1. 配置入口：build.gradle.kts → ohosArm64.binaries.all { freeCompilerArgs += "<旗标>" }
  2. 示例：
// 文件：build.gradle.kts（应用的 Kotlin 模块，例如 composeApp）
kotlin {
  ohosArm64 {  // 按实际 native target 调整
    binaries.all {
      freeCompilerArgs += "-Xbinary=sanitizer=address"  // 示例：把 Native 编译器旗标透传进去
    }
  }
}
  1. 生效：Sync 后执行该目标的 compile/link。
  2. 验证：编译日志中出现你加入的具体参数（Native 任务搜 Arguments =）。
  3. 回滚：从 binaries.all 的 freeCompilerArgs 中删除该项后 Clean 并重编。
  4. 注意：公共配置污染Release

默认行为 未设置

不写这个配置时，编译器会怎么处理？

此选项默认未设置（空列表 / 空映射 / null）。不设置时由其他逻辑决定行为或直接跳过。

默认为空列表，由工程追加。

相关文档

以下摘抄原文中与本配置最相关的段落，便于速读；完整上下文请点原文。 上游与 CPF 分栏对照。

溯源与对照

状态
稳定（正式选项）
版本基线
2.2.21-1.0.0
定义位置类型
Gradle 插件 API（compilerOptions）
源码路径
libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinCommonCompilerToolOptions.kt 在仓库中打开
对应编译器参数
KN-OPT KN-G KN-BINARY-SANITIZER