Использование компилятора Kotlin/JS IR

Начиная с Kotlin 1.4.0, компилятор Kotlin/JS IR имеет стабильность уровня Альфа. Вы можете использовать компилятор IR, но вся функциональность, язык и инструментальные средства, описанные в этом документе, могут быть изменены в будущих версиях Kotlin.

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

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

Компилятор IR доступен начиная с Kotlin 1.4.0 через плагин Kotlin/JS Gradle. Чтобы включить его в свой проект, передайте тип компилятора функции js в вашем скрипте Gradle:

kotlin {
    js(IR) { // or: LEGACY, BOTH
        // . . .
        binaries.executable()
    }
}

• IR использует новый компилятор IR для Kotlin/JS.
• LEGACY использует стандартный компилятор.
• BOTH компилирует ваш проект как с новым компилятором IR, так и со стандартным компилятором. Это в основном полезно для создания библиотек, совместимых с обеими версиями компилятора, см. ниже.

Тип компилятора также может быть задан в файле gradle.properties, с ключом kotlin.js.compiler=ir. (Однако это поведение перекрывается любыми настройками в build.gradle(.kts)).

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

Существенным изменением с новым компилятором IR является отсутствие обратной совместимости с стандартным компилятором. Отсутствие такой совместимости между двумя компиляторами для Kotlin/JS означает, что библиотека, созданная с новым компилятором IR, не может быть использована со стандартным компилятором, и наоборот.

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

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

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

• В настоящее время компилятор IR не генерирует карты исходных данных для Kotlin-кода. Вы можете следить за прогрессом на YouTrack.
• Некоторые библиотеки, которые полагаются на определенные характеристики стандартного компилятора, например, kotlin-wrappers, могут показывать некоторые проблемы. Вы можете следить за расследованием и прогрессом на YouTrack.
• Компилятор IR по умолчанию не делает доступными Kotlin-декларации для JavaScript. Чтобы сделать Kotlin-декларации видимыми для JavaScript, они должны быть аннотированы с @JsExport.

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

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

Генерация файлов объявлений TypeScript — это функция, эксклюзивная для компилятора IR, и находится в активной разработке. Если у вас возникнут проблемы, пожалуйста, отправьте их в систему отслеживания задач Kotlin или проголосуйте за существующие связанные задачи.

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

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

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

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