Kotlin compiler options
Each release of Kotlin includes compilers for the supported targets: JVM, JavaScript, and native binaries for supported platforms.
These compilers are used by:
The IDE, when you click the Compile or Run button for your Kotlin project.
Gradle, when you call
gradle buildin a console or in the IDE.Maven, when you call
mvn compileormvn test-compilein a console or in the IDE.
You can also run Kotlin compilers manually from the command line as described in the Working with command-line compiler tutorial.
Kotlin compilers have a number of options for tailoring the compiling process. Compiler options for different targets are listed on this page together with a description of each one.
There are several ways to set the compiler options and their values (compiler arguments):
In IntelliJ IDEA, write in the compiler arguments in the Additional command line parameters text box in Settings/Preferences | Build, Execution, Deployment | Compiler | Kotlin Compiler.
If you're using Gradle, specify the compiler arguments in the
compilerOptionsproperty of the Kotlin compilation task. For details, see Gradle compiler options.If you're using Maven, specify the compiler arguments in the
<configuration>element of the Maven plugin node. For details, see Maven.If you run a command-line compiler, add the compiler arguments directly to the utility call or write them into an argfile.
For example:
$ kotlinc hello.kt -include-runtime -d hello.jarnote
On Windows, when you pass compiler arguments that contain delimiter characters (whitespace,
=,;,,), surround these arguments with double quotes (").$ kotlinc.bat hello.kt -include-runtime -d "My Folder\hello.jar"
The following options are common for all Kotlin compilers.
Display the compiler version.
Suppress the compiler from displaying warnings during compilation.
Turn any warnings into a compilation error.
Enable additional declaration, expression, and type compiler checks that emit warnings if true.
Enable verbose logging output which includes details of the compilation process.
Evaluate a Kotlin script file. When called with this option, the compiler executes the first Kotlin script (*.kts) file among the given arguments.
Display usage information and exit. Only standard options are shown. To show advanced options, use -X.
Display information about the advanced options and exit. These options are currently unstable: their names and behavior may be changed without notice.
Specify a custom path to the Kotlin compiler used for the discovery of runtime libraries.
Pass an option to a Kotlin compiler plugin. Core plugins and their options are listed in the Core compiler plugins section of the documentation.
Provide source compatibility with the specified version of Kotlin.
Allow using declarations only from the specified version of Kotlin bundled libraries.
Enable the progressive mode for the compiler.
In the progressive mode, deprecations and bug fixes for unstable code take effect immediately, instead of going through a graceful migration cycle. Code written in the progressive mode is backwards compatible; however, code written in a non-progressive mode may cause compilation errors in the progressive mode.
Read the compiler options from the given file. Such a file can contain compiler options with values and paths to the source files. Options and paths should be separated by whitespaces. For example:
-include-runtime -d hello.jar hello.ktTo pass values that contain whitespaces, surround them with single (') or double (") quotes. If a value contains quotation marks in it, escape them with a backslash (\).
-include-runtime -d 'My folder'You can also pass multiple argument files, for example, to separate compiler options from source files.
$ kotlinc @compiler.options @classesIf the files reside in locations different from the current directory, use relative paths.
$ kotlinc @options/compiler.options hello.ktEnable usages of API that requires opt-in with a requirement annotation with the given fully qualified name.
Suppresses specific warnings globally across the whole project, for example:
kotlinc -Xsuppress-warning=NOTHING_TO_INLINE -Xsuppress-warning=NO_TAIL_CALLS_FOUND main.ktThe Kotlin compiler for JVM compiles Kotlin source files into Java class files. The command-line tools for Kotlin to JVM compilation are kotlinc and kotlinc-jvm. You can also use them for executing Kotlin script files.
In addition to the common options, Kotlin/JVM compiler has the options listed below.
Search for class files in the specified paths. Separate elements of the classpath with system path separators (; on Windows, : on macOS/Linux). The classpath can contain file and directory paths, ZIP, or JAR files.
Place the generated class files into the specified location. The location can be a directory, a ZIP, or a JAR file.
Include the Kotlin runtime into the resulting JAR file. Makes the resulting archive runnable on any Java-enabled environment.
Use a custom JDK home directory to include into the classpath if it differs from the default JAVA_HOME.
Specify the target version of the generated JVM bytecode. Limit the API of the JDK in the classpath to the specified Java version. Automatically sets -jvm-target version. Possible values are 1.8, 9, 10, ..., 21.
note
This option is not guaranteed to be effective for each JDK distribution.
Specify the target version of the generated JVM bytecode. Possible values are 1.8, 9, 10, ..., 21. The default value is 1.8.
Generate metadata for Java 1.8 reflection on method parameters.
Set a custom name for the generated .kotlin_module file.
Don't automatically include the Java runtime into the classpath.
Don't automatically include the Kotlin reflection (kotlin-reflect.jar) into the classpath.
Don't automatically include the Kotlin/JVM stdlib (kotlin-stdlib.jar) and Kotlin reflection (kotlin-reflect.jar) into the classpath.
Script definition template classes. Use fully qualified class names and separate them with commas (,).
The Kotlin compiler for JS compiles Kotlin source files into JavaScript code. The command-line tool for Kotlin to JS compilation is kotlinc-js.
In addition to the common options, Kotlin/JS compiler has the options listed below.
Paths to Kotlin libraries with .meta.js and .kjsm files, separated by the system path separator.
Define whether the main function should be called upon execution.
Generate .meta.js and .kjsm files with metadata. Use this option when creating a JS library.
The kind of JS module generated by the compiler:
umd- a Universal Module Definition modulecommonjs- a CommonJS moduleamd- an Asynchronous Module Definition moduleplain- a plain JS module
To learn more about the different kinds of JS module and the distinctions between them, see this article.
Don't automatically include the default Kotlin/JS stdlib into the compilation dependencies.
Set the destination file for the compilation result. The value must be a path to a .js file including its name.
Add the content of the specified file to the end of the output file.
Add the content of the specified file to the beginning of the output file.
Generate the source map.
Use the specified paths as base directories. Base directories are used for calculating relative paths in the source map.
Embed source files into the source map.
Add variable and function names that you declared in Kotlin code into the source map.
Setting | Description | Example output |
|---|---|---|
| Variable names and simple function names are added. (Default) |
|
| Variable names and fully qualified function names are added. |
|
| No variable or function names are added. | N/A |
Add the specified prefix to paths in the source map.
Kotlin/Native compiler compiles Kotlin source files into native binaries for the supported platforms. The command-line tool for Kotlin/Native compilation is kotlinc-native.
In addition to the common options, Kotlin/Native compiler has the options listed below.
Enable runtime assertions in the generated code.
Enable emitting debug information. This option lowers the optimization level and should not be combined with the -opt option.
Produce an application for running unit tests from the project.
Produce an application for running unit tests without an explicit process exit.
Pack external binary within the generated klib file.
Link with the library. To learn about using libraries in Kotlin/native projects, see Kotlin/Native libraries.
Set the library version.
List the available hardware targets.
Provide a manifest addend file.
Specify a name for the compilation module. This option can also be used to specify a name prefix for the declarations exported to Objective-C: How do I specify a custom Objective-C prefix/name for my Kotlin framework?
Include the native bitcode library.
Disable linking user code with the prebuilt platform libraries distributed with the compiler.
Assume the main entry point to be provided by external libraries.
Don't pack the library into a klib file.
Pass an argument to the linker during binary building. This can be used for linking against some native library.
Pass multiple arguments to the linker during binary building. Separate arguments with whitespaces.
Don't link with stdlib.
Enable compilation optimizations and produce a binary with better runtime performance. It's not recommended to combine it with the -g option, which lowers the optimization level.
Set the name for the output file.
Specify the qualified entry point name.
Specify output file kind:
programstaticdynamicframeworklibrarybitcode
Library search path. For more information, see Library search sequence.
Set hardware target. To see the list of available targets, use the -list-targets option.