[KT-48068] Add opt-in support for NSEnum for Kotlin Native iOS via an annotation

kotlin-native/backend.native/compiler/ir/backend.native/src/org/jetbrains/kotlin/backend/konan/llvm/objcexport/ObjCExportCodeGenerator.kt

@@ -20,6 +20,7 @@ import org.jetbrains.kotlin.backend.konan.llvm.objcexport.KotlinToObjCMethodAdap
 import org.jetbrains.kotlin.backend.konan.lower.getLoweredConstructorFunction
 import org.jetbrains.kotlin.backend.konan.lower.getObjectClassInstanceFunction
 import org.jetbrains.kotlin.backend.konan.objcexport.*
+import org.jetbrains.kotlin.backend.konan.objcexport.ObjCMethodSpec.BaseMethod
 import org.jetbrains.kotlin.descriptors.ClassKind
 import org.jetbrains.kotlin.descriptors.Modality
 import org.jetbrains.kotlin.incremental.components.NoLookupLocation
@@ -1375,6 +1376,15 @@ private fun ObjCExportCodeGenerator.createArrayConstructorAdapter(
     return objCToKotlinMethodAdapter(selectorName, methodBridge, imp)
 }
 
+private fun ObjCExportCodeGenerator.createNSEnumAdapter(
+        symbol: IrSimpleFunctionSymbol,
+        methodBridge: MethodBridge,
+        selectorName: String
+): ObjCToKotlinMethodAdapter {
+    val imp = generateObjCImp(symbol.owner, symbol.owner.getLowered<IrSimpleFunction>(), methodBridge)
+    return objCToKotlinMethodAdapter(selectorName, methodBridge, imp)
+}
+
 private fun ObjCExportCodeGenerator.vtableIndex(irFunction: IrSimpleFunction): Int? {
     assert(irFunction.isOverridable)
     val irClass = irFunction.parentAsClass
@@ -1430,6 +1440,9 @@ private fun ObjCExportCodeGenerator.createTypeAdapter(
             is ObjCInitMethodForKotlinConstructor -> {
                 adapters += createConstructorAdapter(it.baseMethod)
             }
+            is ObjCGetterForNSEnumType -> {
+                adapters += createNSEnumAdapter(it.symbol, it.bridge, it. selector)
+            }
             is ObjCFactoryMethodForKotlinArrayConstructor -> {
                 classAdapters += createArrayConstructorAdapter(it.baseMethod)
             }

kotlin-native/backend.native/compiler/ir/backend.native/src/org/jetbrains/kotlin/backend/konan/objcexport/ObjCExportCodeSpec.kt

@@ -13,7 +13,6 @@ import org.jetbrains.kotlin.builtins.KotlinBuiltIns
 import org.jetbrains.kotlin.descriptors.*
 import org.jetbrains.kotlin.ir.ObsoleteDescriptorBasedAPI
 import org.jetbrains.kotlin.ir.symbols.*
-import org.jetbrains.kotlin.ir.util.IdSignature
 import org.jetbrains.kotlin.ir.util.SymbolTable
 import org.jetbrains.kotlin.resolve.descriptorUtil.getSuperClassNotAny
 import java.io.PrintStream
@@ -89,6 +88,14 @@ internal fun ObjCExportedInterface.createCodeSpec(symbolTable: SymbolTable): Obj
             }
 
             if (descriptor.kind == ClassKind.ENUM_CLASS) {
+                if (namer.getNSEnumFunctionTypeName(descriptor) != null) {
+                    val superClass = descriptor.getSuperClassNotAny()!!  // ordinal is declared in KotlinEnum
+                    val ordinalDescriptor = superClass.contributedMethods.first { it.name.asString() == "<get-ordinal>" }
+                    val symbol = symbolTable.descriptorExtension.referenceSimpleFunction(ordinalDescriptor)
+                    val bridge = mapper.bridgeMethod(ordinalDescriptor)
+                    methods += ObjCGetterForNSEnumType(symbol, bridge, "nsEnum")
+                }
+
                 descriptor.enumEntries.mapTo(methods) {
                     ObjCGetterForKotlinEnumEntry(symbolTable.descriptorExtension.referenceEnumEntry(it), namer.getEnumEntrySelector(it))
                 }
@@ -160,6 +167,7 @@ internal fun ObjCExportCodeSpec.dumpSelectorToSignatureMapping(path: String) {
             is ObjCClassMethodForKotlinEnumValuesOrEntries -> false
             is ObjCGetterForKotlinEnumEntry -> false
             is ObjCGetterForObjectInstance -> false
+            is ObjCGetterForNSEnumType -> true
         }
 
         fun ObjCMethodSpec.getMapping(objcClass: String): String? = when (this) {
@@ -170,6 +178,7 @@ internal fun ObjCExportCodeSpec.dumpSelectorToSignatureMapping(path: String) {
             is ObjCInitMethodForKotlinConstructor -> "$objcClass.${baseMethod.selector},${baseMethod.symbol.signature}"
             is ObjCKotlinThrowableAsErrorMethod -> null
             is ObjCMethodForKotlinMethod -> "$objcClass.${baseMethod.selector},${baseMethod.symbol.signature}"
+            is ObjCGetterForNSEnumType -> "$objcClass.$selector,${symbol.signature}"
         }
         out.println("\n# Instance methods mapping")
         for (type in types) {
@@ -224,6 +233,17 @@ internal class ObjCGetterForKotlinEnumEntry(
             "ObjC spec of getter `$selector` for `$irEnumEntrySymbol`"
 }
 
+
+internal class ObjCGetterForNSEnumType(
+        val symbol: IrSimpleFunctionSymbol,
+        val bridge: MethodBridge,
+        val selector: String,
+) : ObjCMethodSpec() {
+    override fun toString(): String =
+            "ObjC spec of $selector for $symbol"
+}
+
+
 internal class ObjCClassMethodForKotlinEnumValuesOrEntries(
         val valuesFunctionSymbol: IrFunctionSymbol,
         val selector: String

kotlin-native/runtime/src/main/kotlin/kotlin/native/Annotations.kt

@@ -6,6 +6,7 @@
 package kotlin.native
 
 import kotlin.experimental.ExperimentalNativeApi
+import kotlin.experimental.ExperimentalObjCEnum
 import kotlin.experimental.ExperimentalObjCName
 import kotlin.experimental.ExperimentalObjCRefinement
 
@@ -116,6 +117,19 @@ public actual annotation class CName(actual val externName: String = "", actual
 @SinceKotlin("1.8")
 public actual annotation class ObjCName(actual val name: String = "", actual val swiftName: String = "", actual val exact: Boolean = false)
 
+/**
+ * Instructs the Kotlin compiler to generate a NS_ENUM typedef for the annotated enum class. The name of the generated type will
+ * be the name of the enum type with "NSEnum" appended. This name can be overridden with the "name" parameter, which is treated
+ * as an exact name. The enum literals will be prefixed with the type name, as they live in a global namespace.
+ * Swift naming will automatically remove these prefixes. The native values are accessible via the "nsEnum" property.
+ */
+@Target(AnnotationTarget.CLASS)
+@Retention(AnnotationRetention.BINARY)
+@MustBeDocumented
+@ExperimentalObjCEnum
+@SinceKotlin("2.3")
+public actual annotation class ObjCEnum(actual val name: String = "")
+
 /**
  * Meta-annotation that instructs the Kotlin compiler to remove the annotated class, function or property from the public Objective-C API.
  *

libraries/stdlib/src/kotlin/annotations/NativeAnnotations.kt

@@ -6,6 +6,7 @@
 package kotlin.native
 
 import kotlin.experimental.ExperimentalNativeApi
+import kotlin.experimental.ExperimentalObjCEnum
 import kotlin.experimental.ExperimentalObjCName
 import kotlin.experimental.ExperimentalObjCRefinement
 
@@ -71,6 +72,22 @@ public expect annotation class FreezingIsDeprecated
 @SinceKotlin("1.8")
 public expect annotation class ObjCName(val name: String = "", val swiftName: String = "", val exact: Boolean = false)
 
+/**
+ * Instructs the Kotlin compiler to generate a NS_ENUM typedef for the annotated enum class. The name of the generated type will
+ * be the name of the enum type with "NSEnum" appended. This name can be overridden with the "name" parameter, which is treated
+ * as an exact name. The enum literals will be prefixed with the type name, as they live in a global namespace.
+ * Swift naming will automatically remove these disambiguation prefixes. The native values are accessible via the "nsEnum" property.
+ */
+@Target(
+    AnnotationTarget.CLASS,
+)
+@Retention(AnnotationRetention.BINARY)
+@MustBeDocumented
+@OptionalExpectation
+@ExperimentalObjCEnum
+@SinceKotlin("2.2.21")
+public expect annotation class ObjCEnum(val name: String = "")
+
 /**
  * Meta-annotation that instructs the Kotlin compiler to remove the annotated class, function or property from the public Objective-C API.
  *

libraries/stdlib/src/kotlin/experimental/ExperimentalObjCEnum.kt

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2010-2022 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kotlin.experimental
+
+/**
+ * This annotation marks the experimental [ObjCEnum][kotlin.native.ObjCEnum] annotation.
+ */
+@RequiresOptIn
+@Target(AnnotationTarget.ANNOTATION_CLASS)
+@Retention(AnnotationRetention.BINARY)
+@MustBeDocumented
+@SinceKotlin("2.2.21")
+public annotation class ExperimentalObjCEnum

libraries/tools/binary-compatibility-validator/klib-public-api/kotlin-stdlib.api

@@ -53,6 +53,10 @@ open annotation class kotlin.experimental/ExperimentalNativeApi : kotlin/Annotat
     constructor <init>() // kotlin.experimental/ExperimentalNativeApi.<init>|<init>(){}[0]
 }
 
+open annotation class kotlin.experimental/ExperimentalObjCEnum : kotlin/Annotation { // kotlin.experimental/ExperimentalObjCEnum|null[0]
+    constructor <init>() // kotlin.experimental/ExperimentalObjCEnum.<init>|<init>(){}[0]
+}
+
 open annotation class kotlin.experimental/ExperimentalObjCName : kotlin/Annotation { // kotlin.experimental/ExperimentalObjCName|null[0]
     constructor <init>() // kotlin.experimental/ExperimentalObjCName.<init>|<init>(){}[0]
 }
@@ -9829,6 +9833,14 @@ open annotation class kotlin.native/NoInline : kotlin/Annotation { // kotlin.nat
     constructor <init>() // kotlin.native/NoInline.<init>|<init>(){}[0]
 }
 
+// Targets: [native]
+open annotation class kotlin.native/ObjCEnum : kotlin/Annotation { // kotlin.native/ObjCEnum|null[0]
+    constructor <init>(kotlin/String = ...) // kotlin.native/ObjCEnum.<init>|<init>(kotlin.String){}[0]
+
+    final val name // kotlin.native/ObjCEnum.name|{}name[0]
+        final fun <get-name>(): kotlin/String // kotlin.native/ObjCEnum.name.<get-name>|<get-name>(){}[0]
+}
+
 // Targets: [native]
 open annotation class kotlin.native/ObjCName : kotlin/Annotation { // kotlin.native/ObjCName|null[0]
     constructor <init>(kotlin/String = ..., kotlin/String = ..., kotlin/Boolean = ...) // kotlin.native/ObjCName.<init>|<init>(kotlin.String;kotlin.String;kotlin.Boolean){}[0]
@@ -13739,6 +13751,14 @@ open annotation class kotlin.native/HidesFromObjC : kotlin/Annotation { // kotli
     constructor <init>() // kotlin.native/HidesFromObjC.<init>|<init>(){}[1]
 }
 
+// Targets: [js, wasmJs, wasmWasi]
+open annotation class kotlin.native/ObjCEnum : kotlin/Annotation { // kotlin.native/ObjCEnum|null[1]
+    constructor <init>(kotlin/String = ...) // kotlin.native/ObjCEnum.<init>|<init>(kotlin.String){}[1]
+
+    final val name // kotlin.native/ObjCEnum.name|{}name[1]
+        final fun <get-name>(): kotlin/String // kotlin.native/ObjCEnum.name.<get-name>|<get-name>(){}[1]
+}
+
 // Targets: [js, wasmJs, wasmWasi]
 open annotation class kotlin.native/ObjCName : kotlin/Annotation { // kotlin.native/ObjCName|null[1]
     constructor <init>(kotlin/String = ..., kotlin/String = ..., kotlin/Boolean = ...) // kotlin.native/ObjCName.<init>|<init>(kotlin.String;kotlin.String;kotlin.Boolean){}[1]

libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt

@@ -3257,6 +3257,9 @@ public abstract interface annotation class kotlin/experimental/ExpectRefinement
 public abstract interface annotation class kotlin/experimental/ExperimentalNativeApi : java/lang/annotation/Annotation {
 }
 
+public abstract interface annotation class kotlin/experimental/ExperimentalObjCEnum : java/lang/annotation/Annotation {
+}
+
 public abstract interface annotation class kotlin/experimental/ExperimentalObjCName : java/lang/annotation/Annotation {
 }
 

native/base/src/main/kotlin/org/jetbrains/kotlin/backend/konan/KonanFqNames.kt

@@ -38,6 +38,7 @@ object KonanFqNames {
     val eagerInitialization = FqName("kotlin.native.EagerInitialization")
     val noReorderFields = FqName("kotlin.native.internal.NoReorderFields")
     val objCName = FqName("kotlin.native.ObjCName")
+    val objCEnum = FqName("kotlin.native.ObjCEnum")
     val hidesFromObjC = FqName("kotlin.native.HidesFromObjC")
     val refinesInSwift = FqName("kotlin.native.RefinesInSwift")
     val shouldRefineInSwift = FqName("kotlin.native.ShouldRefineInSwift")

native/native.tests/testData/framework/objcexport/nativeEnum.kt

@@ -0,0 +1,10 @@
+package nativeEnum
+
+import kotlin.native.ObjCEnum
+import kotlin.experimental.ExperimentalObjCEnum
+
+@OptIn(kotlin.experimental.ExperimentalObjCEnum::class)
+@ObjCEnum("OBJCFoo")
+enum class MyKotlinEnum {
+    ALPHA, BAR_FOO, COPY
+}

native/native.tests/testData/framework/objcexport/nativeEnum.swift

@@ -0,0 +1,21 @@
+import Kt
+
+
+private func testNativeEnumValues() throws {
+    let ktEnum = MyKotlinEnum.alpha
+    let nsEnum = ktEnum.nsEnum
+
+    switch(nsEnum) {
+        case .alpha: try assertEquals(actual: nsEnum, expected: ktEnum.nsEnum)
+        case .barFoo: try fail()
+        case .theCopy: try fail()
+    }
+}
+
+class NativeEnumTests : SimpleTestProvider {
+    override init() {
+        super.init()
+
+        test("TestNativeEnumValues", testNativeEnumValues)
+     }
+}

native/objcexport-header-generator/impl/analysis-api/src/org/jetbrains/kotlin/objcexport/TranslatedClass.kt

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2010-2025 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package org.jetbrains.kotlin.objcexport
+
+import org.jetbrains.kotlin.backend.konan.objcexport.ObjCClass
+import org.jetbrains.kotlin.backend.konan.objcexport.ObjCTopLevel
+
+class TranslatedClass(
+    val auxiliaryDeclarations: List<ObjCTopLevel>,
+    val objCClass: ObjCClass,
+)
+
+fun TranslatedClass(objCClass: ObjCClass?) = objCClass?.let { TranslatedClass(emptyList(), it) }
+

native/objcexport-header-generator/impl/analysis-api/src/org/jetbrains/kotlin/objcexport/analysisApiUtils/getObjCDocumentedAnnotations.kt

@@ -38,6 +38,7 @@ internal fun KaSession.getObjCDocumentedAnnotations(list: KaAnnotationList): Lis
 
 private val mustBeDocumentedAnnotationsStopList = setOf(
     StandardNames.FqNames.deprecated,
+    KonanFqNames.objCEnum,
     KonanFqNames.objCName,
-    KonanFqNames.shouldRefineInSwift
+    KonanFqNames.shouldRefineInSwift,
 )

native/objcexport-header-generator/impl/analysis-api/src/org/jetbrains/kotlin/objcexport/getNSEnumType.kt

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2010-2025 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package org.jetbrains.kotlin.objcexport
+
+import org.jetbrains.kotlin.analysis.api.annotations.KaAnnotationValue
+import org.jetbrains.kotlin.analysis.api.symbols.KaClassSymbol
+import org.jetbrains.kotlin.name.ClassId
+import org.jetbrains.kotlin.name.FqName
+
+/** Returns the NSEnum type for the given enum type if the corresponding annotation is set; null otherwise */
+fun ObjCExportContext.getNSEnumType(symbol: KaClassSymbol): String? {
+    val classId = ClassId(FqName("kotlin.native"), FqName("ObjCEnum"), false)
+    val annotation = symbol.annotations[classId].firstOrNull()
+    return if (annotation == null) {
+        null
+    } else if (annotation.arguments.isEmpty()) {
+        getObjCClassOrProtocolName(symbol).objCName + "NSEnum"
+    } else {
+        (annotation.arguments[0].expression as KaAnnotationValue.ConstantValue).value.value as String
+    }
+}

native/objcexport-header-generator/impl/analysis-api/src/org/jetbrains/kotlin/objcexport/translateEnumMembers.kt

@@ -78,7 +78,7 @@ private fun ObjCExportContext.getEnumEntriesProperty(symbol: KaClassSymbol): Obj
 /**
  * See K1 implementation as [org.jetbrains.kotlin.backend.konan.objcexport.ObjCExportNamerImpl.getEnumEntryName]
  */
-private fun ObjCExportContext.getEnumEntryName(symbol: KaEnumEntrySymbol, forSwift: Boolean): String {
+internal fun ObjCExportContext.getEnumEntryName(symbol: KaEnumEntrySymbol, forSwift: Boolean): String {
 
     val name = getObjCPropertyName(symbol).run {
         when {

native/objcexport-header-generator/impl/analysis-api/src/org/jetbrains/kotlin/objcexport/translateToNSEnum.kt

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2010-2025 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package org.jetbrains.kotlin.objcexport
+
+import org.jetbrains.kotlin.analysis.api.symbols.KaClassSymbol
+import org.jetbrains.kotlin.analysis.api.symbols.KaEnumEntrySymbol
+import org.jetbrains.kotlin.backend.konan.objcexport.ObjCNSEnum
+import org.jetbrains.kotlin.backend.konan.objcexport.ObjCProperty
+import org.jetbrains.kotlin.backend.konan.objcexport.ObjCRawType
+import org.jetbrains.kotlin.backend.konan.objcexport.ObjCTopLevel
+import org.jetbrains.kotlin.backend.konan.objcexport.ObjcExportNativeEnumEntry
+
+internal fun ObjCExportContext.translateNSEnum(symbol: KaClassSymbol, nsEnumTypeName: String, auxiliaryDeclarations: MutableList<ObjCTopLevel>): ObjCProperty {
+    auxiliaryDeclarations.add(ObjCNSEnum(nsEnumTypeName, getNSEnumEntries(symbol, nsEnumTypeName)))
+    return ObjCProperty(
+        "nsEnum",
+        null,
+        null,
+        ObjCRawType(nsEnumTypeName),
+        listOf("readonly")
+    )
+}
+
+
+private fun ObjCExportContext.getNSEnumEntries(symbol: KaClassSymbol, typeName: String): List<ObjcExportNativeEnumEntry> {
+    val staticMembers = with(analysisSession) { symbol.staticDeclaredMemberScope }.callables.toList()
+    // Map the enum entries in declaration order, preserving the ordinal
+    return staticMembers.filterIsInstance<KaEnumEntrySymbol>().mapIndexed { ordinal, entry ->
+        ObjcExportNativeEnumEntry(
+            getEnumEntryName(entry, false),
+            typeName + getEnumEntryName(entry, true).replaceFirstChar { it.uppercaseChar() },
+            ordinal
+        )
+    }
+}
+