DOCSEARCHbyAlgolia
Submit Docs

KMMBridge Documentation

repository·main·Indexed 19 days ago

https://github.com/touchlab/kmmbridge

KMMBridge provides Gradle-based tooling to automate the publishing and consumption of pre-built Kotlin Multiplatform (KMP) Xcode Framework binaries. It streamlines the integration of KMP code into iOS projects by managing the distribution of compiled frameworks via Swift Package Manager (SPM) and CocoaPods, including automated GitHub deploy key setup and podspec generation.

Tokens
1.4K
Snippets
4
Records
9
Agent score
65%

What's inside KMMBridge

  1. What is KMMBridge?

    main
    KMMBridge is a set of Gradle tooling designed to facilitate the publishing and consuming of pre-built Kotlin Multiplatform (KMP) Xcode Framework binaries. It helps bridge the gap between Kotlin Multiplatform development and iOS/Xcode integration by managing the distribution of compiled frameworks.

  2. How KMMBridge project tests work

    main

    KMMBridge tests do not use Gradle include builds. Instead, they follow this lifecycle:

    1. A temporary folder is created.
    2. A sample app project (located in test-projects/basic) is copied into that temporary folder.
    3. A command-line process (typically a Gradle command) is executed within that folder to verify the plugin's behavior.

    The test project at test-projects/basic is pre-configured to point to the local KMMBridge version 9.9.9.

  3. Use the KMMBridge v1 SPM Template

    main
    This template project is designed for Kotlin Multiplatform (KMP) developers who want to use KMMBridge to publish Xcode Framework binaries via Swift Package Manager (SPM). It serves as a starting point for setting up the necessary infrastructure to bridge KMP code to iOS using the KMMBridge v1 workflow.

  4. Publish KMMBridge locally for testing

    main

    To test KMMBridge against external projects, you must first publish it to your local Maven repository using a specific fake version (9.9.9). This allows test projects to reference a local instance of the plugin without needing to use Gradle include builds, which avoids JVM classpath conflicts.

    Run this command from the root folder of the KMMBridge repository:

    ./gradlew publishToMavenLocal -PVERSION_NAME=9.9.9

  5. Configure CocoaPods Spec Repository Type

    main

    When using the CocoapodsDependencyManager, you must specify whether you are pushing to the public CocoaPods Trunk or a private repository. This determines which pod command is executed during the pushRemotePodspec task.

    • Trunk: For public distribution via pod trunk push.
    • Private: For internal/private distribution via pod repo push <specUrl>.

  6. Push Podspecs to CocoaPods via KMMBridge

    main

    KMMBridge provides Gradle tasks to automatically generate and push .podspec files to either the CocoaPods Trunk or a private Spec repository. This allows your KMM library to be consumed as a CocoaPods dependency.

    Available Tasks

    • generateReleasePodspec: Generates a .podspec file based on your Kotlin CocoaPods configuration and the deployment URL provided by KMMBridge.
    • pushRemotePodspec: Triggers the generation and then pushes the podspec to the configured repository.

    Repository Types

    • Trunk: Uses pod trunk push to upload to the public CocoaPods repository.
    • Private: Uses pod repo push <specUrl> <podSpecFile> to upload to a custom, private specification repository.

    Configuration Behavior

    The generated podspec includes:

    • The deployment URL (from KMMBridge's URL file).
    • Versioning derived from your project or KMMBridge settings.
    • Platform deployment targets (iOS, OSX, tvos, watchos).
    • Dependencies defined in your Kotlin CocoaPods block.
    • Custom spec attributes defined via extraSpecAttributes.
    • Automatic inclusion of vendored_frameworks (the .xcframework) and libraries = 'c++' unless explicitly overridden in your configuration.
    # Example usage in a terminal (assuming tasks are registered)
./gradlew pushRemotePodspec

# The task will:
# 1. Generate the podspec in build/kmmbridge/podspec/
# 2. Execute 'pod trunk push' or 'pod repo push' depending on your setup.

  7. Implement a sample KMMBridge test

    main

    Tests are implemented by running shell commands against a test project directory. You can use ProcessHelper.runSh to execute Gradle tasks and verify the exit status. The setup() function in co.touchlab.kmmbridge.SimplePluginTest handles the initialization and copying of the test project.

    @Test
fun runSpmDevBuild() {
    val result = ProcessHelper.runSh("./gradlew spmDevBuild --stacktrace", workingDir = testProjectDir)
    logExecResult(result)
    assertEquals(0, result.status)
}

  8. Configure GitHub deployment repositories

    main

    To use the GitHub integration features of KMMBridge, you must provide the source and target repository names. These are used to set up SSH deploy keys for automated publishing workflows.

    Required properties:

    • githubDeploySourceRepo: The name of the GitHub repository where the SSH private key will be stored as a secret.
    • githubDeployTargetRepo: The name of the GitHub repository where the SSH public deploy key will be added.

  9. Setup GitHub deploy keys with setupDeployKeys

    main

    The setupDeployKeys task is a helper task that automates the creation of SSH deploy keys for GitHub. It performs the following steps:

    1. Generates an ed25519 SSH key pair in a temporary directory.
    2. Uses the GitHub CLI (gh) to add the public key as a deploy key to the githubDeployTargetRepo.
    3. Uses the GitHub CLI (gh) to set the private key as a repository secret in the githubDeploySourceRepo.

    Requirements:

    • The gh (GitHub CLI) must be installed and authenticated on the machine running the task.
    • githubDeploySourceRepo and githubDeployTargetRepo must be configured in your Gradle project.

    Optional Configuration:

    • githubDeployKeyPrefix: A prefix used for the secret name and the deploy key label. Defaults to KMMBridge.
    ./gradlew setupDeployKeys