Компилятор Kotlin/JS IR

Ленивая инициализация свойств верхнего уровня

Для улучшения производительности запуска приложения, компилятор Kotlin/JS IR лениво инициализирует свойства верхнего уровня. Таким образом, приложение загружается без инициализации всех свойств верхнего уровня, используемых в его коде. Инициализируются только необходимые при запуске; другие свойства получают свои значения позже, когда код, который их использует, фактически выполняется.

val a = run { 
    val result = // intensive computations
    println(result)
    result 
} // value is computed upon the first usage

Если по какой-либо причине вам необходимо инициализировать свойство нелениво (при запуске приложения), отметьте его аннотацией @EagerInitialization.

Инкрементная компиляция для библиотек разработки

Компилятор JS IR предоставляет режим инкрементной компиляции для библиотек разработки, ускоряющий процесс разработки. В этом режиме компилятор кэширует результаты задачи compileDevelopmentExecutableKotlinJs Gradle на уровне модуля. Он использует кэшированные результаты компиляции для неизменённых исходных файлов во время последующих компиляций, что ускоряет их выполнение, особенно при небольших изменениях.

Инкрементная компиляция включена по умолчанию. Чтобы отключить инкрементную компиляцию для библиотек разработки, добавьте следующую строку в gradle.properties или local.properties проекта:

kotlin.incremental.js.ir=false // true by default

Выходные файлы .js: по одному на модуль или один для всего проекта

В результате компиляции компилятор JS IR создаёт отдельные .js файлы для каждого модуля проекта. Кроме того, вы можете скомпилировать весь проект в один .js файл, добавив следующую строку в gradle.properties:

kotlin.js.ir.output.granularity=whole-program // 'per-module' is the default

Игнорирование ошибок компиляции

Компилятор Kotlin/JS IR предоставляет новый режим компиляции, недоступный в бэкенде по умолчанию — игнорирование ошибок компиляции. В этом режиме вы можете попробовать запустить приложение, даже если в его коде есть ошибки. Например, когда вы выполняете сложную рефакторинг или работаете над частью системы, которая никак не связана с ошибкой компиляции в другой части.

В этом новом режиме компилятор игнорирует весь некорректный код. Таким образом, вы можете запустить приложение и попробовать части кода, которые не используют некорректный код. Если вы попытаетесь запустить код, который содержал ошибки во время компиляции, вы получите исключение во время выполнения.

Выберите одну из двух стратегий для игнорирования ошибок компиляции в вашем коде:

• SEMANTIC. Компилятор будет принимать код, который синтаксически корректен, но не имеет смысла в семантическом плане. Например, присваивание числа строковой переменной (несовпадение типов).

• SYNTAX. Компилятор будет принимать любой код, даже если он содержит синтаксические ошибки. Независимо от того, что вы напишете, компилятор всё равно попытается сгенерировать исполняемый файл.

В качестве экспериментальной функции игнорирование ошибок компиляции требует опции включения. Чтобы включить этот режим, добавьте опцию компилятора -Xerror-tolerance-policy={SEMANTIC|SYNTAX}:

kotlin {
   js(IR) {
       compilations.all {
           compileTaskProvider.configure {
               compilerOptions.freeCompilerArgs.add("-Xerror-tolerance-policy=SYNTAX")
           }
       }
   }
}

Минификация имён членов в режиме производства

Компилятор Kotlin/JS IR использует внутреннюю информацию о взаимосвязях ваших классов и функций Kotlin для применения более эффективной минификации, сокращая имена функций, свойств и классов. Это уменьшает размер скомпилированных приложений.

Этот тип минификации автоматически применяется при построении вашего приложения Kotlin/JS в режиме производства и включен по умолчанию. Чтобы отключить минификацию имён членов, используйте опцию компилятора -Xir-minimized-member-names:

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

Предварительный просмотр: генерация файлов TypeScript-деклараций (d.ts)

Компилятор Kotlin/JS IR способен генерировать определения TypeScript из вашего кода Kotlin. Эти определения могут использоваться JavaScript-инструментами и IDE при работе с гибридными приложениями для обеспечения автодополнения, поддержки статических анализаторов и упрощения включения кода Kotlin в JavaScript- и TypeScript-проекты.

Декларации верхнего уровня, помеченные аннотацией @JsExport в проекте, создающем исполняемые файлы (binaries.executable()), будут иметь сгенерированный файл .d.ts, содержащий определения TypeScript для экспортированных деклараций Kotlin. Эти определения можно найти в build/js/packages/<package_name>/kotlin наряду с соответствующим не-упакованным JavaScript-кодом.

Текущие ограничения компилятора IR

Основным изменением с новым бэкендом компилятора IR является отсутствие бинарной совместимости с бэкендом по умолчанию. Библиотека, созданная с новым компилятором IR, использует klib формат и не может быть использована из бэкенда по умолчанию. В то же время, библиотека, созданная со старым компилятором, является jar с js файлами, которые не могут быть использованы из бэкенда IR.

Если вы хотите использовать бэкенд компилятора IR для своего проекта, вам нужно обновить все зависимости Kotlin до версий, поддерживающих этот новый бэкенд. Библиотеки, опубликованные JetBrains для Kotlin 1.4+, нацеленные на Kotlin/JS, уже содержат все необходимые артефакты для использования с новым бэкендом компилятора IR.

Если вы автор библиотеки, стремящийся обеспечить совместимость с текущим бэкендом компилятора, а также новым бэкендом компилятора IR, дополнительно ознакомьтесь с разделом создания библиотек для компилятора IR.

Бэкенд компилятора IR также имеет некоторые расхождения по сравнению с бэкендом по умолчанию. При использовании нового бэкенда важно учитывать возможные трудности.

• Некоторые библиотеки, которые зависят от конкретных характеристик бэкенда по умолчанию, например, kotlin-wrappers, могут вызывать некоторые проблемы. Вы можете следить за ходом расследования и прогрессом в YouTrack.

• Бэкенд IR по умолчанию не делает Kotlin-декларации доступными для JavaScript. Чтобы сделать Kotlin-декларации видимыми для JavaScript, их необходимо пометить аннотацией @JsExport.

Миграция существующих проектов в компилятор IR

Из-за значительных различий между двумя компиляторами Kotlin/JS, для работы вашего кода Kotlin/JS с компилятором IR могут потребоваться некоторые корректировки. Узнайте, как мигрировать существующие проекты Kotlin/JS в компилятор IR в руководстве по миграции компилятора Kotlin/JS IR.

Создание библиотек для компилятора IR с обратной совместимостью

Если вы поддерживаете библиотеку и хотите обеспечить совместимость с базовым компилятором, а также с новым компилятором IR, доступно свойство для выбора компилятора, которое позволяет создавать артефакты для обоих компиляторов, сохраняя совместимость для ваших существующих пользователей и обеспечивая поддержку следующего поколения компилятора Kotlin. Этот так называемый both-режим можно включить, используя свойство kotlin.js.compiler=both в вашем файле gradle.properties, или можно установить в качестве одного из проекта-специфичных параметров внутри блока js в файле build.gradle(.kts):

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

В режиме both при построении библиотеки из ваших исходных кодов используются как компилятор IR, так и базовый компилятор (отсюда и название). Это означает, что будут сгенерированы как файлы klib с Kotlin IR, так и файлы jar для базового компилятора. При публикации под одним и тем же коордиатом Maven Gradle автоматически выберет правильный артефакт в зависимости от ситуации — js для старого компилятора, klib для нового. Это позволяет вам компилировать и публиковать вашу библиотеку для проектов, использующих любой из этих двух компиляторов.