Компилятор 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=true // false 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 {
           compileKotlinTask.kotlinOptions.freeCompilerArgs += listOf("-Xerror-tolerance-policy=SYNTAX")
       }
   }
}

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

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

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

kotlin {
   js(IR) {
       compilations.all {
           compileKotlinTask.kotlinOptions.freeCompilerArgs += listOf("-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 для нового. Это позволяет вам скомпилировать и опубликовать вашу библиотеку для проектов, использующих любой из двух бэкендов компилятора.