Update README about using custom Compose Compiler

[igordmn]

No description provided.

[igordmn]

This PR should be merged only after 1.2.2 is released

[AlexeyTsvetkov]

I think it's better to use the exact version instead of "the next version"

[igordmn]

Fixed

[AlexeyTsvetkov]

I think it's better to use the exact version instead of "the next version"

[AlexeyTsvetkov]

garantied should be guaranteed

[igordmn]

Fixed

[AlexeyTsvetkov]

Compose Multiplatform uses Compose Compiler to compile Compose code, and its version is strictly bound to the version of Kotlin.

This sentence repeats the word "Compose" a bit too often. At the same time, the whole paragraph might be a bit confusing, when someone does not understand how the Gradle plugin and the compiler plugin relate to each other.

By default it chooses

By default needs a comma , in the beginning of a sentence (By default,). Also, it might be confusing, what it refers to.

chooses appropriate .. version by the Kotlin version applied to the Gradle project`.

I'm not sure about articles here. appropriate definitely needs one. Also, I'm not sure, why the Kotlin version and the Gradle project?

My suggestion:

The compilation process of composable functions is handled by the Compose compiler plugin. Each release of the compiler plugin is strictly bound to a single version of the Kotlin compiler. Normally, the Gradle plugin chooses an appropriate version of the compiler plugin automatically. But there is a way to choose another version of Compose Compiler. For example, you can use Jetpack Compose Compiler published by Google.

[AlexeyTsvetkov]

First,

[igordmn]

Fixed

[AlexeyTsvetkov]

or you encounter errors

Seems like a very broad suggestion. Ideally, I would like to describe the specific issues, which might be solved by disabling the compatibility check.

[AlexeyTsvetkov]

I think we need a really big warning about this, so people would not try this for a new major version.

[igordmn]

or you encounter errors

It is about errors when you try Jetpack Compose Compiler.

There is no list of specific issues, which we can write here. We can encounter any errors in compile time and runtime, when we using a Jetpack Compose Compiler version that is not tested with Compose Multiplatform.

One of the recent examples - Jetpack Compose Compiler didn't work in the JS target. First we had a compilation error. We fixed that, but recently discovered a runtime error.

I think we need a really big warning about this

I added an additional note. Not sure that for major version of Kotlin we should write a separate warning. I wouldn't recommend overwriting compiler even for minor Kotlin's.

[AlexeyTsvetkov]

Can we just add suppressKotlinCompatibilityCheck property instead of very generic kotlinCompilerPluginArgs? I'm not sure that giving an ability to pass arbitrary arguments to the compiler plugin just for suppressing the check is worth it.

compose {
    kotlinCompilerPlugin.set(dependencies.compiler.forKotlin("1.7.20"))
    suppressKotlinCompatibilityCheck.set("1.7.21")
}

[igordmn]

The reason why I added support for arbitrary properties - because there are other useful properties besides suppressKotlinCompatibilityCheck, and I wouldn't want to modify code every time new properties/rules are added. For example, the useful metricsDestination property was added recently.

Keeping API under control is usually good practice, and allows avoiding many issues, but here we explicitly tell that we use a separate entity (Compose Compiler), and so we can support configuration of it bypassing our API, and reusing its own way of configuration (via properties).

Besides that, we should emphasis that we configure the applied Compose Compiler. Without specifying a custom Compose Compiler, arguments don't make sense, because Compiler can be different for each Kotlin and doesn't have required arguments. In case suppressKotlinCompatibilityCheck we have another problem - it won't be used until we set a custom compiler.

So, if we really don't want to pass arbitrary properties (but I still prefer to pass because it is easier to maintain), we should keep somehow connection to Compose Compiler. The alternative are:

compose {
    kotlinCompilerPlugin(dependencies.compiler.forKotlin("1.7.20")) {
        suppressKotlinCompatibilityCheck = "1.7.21"
    }
}

// and we can still write
compose {
    kotlinCompilerPlugin("androidx.compose.compiler:compiler:1.4.0-alpha02")
}

(I am not sure about the style guidelines, maybe it can be written better)

or

compose {
    kotlinCompilerPlugin.set(dependencies.compiler.forKotlin("1.7.20"))
    kotlinCompilerPluginArgs {
        suppressKotlinCompatibilityCheck.set("1.7.21")
    }
}

[igordmn]

The alternative are

It seems that they won't work well. For example, we have the property metricsDestination. It only makes sense for the latest Compose Compiler, and will be ignored in the previous versions.

[AlexeyTsvetkov]

I'm not sure this sentence explains anything. I mean it's obvious, that suppressKotlinVersionCompatibilityCheck disables the check. However, it might be not obvious why it needs a version.

[igordmn]

However, it might be not obvious why it needs a version.

Is it better in the new version of the doc?