Merge pull request #4 from swiftlang/update-documentation

andriydruk · web-flow · commit 72e2a216a132 · 2025-10-23T15:36:09.000+03:00
Update documentation
diff --git a/README.md b/README.md
@@ -1,15 +1,11 @@
 # Swift Android Examples
 
-This repository contains sample apps that use the [Swift Android SDK](https://www.swift.org/).
+This repository contains example applications that demonstrate how to use the [Swift SDK for Android](https://swift.org/install). Each example showcases different integration patterns for Swift on Android.
 
-# Build and run
+## Available Examples
 
-1. Setup Swift Android SDK
-2. Clone this repository
-3. Open the whole project in Android Studio
-4. Select the sample you want to run in the top bar (you may need to sync gradle first)
-5. Click the play button to run the sample
-
-You can also build the samples from the command line if you prefer. Use `./gradlew` build to build everything. For individual tasks, see `./gradlew tasks`. To see the tasks for an individual sample, run the tasks task for that directory. For example, `./gradlew :hello-swift:tasks` will show the tasks for the hello-swift app.
-
-You can build all sample apps for both the debug and release build types by running `./gradlew assemble`.
+- **[hello-swift](hello-swift/)** - basic Swift integration that calls a Swift function.
+- **[hello-swift-callback](hello-swift-callback/)** - demonstrates bidirectional communication with Swift timer callbacks updating Android UI.
+- **[hello-swift-library](hello-swift-library/)** - shows how to package Swift code as a reusable Android library component.
+- **[native-activity](native-activity/)** - complete native Android activity with OpenGL ES rendering written entirely in Swift.
+- **[swift-java-hashing-example](swift-java-hashing-example/)** - application that demonstrates how to call Swift code from an Android app with automatically generated Java wrappers and JNI code using [swift-java](https://github.com/swiftlang/swift-java).
diff --git a/hello-swift-callback/README.md b/hello-swift-callback/README.md
@@ -0,0 +1,38 @@
+# Swift to Android Callbacks
+
+This example demonstrates bidirectional communication between Swift and Android. The Swift code runs a timer that calls back to Android every second to update the UI with the current time (HH:MM:SS format).
+
+![Screenshot](screenshot.png)
+
+## Overview
+
+The project consists of:
+
+1. **Android App**: A Kotlin activity that starts/stops a timer and displays the current time. It includes a callback method `updateTimer()` that gets called from Swift.
+2. **Swift Code**: Implements a background timer using `DispatchQueue` that calls back to the Android activity every second to update the timer display.
+
+## Prerequisites
+
+Before you can build and run this project, you need to have the following installed:
+
+* **Java Development Kit (JDK)**: We recommend using JDK 21. Ensure the `JAVA_HOME` environment variable is set to your JDK installation path.
+* **Swiftly**: You need to install [Swiftly](https://www.swift.org/install/)
+* **Swift SDK for Android**: You need to install the [Swift SDK for Android](https://swift.org/install)
+
+## Running the example
+
+1. Open the `swift-android-examples` project in Android Studio.
+
+2. Select the `hello-swift-callback` Gradle target.
+
+3. Run the app on an Android emulator or a physical device.
+
+## Building from command line
+
+```bash
+# Build the example
+./gradlew :hello-swift-callback:assembleDebug
+
+# Install on device/emulator
+./gradlew :hello-swift-callback:installDebug
+```
diff --git a/hello-swift-callback/screenshot.png b/hello-swift-callback/screenshot.png
diff --git a/hello-swift-library/README.md b/hello-swift-library/README.md
@@ -0,0 +1,47 @@
+# Swift as Android Library
+
+This example demonstrates how to package Swift code as a reusable Android library. It shows how to create a Swift library that can be consumed by other Android applications, making Swift functionality available as a standard Android library component.
+
+## Overview
+
+The project consists of:
+
+1. **Swift Library**: A `SwiftLibrary` class that declares external Swift functions and loads the native library.
+2. **Swift Implementation**: Implements the library functions using JNI conventions for consumption by other Android projects.
+
+## Prerequisites
+
+Before you can build and run this project, you need to have the following installed:
+
+* **Java Development Kit (JDK)**: We recommend using JDK 21. Ensure the `JAVA_HOME` environment variable is set to your JDK installation path.
+* **Swiftly**: You need to install [Swiftly](https://www.swift.org/install/)
+* **Swift SDK for Android**: You need to install the [Swift SDK for Android](https://swift.org/install)
+
+## Building the library
+
+1. Open the `swift-android-examples` project in Android Studio.
+
+2. Select the `hello-swift-library` Gradle target.
+
+3. Build the library (it doesn't have a runnable app).
+
+## Building from command line
+
+```bash
+# Build the library
+./gradlew :hello-swift-library:assembleDebug
+
+# Build the AAR file
+./gradlew :hello-swift-library:bundleReleaseAar
+```
+
+After a successful build, the Android library will be located at `hello-swift-library/build/outputs/aar/hello-swift-library-release.aar`.
+
+## Using the library in other projects
+
+1. Copy the generated AAR file to your project's `libs/` directory
+2. Add the dependency in your `build.gradle`:
+   ```gradle
+   implementation files('libs/hello-swift-library-release.aar')
+   ```
+3. Use the `SwiftLibrary` class in your code
diff --git a/hello-swift/README.md b/hello-swift/README.md
@@ -0,0 +1,38 @@
+# Basic Swift Integration
+
+This example demonstrates the most basic Swift integration pattern with Android. The app calls a Swift function that returns a "Hello from Swift ❤️" message and displays it in the Android UI.
+
+![Screenshot](screenshot.png)
+
+## Overview
+
+The project consists of:
+
+1. **Android App**: A simple Kotlin activity that declares an external function `stringFromSwift()` and loads the native library.
+2. **Swift Code**: Implements the function using `@_cdecl` attribute to match JNI naming convention, returning a greeting message.
+
+## Prerequisites
+
+Before you can build and run this project, you need to have the following installed:
+
+* **Java Development Kit (JDK)**: We recommend using JDK 21. Ensure the `JAVA_HOME` environment variable is set to your JDK installation path.
+* **Swiftly**: You need to install [Swiftly](https://www.swift.org/install/)
+* **Swift SDK for Android**: You need to install the [Swift SDK for Android](https://swift.org/install)
+
+## Running the example
+
+1. Open the `swift-android-examples` project in Android Studio.
+
+2. Select the `hello-swift` Gradle target.
+
+3. Run the app on an Android emulator or a physical device.
+
+## Building from command line
+
+```bash
+# Build the example
+./gradlew :hello-swift:assembleDebug
+
+# Install on device/emulator
+./gradlew :hello-swift:installDebug
+```
diff --git a/hello-swift/screenshot.png b/hello-swift/screenshot.png
diff --git a/native-activity/README.md b/native-activity/README.md
@@ -0,0 +1,39 @@
+# Full Native Activity
+
+This example demonstrates a complete native Android activity written entirely in Swift. It showcases Android integration including OpenGL ES rendering, native app lifecycle management, and the Android Native App Glue framework.
+
+![Screenshot](screenshot.png)
+
+## Overview
+
+The project consists of:
+
+1. **Native Activity**: A complete Swift implementation that creates an OpenGL ES context and renders a continuously changing colored background.
+2. **Android Native App Glue**: Uses the Android Native App Glue framework to handle Android lifecycle and integrates with Choreographer for smooth rendering at 60fps.
+
+## Prerequisites
+
+Before you can build and run this project, you need to have the following installed:
+
+* **Java Development Kit (JDK)**: We recommend using JDK 21. Ensure the `JAVA_HOME` environment variable is set to your JDK installation path.
+* **Swiftly**: You need to install [Swiftly](https://www.swift.org/install/)
+* **Swift SDK for Android**: You need to install the [Swift SDK for Android](https://swift.org/install)
+* **Device/emulator with OpenGL ES support**
+
+## Running the example
+
+1. Open the `swift-android-examples` project in Android Studio.
+
+2. Select the `native-activity` Gradle target.
+
+3. Run the app on an Android emulator or a physical device.
+
+## Building from command line
+
+```bash
+# Build the example
+./gradlew :native-activity:assembleDebug
+
+# Install on device/emulator
+./gradlew :native-activity:installDebug
+```
diff --git a/native-activity/screenshot.png b/native-activity/screenshot.png
diff --git a/swift-android.gradle.kts b/swift-android.gradle.kts
@@ -7,15 +7,15 @@ import org.gradle.api.file.DuplicatesStrategy
 
 // Configuration class for Swift builds
 data class SwiftConfig(
-    var apiLevel: Int = 29, // Default API level
+    var apiLevel: Int = 28, // Default API level
     var debugAbiFilters: Set<String> = setOf("arm64-v8a"),
     var debugExtraBuildFlags: List<String> = emptyList(),
     var releaseAbiFilters: Set<String> = setOf("arm64-v8a", "armeabi-v7a", "x86_64"),
     var releaseExtraBuildFlags: List<String> = emptyList(),
     var swiftlyPath: String? = null, // Optional custom swiftly path
     var swiftSDKPath: String? = null, // Optional custom Swift SDK path
-    var swiftVersion: String = "6.2.0", // Swift version
-    var androidSdkVersion: String = "6.2-RELEASE-android-0.1" // SDK version
+    var swiftVersion: String = "main-snapshot-2025-10-16", // Swift version
+    var androidSdkVersion: String = "DEVELOPMENT-SNAPSHOT-2025-10-16-a-android-0.1" // SDK version
 )
 
 // Architecture definitions
diff --git a/swift-java-hashing-example/README.md b/swift-java-hashing-example/README.md
@@ -21,7 +21,7 @@ Before you can build and run this project, you need to have the following instal
 
 * **Java Development Kit (JDK)**: We recommend using JDK 21. Ensure the `JAVA_HOME` environment variable is set to your JDK installation path.
 * **Swiftly**: You need to install [Swiftly](https://www.swift.org/install/)
-* **Swift SDK for Android**: You need to install the [Swift Android SDK](https://swift.org/install)
+* **Swift SDK for Android**: You need to install the [Swift SDK for Android](https://swift.org/install)
 
 ## Setup and Configuration
 
