Improve Android SDK/NDK discovery

jakepetroules · jakepetroules · commit 6d3346f46c86 · 2025-08-02T05:07:47.000-07:00
Now respects the environment variable overrides and looks for the Debian/Ubuntu package location. Closes #495
diff --git a/.github/scripts/linux_pre_build.sh b/.github/scripts/linux_pre_build.sh
@@ -0,0 +1,50 @@
+#!/bin/bash
+set -e
+
+if command -v apt-get >/dev/null 2>&1 ; then # bookworm, noble, jammy
+    export DEBIAN_FRONTEND=noninteractive
+
+    apt-get update -y
+
+    # Build dependencies
+    apt-get install -y libsqlite3-dev libncurses-dev
+
+    # Debug symbols
+    apt-get install -y libc6-dbg
+
+    # Android NDK
+    dpkg_architecture="$(dpkg --print-architecture)"
+    if [[ "$dpkg_architecture" == amd64 ]] ; then
+        eval "$(cat /etc/lsb-release)"
+        case "$DISTRIB_CODENAME" in
+            bookworm|jammy)
+                : # Not available
+                ;;
+            noble)
+                apt-get install -y google-android-ndk-r26c-installer
+                ;;
+            *)
+                echo "Unknown distribution: $DISTRIB_CODENAME" >&2
+                exit 1
+        esac
+    else
+        echo "Skipping Android NDK installation on $dpkg_architecture" >&2
+    fi
+elif command -v dnf >/dev/null 2>&1 ; then # rhel-ubi9
+    dnf update -y
+
+    # Build dependencies
+    dnf install -y sqlite-devel ncurses-devel
+
+    # Debug symbols
+    dnf debuginfo-install -y glibc
+elif command -v yum >/dev/null 2>&1 ; then # amazonlinux2
+    yum update -y
+
+    # Build dependencies
+    yum install -y sqlite-devel ncurses-devel
+
+    # Debug symbols
+    yum install -y yum-utils
+    debuginfo-install -y glibc
+fi
diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml
@@ -14,33 +14,7 @@ jobs:
     uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@main
     with:
       linux_os_versions: '["noble", "jammy", "rhel-ubi9"]'
-      linux_pre_build_command: |
-        if command -v apt-get >/dev/null 2>&1 ; then # bookworm, noble, jammy
-          apt-get update -y
-
-          # Build dependencies
-          apt-get install -y libsqlite3-dev libncurses-dev
-
-          # Debug symbols
-          apt-get install -y libc6-dbg
-        elif command -v dnf >/dev/null 2>&1 ; then # rhel-ubi9
-          dnf update -y
-
-          # Build dependencies
-          dnf install -y sqlite-devel ncurses-devel
-
-          # Debug symbols
-          dnf debuginfo-install -y glibc
-        elif command -v yum >/dev/null 2>&1 ; then # amazonlinux2
-          yum update -y
-
-          # Build dependencies
-          yum install -y sqlite-devel ncurses-devel
-
-          # Debug symbols
-          yum install -y yum-utils
-          debuginfo-install -y glibc
-        fi
+      linux_pre_build_command: ./github/scripts/linux_pre_build.sh
       linux_build_command: 'swift test --no-parallel'
       linux_swift_versions: '["nightly-main", "nightly-6.2"]'
       windows_swift_versions: '["nightly-main"]'
diff --git a/Sources/SWBAndroidPlatform/AndroidSDK.swift b/Sources/SWBAndroidPlatform/AndroidSDK.swift
@@ -16,18 +16,21 @@ public import Foundation
 @_spi(Testing) public struct AndroidSDK: Sendable {
     public let host: OperatingSystem
     public let path: Path
+    private let ndkInstallations: NDK.Installations
 
     /// List of NDKs available in this SDK installation, sorted by version number from oldest to newest.
-    @_spi(Testing) public let ndks: [NDK]
+    @_spi(Testing) public var ndks: [NDK] {
+        ndkInstallations.ndks
+    }
 
-    public var latestNDK: NDK? {
-        ndks.last
+    public var preferredNDK: NDK? {
+        ndkInstallations.preferredNDK ?? ndks.last
     }
 
     init(host: OperatingSystem, path: Path, fs: any FSProxy) throws {
         self.host = host
         self.path = path
-        self.ndks = try NDK.findInstallations(host: host, sdkPath: path, fs: fs)
+        self.ndkInstallations = try NDK.findInstallations(host: host, sdkPath: path, fs: fs)
     }
 
     @_spi(Testing) public struct NDK: Equatable, Sendable {
@@ -39,10 +42,16 @@ public import Foundation
         public let abis: [String: ABI]
         public let deploymentTargetRange: DeploymentTargetRange
 
-        init(host: OperatingSystem, path ndkPath: Path, version: Version, fs: any FSProxy) throws {
+        @_spi(Testing) public init(host: OperatingSystem, path ndkPath: Path, fs: any FSProxy) throws {
             self.host = host
             self.path = ndkPath
-            self.version = version
+
+            let propertiesFile = ndkPath.join("source.properties")
+            guard fs.exists(propertiesFile) else {
+                throw Error.notAnNDK(ndkPath)
+            }
+
+            self.version = try NDK.Properties(data: Data(fs.read(propertiesFile))).revision
 
             let metaPath = ndkPath.join("meta")
 
@@ -51,7 +60,7 @@ public import Foundation
             }
 
             if version < Self.minimumNDKVersion {
-                throw StubError.error("Android NDK version at path '\(ndkPath.str)' is not supported (r\(Self.minimumNDKVersion.description) or later required)")
+                throw Error.unsupportedVersion(path: ndkPath, minimumVersion: Self.minimumNDKVersion)
             }
 
             self.abis = try JSONDecoder().decode(ABIs.self, from: Data(fs.read(metaPath.join("abis.json"))), configuration: version).abis
@@ -65,6 +74,36 @@ public import Foundation
             deploymentTargetRange = DeploymentTargetRange(min: platformsInfo.min, max: platformsInfo.max)
         }
 
+        public enum Error: Swift.Error, CustomStringConvertible, Sendable {
+            case notAnNDK(Path)
+            case unsupportedVersion(path: Path, minimumVersion: Version)
+            case noSupportedVersions(minimumVersion: Version)
+
+            public var description: String {
+                switch self {
+                case let .notAnNDK(path):
+                    "Package at path '\(path.str)' is not an Android NDK (no source.properties file)"
+                case let .unsupportedVersion(path, minimumVersion):
+                    "Android NDK version at path '\(path.str)' is not supported (r\(minimumVersion.description) or later required)"
+                case let .noSupportedVersions(minimumVersion):
+                    "All installed NDK versions are not supported (r\(minimumVersion.description) or later required)"
+                }
+            }
+        }
+
+        struct Properties {
+            let properties: JavaProperties
+            let revision: Version
+
+            init(data: Data) throws {
+                properties = try .init(data: data)
+                guard properties["Pkg.Desc"] == "Android NDK" else {
+                    throw StubError.error("Package is not an Android NDK")
+                }
+                revision = try Version(properties["Pkg.BaseRevision"] ?? properties["Pkg.Revision"] ?? "")
+            }
+        }
+
         struct ABIs: DecodableWithConfiguration {
             let abis: [String: ABI]
 
@@ -185,27 +224,96 @@ public import Foundation
             }
         }
 
-        public static func findInstallations(host: OperatingSystem, sdkPath: Path, fs: any FSProxy) throws -> [NDK] {
+        public struct Installations: Sendable {
+            private let preferredIndex: Int?
+            public let ndks: [NDK]
+
+            init(preferredIndex: Int? = nil, ndks: [NDK]) {
+                self.preferredIndex = preferredIndex
+                self.ndks = ndks
+            }
+
+            public var preferredNDK: NDK? {
+                preferredIndex.map { ndks[$0] } ?? ndks.only
+            }
+        }
+
+        public static func findInstallations(host: OperatingSystem, sdkPath: Path, fs: any FSProxy) throws -> Installations {
+            if let overridePath = NDK.environmentOverrideLocation {
+                return try Installations(ndks: [NDK(host: host, path: overridePath, fs: fs)])
+            }
+
             let ndkBasePath = sdkPath.join("ndk")
             guard fs.exists(ndkBasePath) else {
-                return []
+                return Installations(ndks: [])
             }
 
-            let ndks = try fs.listdir(ndkBasePath).map({ try Version($0) }).sorted()
-            let supportedNdks = ndks.filter { $0 >= minimumNDKVersion }
+            var hadUnsupportedVersions: Bool = false
+            let ndks = try fs.listdir(ndkBasePath).compactMap({ subdir in
+                do {
+                    return try NDK(host: host, path: ndkBasePath.join(subdir), fs: fs)
+                } catch Error.notAnNDK(_) {
+                    return nil
+                } catch Error.unsupportedVersion(_, _) {
+                    hadUnsupportedVersions = true
+                    return nil
+                }
+            }).sorted(by: \.version)
 
-            // If we have some NDKs but all of them are unsupported, try parsing them so that parsing fails and provides a more useful error. Otherwise, simply filter out and ignore the unsupported versions.
-            let discoveredNdks = supportedNdks.isEmpty && !ndks.isEmpty ? ndks : supportedNdks
+            // If we have some NDKs but all of them are unsupported, provide a more useful error. Otherwise, simply filter out and ignore the unsupported versions.
+            if ndks.isEmpty && hadUnsupportedVersions {
+                throw Error.noSupportedVersions(minimumVersion: Self.minimumNDKVersion)
+            }
 
-            return try discoveredNdks.map { ndkVersion in
-                let ndkPath = ndkBasePath.join(ndkVersion.description)
-                return try NDK(host: host, path: ndkPath, version: ndkVersion, fs: fs)
+            // Respect Debian alternatives
+            let preferredIndex: Int?
+            if sdkPath == AndroidSDK.defaultDebianLocation {
+                preferredIndex = try ndks.firstIndex(where: { try $0.path == fs.realpath(Path("/usr/lib/android-ndk")) })
+            } else {
+                preferredIndex = nil
             }
+
+            return Installations(preferredIndex: preferredIndex, ndks: ndks)
         }
     }
 
     public static func findInstallations(host: OperatingSystem, fs: any FSProxy) async throws -> [AndroidSDK] {
-        let defaultLocation: Path? = switch host {
+        var paths: [Path] = []
+        if let path = AndroidSDK.environmentOverrideLocation {
+            paths.append(path)
+        }
+        if let path = try AndroidSDK.defaultAndroidStudioLocation(host: host) {
+            paths.append(path)
+        }
+        if host == .linux {
+            paths.append(AndroidSDK.defaultDebianLocation)
+        }
+        return try paths.compactMap { path in
+            guard fs.exists(path) else {
+                return nil
+            }
+            return try AndroidSDK(host: host, path: path, fs: fs)
+        }
+    }
+}
+
+fileprivate extension AndroidSDK.NDK {
+    /// The location of the Android NDK based on the `ANDROID_NDK_ROOT` environment variable (falling back to the deprecated but well known `ANDROID_NDK_HOME`).
+    /// - seealso: [Configuring NDK Path](https://github.com/android/ndk-samples/wiki/Configure-NDK-Path#terminologies)
+    static var environmentOverrideLocation: Path? {
+        (getEnvironmentVariable("ANDROID_NDK_ROOT") ?? getEnvironmentVariable("ANDROID_NDK_HOME"))?.nilIfEmpty.map(Path.init)
+    }
+}
+
+fileprivate extension AndroidSDK {
+    /// The location of the Android SDK based on the `ANDROID_HOME` environment variable (falling back to the deprecated but well known `ANDROID_SDK_ROOT`).
+    /// - seealso: [Android environment variables](https://developer.android.com/tools/variables)
+    static var environmentOverrideLocation: Path? {
+        (getEnvironmentVariable("ANDROID_HOME") ?? getEnvironmentVariable("ANDROID_SDK_ROOT"))?.nilIfEmpty.map(Path.init)
+    }
+
+    static func defaultAndroidStudioLocation(host: OperatingSystem) throws -> Path? {
+        switch host {
         case .windows:
             // %LOCALAPPDATA%\Android\Sdk
             try FileManager.default.url(for: .applicationSupportDirectory, in: .userDomainMask, appropriateFor: nil, create: false).appendingPathComponent("Android").appendingPathComponent("Sdk").filePath
@@ -218,11 +326,11 @@ public import Foundation
         default:
             nil
         }
+    }
 
-        if let path = defaultLocation, fs.exists(path) {
-            return try [AndroidSDK(host: host, path: path, fs: fs)]
-        }
-
-        return []
+    /// Location of the Android NDK installed by the `google-android-ndk-*-installer` family of packages available in Debian 13 "Trixie" and Ubuntu 24.04 "Noble".
+    /// These packages are available in non-free / multiverse and multiple versions can be installed simultaneously.
+    static var defaultDebianLocation: Path {
+        Path("/usr/lib/android-sdk")
     }
 }
diff --git a/Sources/SWBAndroidPlatform/CMakeLists.txt b/Sources/SWBAndroidPlatform/CMakeLists.txt
@@ -10,6 +10,7 @@ See http://swift.org/CONTRIBUTORS.txt for Swift project authors
 
 add_library(SWBAndroidPlatform
   AndroidSDK.swift
+  JavaProperties.swift
   Plugin.swift)
 SwiftBuild_Bundle(MODULE SWBAndroidPlatform FILES
   Specs/Android.xcspec)
diff --git a/Sources/SWBAndroidPlatform/JavaProperties.swift b/Sources/SWBAndroidPlatform/JavaProperties.swift
@@ -0,0 +1,32 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2025 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import Foundation
+internal import SWBUtil
+
+/// A simple representation of a Java properties file.
+///
+/// See `java.util.Properties` for a description of the file format. This parser is a simplified version that doesn't handle line continuations, etc., because our use case is narrow.
+struct JavaProperties {
+    private let properties: [String: String]
+
+    init(data: Data) throws {
+        properties = Dictionary(uniqueKeysWithValues: String(decoding: data, as: UTF8.self).split(whereSeparator: { $0.isNewline }).map(String.init).map {
+            let (key, value) = $0.split("=")
+            return (key.trimmingCharacters(in: .whitespaces), value.trimmingCharacters(in: .whitespaces))
+        })
+    }
+
+    subscript(_ propertyName: String) -> String? {
+        properties[propertyName]
+    }
+}
diff --git a/Sources/SWBAndroidPlatform/Plugin.swift b/Sources/SWBAndroidPlatform/Plugin.swift
@@ -52,9 +52,13 @@ struct AndroidEnvironmentExtension: EnvironmentExtension {
         switch context.hostOperatingSystem {
         case .windows, .macOS, .linux:
             if let latest = try? await plugin.cachedAndroidSDKInstallations(host: context.hostOperatingSystem).first {
+                let sdkPath = latest.path.str
+                let ndkPath = latest.preferredNDK?.path.str
                 return [
-                    "ANDROID_SDK_ROOT": latest.path.str,
-                    "ANDROID_NDK_ROOT": latest.ndks.last?.path.str,
+                    "ANDROID_HOME": sdkPath,
+                    "ANDROID_SDK_ROOT": sdkPath,
+                    "ANDROID_NDK_ROOT": ndkPath,
+                    "ANDROID_NDK_HOME": ndkPath,
                 ].compactMapValues { $0 }
             }
         default:
@@ -112,7 +116,7 @@ struct AndroidSDKRegistryExtension: SDKRegistryExtension {
             return []
         }
 
-        guard let androidNdk = androidSdk.latestNDK else {
+        guard let androidNdk = androidSdk.preferredNDK else {
             return []
         }
 
@@ -187,7 +191,7 @@ struct AndroidToolchainRegistryExtension: ToolchainRegistryExtension {
     let plugin: AndroidPlugin
 
     func additionalToolchains(context: any ToolchainRegistryExtensionAdditionalToolchainsContext) async throws -> [Toolchain] {
-        guard let toolchainPath = try? await plugin.cachedAndroidSDKInstallations(host: context.hostOperatingSystem).first?.latestNDK?.toolchainPath else {
+        guard let toolchainPath = try? await plugin.cachedAndroidSDKInstallations(host: context.hostOperatingSystem).first?.preferredNDK?.toolchainPath else {
             return []
         }
 
diff --git a/Sources/SWBUtil/FSProxy.swift b/Sources/SWBUtil/FSProxy.swift
@@ -879,9 +879,13 @@ public class PseudoFS: FSProxy, @unchecked Sendable {
 
     public func realpath(_ path: Path) throws -> Path {
         // TODO: Update this to actually return the link target when we support
-        // symlinks; for now it just returns the input, which seems reasonably
-        // correct.
-        return path
+        // symlinks; for now it just returns the input (or the link target if it's a symlink),
+        // which seems reasonably correct for simple cases.
+        do {
+            return try readlink(path)
+        } catch {
+            return path
+        }
     }
 
     public func readlink(_ path: Path) throws -> Path {
diff --git a/Tests/SWBAndroidPlatformTests/AndroidSDKTests.swift b/Tests/SWBAndroidPlatformTests/AndroidSDKTests.swift
