CPF-KMP-CMP · 2.2.21-1.0.0

能力地图

本文档面向 App 开发人员。配置按开发时要办的事归组：写代码（语言、警告） → 搭工程（KMP、模块） → 出包和链接（产物类型、拆 so、互操作） → 调运行时（内存、调试、包体） → 配缓存和插件（增量、插件、工具链） → 查编译器（内部排障）。

写代码

语言能力与兼容38 决定语言版本、实验语法、opt-in，以及类型检查松紧。

语言 / API 版本对齐

apiVersion 不应高于 languageVersion；工程里优先用 compilerOptions。

  • APP-LANGUAGEVERSION languageVersion Gradle 稳定（正式选项） 跨侧 K/N侧 KN-LANGUAGE-VERSION — 按指定 Kotlin 语言版本提供源码兼容（语法与语言语义）
  • APP-APIVERSION apiVersion Gradle 稳定（正式选项） 跨侧 K/N侧 KN-API-VERSION — 限制只能使用指定版本及更早的 Kotlin 标准库 API

本任务下的选项

场景可配（35）
  • APP-OPTIN optIn Gradle 稳定（正式选项） 跨侧 K/N侧 KN-OPT-IN — 启用带 Opt-in 标记的 API（传入要求注解的全限定名列表）
  • APP-PROGRESSIVEMODE progressiveMode Gradle 稳定（正式选项） 跨侧 K/N侧 KN-PROGRESSIVE — 启用渐进模式：不稳定代码相关的废弃与修复立即生效，不等待迁移周期
  • KN-BINARY-GENERICSAFECASTS Xbinary=genericSafeCasts Native -Xbinary 实验（-X，兼容性不保证） — 对泛型相关转型使用更安全的检查
  • KN-BINARY-GLOBALDATALAZYINIT Xbinary=globalDataLazyInit Native -Xbinary 实验（-X，兼容性不保证） — 全局数据延迟初始化
  • KN-XALLOW-CONDITION-IMPLIES-RETURNS-CONTRACTS Xallow-condition-implies-returns-contracts Native 参数 实验（-X，兼容性不保证） — 允许有限条件返回后置条件的 contract
  • KN-XALLOW-CONTRACTS-ON-MORE-FUNCTIONS Xallow-contracts-on-more-functions Native 参数 实验（-X，兼容性不保证） — 允许在部分运算符/访问器上使用 contract
  • KN-XALLOW-HOLDSIN-CONTRACT Xallow-holdsin-contract Native 参数 实验（-X，兼容性不保证） — 允许描述 lambda 内条件成立的 contract
  • KN-XALLOW-KOTLIN-PACKAGE Xallow-kotlin-package Native 参数 实验（-X，兼容性不保证） — 允许编译 kotlin 包内代码，并可放宽对 kotlin.stdlib 的要求
  • KN-XALLOW-REIFIED-TYPE-IN-CATCH Xallow-reified-type-in-catch Native 参数 实验（-X，兼容性不保证） — 允许 catch 参数使用具体化类型
  • KN-XANNOTATION-DEFAULT-TARGET Xannotation-default-target Native 参数 实验（-X，兼容性不保证） — 更改构造属性的默认注解目标
  • KN-XANNOTATION-TARGET-ALL Xannotation-target-all Native 参数 实验（-X，兼容性不保证） — 启用 @all: 注解使用点实验支持
  • KN-XCONSISTENT-DATA-CLASS-COPY-VISIBILITY Xconsistent-data-class-copy-visibility Native 参数 实验（-X，兼容性不保证） — 效果等同于为 data class 应用 @ConsistentCopyVisibility
  • KN-XCONTEXT-PARAMETERS Xcontext-parameters Native 参数 实验（-X，兼容性不保证） — 启用实验性 context parameters
  • KN-XCONTEXT-RECEIVERS Xcontext-receivers Native 参数 实验（-X，兼容性不保证） — 启用实验性 context receivers
  • KN-XCONTEXT-SENSITIVE-RESOLUTION Xcontext-sensitive-resolution Native 参数 实验（-X，兼容性不保证） — 启用实验性上下文敏感解析
  • KN-XDATA-FLOW-BASED-EXHAUSTIVENESS Xdata-flow-based-exhaustiveness Native 参数 实验（-X，兼容性不保证） — 启用基于数据流的 when 穷尽性改进
  • KN-XDIRECT-JAVA-ACTUALIZATION Xdirect-java-actualization Native 参数 实验（-X，兼容性不保证） — 启用实验性 Java actualization
  • KN-XEXPLICIT-API Xexplicit-api Native 参数 实验（-X，兼容性不保证） — 强制the compiler to report errors on all public AP
  • KN-XINLINE-CLASSES Xinline-classes Native 参数 实验（-X，兼容性不保证） — 启用实验性inline classes
  • KN-XIR-PROPERTY-LAZY-INITIALIZATION Xir-property-lazy-initialization Native 参数 实验（-X，兼容性不保证） — 按文件延迟初始化顶层属性
  • KN-XMULTI-DOLLAR-INTERPOLATION Xmulti-dollar-interpolation Native 参数 实验（-X，兼容性不保证） — 启用实验性多 $ 字符串插值
  • KN-XNESTED-TYPE-ALIASES Xnested-type-aliases Native 参数 实验（-X，兼容性不保证） — 启用嵌套类型别名实验支持
  • KN-XNEW-INFERENCE Xnew-inference Native 参数 实验（-X，兼容性不保证） — 启用the new experimental generic type inference al
  • KN-XNON-LOCAL-BREAK-CONTINUE Xnon-local-break-continue Native 参数 实验（-X，兼容性不保证） — 启用实验性非局部 break/continue
  • KN-XRETURN-VALUE-CHECKER Xreturn-value-checker Native 参数 实验（-X，兼容性不保证） — 设置未使用返回值检查模式
  • KN-XSKIP-METADATA-VERSION-CHECK Xskip-metadata-version-check Native 参数 实验（-X，兼容性不保证） — 允许加载元数据版本异常或预发布类
  • KN-XSKIP-PRERELEASE-CHECK Xskip-prerelease-check Native 参数 实验（-X，兼容性不保证） — 允许加载预发布类
  • KN-XSTDLIB-COMPILATION Xstdlib-compilation Native 参数 实验（-X，兼容性不保证） — 仅标准库编译需要的特殊能力
  • KN-XSUPPRESS-API-VERSION-GREATER-THAN-LANGUAGE-VERSION-ERROR Xsuppress-api-version-greater-than-language-version-error Native 参数 实验（-X，兼容性不保证） — 抑制 API 版本高于语言版本的错误
  • KN-XSUPPRESS-VERSION-WARNINGS Xsuppress-version-warnings Native 参数 实验（-X，兼容性不保证） — 抑制语言/API 版本过时或不一致类警告
  • KN-XUNRESTRICTED-BUILDER-INFERENCE Xunrestricted-builder-inference Native 参数 实验（-X，兼容性不保证） — 放宽 builder inference 限制
  • KN-XUSE-FIR-EXPERIMENTAL-CHECKERS Xuse-fir-experimental-checkers Native 参数 实验（-X，兼容性不保证） — 启用尚未用于生产的前端 IR 实验检查
  • KN-XUSE-FIR-LT Xuse-fir-lt Native 参数 实验（-X，兼容性不保证） — 使用 LightTree 解析器配合前端 IR
  • KN-XUSE-K2 Xuse-k2 Native 参数 实验（-X，兼容性不保证） — 使用实验性 K2 编译管线
  • KN-XWHEN-GUARDS Xwhen-guards Native 参数 实验（-X，兼容性不保证） — 启用实验性language support for when guards
排障诊断（1）
  • KN-XXEXPLICIT-RETURN-TYPES XXexplicit-return-types Native 参数 内部（-XX，更不稳定） — 强制the compiler to report errors on all public AP
警告、错误与编译日志8 让编译更严或更静，或打出更多编译过程日志。

本任务下的选项

场景可配（6）
  • APP-ALLWARNINGSASERRORS allWarningsAsErrors Gradle 稳定（正式选项） 跨侧 K/N侧 KN-WERROR — 存在警告时按错误失败（对齐 -Werror），适合 CI 门禁
  • APP-EXTRAWARNINGS extraWarnings Gradle 稳定（正式选项） 跨侧 K/N侧 KN-WEXTRA — 启用 K2 额外检查（对齐 -Wextra），发现更多潜在问题
  • APP-SUPPRESSWARNINGS suppressWarnings Gradle 稳定（正式选项） 跨侧 K/N侧 KN-NOWARN — 抑制编译警告输出（对齐 -nowarn）
  • KN-XDONT-WARN-ON-ERROR-SUPPRESSION Xdont-warn-on-error-suppression Native 参数 实验（-X，兼容性不保证） — 错误被抑制时不报告警告（主要影响 K2）
  • KN-XRENDER-INTERNAL-DIAGNOSTIC-NAMES Xrender-internal-diagnostic-names Native 参数 实验（-X，兼容性不保证） — 渲染警告/错误的内部名称
  • KN-XWARNING-LEVEL Xwarning-level Native 参数 实验（-X，兼容性不保证） 同功能 1 入口 — 设置指定警告的级别（如升为 error）
排障诊断（2）
  • APP-VERBOSE verbose Gradle 稳定（正式选项） 跨侧 K/N侧 KN-VERBOSE — 输出更详细的编译日志，便于排查配置或编译失败
  • KN-XREPORT-ALL-WARNINGS Xreport-all-warnings Native 参数 实验（-X，兼容性不保证） — 即使已有错误仍报告全部警告

搭工程

多平台工程与源集10 KMP fragment、expect/actual、common 源怎么编到一起。

Fragment 编译

声明 fragment、源与依赖，属于同一套 KMP 编译模型。

  • KN-XFRAGMENTS Xfragments Native 参数 实验（-X，兼容性不保证） — 声明多平台编译的全部 fragment
  • KN-XFRAGMENT-SOURCES Xfragment-sources Native 参数 实验（-X，兼容性不保证） — 向指定 fragment 添加源码
  • KN-XFRAGMENT-REFINES Xfragment-refines Native 参数 实验（-X，兼容性不保证） — 高级编译选项 -Xfragment-refines，多为实验向
  • KN-XFRAGMENT-DEPENDENCY Xfragment-dependency Native 参数 实验（-X，兼容性不保证） — 高级编译选项 -Xfragment-dependency，多为实验向

本任务下的选项

场景可配（5）
  • KN-XCOMMON-SOURCES Xcommon-sources Native 参数 实验（-X，兼容性不保证） — 与本模块一并编译的 common 源集
  • KN-XEXPECT-ACTUAL-CLASSES Xexpect-actual-classes Native 参数 实验（-X，兼容性不保证） — 与 expect/actual 类相关的编译行为开关
  • KN-XMULTI-PLATFORM Xmulti-platform Native 参数 实验（-X，兼容性不保证） — 启用多平台项目语言支持
  • KN-XNO-CHECK-ACTUAL Xno-check-actual Native 参数 实验（-X，兼容性不保证） — 不要check for the presence of the 'actual' modifie
  • KN-XSEPARATE-KMP-COMPILATION Xseparate-kmp-compilation Native 参数 实验（-X，兼容性不保证） — 启用分离式 KMP 编译方案
排障诊断（1）
  • KN-XXLENIENT-MODE XXlenient-mode Native 参数 内部（-XX，更不稳定） — 宽松模式：缺失 actual 时生成占位声明
模块、KLIB 与依赖29 模块名、klib、friend、部分链接，以及要链哪些库。

本任务下的选项

  • APP-MODULENAME moduleName 场景可配 Gradle 稳定（正式选项） 跨侧 K/N侧 KN-MODULE-NAME — 指定编译模块名；Native 下也可用作 ObjC 导出名前缀相关配置
  • KN-FRIEND-MODULES friend-modules 场景可配 Native 参数 稳定（正式选项） — 指定 friend 模块路径
  • KN-INCLUDE-BINARY include-binary 场景可配 Native 参数 稳定（正式选项） — 将外部二进制打包进 klib
  • KN-LIBRARY library 场景可配 Native 参数 稳定（正式选项） — 链接指定库
  • KN-LIBRARY-VERSION library-version 场景可配 Native 参数 稳定（正式选项） — 库版本（可能已弃用）
  • KN-NATIVE-LIBRARY native-library 场景可配 Native 参数 稳定（正式选项） — 纳入给定的原生 bitcode 库
  • KN-NO-DEFAULT-LIBS no-default-libs 场景可配 Native 参数 稳定（正式选项） — 不自动链接 dist/klib 中的库
  • KN-NO-ENDORSED-LIBS no-endorsed-libs 场景可配 Native 参数 稳定（正式选项） — 不自动链接 dist 中的 endorsed 库（可能已弃用）
  • KN-NOPACK nopack 场景可配 Native 参数 稳定（正式选项） — 不把库打包成 klib
  • KN-NOSTDLIB nostdlib 场景可配 Native 参数 稳定（正式选项） — 不自动链接标准库
  • KN-XCHECK-DEPENDENCIES Xcheck-dependencies 场景可配 Native 参数 实验（-X，兼容性不保证） — 检查依赖并下载缺失项
  • KN-XEXTERNAL-DEPENDENCIES Xexternal-dependencies 场景可配 Native 参数 实验（-X，兼容性不保证） — 外部依赖描述文件路径
  • KN-XHEADER-KLIB-PATH Xheader-klib-path 场景可配 Native 参数 实验（-X，兼容性不保证） — 将仅含公开 ABI 的 klib 保存到指定路径
  • KN-XINCLUDE Xinclude 场景可配 Native 参数 实验（-X，兼容性不保证） — 将中间库按源文件同等方式处理
  • KN-XKLIB-ABI-VERSION Xklib-abi-version 场景可配 Native 参数 实验（-X，兼容性不保证） — 指定写入 klib 的自定义 ABI 版本（测试向）
  • KN-XKLIB-DUPLICATED-UNIQUE-NAME-STRATEGY Xklib-duplicated-unique-name-strategy 场景可配 Native 参数 实验（-X，兼容性不保证） — 多个 klib 同 unique_name 时的依赖使用策略
  • KN-XKLIB-ENABLE-SIGNATURE-CLASH-CHECKS Xklib-enable-signature-clash-checks 场景可配 Native 参数 实验（-X，兼容性不保证） — 启用签名唯一性检查
  • KN-XKLIB-IR-INLINER Xklib-ir-inliner 场景可配 Native 参数 实验（-X，兼容性不保证） — 在 klib 序列化前启用实验性 IR Inliner
  • KN-XKLIB-NORMALIZE-ABSOLUTE-PATH Xklib-normalize-absolute-path 场景可配 Native 参数 实验（-X，兼容性不保证） — 规范化 klib 中的绝对路径
  • KN-XKLIB-RELATIVE-PATH-BASE Xklib-relative-path-base 场景可配 Native 参数 实验（-X，兼容性不保证） — 提供基准路径以计算 klib 中的相对源路径
  • KN-XMETADATA-KLIB Xmetadata-klib 场景可配 Native 参数 实验（-X，兼容性不保证） — 仅生成包含声明元数据的 klib
  • KN-XMETADATA-VERSION Xmetadata-version 场景可配 Native 参数 实验（-X，兼容性不保证） — 修改生成二进制的元数据版本
  • KN-XPARTIAL-LINKAGE Xpartial-linkage 场景可配 Native 参数 实验（-X，兼容性不保证） — 启用部分链接（partial linkage）
  • KN-XPARTIAL-LINKAGE-LOGLEVEL Xpartial-linkage-loglevel 场景可配 Native 参数 实验（-X，兼容性不保证） — 设置部分链接的编译期日志级别
  • KN-XPURGE-USER-LIBS Xpurge-user-libs 场景可配 Native 参数 实验（-X，兼容性不保证） — 即使显式指定也不链接未使用的库
  • KN-XREAD-DEPENDENCIES-FROM Xread-dependencies-from 场景可配 Native 参数 实验（-X，兼容性不保证） — 用于链接的序列化依赖
  • KN-XREFINES-PATHS Xrefines-paths 场景可配 Native 参数 实验（-X，兼容性不保证） — 路径：output directories for refined modules (module
  • KN-XWRITE-DEPENDENCIES-OF-PRODUCED-KLIB-TO Xwrite-dependencies-of-produced-klib-to 场景可配 Native 参数 实验（-X，兼容性不保证） — 写入file containing the paths of dependencies used
  • KN-XWRITE-DEPENDENCIES-TO Xwrite-dependencies-to 场景可配 Native 参数 实验（-X，兼容性不保证） — 后端依赖写出路径

出包和链接

产物类型、链接与入口13 要可执行文件、framework 还是库；入口点、链接器和目标平台。

本任务下的选项

场景可配（12）
  • KN-BINARY-ANDROIDPROGRAMTYPE Xbinary=androidProgramType Native -Xbinary 实验（-X，兼容性不保证） — 指定 Android 程序类型相关二进制行为
  • KN-BINARY-LINKRUNTIME Xbinary=linkRuntime Native -Xbinary 实验（-X，兼容性不保证） — 控制 runtime 的链接策略
  • KN-ENTRY entry Native 参数 稳定（正式选项） — 指定限定名形式的入口点
  • KN-LINKER-OPTION linker-option Native 参数 稳定（正式选项） — 向链接器传递单个参数
  • KN-LINKER-OPTIONS linker-options Native 参数 稳定（正式选项） — 向链接器传递参数
  • KN-MANIFEST manifest Native 参数 稳定（正式选项） — 提供 manifest 附加文件
  • KN-NOMAIN nomain Native 参数 稳定（正式选项） — 假定 main 入口由外部库提供
  • KN-OUTPUT output Native 参数 稳定（正式选项） — 指定输出文件/产物名称
  • KN-PRODUCE produce Native 参数 稳定（正式选项） — 指定产物类型（可执行文件、框架、库等）
  • KN-TARGET target Native 参数 稳定（正式选项） — 指定硬件/平台编译目标
  • KN-XCOMPILE-FROM-BITCODE Xcompile-from-bitcode Native 参数 实验（-X，兼容性不保证） — 从给定 bitcode 文件继续编译
  • KN-XMANIFEST-NATIVE-TARGETS Xmanifest-native-targets Native 参数 实验（-X，兼容性不保证） — 写入 manifest 的 native_targets 列表
排障诊断（1）
  • KN-LIST-TARGETS list-targets Native 参数 稳定（正式选项） — 列出可用硬件目标
多 so 拆分与 runtime 独立发布10 把 runtime / stdlib 拆出去，按模块出多个 .so。

模块化拆分构建

KonanConfig.moduleIncludeOnly 由 outputModule + moduleIncludes + emitStdlib 推导；Linker.kt 写明 moduleIncludeOnly.isNotEmpty() ≡ modular/split build；codesizeOpt 注释写明用于 split compilation 削减跨 klib 导出符号。

  • KN-BINARY-MODULEINCLUDES Xbinary=moduleIncludes Native -Xbinary 实验（-X，兼容性不保证） — 定义每个输出模块应包含哪些 klib（模块→klib 映射表）
  • KN-BINARY-MODULEINCLUDEONLY Xbinary=moduleIncludeOnly Native -Xbinary 实验（-X，兼容性不保证） — 指定当前编译单元只纳入哪些 klib（由 moduleIncludes 等推导，不建议应用工程手写）
  • KN-BINARY-OUTPUTMODULE Xbinary=outputModule Native -Xbinary 实验（-X，兼容性不保证） — 声明本次输出属于哪个模块，与 moduleIncludes 的 key 对应
  • KN-BINARY-RUNTIMENAME Xbinary=runtimeName Native -Xbinary 实验（-X，兼容性不保证） — runtime 模块名（跨模块须一致）
  • KN-BINARY-STDLIBNAME Xbinary=stdlibName Native -Xbinary 实验（-X，兼容性不保证） — stdlib 模块名（跨模块须一致）
  • KN-BINARY-EMITRUNTIME Xbinary=emitRuntime Native -Xbinary 实验（-X，兼容性不保证） — 是否在本次编译产物中生成 runtime
  • KN-BINARY-EMITSTDLIB Xbinary=emitStdlib Native -Xbinary 实验（-X，兼容性不保证） — 是否在本次编译产物中生成 stdlib
  • KN-BINARY-SPLITBCFILE Xbinary=splitBCfile Native -Xbinary 实验（-X，兼容性不保证） — 是否把 bitcode 拆分成独立文件（ohos_arm64 非 debug 时生效）
  • KN-BINARY-CODESIZEOPT Xbinary=codesizeOpt Native -Xbinary 实验（-X，兼容性不保证） — 削减跨 klib 的导出符号，减小包体；拆分编译默认开

本任务下的选项

  • KN-BINARY-EMITRUNTIMEOPT Xbinary=emitRuntimeOpt 不推荐 Native -Xbinary 实验（-X，兼容性不保证） — 控制 runtime 以何种优化/发射模式打入产物
ObjC / Swift / C 互操作25 出 framework、导出名、Bundle 信息，和 Apple 运行时协作。

本任务下的选项

场景可配（23）
  • KN-BINARY-BUNDLEID Xbinary=bundleId Native -Xbinary 实验（-X，兼容性不保证） 同功能 1 入口 — 写入产物 Bundle Identifier（Apple 生态）
  • KN-BINARY-BUNDLESHORTVERSIONSTRING Xbinary=bundleShortVersionString Native -Xbinary 实验（-X，兼容性不保证） — 写入 Bundle 短版本号
  • KN-BINARY-BUNDLEVERSION Xbinary=bundleVersion Native -Xbinary 实验（-X，兼容性不保证） — 写入 Bundle 版本号
  • KN-BINARY-CINTERFACEMODE Xbinary=cInterfaceMode Native -Xbinary 实验（-X，兼容性不保证） — ObjC 互操作模式（stable / unstable）
  • KN-BINARY-OBJCDISPOSEONMAIN Xbinary=objcDisposeOnMain Native -Xbinary 实验（-X，兼容性不保证） — 在主线程执行 ObjC 对象释放
  • KN-BINARY-OBJCDISPOSEWITHRUNLOOP Xbinary=objcDisposeWithRunLoop Native -Xbinary 实验（-X，兼容性不保证） — 结合 RunLoop 安排 ObjC 对象释放
  • KN-BINARY-OBJCEXPORTBLOCKEXPLICITPARAMETERNAMES Xbinary=objcExportBlockExplicitParameterNames Native -Xbinary 实验（-X，兼容性不保证） — 在 ObjC block 参数中保留 Kotlin 参数名
  • KN-BINARY-OBJCEXPORTDISABLESWIFTMEMBERNAMEMANGLING Xbinary=objcExportDisableSwiftMemberNameMangling Native -Xbinary 实验（-X，兼容性不保证） — 关闭 Swift 成员名 mangling
  • KN-BINARY-OBJCEXPORTENTRYPOINTSPATH Xbinary=objcExportEntryPointsPath Native -Xbinary 实验（-X，兼容性不保证） — 指定 ObjC 导出入点列表文件路径
  • KN-BINARY-OBJCEXPORTERRORONNAMECOLLISIONS Xbinary=objcExportErrorOnNameCollisions Native -Xbinary 实验（-X，兼容性不保证） — 名称冲突时报错，避免暴露歧义 API
  • KN-BINARY-OBJCEXPORTEXPLICITMETHODFAMILY Xbinary=objcExportExplicitMethodFamily Native -Xbinary 实验（-X，兼容性不保证） — 为 ObjC 导出显式标注方法族
  • KN-BINARY-OBJCEXPORTIGNOREINTERFACEMETHODCOLLISIONS Xbinary=objcExportIgnoreInterfaceMethodCollisions Native -Xbinary 实验（-X，兼容性不保证） — 忽略接口方法冲突（宽松模式）
  • KN-BINARY-OBJCEXPORTSUSPENDFUNCTIONLAUNCHTHREADRESTRICTION Xbinary=objcExportSuspendFunctionLaunchThreadRestriction Native -Xbinary 实验（-X，兼容性不保证） — 控制挂起函数导出时的线程限制
  • KN-BINARY-SWIFTEXPORT Xbinary=swiftExport Native -Xbinary 实验（-X，兼容性不保证） — 启用实验性 Swift Export（生成 .swiftmodule）
  • KN-BINARY-UNITSUSPENDFUNCTIONOBJCEXPORT Xbinary=unitSuspendFunctionObjCExport Native -Xbinary 实验（-X，兼容性不保证） — 控制 Unit 挂起函数导出到 Objective-C 的方式
  • KN-XEMIT-LAZY-OBJC-HEADER Xemit-lazy-objc-header Native 参数 实验（-X，兼容性不保证） — 向给定路径生成 lazy Objective-C header，用于 framework 导出相关的调试或校验
  • KN-XEXPORT-KDOC Xexport-kdoc Native 参数 实验（-X，兼容性不保证） — 把 KDoc 导出到 framework 头文件
  • KN-XEXPORT-LIBRARY Xexport-library Native 参数 实验（-X，兼容性不保证） — 纳入 framework API 的库
  • KN-XFRAMEWORK-IMPORT-HEADER Xframework-import-header Native 参数 实验（-X，兼容性不保证） — 向 framework 头文件追加 import
  • KN-XNO-OBJC-GENERICS Xno-objc-generics Native 参数 实验（-X，兼容性不保证） — 在 framework 头文件中禁用泛型支持
  • KN-XOMIT-FRAMEWORK-BINARY Xomit-framework-binary Native 参数 实验（-X，兼容性不保证） — 编译 framework 时省略二进制
  • KN-XSHORT-MODULE-NAME Xshort-module-name Native 参数 实验（-X，兼容性不保证） — 库在 IDE / 生成的 ObjC 头中的短名称
  • KN-XSTATIC-FRAMEWORK Xstatic-framework Native 参数 实验（-X，兼容性不保证） — 生成静态库形式的 framework
排障诊断（2）

调运行时

内存、GC 与并发模型17 选 GC、内存模型和分配器，影响卡顿与内存占用。

本任务下的选项

  • KN-BINARY-APPSTATETRACKING Xbinary=appStateTracking 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 后台时抑制定时 GC
  • KN-BINARY-AUXGCTHREADS Xbinary=auxGCThreads 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 设置辅助 GC 线程数量
  • KN-BINARY-CONCURRENTMARKMAXITERATIONS Xbinary=concurrentMarkMaxIterations 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 并发 mark 最大迭代数
  • KN-BINARY-CONCURRENTWEAKSWEEP Xbinary=concurrentWeakSweep 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 并发弱引用扫描
  • KN-BINARY-DISABLEMMAP Xbinary=disableMmap 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 禁用 mmap 相关分配路径
  • KN-BINARY-ENABLEGCFASTPATH Xbinary=enableGcFastpath 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — GC fast path（ohos_arm64 默认开）
  • KN-BINARY-FIXEDBLOCKPAGESIZE Xbinary=fixedBlockPageSize 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 固定块页大小
  • KN-BINARY-FREEZING Xbinary=freezing 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 控制对象冻结相关行为（与内存模型配套）
  • KN-BINARY-GC Xbinary=gc 场景可配 Native -Xbinary 实验（-X，兼容性不保证） 同功能 1 入口 — GC 实现（cms / pmcs / stwms / noop / cmc）
  • KN-BINARY-GCMARKSINGLETHREADED Xbinary=gcMarkSingleThreaded 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 关闭并行 mark（调试 GC 竞态用）
  • KN-BINARY-GCMUTATORSCOOPERATE Xbinary=gcMutatorsCooperate 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — mutator 协作 GC
  • KN-BINARY-GCSCHEDULERTYPE Xbinary=gcSchedulerType 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — GC 调度策略
  • KN-BINARY-MEMORYMODEL Xbinary=memoryModel 场景可配 Native -Xbinary 实验（-X，兼容性不保证） 同功能 1 入口 — 内存模型（strict / experimental）
  • KN-BINARY-MMAPTAG Xbinary=mmapTag 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 设置 mmap 标签（便于诊断）
  • KN-BINARY-PAGEDALLOCATOR Xbinary=pagedAllocator 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 按页分配（vs. 按对象）
  • KN-BINARY-RUNTIMESWITCHMEMORYMANAGER Xbinary=runtimeSwitchMemoryManager 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 运行时切换内存管理器（实验）
  • KN-XALLOCATOR Xallocator 场景可配 Native 参数 实验（-X，兼容性不保证） — 选择运行时分配器
调试、符号化与运行时诊断24 断点、调试信息、HiLog、sanitizer、崩溃转储。

本任务下的选项

开发必用（1）
  • KN-G g Native 参数 稳定（正式选项） — 生成调试信息，便于断点与符号化
场景可配（22）
  • KN-BINARY-CHECKSTATEATEXTERNALCALLS Xbinary=checkStateAtExternalCalls Native -Xbinary 实验（-X，兼容性不保证） 同功能 1 入口 — 在可能较慢的外部调用处检查线程状态，避免错误线程状态调用
  • KN-BINARY-CORESYMBOLICATIONIMAGELISTTYPE Xbinary=coreSymbolicationImageListType Native -Xbinary 实验（-X，兼容性不保证） — 配置 Core Symbolication 镜像列表类型（Apple 平台符号化）
  • KN-BINARY-DEBUGCOMPILATIONDIR Xbinary=debugCompilationDir Native -Xbinary 实验（-X，兼容性不保证） — 指定调试信息中的编译目录映射
  • KN-BINARY-ENABLEDEBUGTRANSPARENTSTEPPING Xbinary=enableDebugTransparentStepping Native -Xbinary 实验（-X，兼容性不保证） — 改善调试器对内联等场景的步进体验
  • KN-BINARY-ENABLESAFEPOINTSIGNPOSTS Xbinary=enableSafepointSignposts Native -Xbinary 实验（-X，兼容性不保证） — 启用 safepoint 相关 signpost 追踪
  • KN-BINARY-ENABLESTACKMAP Xbinary=enableStackmap Native -Xbinary 实验（-X，兼容性不保证） — 启用精确 stackmap 代码生成，供 CMC/CRT 等精确根扫描使用
  • KN-BINARY-FORCEEXPORTINTERNALSYMBOLNAMES Xbinary=forceExportInternalSymbolNames Native -Xbinary 实验（-X，兼容性不保证） — 强制导出所列内部符号名（调试/互操作高级用法）
  • KN-BINARY-FORCENATIVETHREADSTATEFORFUNCTIONS Xbinary=forceNativeThreadStateForFunctions Native -Xbinary 实验（-X，兼容性不保证） — 强制所列函数在 native 线程状态执行
  • KN-BINARY-PRINTTOOHOSHILOG Xbinary=printToOhosHiLog Native -Xbinary 实验（-X，兼容性不保证） — 将运行时日志输出到鸿蒙 HiLog
  • KN-BINARY-RUNTIMEASSERTIONSMODE Xbinary=runtimeAssertionsMode Native -Xbinary 实验（-X，兼容性不保证） — 控制运行时断言的检查与失败处理模式
  • KN-BINARY-SANITIZER Xbinary=sanitizer Native -Xbinary 实验（-X，兼容性不保证） — 启用 Address/Thread 等 sanitizer，放大内存类错误以便排障
  • KN-BINARY-SOURCEINFOTYPE Xbinary=sourceInfoType Native -Xbinary 实验（-X，兼容性不保证） — 选择源码位置信息写入调试信息的方式
  • KN-BINARY-STACKPROTECTOR Xbinary=stackProtector Native -Xbinary 实验（-X，兼容性不保证） — 启用栈保护（stack protector）模式
  • KN-ENABLE-ASSERTIONS enable-assertions Native 参数 稳定（正式选项） — 在生成代码中启用运行时断言
  • KN-XADD-LIGHT-DEBUG Xadd-light-debug Native 参数 实验（-X，兼容性不保证） 同功能 1 入口 — 为优化构建附加轻量调试信息
  • KN-XDEBUG-INFO-VERSION Xdebug-info-version Native 参数 实验（-X，兼容性不保证） — 生成指定版本的调试信息
  • KN-XDEBUG-PREFIX-MAP Xdebug-prefix-map Native 参数 实验（-X，兼容性不保证） — 重映射调试信息中的源码目录路径
  • KN-XDESTROY-RUNTIME-MODE Xdestroy-runtime-mode Native 参数 实验（-X，兼容性不保证） — 控制 runtime 销毁时机
  • KN-XG-GENERATE-DEBUG-TRAMPOLINE Xg-generate-debug-trampoline Native 参数 实验（-X，兼容性不保证） — 生成 trampoline 以提升调试断点解析精度
  • KN-XNATIVE-DEBUGINFO-MINIFY Xnative-debuginfo-minify Native 参数 实验（-X，兼容性不保证） — 删除未被引用的调试信息并压缩调试信息，控制 Debug 产物体积
  • KN-XRUNTIME-LOGS Xruntime-logs Native 参数 实验（-X，兼容性不保证） — 启用 Native runtime 内部日志
  • KN-XWORKER-EXCEPTION-HANDLING Xworker-exception-handling Native 参数 实验（-X，兼容性不保证） — 配置 Worker.executeAfter 中未处理异常的行为
排障诊断（1）
  • KN-BINARY-MINIDUMPLOCATION Xbinary=minidumpLocation Native -Xbinary 实验（-X，兼容性不保证） — 指定 minidump 输出位置
包体与运行性能10 打开优化、缩小二进制、调整内联和字符串布局。

本任务下的选项

  • KN-BINARY-LATIN1STRINGS Xbinary=latin1Strings 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 对 Latin-1 字符串使用更紧凑表示
  • KN-BINARY-PACKFIELDS Xbinary=packFields 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 打包对象字段布局以节省空间
  • KN-BINARY-PRECODEGENINLINETHRESHOLD Xbinary=preCodegenInlineThreshold 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 代码生成前内联阈值
  • KN-BINARY-SMALLBINARY Xbinary=smallBinary 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 偏向生成更小的二进制（可能影响性能）
  • KN-BINARY-STRIPDEBUGINFOFROMNATIVELIBS Xbinary=stripDebugInfoFromNativeLibs 场景可配 Native -Xbinary 实验（-X，兼容性不保证） — 从原生依赖库中剥离调试信息以减小体积
  • KN-OPT opt 场景可配 Native 参数 稳定（正式选项） — 启用编译期优化，通常用于发布/性能构建
  • KN-XIGNORE-CONST-OPTIMIZATION-ERRORS Xignore-const-optimization-errors 场景可配 Native 参数 实验（-X，兼容性不保证） — 常量表达式优化时忽略编译异常
  • KN-XLLVM-LTO-PASSES Xllvm-lto-passes 场景可配 Native 参数 实验（-X，兼容性不保证） — 自定义 LTO 优化 LLVM pass 集合
  • KN-XLLVM-MODULE-PASSES Xllvm-module-passes 场景可配 Native 参数 实验（-X，兼容性不保证） — 自定义模块优化 LLVM pass 集合
  • KN-XNO-INLINE Xno-inline 场景可配 Native 参数 实验（-X，兼容性不保证） — 禁用方法内联

配缓存和插件

构建缓存与增量13 让二次编译更快。

本任务下的选项

  • KN-XADD-CACHE Xadd-cache 场景可配 Native 参数 实验（-X，兼容性不保证） — 将指定库加入缓存
  • KN-XAUTO-CACHE-DIR Xauto-cache-dir 场景可配 Native 参数 实验（-X，兼容性不保证） — 自动可缓存依赖的缓存输出目录
  • KN-XAUTO-CACHE-FROM Xauto-cache-from 场景可配 Native 参数 实验（-X，兼容性不保证） — 自动缓存依赖的根目录
  • KN-XBACKEND-THREADS Xbackend-threads 场景可配 Native 参数 实验（-X，兼容性不保证） — 按文件并行代码生成（N 个线程）
  • KN-XCACHE-DIRECTORY Xcache-directory 场景可配 Native 参数 实验（-X，兼容性不保证） — 缓存目录路径
  • KN-XCACHED-LIBRARY Xcached-library 场景可配 Native 参数 实验（-X，兼容性不保证） — 库路径与其缓存路径（逗号分隔）
  • KN-XENABLE-INCREMENTAL-COMPILATION Xenable-incremental-compilation 场景可配 Native 参数 实验（-X，兼容性不保证） — 启用增量编译
  • KN-XFILE-TO-CACHE Xfile-to-cache 场景可配 Native 参数 实验（-X，兼容性不保证） — 要缓存的文件路径
  • KN-XIC-CACHE-DIR Xic-cache-dir 场景可配 Native 参数 实验（-X，兼容性不保证） — 增量编译缓存目录
  • KN-XLAZY-IR-FOR-CACHES Xlazy-ir-for-caches 场景可配 Native 参数 实验（-X，兼容性不保证） — 对缓存库使用 lazy IR
  • KN-XMAKE-PER-FILE-CACHE Xmake-per-file-cache 场景可配 Native 参数 实验（-X，兼容性不保证） — 强制生成按文件缓存
  • KN-XPRE-LINK-CACHES Xpre-link-caches 场景可配 Native 参数 实验（-X，兼容性不保证） — 执行缓存预链接
  • KN-XUSE-FIR-IC Xuse-fir-ic 场景可配 Native 参数 实验（-X，兼容性不保证） — 使用前端 IR 内部增量编译（实验）
插件、脚本与测试运行器11 编译器插件、kts / REPL、生成测试 runner。

本任务下的选项

场景可配（10）
  • KN-GENERATE-NO-EXIT-TEST-RUNNER generate-no-exit-test-runner Native 参数 稳定（正式选项） — 生成不强制退出的单元测试运行器
  • KN-GENERATE-TEST-RUNNER generate-test-runner Native 参数 稳定（正式选项） — 生成单元测试运行器
  • KN-GENERATE-WORKER-TEST-RUNNER generate-worker-test-runner Native 参数 稳定（正式选项） — 生成 worker 单元测试运行器
  • KN-P P Native 参数 稳定（正式选项） — 向插件传递选项
  • KN-SCRIPT script Native 参数 稳定（正式选项） — 执行给定的 Kotlin 脚本（*.kts）
  • KN-XALLOW-ANY-SCRIPTS-IN-SOURCE-ROOTS Xallow-any-scripts-in-source-roots Native 参数 实验（-X，兼容性不保证） — 允许脚本与普通 Kotlin 源一并编译
  • KN-XCOMPILER-PLUGIN Xcompiler-plugin Native 参数 实验（-X，兼容性不保证） — 注册编译器插件
  • KN-XDISABLE-DEFAULT-SCRIPTING-PLUGIN Xdisable-default-scripting-plugin Native 参数 实验（-X，兼容性不保证） — 默认不启用脚本插件
  • KN-XPLUGIN Xplugin Native 参数 实验（-X，兼容性不保证） — 从给定 classpath 加载编译器插件
  • KN-XREPL Xrepl Native 参数 实验（-X，兼容性不保证） — 运行Kotlin REPL (deprecated)
排障诊断（1）
  • KN-XDUMP-TESTS-TO Xdump-tests-to Native 参数 实验（-X，兼容性不保证） — 将可用测试列表转储到指定文件
工具链、环境与参数透传15 编译器路径、临时目录、以及 freeCompilerArgs 这种透传入口。

本任务下的选项

开发必用（1）
  • APP-FREECOMPILERARGS freeCompilerArgs Gradle 稳定（正式选项） — Gradle 向编译器透传额外参数的入口（如 -g、-opt、-Xbinary=…）
场景可配（10）
  • KN-BINARY-COMPILEBITCODEWITHXCODELLVM Xbinary=compileBitcodeWithXcodeLlvm Native -Xbinary 实验（-X，兼容性不保证） — 使用 Xcode 自带 LLVM 编译 bitcode
  • KN-KOTLIN-HOME kotlin-home Native 参数 稳定（正式选项） — Kotlin 编译器 home 目录路径，用于发现运行时库
  • KN-XBINARY Xbinary Native 参数 实验（-X，兼容性不保证） — 设置 -Xbinary 二进制选项（name=value）
  • KN-XINTELLIJ-PLUGIN-ROOT Xintellij-plugin-root Native 参数 实验（-X，兼容性不保证） — 路径：'kotlin-compiler.jar' or the directory where t
  • KN-XKONAN-DATA-DIR Xkonan-data-dir Native 参数 实验（-X，兼容性不保证） — 自定义 konan 发行版目录
  • KN-XLLVM-VARIANT Xllvm-variant Native 参数 实验（-X，兼容性不保证） — 选择编译所用的 LLVM 发行版
  • KN-XOVERRIDE-CLANG-OPTIONS Xoverride-clang-options Native 参数 实验（-X，兼容性不保证） — 显式传入 Clang 选项列表
  • KN-XOVERRIDE-KONAN-PROPERTIES Xoverride-konan-properties Native 参数 实验（-X，兼容性不保证） — 用给定键值覆盖 konan.properties
  • KN-XRUNTIME Xruntime Native 参数 实验（-X，兼容性不保证） — 覆盖默认 runtime.bc 路径
  • KN-XTEMPORARY-FILES-DIR Xtemporary-files-dir Native 参数 实验（-X，兼容性不保证） — 将临时文件保存到指定目录
排障诊断（3）
  • KN-HELP help Native 参数 稳定（正式选项） — 打印常用编译选项说明
  • KN-VERSION version Native 参数 稳定（正式选项） — 显示编译器版本
  • KN-X X Native 参数 实验（-X，兼容性不保证） — 打印高级（-X）编译选项说明
不推荐（1）
  • KN-BINARY-LLVMSPLITPATH Xbinary=llvmSplitPath Native -Xbinary 实验（-X，兼容性不保证） — 指定 LLVM split 相关工具路径

查编译器

编译器内部排障28 转储 IR / bitcode、校验阶段——查编译器自己，不是改 App 行为。

本任务下的选项

场景可配（14）
  • KN-XCHECK-PHASE-CONDITIONS Xcheck-phase-conditions Native 参数 实验（-X，兼容性不保证） — 检查 IR lowering 阶段的前后条件
  • KN-XDISABLE-PHASES Xdisable-phases Native 参数 实验（-X，兼容性不保证） — 禁用指定后端阶段
  • KN-XFAKE-OVERRIDE-VALIDATOR Xfake-override-validator Native 参数 实验（-X，兼容性不保证） — 启用 IR fake override 校验
  • KN-XLIST-PHASES Xlist-phases Native 参数 实验（-X，兼容性不保证） — 列出后端阶段
  • KN-XPHASES-TO-VALIDATE Xphases-to-validate Native 参数 实验（-X，兼容性不保证） — 在指定后端阶段前后都校验状态
  • KN-XPHASES-TO-VALIDATE-AFTER Xphases-to-validate-after Native 参数 实验（-X，兼容性不保证） — 在指定后端阶段后校验状态
  • KN-XPHASES-TO-VALIDATE-BEFORE Xphases-to-validate-before Native 参数 实验（-X，兼容性不保证） — 在指定后端阶段前校验状态
  • KN-XSAVE-LLVM-IR-AFTER Xsave-llvm-ir-after Native 参数 实验（-X，兼容性不保证） — 将 Kotlin IR→LLVM IR 结果保存到指定目录
  • KN-XSAVE-LLVM-IR-DIRECTORY Xsave-llvm-ir-directory Native 参数 实验（-X，兼容性不保证） — 保存 LLVM IR 阶段性结果的目录
  • KN-XVERBOSE-PHASES Xverbose-phases Native 参数 实验（-X，兼容性不保证） — 对指定后端阶段输出详细日志
  • KN-XVERIFY-BITCODE Xverify-bitcode Native 参数 实验（-X，兼容性不保证） — 每个方法后校验 LLVM bitcode
  • KN-XVERIFY-COMPILER Xverify-compiler Native 参数 实验（-X，兼容性不保证） — 启用编译器自检
  • KN-XVERIFY-IR Xverify-ir Native 参数 实验（-X，兼容性不保证） — IR 校验模式
  • KN-XVERIFY-IR-VISIBILITY Xverify-ir-visibility Native 参数 实验（-X，兼容性不保证） — 在 lowering 前校验 IR 可见性违规
排障诊断（14）
  • KN-BINARY-PRINTMODULE Xbinary=printModule Native -Xbinary 实验（-X，兼容性不保证） — 打印编译模块相关调试信息
  • KN-XDUMP-DIRECTORY Xdump-directory Native 参数 实验（-X，兼容性不保证） — 将后端状态转储到该目录
  • KN-XDUMP-FQNAME Xdump-fqname Native 参数 实验（-X，兼容性不保证） — 按 FqName 转储声明
  • KN-XDUMP-PERF Xdump-perf Native 参数 实验（-X，兼容性不保证） — 将详细性能统计写入指定文件（按扩展名选择 plain/JSON/markdown）
  • KN-XPHASES-TO-DUMP Xphases-to-dump Native 参数 实验（-X，兼容性不保证） — 在指定后端阶段前后都转储状态
  • KN-XPHASES-TO-DUMP-AFTER Xphases-to-dump-after Native 参数 实验（-X，兼容性不保证） — 在指定后端阶段后转储状态
  • KN-XPHASES-TO-DUMP-BEFORE Xphases-to-dump-before Native 参数 实验（-X，兼容性不保证） — 在指定后端阶段前转储状态
  • KN-XPRINT-BITCODE Xprint-bitcode Native 参数 实验（-X，兼容性不保证） — 打印 LLVM bitcode
  • KN-XPRINT-FILES Xprint-files Native 参数 实验（-X，兼容性不保证） — 打印参与编译的文件列表
  • KN-XPRINT-IR Xprint-ir Native 参数 实验（-X，兼容性不保证） — 打印 IR
  • KN-XPROFILE-PHASES Xprofile-phases Native 参数 实验（-X，兼容性不保证） — 对后端阶段做性能剖析
  • KN-XREPORT-OUTPUT-FILES Xreport-output-files Native 参数 实验（-X，兼容性不保证） — 报告源文件到输出文件的映射
  • KN-XREPORT-PERF Xreport-perf Native 参数 实验（-X，兼容性不保证） — 输出详细性能统计
  • KN-XXDEBUG-LEVEL-COMPILER-CHECKS XXdebug-level-compiler-checks Native 参数 内部（-XX，更不稳定） — 启用调试级编译器检查（可能显著变慢）