Expected and actual declarations

You can define an Identity type and a factory function buildIdentity(), which is declared in the common source set and implemented differently in platform source sets:

1. In commonMain, declare a simple type and expect a factory function:

   package identity
   
   class Identity(val userName: String, val processID: Long)
   
   expect fun buildIdentity(): Identity

2. In the jvmMain source set, implement a solution using standard Java libraries:

   package identity
   
   import java.lang.System
   import java.lang.ProcessHandle
   
   actual fun buildIdentity() = Identity(
       System.getProperty("user.name") ?: "None",
       ProcessHandle.current().pid()
   )

3. In the nativeMain source set, implement a solution with POSIX using native dependencies:

   package identity
   
   import kotlinx.cinterop.toKString
   import platform.posix.getlogin
   import platform.posix.getpid
   
   actual fun buildIdentity() = Identity(
       getlogin()?.toKString() ?: "None",
       getpid().toLong()
   )

Here, platform functions return platform-specific Identity instances.

note

Starting with Kotlin 1.9.0, using getlogin() and getpid() functions requires the @OptIn annotation.

If the factory function becomes too large, consider using a common Identity interface and implementing it differently on different platforms.

A buildIdentity() factory function should return Identity, but this time, it's an object implementing the common interface:

1. In commonMain, define the Identity interface and the buildIdentity() factory function:

   // In the commonMain source set:
   expect fun buildIdentity(): Identity
   
   interface Identity {
       val userName: String
       val processID: Long
   }

2. Create platform-specific implementations of the interface without additional use of expected and actual declarations:

   // In the jvmMain source set:
   actual fun buildIdentity(): Identity = JVMIdentity()
   
   class JVMIdentity(
       override val userName: String = System.getProperty("user.name") ?: "none",
       override val processID: Long = ProcessHandle.current().pid()
   ) : Identity

   // In the nativeMain source set:
   actual fun buildIdentity(): Identity = NativeIdentity()
   
   class NativeIdentity(
       override val userName: String = getlogin()?.toKString() ?: "None",
       override val processID: Long = getpid().toLong()
   ) : Identity

These platform functions return platform-specific Identity instances, which are implemented as JVMIdentity and NativeIdentity platform types.

//In commonMain source set:
expect val identity: Identity

interface Identity {
    val userName: String
    val processID: Long
}

//In jvmMain source set:
actual val identity: Identity = JVMIdentity()

class JVMIdentity(
    override val userName: String = System.getProperty("user.name") ?: "none",
    override val processID: Long = ProcessHandle.current().pid()
) : Identity

//In nativeMain source set:
actual val identity: Identity = NativeIdentity()

class NativeIdentity(
    override val userName: String = getlogin()?.toKString() ?: "None",
    override val processID: Long = getpid().toLong()
) : Identity

// In the commonMain source set:
expect object IdentityBuilder {
    fun build(): Identity
}

class Identity(
    val userName: String,
    val processID: Long
)

// In the jvmMain source set:
actual object IdentityBuilder {
    actual fun build() = Identity(
        System.getProperty("user.name") ?: "none",
        ProcessHandle.current().pid()
    )
}

// In the nativeMain source set:
actual object IdentityBuilder {
    actual fun build() = Identity(
        getlogin()?.toKString() ?: "None",
        getpid().toLong()
    )
}

warning

Expected and actual classes are in Beta. They are almost stable, but migration steps may be required in the future. We'll do our best to minimize any further changes for you to make.

You can use expected and actual classes to implement the same solution:

// In the commonMain source set:
expect class Identity() {
    val userName: String
    val processID: Int
}

// In the jvmMain source set:
actual class Identity {
    actual val userName: String = System.getProperty("user.name") ?: "None"
    actual val processID: Long = ProcessHandle.current().pid()
}

// In the nativeMain source set:
actual class Identity {
    actual val userName: String = getlogin()?.toKString() ?: "None"
    actual val processID: Long = getpid().toLong()
}

You might have already seen this approach in demonstration materials. However, using classes in simple cases where interfaces would be sufficient is not recommended.

With interfaces, you don't limit your design to one implementation per target platform. Also, it's much easier to substitute a fake implementation in tests or provide multiple implementations on a single platform.

As a general rule, rely on standard language constructs wherever possible instead of using expected and actual declarations.

If you do decide to use expected and actual classes, the Kotlin compiler will warn you about the Beta status of the feature. To suppress this warning, add the following compiler option to your Gradle build file:

kotlin {
    compilerOptions {
        // Common compiler options applied to all Kotlin source sets
        freeCompilerArgs.add("-Xexpect-actual-classes")
    }
}

open class Identity {
    val login: String = System.getProperty("user.name") ?: "none"
    val pid: Long = ProcessHandle.current().pid()
}

// In commonMain of the framework codebase:
expect abstract class CommonIdentity() {
    val userName: String
    val processID: Long
    abstract val displayName: String
}

// In nativeMain of the framework codebase:
actual abstract class CommonIdentity {
    actual val userName = getlogin()?.toKString() ?: "None"
    actual val processID = getpid().toLong()
    actual abstract val displayName: String
}

// In jvmMain of the framework codebase:
actual abstract class CommonIdentity : Identity() {
    actual val userName = login
    actual val processID = pid
    actual abstract val displayName: String
}

// In commonMain of the users' codebase:
class MyCommonIdentity : CommonIdentity() {
    override val displayName = "Admin"
}

The implementation of an actual declaration does not have to be written from scratch. It can be an existing type, such as a class provided by a third-party library.

You can use this type as long as it meets all the requirements associated with the expected declaration. For example, consider these two expected declarations:

expect enum class Month {
    JANUARY, FEBRUARY, MARCH, APRIL, MAY, JUNE, JULY,
    AUGUST, SEPTEMBER, OCTOBER, NOVEMBER, DECEMBER
}

expect class MyDate {
    fun getYear(): Int
    fun getMonth(): Month
    fun getDayOfMonth(): Int
}

Within a JVM module, the java.time.Month enum can be used to implement the first expected declaration and the java.time.LocalDate class to implement the second. However, there's no way to add the actual keyword directly to these types.

Instead, you can use type aliases to connect the expected declarations and the platform-specific types:

actual typealias Month = java.time.Month
actual typealias MyDate = java.time.LocalDate

In this case, define the typealias declaration in the same package as the expected declaration and create the referred class elsewhere.

note

Since the LocalDate type uses the Month enum, you need to declare both of them as expected classes in the common code.

You can make actual implementations more visible than the corresponding expected declaration. This is useful if you don't want to expose your API as public for common clients.

Currently, the Kotlin compiler issues an error in the case of visibility changes. You can suppress this error by applying @Suppress("ACTUAL_WITHOUT_EXPECT") to the actual type alias declaration. Starting with Kotlin 2.0, this limitation will not apply.

For example, if you declare the following expected declaration in the common source set:

internal expect class Messenger {
    fun sendMessage(message: String)
}

You can use the following actual implementation in a platform-specific source set as well:

@Suppress("ACTUAL_WITHOUT_EXPECT")
public actual typealias Messenger = MyMessenger

Here, an internal expected class has an actual implementation with an existing public MyMessenger using type aliases.

When an enumeration is declared with expect in the common source set, each platform module should have a corresponding actual declaration. These declarations must contain the same enum constants, but they can also have additional constants.

This is useful when you actualize an expected enum with an existing platform enum. For example, consider the following enumeration in the common source set:

// In the commonMain source set:
expect enum class Department { IT, HR, Sales }

When you provide an actual declaration for Department in platform source sets, you can add extra constants:

// In the jvmMain source set:
actual enum class Department { IT, HR, Sales, Legal }

// In the nativeMain source set:
actual enum class Department { IT, HR, Sales, Marketing }

However, in this case, these extra constants in the platform source sets won't match with those in the common code. Therefore, the compiler requires you to handle all additional cases.

The function that implements the when construction on Department requires an else clause:

// An else clause is required:
fun matchOnDepartment(dept: Department) {
    when (dept) {
        Department.IT -> println("The IT Department")
        Department.HR -> println("The HR Department")
        Department.Sales -> println("The Sales Department")
        else -> println("Some other department")
    }
}

Expected and actual declarations can be used with annotations. For example, you can declare an @XmlSerializable annotation, which must have a corresponding actual declaration in each platform source set:

@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
expect annotation class XmlSerializable()

@XmlSerializable
class Person(val name: String, val age: Int)

It might be helpful to reuse existing types on a particular platform. For example, on the JVM, you can define your annotation using the existing type from the JAXB specification:

import javax.xml.bind.annotation.XmlRootElement

actual typealias XmlSerializable = XmlRootElement

There is an additional consideration when using expect with annotation classes. Annotations are used to attach metadata to code and do not appear as types in signatures. It's not essential for an expected annotation to have an actual class on a platform where it's never required.

You only need to provide an actual declaration on platforms where the annotation is used. This behavior isn't enabled by default, and it requires the type to be marked with OptionalExpectation.

Take the @XmlSerializable annotation declared above and add OptionalExpectation:

@OptIn(ExperimentalMultiplatform::class)
@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.RUNTIME)
@OptionalExpectation
expect annotation class XmlSerializable()

If an actual declaration is missing on a platform where it's not required, the compiler won't generate an error.