|
| 1 | +[//]: # (title: Compose compiler options DSL) |
| 2 | + |
| 3 | +The Compose compiler Gradle plugin offers a DSL for various compiler options. |
| 4 | +You can use it to configure the compiler in the `composeCompiler {}` block of the `build.gradle.kts` file for the module |
| 5 | +you're applying the plugin to. |
| 6 | + |
| 7 | +There are two kinds of options you can specify: |
| 8 | + |
| 9 | +* General compiler settings. |
| 10 | +* Feature flags that enable or disable new and experimental features, which should eventually become part of the baseline. |
| 11 | + |
| 12 | +Here's an example configuration: |
| 13 | + |
| 14 | +```kotlin |
| 15 | +composeCompiler { |
| 16 | + includeSourceInformation = true |
| 17 | + |
| 18 | + featureFlags = setOf( |
| 19 | + ComposeFeatureFlag.StrongSkipping.disabled(), |
| 20 | + ComposeFeatureFlag.OptimizeNonSkippingGroups |
| 21 | + ) |
| 22 | +} |
| 23 | +``` |
| 24 | + |
| 25 | +> The Gradle plugin provides defaults for several Compose compiler options that were only specified manually before. |
| 26 | +> If you have any of them set up with `freeCompilerArgs`, for example, Gradle will report a duplicate options error. |
| 27 | +> |
| 28 | +{style="warning"} |
| 29 | + |
| 30 | +## General settings |
| 31 | + |
| 32 | +### generateFunctionKeyMetaClasses |
| 33 | + |
| 34 | +**Type**: `Property<Boolean>` |
| 35 | + |
| 36 | +**Default**: `false` |
| 37 | + |
| 38 | +If `true`, generate function key meta classes with annotations indicating the functions and their group keys. |
| 39 | + |
| 40 | +### includeSourceInformation |
| 41 | + |
| 42 | +**Type**: `Property<Boolean>` |
| 43 | + |
| 44 | +**Default**: `false` (`true` for Android) |
| 45 | + |
| 46 | +If `true`, include source information in generated code. |
| 47 | + |
| 48 | +Records source information that can be used for tooling to determine the source location of the corresponding composable function. |
| 49 | +This option does not affect the presence of symbols or line information normally added by the Kotlin compiler; |
| 50 | +it only controls source information added by the Compose compiler. |
| 51 | + |
| 52 | +### metricsDestination |
| 53 | + |
| 54 | +**Type**: `DirectoryProperty` |
| 55 | + |
| 56 | +When a directory is specified, the Compose compiler will use the directory to dump [compiler metrics](https://github.com/JetBrains/kotlin/blob/master/plugins/compose/design/compiler-metrics.md#reports-breakdown). |
| 57 | +They can be useful for debugging and optimizing your application's runtime performance: |
| 58 | +the metrics show which composable functions are skippable, restartable, read-only, and so on. |
| 59 | + |
| 60 | +The [reportsDestination](#reportsdestination) option allows dumping descriptive reports as well. |
| 61 | + |
| 62 | +For a deep dive into the compiler metrics, see this [Composable metrics blog post](https://chrisbanes.me/posts/composable-metrics/). |
| 63 | + |
| 64 | +### reportsDestination |
| 65 | + |
| 66 | +**Type**: `DirectoryProperty` |
| 67 | + |
| 68 | +When a directory is specified, the Compose compiler will use the directory to dump [compiler metrics reports](https://github.com/JetBrains/kotlin/blob/master/plugins/compose/design/compiler-metrics.md#reports-breakdown). |
| 69 | +They can be useful for optimizing your application's runtime performance: |
| 70 | +the reports show which composable functions are skippable, restartable, read-only, and so on. |
| 71 | + |
| 72 | +The [metricsDestination](#metricsdestination) option allows dumping raw metrics. |
| 73 | + |
| 74 | +For a deep dive into the compiler metrics, see this [Composable metrics blog post](https://chrisbanes.me/posts/composable-metrics/). |
| 75 | + |
| 76 | +### stabilityConfigurationFile |
| 77 | + |
| 78 | +> _Deprecated_ in Kotlin 2.1.0-Beta1 in favor of [stabilityConfigurationFiles](#stabilityconfigurationfiles), |
| 79 | +> which allows using more than one stability configuration file. |
| 80 | +> |
| 81 | +{style="warning"} |
| 82 | + |
| 83 | +**Type**: `RegularFileProperty` |
| 84 | + |
| 85 | +A stability configuration file contains a list of classes, which should be considered stable. |
| 86 | +For details, see [Stability configuration file](https://developer.android.com/develop/ui/compose/performance/stability/fix#configuration-file) |
| 87 | +in the Jetpack Compose documentation. |
| 88 | + |
| 89 | +### stabilityConfigurationFiles |
| 90 | + |
| 91 | +**Type**: `ListProperty<RegularFile>` |
| 92 | + |
| 93 | +Stability configuration files to be used for the current module. |
| 94 | + |
| 95 | +Stability configuration files contain a list of classes that should be considered stable by the compiler. |
| 96 | +For details, see [Stability configuration file](https://developer.android.com/develop/ui/compose/performance/stability/fix#configuration-file) |
| 97 | +in the Jetpack Compose documentation. |
| 98 | + |
| 99 | +Here's an example of specifying paths to several files: |
| 100 | + |
| 101 | +```kotlin |
| 102 | +composeCompiler { |
| 103 | + stabilityConfigurationFiles.addAll( |
| 104 | + project.layout.projectDirectory.file("configuration-file1.conf"), |
| 105 | + project.layout.projectDirectory.file("configuration-file2.conf"), |
| 106 | + ) |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +### includeTraceMarkers |
| 111 | + |
| 112 | +**Type**: `Property<Boolean>` |
| 113 | + |
| 114 | +**Default**: `true` |
| 115 | + |
| 116 | +If `true`, include composition trace markers in the generated code. |
| 117 | + |
| 118 | +The Compose compiler can inject additional tracing information into the bytecode, which allows it to show composable functions |
| 119 | +in the Android Studio system trace profiler. |
| 120 | + |
| 121 | +For details, see this [Android Developers blog post](https://medium.com/androiddevelopers/jetpack-compose-composition-tracing-9ec2b3aea535). |
| 122 | + |
| 123 | +### targetKotlinPlatforms |
| 124 | + |
| 125 | +**Type**: `SetProperty<KotlinPlatformType>` |
| 126 | + |
| 127 | +Indicates Kotlin platforms to which the Compose compiler Gradle plugin should be applied. |
| 128 | +By default, the plugin is applied to all Kotlin platforms. |
| 129 | + |
| 130 | +To enable only one specific Kotlin platform, for example, Kotlin/JVM: |
| 131 | + |
| 132 | +```kotlin |
| 133 | +composeCompiler { |
| 134 | + targetKotlinPlatforms.set(setOf(KotlinPlatformType.jvm)) |
| 135 | +} |
| 136 | +``` |
| 137 | + |
| 138 | +To disable the Gradle plugin for one or more Kotlin platforms, for example, Kotlin/Native and Kotlin/JS: |
| 139 | + |
| 140 | +```kotlin |
| 141 | +composeCompiler { |
| 142 | + targetKotlinPlatforms.set( |
| 143 | + KotlinPlatformType.values() |
| 144 | + .filterNot { it == KotlinPlatformType.native || it == KotlinPlatformType.js } |
| 145 | + .asIterable() |
| 146 | + ) |
| 147 | +} |
| 148 | +``` |
| 149 | + |
| 150 | +## Feature flags |
| 151 | + |
| 152 | +Feature flags are organized into a separate set to minimize changes to top-level properties as new flags |
| 153 | +are continuously rolled out and deprecated. |
| 154 | + |
| 155 | +To enable a feature flag that is disabled by default, specify it in the set, for example: |
| 156 | + |
| 157 | +```kotlin |
| 158 | +featureFlags = setOf(ComposeFeatureFlag.OptimizeNonSkippingGroups) |
| 159 | +``` |
| 160 | + |
| 161 | +To disable a feature flag that is enabled by default, call the `disabled()` function on it, for example: |
| 162 | + |
| 163 | +```kotlin |
| 164 | +featureFlags = setOf(ComposeFeatureFlag.StrongSkipping.disabled()) |
| 165 | +``` |
| 166 | + |
| 167 | +If you are configuring the Compose compiler directly, use the following syntax to pass feature flags to it: |
| 168 | + |
| 169 | +```none |
| 170 | +-P plugin:androidx.compose.compiler.plugins.kotlin:featureFlag=<flag name> |
| 171 | +``` |
| 172 | + |
| 173 | +### IntrinsicRemember |
| 174 | + |
| 175 | +**Default**: enabled |
| 176 | + |
| 177 | +If enabled, turns on intrinsic remember performance optimization. |
| 178 | + |
| 179 | +Intrinsic remember is an optimization mode that inlines `remember` invocations and, where possible, replaces `.equals()` comparisons for keys with comparisons of the `$changed` meta parameter. |
| 180 | +This results in fewer slots being used and fewer comparisons being made at runtime. |
| 181 | + |
| 182 | +### OptimizeNonSkippingGroups |
| 183 | + |
| 184 | +**Default**: disabled |
| 185 | + |
| 186 | +If enabled, remove groups around non-skipping composable functions. |
| 187 | + |
| 188 | +This optimization improves the runtime performance of your application by skipping |
| 189 | +unnecessary groups around composables which do not skip (and thus do not require a group). |
| 190 | +This optimization will remove the groups, for example, around functions explicitly marked as `@NonSkippableComposable` |
| 191 | +and functions that are implicitly not skippable (inline functions and functions that return a non-`Unit` value such as `remember`). |
| 192 | + |
| 193 | +> This feature is considered [Experimental](components-stability.md#stability-levels-explained) and is disabled by default. |
| 194 | +> |
| 195 | +{style="warning"} |
| 196 | + |
| 197 | +### StrongSkipping |
| 198 | + |
| 199 | +**Default**: enabled |
| 200 | + |
| 201 | +If enabled, turns on strong skipping mode. |
| 202 | + |
| 203 | +Strong skipping mode improves the runtime performance of your application by applying optimizations previously reserved only for stable values of composable functions whose parameters haven't changed. |
| 204 | +For example, composables with unstable parameters become skippable, and lambdas with unstable captures are memoized. |
| 205 | + |
| 206 | +For details, see the [description of strong skipping mode](https://github.com/JetBrains/kotlin/blob/master/plugins/compose/design/strong-skipping.md) |
| 207 | +in the Kotlin GitHub repository. |
0 commit comments