Skip to content

Commit a56b44a

Browse files
marcpruxmarcprux
committed
Add article: Getting Started with the Swift Android SDK
1 parent ec101e7 commit a56b44a

File tree

3 files changed

+169
-1
lines changed

3 files changed

+169
-1
lines changed

‎_data/authors.yml‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -508,4 +508,12 @@ chris-mcgee:
508508

509509
parispittman:
510510
name: Paris Pittman
511-
github: parispittman
511+
github: parispittman
512+
513+
marcprux:
514+
name: Marc Prud'hommeaux
515+
email: [email protected]
516+
gravatar: marcprux
517+
github: marcprux
518+
about: "Marc Prud'hommeaux works on bringing Swift application development to Android at Skip.tools."
519+

‎_data/documentation.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,10 @@
6767
description: |
6868
Learn how to get started building binaries for Linux with no system dependencies (not even the Swift runtime or C library).
6969
Even better, you can do this from any system with a Swift toolchain, allowing you to develop on macOS or Windows and easily deploy to Linux when you go to production.
70+
- title: Getting Started with the Swift Android SDK
71+
url: /documentation/articles/swift-android-getting-started.html
72+
description: |
73+
Learn how to get started cross-compiling Swift packages for Android.
7074
#----------------------------------------------------
7175
- header: Contributing
7276
pages:

‎documentation/articles/swift-android-getting-started.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
layout: page
3+
date: 2025-06-01 12:00:00
4+
title: Getting Started with the Swift Android SDK
5+
author: [marcprux]
6+
---
7+
8+
Since it was first open-sourced in 2015, Swift has grown from a language focused on creating apps for Darwin based systems (iOS, macOS, etc.) into a cross-platform development language supporting Linux, Windows, and various embedded systems. With the release of the Swift Android SDK, it is now possible to use Swift for Android application development as well.
9+
10+
### Getting Started
11+
12+
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 macOS or Linux machine (the host) to produce executables or libraries for Android devices (the target). 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).
13+
14+
To cross-compile Swift code for Android, you need three separate components:
15+
16+
1. **The Host Toolchain**: this is the `swift` command and related tools that you will use to build and run your Swift code.
17+
2. **The Swift Android SDK**: the set of libraries, headers, and other resources needed to generate and run Swift code for the Android target.
18+
3. **The Android NDK**: the "native development kit" for Android includes the cross-compilation tools like `clang` that are used by the host toolchain to perform compilation and linking.
19+
20+
21+
#### 1. Install the Host Toolchain
22+
23+
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.
24+
25+
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:
26+
27+
```console
28+
$ swiftly install 6.1.1
29+
Installing Swift 6.1.1
30+
Installing package in user home directory...
31+
Swift 6.1.1 installed successfully!
32+
33+
$ swiftly use 6.1.1
34+
The global default toolchain has been set to `Swift 6.1.1` (was 6.1.0)
35+
36+
$ swiftly run swift --version
37+
Apple Swift version 6.1.1 (swift-6.1.1-RELEASE)
38+
Target: arm64-apple-macosx15.0
39+
```
40+
41+
#### 2. Install the Swift Android SDK
42+
43+
Next, you can download and install the SDK bundle using the built-in `swift sdk` command:
44+
45+
```console
46+
$ curl -fSLO https://github.com/skiptools/swift-android-toolchain/releases/download/6.1.1/swift-6.1.1-RELEASE-android-0.1.artifactbundle.tar.gz
47+
$ swiftly run swift sdk install swift-6.1.1-RELEASE-android-0.1.artifactbundle.tar.gz
48+
Swift SDK bundle at `swift-6.1.1-RELEASE-android-0.1.artifactbundle.tar.gz` successfully installed as swift-6.1.1-RELEASE-android-0.1.artifactbundle.
49+
```
50+
51+
You should now see the Android SDK included in the `swift sdk list` command:
52+
53+
```console
54+
$ swiftly run swift sdk list
55+
swift-6.1.1-RELEASE-android-0.1
56+
```
57+
58+
#### 3. Install and configure the Android NDK
59+
60+
The Swift Android SDK depends on the Android Native Development Toolkit (NDK) version 27c 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.
61+
62+
You can automate this with the following commands in a directory of your choosing:
63+
64+
```console
65+
$ mkdir ~/android-ndk
66+
$ cd ~/android-ndk
67+
$ curl -fSLO https://dl.google.com/android/repository/android-ndk-r27c-$(uname -s).zip
68+
$ unzip -q android-ndk-r27c-*.zip
69+
$ export ANDROID_NDK_HOME=$PWD/android-ndk-r27c
70+
```
71+
72+
Once you have downloaded and unpacked the NDK, you can link it up to the Swift Android SDK by running the `setup-android-sdk.sh` utility script included with the SDK bundle:
73+
74+
```console
75+
$ cd ~/Library/org.swift.swiftpm || cd ~/.swiftpm
76+
$ ./swift-sdks/swift-6.1.1-RELEASE-android-0.1.artifactbundle/swift-android/scripts/setup-android-sdk.sh
77+
setup-android-sdk.sh: success: ndk-sysroot linked to Android NDK at android-ndk-r27c/toolchains/llvm/prebuilt
78+
```
79+
80+
*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`*
81+
82+
At this point, you will have a fully working cross-compilation toolchain for Android.
83+
84+
### Hello World on Android
85+
86+
Now let's try it out with the canonical "Hello World" program. First, create a directory to hold your code:
87+
88+
```console
89+
$ mkdir hello
90+
$ cd hello
91+
```
92+
93+
Next, ask Swift to create a new program package for you:
94+
95+
```console
96+
$ swiftly run swift package init --type executable
97+
```
98+
99+
Try it out by building and running locally for the host machine:
100+
101+
```console
102+
$ swiftly run swift build
103+
Building for debugging...
104+
[8/8] Applying hello
105+
Build complete! (15.29s)
106+
107+
$ .build/debug/hello
108+
Hello, world!
109+
```
110+
111+
With the Swift Android SDK installed and configured, you can now cross-compile the executable for Android for the `x86_64` architecture:
112+
113+
```console
114+
$ swiftly run swift build --swift-sdk x86_64-unknown-linux-android28 --static-swift-stdlib
115+
Building for debugging...
116+
[8/8] Linking hello
117+
Build complete! (2.04s)
118+
119+
$ file .build/x86_64-unknown-linux-android28/debug/hello
120+
.build/x86_64-unknown-linux-android28/debug/hello: ELF 64-bit LSB pie executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /system/bin/linker64, with debug_info, not stripped
121+
```
122+
123+
or for the `aarch64` architecture:
124+
125+
```console
126+
$ swiftly run swift build --swift-sdk aarch64-unknown-linux-android28 --static-swift-stdlib
127+
Building for debugging...
128+
[8/8] Linking hello
129+
Build complete! (2.04s)
130+
131+
$ file .build/aarch64-unknown-linux-android28/debug/hello
132+
.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
133+
```
134+
135+
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:
136+
137+
```console
138+
$ adb push .build/aarch64-unknown-linux-android28/debug/hello /data/local/tmp
139+
.build/aarch64-unknown-linux-android28/debug/hello: 1 file pushed, 0 skipped. 155.9 MB/s (69559568 bytes in 0.425s)
140+
141+
$ adb push $ANDROID_NDK_HOME/toolchains/llvm/prebuilt/*/sysroot/usr/lib/aarch64-linux-android/libc++_shared.so /data/local/tmp/
142+
aarch64-linux-android/libc++_shared.so: 1 file pushed, 0 skipped. 145.7 MB/s (1794776 bytes in 0.012s)
143+
144+
$ adb shell /data/local/tmp/hello
145+
Hello, world!
146+
```
147+
148+
### Next Steps
149+
150+
Congratulations, you have built and run your first Swift program on Android!
151+
152+
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)).
153+
154+
This is a larger development topic that will be expanded on in future articles and documentation. In the meantime, please visit the [Swift Android forums](https://forums.swift.org/c/development/android/) to discuss and seek help with the Swift Android SDK.
155+
156+

0 commit comments

Comments
 (0)