Linking Native Libraries

Some SPM packages depend on a native library that isn’t part of the Swift toolchain itself — for example, a Swift wrapper around SQLite needs to link against libsqlite3.

Linking is also needed when a Swift library itself is distributed in prebuilt binary form for Android, rather than being built from source.

scd bundles a custom fork of swift-build with support for native (Swift/C/C++) libraries on Android. Native libraries can be linked as an XCFramework binary target, an AAR archive, or via manual flags.

XCFramework Binary Target

XCFramework is Apple’s cross-platform binary distribution format, bundling prebuilt libraries and headers for multiple platforms in a single package. scd supports XCFrameworks for Android out of the box, with no extra flags needed — Android platform support for binary targets is built into the bundled swift-build fork.

To use an XCFramework, declare it as a binary target in Package.swift:

.binaryTarget(
    name: "foo",
    path: "relative/path/to/foo.xcframework"
)

The library’s .so is detected automatically, and scd will embed it into resulting archives when doing run, test, or archive, without any extra options.

AAR Archive

AAR (Android Archive) is Android’s native library and resource distribution format. scd supports linking against AAR archives for the Android platform out of the box.

To use an AAR, pass its path to -l/--link-library or -L/--link-library-path. scd build automatically extracts the headers and the native libraries for the current ABI from the archive and links against them:

scd build --platform android-arm64-v8a --link-library ./MyDependency.aar

This only passes options required at link time. To embed the library’s .so into resulting archives when doing run, test, or archive, you still need to pass it explicitly with --embed-library:<platform> — see Libraries Options.

Manual Flags

Sometimes a library is available neither as an XCFramework nor as an AAR archive — for example, when wrapping a system library via a module.modulemap. In that case, additional include and link paths can be passed to scd to resolve the library at compile and link time:

scd build --platform android-arm64-v8a -Xcc -I./MyDependency/include -Xlinker -L./MyDependency/lib -Xlinker -lfoo

This command adds ./MyDependency/include as an include directory, ./MyDependency/lib as a library search directory, and links against libfoo with the -l flag.

As with AAR archives, you also need to embed the library into resulting archives when doing run, test, or archive with --embed-library:<platform> — see SPM Build Options and Libraries Options.