This project comprises a collection of scripts to build a GNUstep toolchain for Android. The toolchain can then be used in an Android project to compile and run Objective-C code using the Foundation and CoreFoundation libraries.
The toolchain is built using the Android NDK (installed e.g. via Android Studio), and is set up to target Android API level 23 (6.0 / Marshmallow) and all common Android ABIs (armeabi-v7a, arm64-v8a, x86, x86_64).
The toolchain currently compiles the following libraries for Android:
- GNUstep Base Library (Foundation)
- GNUstep CoreBase Library (CoreFoundation)
- libobjc2 (using gnustep-2.0 runtime)
- libdispatch (official Apple release from the Swift Core Libraries)
- libffi
- libiconv
- libxml2
- libxslt
- ICU
Supported host platforms are macOS and Linux.
You must have the Android NDK installed. The toolchain assumes the following version to be installed via Android Studio’s SDK Manager:
- NDK (Side by side) – version 21.3.6528147 (r21d)
A different NDK version or location can be provided using the --ndk
flag (see below). Please note that NDK r21 (or later) is required, as earlier NDK releases contain Clang versions with bugs which prevent usage of the gnustep-2.0 Objective-C runtime.
Additionally, the following packages are required depending on your system.
macOS
Install required packages via Homebrew:
brew install git-lfs cmake autoconf automake libtool pkg-config
git lfs install
Linux
Install required packages via APT:
sudo apt install git git-lfs curl cmake make autoconf libtool pkg-config texinfo python3-distutils
git lfs install
Please note that you need to have CMake version 3.15.1 or later (for libdispatch).
Run the build.sh script to build the toolchain:
Usage: ./build.sh
--prefix INSTALL_ROOT Install toolchain into given directory (default: ~/Library/Android/GNUstep)
--dist-root DIST_ROOT Make toolchain relocatable to given path relative to home folder on other machines
(use "HOME" as placeholder for home folder, e.g. "HOME/Library/Android/GNUstep")
-n, --ndk NDK_PATH Path to existing Android NDK (default: ~/Library/Android/sdk/ndk/21.3.6528147)
-a, --abis ABI_NAMES ABIs being targeted (default: "armeabi-v7a arm64-v8a x86 x86_64")
-l, --level API_LEVEL Android API level being targeted (default: 23)
-b, --build BUILD_TYPE Build type "Debug" or "Release" or "RelWithDebInfo" (default: RelWithDebInfo)
-u, --no-update Don't update projects to latest version from GitHub
-c, --no-clean Don't clean projects during build (e.g. for building local changes, only applies to first ABI being built)
-p, --patches DIR Apply additional patches from given directory
-o, --only PHASE Build only the given phase (e.g. "gnustep-base", requires previous build)
-h, --help Print usage information and exit
The toolchain builds and installs the GNUstep toolchain into the following location ($GNUSTEP_HOME
):
- macOS:
~/Library/Android/GNUstep
- Linux:
~/Android/GNUstep
The build for each supported ABI is installed into its separate subfolder at that location (both libraries and header files differ per ABI).
To use the toolchain from an Android project, you can use $GNUSTEP_HOME/$ABI_NAME/bin/gnustep-config
to obtain various flags that should be used to compile and link Objective-C files, e.g.
gnustep-config --variable=CC
gnustep-config --objc-flags
(or--debug-flags
)gnustep-config --base-libs
Call gnustep-config --help
to obtain the full list of available variables.
- GNUstep base currently has no native integration between the Android run-loop and NSRunLoop or the libdispatch main queue, so things like
-performSelector:withObject:afterDelay:
or dispatching ondispatch_get_main_queue()
will not work out of the box. An integration depends on the setup of the app (e.g. whether using Android Studio, Qt, or something else), and is possible to add in the app by swizzing NSRunLoop. Feel free to open an issue if this is of interest to you and you would like more information. - GNUstep Base is integrated with Android’s app-specific storage and uses the path returned by
Context.getFilesDir()
asNSHomeDirectory()
and when querying for directory paths (NSLibraryDirectory
,NSApplicationSupportDirectory
, etc.). It also usesContext.getCacheDir()
asNSTemporaryDirectory
andNSCachesDirectory
(withNSUserDomainMask
). - GNUstep Base is further integrated with the Android asset manager, and supports accessing the app’s resources from
[NSBundle mainBundle]
via APIs such as-pathForResource:ofType:
and-URLForResource:ofType:
, and reading them using NSFileManager, NSFileHandle, and NSDirectoryEnumerator APIs. This is done by returning paths from NSBundle APIs with a fixed, fake, per-app prefix (Context.getPackageCodePath()
without extension +/Resources
), which internally get routed through the NDK’s AAsset API for reading. - Note that NSDirectoryEnumerator is not able to enumerate directories in the app’s main bundle due to a limitation of the AAssetDir API.
- The app must call
GSInitializeProcessAndroid()
(defined inNSProcessInfo.h
) on launch in order to initialize the above Android-specific functionality in GNUstep. - GNUstep Base doesn’t currently get the system languages on Android, which combined with the inability to list directories in the main bundle (see above) means that
NSLocalizedString()
won’t work out of the box even if localized strings are present in the app’s assets. As a workaround, the app should manually call-[NSUserDefaults setUserLanguages:]
with a list of supported locales ordered by the user’s system language preferences. - GNUstep Base will also currently not return the system locale as the current
NSLocale
on Android (the current locale will always default toen_US_POSIX
). As a workaround, the app can manually set the system’s locale identifier for the key"Locale"
in NSUserDefaults, and use-[NSLocale autoupdatingCurrentLocale]
to retreive the locale. - Android will not output stdout or stderr to logcat by default, which might cause some log or error output from GNUstep or other libraries to be missing. You can run a thread in your app to write these streams to the Android log to work around this, which is recommended for debugging.
For the last three points above please refer to GSInitialize.m in the examples for details.
The android-examples repository contains example projects using this project.
Based on original work by Ivan Vučica.