Параметры компилятора Kotlin

-api-version version

Задайте версию API, чтобы контролировать, какие API Kotlin можно использовать в коде во время выполнения. Например, если вы используете компилятор Kotlin версии 2.4.0 с -api-version=2.1, ваш код останется совместимым со стандартной библиотекой Kotlin версии 2.1.0.

Нельзя задать значение -api-version выше значения -language-version.

В большинстве случаев версия API и версия языка должны совпадать. Исключение — разработка библиотеки для пользователей, которым необходимо запускать более старую версию стандартной библиотеки Kotlin. В этом случае укажите более старую версию API, чтобы случайно не использовать API, недоступные этим пользователям.

Подробнее о влиянии версии API на совместимость см. в разделе Рекомендации по обратной совместимости для авторов библиотек.

-help (-h)

Показать справочную информацию и завершить работу. Отображаются только стандартные параметры. Чтобы показать дополнительные параметры, используйте -X.

-kotlin-home path

Укажите пользовательский путь к компилятору Kotlin, который используется для поиска библиотек среды выполнения.

-language-version version

Задайте версию языка, чтобы определить, какие языковые возможности Kotlin доступны во время компиляции.

Например, чтобы воспользоваться новыми улучшениями производительности компиляции, не меняя поведение компилятора, можно использовать новую версию компилятора с более старой версией языка. При использовании более старой версии языка новые языковые возможности будут недоступны, но также не появятся новые ошибки и предупреждения об устаревших элементах, добавленные после этой версии. Такой подход особенно полезен авторам библиотек, которым необходимо сохранить совместимость со старыми версиями Kotlin. Подробнее см. в разделе Рекомендации по обратной совместимости для авторов библиотек.

В качестве версии языка можно настроить одну из трех последних стабильных версий Kotlin. Например, Kotlin 2.5.0 поддерживает версии языка вплоть до 2.2.

При использовании более старой версии языка необходимо также использовать более старую версию API. Подробнее см. в разделе -api-version version .

-opt-in annotation

Разрешить использование API, для которого требуется явное согласие, с аннотацией-требованием, указанной полным именем.

-P plugin:pluginId:optionName=value

Передать параметр плагину компилятора Kotlin. Основные плагины и их параметры перечислены в разделе Основные плагины компилятора документации.

-progressive

Включить для компилятора прогрессивный режим.

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

-script

Выполнить файл скрипта Kotlin. При вызове с этим параметром компилятор выполняет первый файл скрипта Kotlin (*.kts) среди переданных аргументов.

-verbose

Включить подробный вывод журнала с информацией о процессе компиляции.

-version

Показать версию компилятора.

-X

Показать сведения о дополнительных параметрах и завершить работу. Сейчас эти параметры нестабильны: их имена и поведение могут измениться без уведомления.

Параметры контрактов Kotlin

Следующие параметры включают экспериментальные возможности контрактов Kotlin.

-Xallow-reified-type-in-catch

Включает поддержку реифицированных параметров типа Throwable в предложениях catch функций inline.

-Xcollection-literals

Включает поддержку литералов коллекций с синтаксисом скобок [].

-Xcompiler-plugin-order={plugin.before>plugin.after}

Настроить порядок запуска плагинов компилятора. Компилятор сначала запускает plugin.before, а затем plugin.after:

Для трех и более плагинов можно задать несколько правил порядка. Например:

kotlinc -Xcompiler-plugin-order=plugin.first>plugin.middle
kotlinc -Xcompiler-plugin-order=plugin.middle>plugin.last

В результате плагины запускаются в следующем порядке:

1. plugin.first

2. plugin.middle

3. plugin.last

Если плагин компилятора отсутствует, соответствующее правило игнорируется.

Для следующих плагинов можно настроить порядок по их идентификаторам:

Этот порядок запуска определяет только порядок работы серверной части плагинов компилятора, но не интерфейсной.

-Xdata-flow-based-exhaustiveness

Включает проверки полноты выражений when на основе потока данных.

-Xexplicit-context-arguments

Включает явную передачу контекстных аргументов для контекстных параметров.

Это позволяет разрешать неоднозначность перегрузки, передавая контекстные аргументы в месте вызова.

-Xklib-ir-inliner

Настроить, включена ли внутримодульная подстановка для Kotlin/Native, Kotlin/JS и Kotlin/Wasm. По умолчанию она включена.

Параметр поддерживает следующие режимы:

• disabled: отключает внутримодульную подстановку для Kotlin/Native, Kotlin/JS и Kotlin/Wasm.

• full: включает межмодульную подстановку.

-Xintrinsic-const-evaluation

Включает улучшенную поддержку констант времени компиляции.

-Xname-based-destructuring

Настроить интерпретацию компилятором объявлений с деструктуризацией на основе имен свойств.

Параметр поддерживает следующие режимы:

• only-syntax: включает явную форму деструктуризации по именам, не меняя поведение существующих объявлений с деструктуризацией.

• name-mismatch: выводит предупреждения, если при позиционной деструктуризации классов данных используются имена переменных, не совпадающие с именами свойств.

• complete: включает краткую форму деструктуризации по именам с круглыми скобками и сохраняет поддержку позиционной деструктуризации с квадратными скобками.

-Xphases-to-dump-before

Установите значение ExternalPackageParentPatcherLowering, чтобы создать файл дампа после этапа понижения IR при компиляции. Настройте выходной каталог для Kotlin/JVM с помощью параметра компилятора -Xdump-directory.

-Xrepl

Активирует REPL Kotlin.

kotlinc -Xrepl

-Xreturn-value-checker

Настроить способ, которым компилятор сообщает об игнорируемых результатах:

• disable: отключает проверку неиспользуемых возвращаемых значений (по умолчанию).

• check: включает проверку и выводит предупреждения об игнорируемых результатах помеченных функций.

• full: включает проверку, считает все функции проекта помеченными и выводит предупреждения об игнорируемых результатах.

Управление предупреждениями

kotlinc -Xwarning-level=DIAGNOSTIC_NAME:(error|warning|disabled)

@argfile

Прочитать параметры компилятора из указанного файла. Такой файл может содержать параметры компилятора со значениями и пути к исходным файлам. Параметры и пути следует разделять пробелами. Например:

-include-runtime -d hello.jar hello.kt

Чтобы передать значения, содержащие пробелы, заключите их в одинарные (') или двойные (") кавычки. Если значение содержит кавычки, экранируйте их обратной косой чертой (\).

-include-runtime -d 'My folder'

Можно также передать несколько файлов аргументов, например, чтобы отделить параметры компилятора от исходных файлов.

$ kotlinc @compiler.options @classes

Если файлы находятся не в текущем каталоге, используйте относительные пути.

$ kotlinc @options/compiler.options hello.kt

-classpath path (-cp path)

Искать файлы классов по указанным путям. Элементы пути к классам разделяются системными разделителями путей (; в Windows, : в macOS/Linux). Путь к классам может содержать пути к файлам и каталогам, ZIP- или JAR-файлам.

-d path

Поместить сгенерированные файлы классов в указанное расположение. Это может быть каталог, ZIP- или JAR-файл.

-include-runtime

Включить среду выполнения Kotlin в результирующий JAR-файл. Полученный архив можно запускать в любой среде с поддержкой Java.

-jdk-home path

Использовать пользовательский домашний каталог JDK для включения в путь к классам, если он отличается от значения по умолчанию JAVA_HOME.

-Xjdk-release=version

Указать целевую версию генерируемого байт-кода JVM. Ограничить API JDK в пути к классам указанной версией Java. Автоматически задает -jvm-target version. Возможные значения: 1.8, 9, 10, ..., 26.

-jvm-default mode

Управлять компиляцией функций, объявленных в интерфейсах, в методы по умолчанию JVM.

-jvm-target version

Указать целевую версию генерируемого байт-кода JVM. Возможные значения: 1.8, 9, 10, ..., 26. Значение по умолчанию — 1.8.

-java-parameters

Сгенерировать метаданные для рефлексии Java 1.8 по параметрам методов.

-module-name name (JVM)

Задать пользовательское имя для генерируемого файла .kotlin_module.

-no-jdk

Не включать среду выполнения Java в путь к классам автоматически.

-no-reflect

Не включать библиотеку рефлексии Kotlin (kotlin-reflect.jar) в путь к классам автоматически.

-no-stdlib (JVM)

Не включать стандартную библиотеку Kotlin/JVM (kotlin-stdlib.jar) и библиотеку рефлексии Kotlin (kotlin-reflect.jar) в путь к классам автоматически.

-script-templates classnames[,]

Классы шаблонов определения скриптов. Используйте полные имена классов и разделяйте их запятыми (,).

-Xdump-directory

Настроить каталог файлов дампа для параметра компилятора -Xphases-to-dump-before`.

-Xjvm-expose-boxed

Сгенерировать упакованные версии всех встроенных классов-значений в модуле, а также упакованные варианты использующих их функций, чтобы сделать их доступными из Java. Подробнее см. раздел Встроенные классы-значения в руководстве по вызову Kotlin из Java.

-Xnullability-annotations

Настроить интерпретацию компилятором Kotlin аннотаций nullability из определенных пакетов Java.

Полный список поддерживаемых аннотаций и параметров конфигурации см. в разделе Аннотации nullability.

-libraries path

Пути к библиотекам Kotlin с файлами .meta.js и .kjsm, разделённые системным разделителем путей.

-main {call|noCall}

Определяет, следует ли вызывать функцию main при выполнении.

-meta-info

Создаёт файлы .meta.js и .kjsm с метаданными. Используйте этот параметр при создании библиотеки JS.

-module-kind {umd|commonjs|amd|plain}

Тип модуля JS, создаваемого компилятором:

• umd — модуль Universal Module Definition

• commonjs — модуль CommonJS

• amd — модуль Asynchronous Module Definition

• plain — обычный модуль JS

Подробнее о типах модулей JS и различиях между ними см. в этой статье.

-no-stdlib (JS)

Не включать автоматически стандартную библиотеку Kotlin/JS в зависимости компиляции.

-output filepath

Задаёт файл назначения для результата компиляции. Значением должен быть путь к файлу .js, включающий его имя.

-output-postfix filepath

Добавляет содержимое указанного файла в конец выходного файла.

-output-prefix filepath

Добавляет содержимое указанного файла в начало выходного файла.

-source-map

Создаёт source map.

-source-map-base-dirs path

Использует указанные пути в качестве базовых каталогов. Базовые каталоги используются для вычисления относительных путей в source map.

-source-map-embed-sources {always|never|inlining}

Встраивает исходные файлы в source map.

-source-map-names-policy {simple-names|fully-qualified-names|no}

Добавляет в source map имена переменных и функций, объявленных в коде Kotlin.

-source-map-prefix

Добавляет указанный префикс к путям в source map.

-target {es5|es2015}

Создаёт файлы JS для указанной версии ECMA.

-Xenable-implementing-interfaces-from-typescript

Разрешает реализовывать интерфейсы Kotlin, экспортированные с аннотацией @JsExport, из JavaScript/TypeScript.

-Xes-long-as-bigint

Включает поддержку типа JavaScript BigInt для представления значений Kotlin Long при компиляции в современный JavaScript (ES2020).

-Xsuspend-lambda-exporting

Разрешает экспортировать приостанавливающие лямбда-выражения, объявленные в декларациях @JsExport, в качестве функций JavaScript async.

-enable-assertions (-ea)

Включает проверки во время выполнения в сгенерированном коде.

-entry name (-e name)

Задаёт полное имя точки входа.

-g

Включает генерацию отладочной информации. Этот параметр снижает уровень оптимизации, поэтому его не следует сочетать с параметром -opt.

-generate-test-runner (-tr)

Создаёт приложение для запуска модульных тестов проекта.

-generate-no-exit-test-runner (-trn)

Создаёт приложение для запуска модульных тестов без явного завершения процесса.

-include-binary path (-ib path)

Упаковывает внешний бинарный файл в создаваемый файл klib.

-library path (-l path)

Связывает с библиотекой. О том, как использовать библиотеки в проектах Kotlin/Native, см. в разделе Библиотеки Kotlin/Native.

-library-version version (-lv version)

Задаёт версию библиотеки.

-linker-option

Передаёт аргумент компоновщику при сборке бинарного файла. Этот параметр можно использовать для связывания с нативной библиотекой.

-linker-options args

Передаёт несколько аргументов компоновщику при сборке бинарного файла. Аргументы разделяются пробелами.

-list-targets

Выводит список доступных аппаратных целей.

-manifest path

Задаёт файл дополнения манифеста.

-module-name name (Native)

Задаёт имя модуля компиляции. Этот параметр также можно использовать, чтобы задать префикс имён объявлений, экспортируемых в Objective-C: Как задать пользовательский префикс/имя Objective-C для фреймворка Kotlin?

-native-library path (-nl path)

Включает библиотеку нативного битового кода.

-no-default-libs

Отключает связывание пользовательского кода с предварительно собранными библиотеками платформы, распространяемыми вместе с компилятором.

-nomain

Предполагает, что точка входа main предоставляется внешними библиотеками.

-nopack

Не упаковывает библиотеку в файл klib.

-nostdlib

Не связывает со стандартной библиотекой.

-opt

Включает оптимизацию компиляции и создаёт бинарный файл с более высокой производительностью во время выполнения. Не рекомендуется сочетать этот параметр с параметром -g, который снижает уровень оптимизации.

-output name (-o name)

Задаёт имя выходного файла.

-produce output (-p output)

Задаёт тип выходного файла:

• program

• static

• dynamic

• framework

• library

• bitcode

-repo path (-r path)

Путь поиска библиотек. Подробнее см. в разделе Последовательность поиска библиотек.

-target target

Задаёт аппаратную цель. Чтобы просмотреть список доступных целей, используйте параметр -list-targets.

-Xccall-mode

Включает новый режим взаимодействия с библиотеками C или Objective-C, импортированными через cinterop.

-Xoverride-konan-properties=min.version.*

Настраивает более низкие минимальные поддерживаемые версии целей Apple, чем установленные по умолчанию в Kotlin. Например:

kotlinc -Xoverride-konan-properties=minVersion.ios=14.0
kotlinc -Xoverride-konan-properties=minVersion.macos=11.0
kotlinc -Xoverride-konan-properties=minVersion.tvos=14.0
kotlinc -Xoverride-konan-properties=minVersion.watchos=7.0