0
# JVM Compilation
1

2
Complete JVM bytecode compilation supporting all Kotlin language features, Java interoperability, and advanced optimization passes. The JVM compiler produces bytecode compatible with Java 8+ and supports both standalone and incremental compilation modes.
3

4
## Capabilities
5

6
### K2JVMCompiler
7

8
Main entry point for JVM compilation, handling the complete compilation pipeline from source analysis to bytecode generation.
9

10
```kotlin { .api }
11
/**
12
 * Kotlin to JVM bytecode compiler implementation
13
 * Supports K2 (new) compiler pipeline with enhanced performance and analysis
14
 */
15
class K2JVMCompiler : CLICompiler<K2JVMCompilerArguments>() {
16
    override val platform: TargetPlatform // JvmPlatforms.defaultJvmPlatform
17
    
18
    override fun createArguments(): K2JVMCompilerArguments
19
    
20
    override fun doExecute(
21
        arguments: K2JVMCompilerArguments,
22
        configuration: CompilerConfiguration,
23
        rootDisposable: Disposable,
24
        paths: KotlinPaths?
25
    ): ExitCode
26
    
27
    override fun doExecutePhased(
28
        arguments: K2JVMCompilerArguments,
29
        services: Services,
30
        messageCollector: MessageCollector
31
    ): ExitCode
32
}
33
```
34

35
### JVM Compiler Arguments
36

37
Comprehensive argument configuration for JVM compilation including output control, classpath management, and optimization settings.
38

39
```kotlin { .api }
40
/**
41
 * Arguments specific to JVM compilation
42
 * Extends CommonCompilerArguments with JVM-specific options
43
 */
44
class K2JVMCompilerArguments : CommonCompilerArguments() {
45
    /** Output directory for compiled .class files */
46
    var destination: String?
47
    
48
    /** Output JAR file path */
49
    var jar: String?
50
    
51
    /** Classpath for compilation (directories and JAR files) */
52
    var classpath: String?
53
    
54
    /** Include Kotlin runtime in the resulting JAR */
55
    var includeRuntime: Boolean
56
    
57
    /** Path to JDK home directory */
58
    var jdkHome: String?
59
    
60
    /** Target JVM version (1.8, 9, 10, 11, 15, 17, 18, 19, 20, 21) */
61
    var jvmTarget: String?
62
    
63
    /** Module name for the compilation */
64
    var moduleName: String?
65
    
66
    /** Disable standard script definitions */
67
    var disableStandardScript: Boolean
68
    
69
    /** Enable script mode compilation */
70
    var script: Boolean
71
    
72
    /** Compile and execute script expression */
73
    var expression: String?
74
    
75
    /** Enable REPL mode */
76
    var repl: Boolean
77
    
78
    /** Build file for module compilation */
79
    var buildFile: String?
80
    
81
    /** Java module path */
82
    var javaModulePath: String?
83
    
84
    /** Add modules to compile */
85
    var addModules: String?
86
    
87
    /** No JDK class path roots */
88
    var noJdk: Boolean
89
    
90
    /** No standard library */
91
    var noStdlib: Boolean
92
    
93
    /** No reflection */
94
    var noReflect: Boolean
95
    
96
    /** Emit JVM debug information */
97
    var jvmDebug: Boolean
98
    
99
    /** Use old class file format with JVM target */
100
    var useOldClassFiles: Boolean
101
}
102
```
103

104
### JVM Configuration Keys
105

106
JVM-specific configuration keys for fine-grained compilation control.
107

108
```kotlin { .api }
109
object JVMConfigurationKeys {
110
    /** Output directory for .class files */
111
    val OUTPUT_DIRECTORY: CompilerConfigurationKey<File>
112
    
113
    /** Output JAR file */
114
    val OUTPUT_JAR: CompilerConfigurationKey<File>
115
    
116
    /** Classpath entries (directories and JARs) */
117
    val CLASSPATH_ROOTS: CompilerConfigurationKey<List<File>>
118
    
119
    /** Include Kotlin runtime in output */
120
    val INCLUDE_RUNTIME: CompilerConfigurationKey<Boolean>
121
    
122
    /** JDK home directory */
123
    val JDK_HOME: CompilerConfigurationKey<File>
124
    
125
    /** JVM target version */
126
    val JVM_TARGET: CompilerConfigurationKey<JvmTarget>
127
    
128
    /** Disable standard script definition */
129
    val DISABLE_STANDARD_SCRIPT_DEFINITION: CompilerConfigurationKey<Boolean>
130
    
131
    /** Retain output in memory */
132
    val RETAIN_OUTPUT_IN_MEMORY: CompilerConfigurationKey<Boolean>
133
    
134
    /** Disable optimization */
135
    val DISABLE_OPTIMIZATION: CompilerConfigurationKey<Boolean>
136
}
137
```
138

139
### JVM Target Versions
140

141
Supported JVM bytecode target versions with corresponding class file format versions.
142

143
```kotlin { .api }
144
enum class JvmTarget(
145
    val majorVersion: Int,
146
    val description: String
147
) {
148
    JVM_1_8(52, "1.8"),
149
    JVM_9(53, "9"), 
150
    JVM_10(54, "10"),
151
    JVM_11(55, "11"),
152
    JVM_15(59, "15"),
153
    JVM_17(61, "17"),
154
    JVM_18(62, "18"),
155
    JVM_19(63, "19"),
156
    JVM_20(64, "20"),
157
    JVM_21(65, "21");
158
    
159
    companion object {
160
        val DEFAULT: JvmTarget
161
        fun fromString(string: String): JvmTarget?
162
    }
163
}
164
```
165

166
### Bytecode Compilation
167

168
Core bytecode compilation functionality transforming Kotlin IR to JVM bytecode.
169

170
```kotlin { .api }
171
/**
172
 * Main bytecode compilation entry point
173
 * Handles the complete pipeline from resolved program to bytecode
174
 */
175
object KotlinToJVMBytecodeCompiler {
176
    /**
177
     * Compile Kotlin sources to JVM bytecode
178
     * 
179
     * @param environment Kotlin compilation environment
180
     * @param configuration Compiler configuration
181
     * @param chunk Module chunk to compile
182
     * @return Compilation result with generated files
183
     */
184
    fun compileModules(
185
        environment: KotlinCoreEnvironment,
186
        configuration: CompilerConfiguration,
187
        chunk: ModuleChunk
188
    ): Boolean
189
    
190
    /**
191
     * Generate class files from analysis result
192
     * 
193
     * @param environment Compilation environment
194
     * @param analysisResult Frontend analysis result
195
     * @param files Source files to compile
196
     * @return Success status
197
     */
198
    fun generateClassFiles(
199
        environment: KotlinCoreEnvironment,
200
        analysisResult: AnalysisResult,
201
        files: Collection<KtFile>
202
    ): Boolean
203
}
204
```
205

206
## Usage Examples
207

208
### Basic JVM Compilation
209

210
```kotlin
211
import org.jetbrains.kotlin.cli.jvm.K2JVMCompiler
212
import org.jetbrains.kotlin.cli.common.arguments.K2JVMCompilerArguments
213
import org.jetbrains.kotlin.cli.common.ExitCode
214

215
// Configure compilation arguments
216
val args = K2JVMCompilerArguments().apply {
217
    // Source files to compile
218
    freeArgs = listOf(
219
        "src/main/kotlin/Main.kt",
220
        "src/main/kotlin/Utils.kt"
221
    )
222
    
223
    // Output directory
224
    destination = "build/classes/kotlin/main"
225
    
226
    // Classpath including dependencies
227
    classpath = listOf(
228
        "lib/kotlin-stdlib-1.9.0.jar",
229
        "lib/my-dependency.jar"
230
    ).joinToString(File.pathSeparator)
231
    
232
    // JVM target version
233
    jvmTarget = "11"
234
    
235
    // Module name
236
    moduleName = "my-app"
237
}
238

239
// Create and execute compiler
240
val compiler = K2JVMCompiler()
241
val exitCode = compiler.exec(System.err, Services.EMPTY, args)
242

243
when (exitCode) {
244
    ExitCode.OK -> println("Compilation successful")
245
    ExitCode.COMPILATION_ERROR -> println("Compilation failed")
246
    else -> println("Internal error: $exitCode")
247
}
248
```
249

250
### JAR File Generation
251

252
```kotlin
253
val args = K2JVMCompilerArguments().apply {
254
    freeArgs = listOf("src/")
255
    jar = "build/libs/my-app.jar"
256
    includeRuntime = true
257
    jvmTarget = "1.8"
258
    
259
    // Include manifest
260
    manifestMain = "com.example.MainKt"
261
}
262

263
val compiler = K2JVMCompiler()
264
val result = compiler.exec(System.err, Services.EMPTY, args)
265
```
266

267
### Script Compilation and Execution
268

269
```kotlin
270
val args = K2JVMCompilerArguments().apply {
271
    script = true
272
    freeArgs = listOf("script.kts")
273
    classpath = "lib/kotlin-stdlib.jar"
274
}
275

276
val compiler = K2JVMCompiler()
277
compiler.exec(System.err, Services.EMPTY, args)
278
```
279

280
### Programmatic Configuration
281

282
```kotlin
283
import org.jetbrains.kotlin.cli.jvm.compiler.KotlinCoreEnvironment
284
import org.jetbrains.kotlin.config.CompilerConfiguration
285
import org.jetbrains.kotlin.config.JVMConfigurationKeys
286
import org.jetbrains.kotlin.config.CommonConfigurationKeys
287
import java.io.File
288

289
// Create configuration
290
val configuration = CompilerConfiguration().apply {
291
    put(JVMConfigurationKeys.OUTPUT_DIRECTORY, File("build/classes"))
292
    put(JVMConfigurationKeys.JVM_TARGET, JvmTarget.JVM_11)
293
    put(CommonConfigurationKeys.MODULE_NAME, "my-module")
294
    put(JVMConfigurationKeys.CLASSPATH_ROOTS, listOf(
295
        File("lib/kotlin-stdlib.jar"),
296
        File("lib/dependencies.jar")
297
    ))
298
}
299

300
// Create environment and compile
301
val environment = KotlinCoreEnvironment.createForProduction(
302
    parentDisposable = Disposer.newDisposable(),
303
    configuration = configuration,
304
    configFiles = EnvironmentConfigFiles.JVM_CONFIG_FILES
305
)
306

307
val success = KotlinToJVMBytecodeCompiler.compileModules(
308
    environment = environment,
309
    configuration = configuration,
310
    chunk = ModuleChunk(listOf(module))
311
)
312
```
313

314
## Error Handling
315

316
```kotlin { .api }
317
class CompilationException(message: String, cause: Throwable? = null) : RuntimeException(message, cause)
318

319
class CompileEnvironmentException(message: String) : Exception(message)
320
```
321

322
Common compilation errors and their handling:
323

324
- **COMPILATION_ERROR**: Source code compilation failures (syntax, type errors)
325
- **INTERNAL_ERROR**: Compiler internal failures or configuration issues  
326
- **SCRIPT_EXECUTION_ERROR**: Runtime errors during script execution
327
- **CompileEnvironmentException**: Environment setup failures (missing JDK, invalid paths)