Add a Getting Started document for the Swift Android SDK #985
Conversation
marcprux
requested review from
0xTim,
alexandersandberg,
davelester,
daveverwer,
dempseyatgithub,
federicobucchi,
kaishin,
shahmishal and
timsneath
as code owners
|
Moving this to draft until we have the official release of Swift Android SDK on swift.org |
|
Looks good, only wonder if we should add more info on next steps and upcoming work at the end, say linking to swift-java tools. |
| The easiest and recommended way to manage host toolchains on macOS and Linux is to use the [swiftly](https://www.swift.org/swiftly/documentation/swiftly/getting-started) command. Once that has been setup, you can install the host toolchain with: | ||
|
|
||
| ```console | ||
| $ swiftly install 6.2 |
There was a problem hiding this comment.
Sorry, but since we are only doing the trunk snapshots initially, could you change all these to that? We can change it to this once we have a release SDK available, which we won't initially.
There was a problem hiding this comment.
Happy to update this, but we'll need to know which nightly to recommend installing, which we won't know until we have one ready to publish. I expect that we'll just replace all "6.2" with "swift-DEVELOPMENT-SNAPSHOT-2025-10-02" (or whatever) when we are ready to go.
Or are there other changes that need to be made to update the instructions for the snapshots?
There was a problem hiding this comment.
Good point, we do need the date ready, my mistake. 🫤
I'll check if there's anything else.
|
|
||
| ### Getting Started | ||
|
|
||
| Building a Swift package for Android involves installing and configuring a cross-compilation SDK. Cross-compilation is the process of building code on one platform, the host, to run on a different platform, the target. In the context of Swift for Android, this typically involves compiling Swift code on a host macOS or Linux machine to produce executables or libraries for the target Android OS. This differs from compiling Swift for the host platform, where the host and target are the same (e.g., compiling and running Swift code on macOS for macOS). |
There was a problem hiding this comment.
Replace eg with "for example," not everybody knows what eg is 😉
|
|
||
| 1. **The Host Toolchain**: this is the `swift` command and related tools that you will use to build and run your Swift code. | ||
| 2. **The Swift SDK for Android**: the set of libraries, headers, and other resources needed to generate and run Swift code for the Android target. | ||
| 3. **The Android NDK**: the "Native Development Kit" for Android includes the cross-compilation tools like `clang` and `ld` that are used by the host toolchain to cross-compile and perform linking. |
|
|
||
| The first thing to note is that while `swift` may already be installed on your system (such as through an Xcode installation on macOS), using a cross-compilation SDK requires that the host toolchain and the SDK versions match exactly. For this reason, you will need to install the specific version of the host toolchain for the given SDK version. | ||
|
|
||
| The easiest and recommended way to manage host toolchains on macOS and Linux is to use the [swiftly](https://www.swift.org/swiftly/documentation/swiftly/getting-started) command. Once that has been setup, you can install the host toolchain with: |
There was a problem hiding this comment.
Swift.org URLs are relative in markdown, (/documentation/blah/blah) will work.
|
|
||
| #### 3. Install and configure the Android NDK | ||
|
|
||
| The Swift SDK for Android depends on the Android Native Development Toolkit (NDK) version 27d to provide the headers and tools necessary for cross-compiling to Android architectures. There are a variety of ways to [install the Android NDK](https://developer.android.com/ndk/guides), but the simplest is to just download and unzip the archive from the [NDK Downloads page](https://developer.android.com/ndk/downloads/#lts-downloads) directly. |
There was a problem hiding this comment.
Just say Android NDK version 27d at top of this paragraph, as you already explained the acronym earlier.
| setup-android-sdk.sh: success: ndk-sysroot linked to Android NDK at android-ndk-r27d/toolchains/llvm/prebuilt | ||
| ``` | ||
|
|
||
| *Note that if you have already installed the NDK in a different location, you can simply set the `ANDROID_NDK_HOME` environment variable to that location and run the `setup-android-sdk.sh`* |
There was a problem hiding this comment.
Missing period at end of sentence
| Now let's try it out with the canonical "Hello World" program. First, create a directory to hold your code: | ||
|
|
||
| ```console | ||
| $ mkdir hello |
There was a problem hiding this comment.
Add a plain cd first to get user back into their home directory or some new users will create this in .swiftpm from previous step.
| Hello, world! | ||
| ``` | ||
|
|
||
| With the Swift SDK for Android installed and configured, you can now cross-compile the executable for Android for the `x86_64` architecture: |
| .build/aarch64-unknown-linux-android28/debug/hello: ELF 64-bit LSB pie executable, ARM aarch64, version 1 (SYSV), dynamically linked, interpreter /system/bin/linker64, with debug_info, not stripped | ||
| ``` | ||
|
|
||
| With a connected Android device (with [USB debugging enabled](https://developer.android.com/studio/debug/dev-options#Enable-debugging)) or a locally-running Android [emulator](https://developer.android.com/studio/run/emulator#get-started), you can now copy the executable over, along with the required `libc++_shared.so` dependency from the Android NDK, and run it with the [`adb`](https://developer.android.com/tools/adb) utility: |
There was a problem hiding this comment.
device (with USB -> device that has USB or wifi
Remove parentheses, this is important info.
|
|
||
| Congratulations, you have built and run your first Swift program on Android! | ||
|
|
||
| Note that Android applications are typically not deployed as command-line executable tools. Rather, they are assembled into an `.apk` archive and launched as an app from the home screen. To support this, Swift modules can be built as shared object libraries for each supported architecture and included in the app archive. The Swift code can then be accessed from the Android app — which is typically written in Java or Kotlin — through the Java Native Interface ([JNI](https://developer.android.com/training/articles/perf-jni)). |
There was a problem hiding this comment.
Add a sentence or clause noting the in-progress Swift-Java interop?
There was a problem hiding this comment.
Oh, link to the new examples repo?
There was a problem hiding this comment.
This still has no mention of swift-java, can we please correct this @finagolfin @marcprux ?
There was a problem hiding this comment.
Thanks for putting this together, Marc, a good hand-holding for installing an SDK. 😄
I've added some nits that I think would make it read or work better. Might as well go ahead and change it to use the last 10/2 snapshot too, then once the official trunk snapshots are out, all we have to do is update the dates and the download URL.
Co-authored-by: Konrad `ktoso` Malawski <[email protected]>
|
I've merged all the suggestions and updated the sample to reference I've also added mention of the I'll leave it to @shahmishal to move this out of draft when we are ready to stage it all. |
|
|
||
| The first thing to note is that while `swift` may already be installed on your system (such as through an Xcode installation on macOS), using a cross-compilation SDK requires that the host toolchain and the SDK versions match exactly. For this reason, you will need to install the specific version of the host toolchain for the given SDK version. | ||
|
|
||
| The easiest and recommended way to manage host toolchains on macOS and Linux is to use the [swiftly](/documentation/swiftly/getting-started) command. Once that has been setup, you can install the host toolchain with: |
There was a problem hiding this comment.
I was wrong, you'll need the full URL here. 😬 I missed the /swiftly/ after swift.org, just checked and that is not part of this website repo. Also, please expand the linked text to "the swiftly command," as one-word links are not as usable in mobile browsers.
| swift-DEVELOPMENT-SNAPSHOT-2025-10-16-a-android-0.1 | ||
| ``` | ||
|
|
||
| #### 3. Install and configure the Android NDK |
There was a problem hiding this comment.
Can we split this into "Install the Android NDK" and "Configure the Android NDK"?
I'd like to eliminate the second step in the future or make it optional only if you've installed the NDK at a non-standard location which isn't picked up by the build system automatically.
5 participants
Motivation:
This article provides instructions for installing and setting up the Android SDK (swiftlang/swift#80788). It describes the process for the SDK bundle that is created with swiftlang/swift-docker#467.
The structure of the article largely follows the format of the Static Linux Getting Started guide (#686).
Modifications:
Add a documentation/articles/swift-android-getting-started.md article and updates to the articles index and authors list.
Result:
There will now be a new article titled "Getting Started with the Swift Android SDK".