binary-compatibility-validator/kotlinx.validation.api.klib/inferAbi

inferAbi

fun inferAbi(unsupportedTarget: KlibTarget, supportedTargetDumps: Iterable<KlibDump>, oldMergedDump: KlibDump? = null): KlibDump(source)

Infer a possible public ABI for unsupportedTarget as an ABI common across all supportedTargetDumps. If there's an oldMergedDump consisting of declarations of multiple targets, including unsupportedTarget, a portion of that dump specific to the unsupportedTarget will be extracted and merged to the common ABI build from supportedTargetDumps.

Returned dump contains only declarations for unsupportedTarget.

The function aimed to facilitate ABI dumps generation for targets that are not supported by a host compiler. In practice, it means generating dumps for Apple targets on non-Apple hosts.

Throws

when supportedTargetDumps are empty and oldMergedDump is null

Samples

import kotlinx.validation.ExperimentalBCVApi
import kotlinx.validation.api.klib.KlibDump
import kotlinx.validation.api.klib.KlibTarget
import kotlinx.validation.api.klib.inferAbi
import org.junit.Rule
import org.junit.Test
import org.junit.rules.TemporaryFolder
import java.io.File
import kotlin.test.assertEquals

fun main() { 
   //sampleStart 
   // We want to get a dump for iosArm64, but our host compiler doesn't support it.
val unsupportedTarget = KlibTarget.parse("iosArm64")
// Thankfully, we have an old merged dump ...
val oldMergedDump = createDumpWithContent("""
    // Klib ABI Dump
    // Targets: [iosArm64, linuxArm64]
    // Rendering settings:
    // - Signature version: 2
    // - Show manifest properties: true
    // - Show declarations: true

    // Library unique name: <testproject>
    abstract class examples.classes/Klass // examples.classes/Klass|null[0]
    // Targets: [iosArm64]
    abstract interface examples.classes/Iface // examples.classes/Iface|null[0]

""".trimIndent())

// ... and a new dump for linuxArm64
val linuxDump = createDumpWithContent("""
    // Klib ABI Dump
    // Targets: [linuxArm64]
    // Rendering settings:
    // - Signature version: 2
    // - Show manifest properties: true
    // - Show declarations: true

    // Library unique name: <testproject>
    abstract class examples.classes/NewKlass // examples.classes/NewKlass|null[0]

""".trimIndent())

// Let's use these dumps to infer a public ABI on iosArm64
val inferredIosArm64Dump = inferAbi(
    unsupportedTarget = unsupportedTarget,
    supportedTargetDumps = listOf(KlibDump.from(linuxDump)),
    oldMergedDump = KlibDump.from(oldMergedDump))

assertEquals(unsupportedTarget, inferredIosArm64Dump.targets.single())

val inferredDumpContent = buildString { inferredIosArm64Dump.saveTo(this) }
assertEquals("""
    // Klib ABI Dump
    // Targets: [iosArm64]
    // Rendering settings:
    // - Signature version: 2
    // - Show manifest properties: true
    // - Show declarations: true

    // Library unique name: <testproject>
    abstract class examples.classes/NewKlass // examples.classes/NewKlass|null[0]
    abstract interface examples.classes/Iface // examples.classes/Iface|null[0]

""".trimIndent(),
    inferredDumpContent) 
   //sampleEnd
}