使用 IR 编译器

顶级属性(top-level property)的延迟初始化(Lazy initialization)

val a = run {
    val result = // 假设这里是一段计算密集的代码
    println(result)
    result
} // 属性值直到初次使用时才会计算

对开发阶段二进制文件进行增量编译

JS IR 编译器提供了对开发阶段二进制文件的增量编译模式, 可以对开发过程提高速度. 在这种模式下, 编译器会在模型层级缓存 Gradle task compileDevelopmentExecutableKotlinJs 的结果. 在后续的编译中, 对未修改的源代码文件使用缓存的编译结果, 可以使得编译更快完成, 尤其是在对代码进行少量修改的情况.

增量编译是默认启用的. 如果要对开发阶段二进制文件禁用增量编译, 请向项目的 gradle.properties 或 local.properties 文件添加以下设置:

kotlin.incremental.js.ir=false // 默认为 true

输出模式

你可以选择让 JS IR 编译器在你的项目中如何输出 .js 文件:

对每个模块输出 .js 文件. 默认情况下, JS 编译器的编译结果是对项目的每个模块输出单独的 .js 文件.
对每个项目输出 .js 文件. 你也可以将整个项目编译为单个 .js 文件, 方法是向 gradle.properties 添加以下设置:
```
kotlin.js.ir.output.granularity=whole-program // 默认值是 'per-module'
```
对每个文件输出 .js 文件. 你也可以设置更加细粒度的输出, 为每个 Kotlin 文件生成 1 个 JavaScript 文件 (如果 Kotlin 文件包含导出的声明, 则会生成 2 个 JavaScript 文件). 启用这个模式的方法如下:
1. 向你的构建文件, 添加 useEsModules() 函数, 支持 ECMAScript 模块:
```
// build.gradle.kts
kotlin {
    js(IR) {
        useEsModules() // 启用 ES2015 模块
        browser()
    }
}
```
  或者, 你也可以使用 es2015 编译目标, 在你的项目中支持 ES2015 功能.
2. 使用 -Xir-per-file 编译器选项, 或者更新你的 gradle.properties 文件, 如下:
```
# gradle.properties
kotlin.js.ir.output.granularity=per-file // 默认值是 `per-module`
```

在产品(Production)模式中对成员名称的极简化(Minification)

当你使用产品(Production) 模式构建你的 Kotlin/JS 应用程序时, 会自动应用这样的极简化处理, 并默认启用. 要关闭对成员名称的极简化处理, 请使用 -Xir-minimized-member-names 编译器选项:

kotlin {
    js(IR) {
        compilations.all {
            compileTaskProvider.configure {
                compilerOptions.freeCompilerArgs.add("-Xir-minimized-member-names=false")
            }
        }
    }
}

预览功能: 生成 TypeScript 声明文件 (d.ts)

如果你的项目输出可执行文件 (binaries.executable()), Kotlin/JS IR 编译器会收集所有标注了 @JsExport 注解的顶级声明, 并自动在一个 .d.ts 文件中生成 TypeScript 定义.

如果你想要生成 TypeScript 定义, 你需要在 Gradle 构建文件中明确进行配置. 请在你的 build.gradle.kts 文件的 js 小节中添加 generateTypeScriptDefinitions(). 例如:

kotlin {
    js {
        binaries.executable()
        browser {
        }
        generateTypeScriptDefinitions()
    }
}

这些声明位于 build/js/packages/<package_name>/kotlin 目录中, 与相应的未经 webpack 处理的 JavaScript 代码在一起.

IR 编译器目前的限制

新的 IR 编译器后端的一个重要变化是与默认后端之间没有二进制兼容性. 使用新的 IR 编译器后端创建的库, 会使用 klib 格式, 在默认后端中将无法使用. 同时, 使用旧编译器创建的库, 就是一个包含 js 文件的 jar, 也不能在 IR 后端中使用.

将既有的项目迁移到 IR 编译器

针对 IR 编译器开发向后兼容的库

如果你是库的维护者, 希望同时兼容默认后端和新的 IR 编译器后端, 有一种编译器选择设置可以让你对两种后端都创建 artifact, 因此可以支持下一代 Kotlin 编译器, 同时又对你的既有用户保持兼容性. 这就是所谓的 both 模式, 可以在 gradle.properties 文件中通过 kotlin.js.compiler=both 来启用, 或者, 也可以在 build.gradle(.kts) 文件的 js 代码块之内, 设置为项目独有的选项:

kotlin {
    js(BOTH) {
        // ...
    }
}

使用 both 模式时, 从你的源代码构建库时, IR 编译器后端和默认编译器后端都会被使用(如同它的名称所指的那样). 也就是说, Kotlin IR 的 klib 文件, 以及默认编译器的 jar 文件都会生成. 当发布到相同的 Maven 路径时, Gradle 会根据使用场景自动选择正确的 artifact – 对旧的编译器是 js, 对新的编译器是 klib. 因此对于使用两种编译器后端中的任何一个的项目, 你都可以编译并发布你的库.

使用 IR 编译器﻿

warning

顶级属性(top-level property)的延迟初始化(Lazy initialization)﻿

对开发阶段二进制文件进行增量编译﻿

note

输出模式﻿

在产品(Production)模式中对成员名称的极简化(Minification)﻿

预览功能: 生成 TypeScript 声明文件 (d.ts)﻿