Skip to content

Commit 9f1853b

Browse files
tripleftriplef
committed
Updated readme
1 parent a7f3118 commit 9f1853b

1 file changed

Lines changed: 56 additions & 36 deletions

File tree

‎README.md‎

Lines changed: 56 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ This project comprises a collection of scripts to build a GNUstep toolchain for
77

88
The toolchain is built using the Android NDK (installed e.g. via [Android Studio](https://developer.android.com/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).
99

10+
1011
Libraries
1112
---------
1213

@@ -22,18 +23,63 @@ The toolchain currently compiles the following libraries for Android:
2223
* [libxslt](https://github.com/GNOME/libxslt)
2324
* [ICU](https://github.com/unicode-org/icu)
2425

26+
2527
Requirements
2628
------------
2729

2830
Supported host platforms are macOS and Linux.
2931

30-
You must have the Android NDK installed. The toolchain assumes the following version to be installed via [Android Studio](https://developer.android.com/studio)’s SDK Manager:
32+
The toolchain requires the Android NDK, which can be installed via [Android Studio](https://developer.android.com/studio)’s SDK Manager. The NDK installation will be located using the `ANDROID_NDK_ROOT` environment variable if set, or otherwise it will use the latest version in `~/Library/Android/sdk/ndk` (macOS) / `~/Android/sdk/ndk` (Linux). A different NDK path can also be provided using the `--ndk` flag when building the toolchain (see below).
33+
34+
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.
35+
36+
37+
Installation
38+
------------
39+
40+
To install a pre-built release, download it from [the releases on GitHub](https://github.com/gnustep/tools-android/releases) and unpack the "GNUstep" folder into the following location depending on your OS (`$GNUSTEP_HOME`):
41+
42+
* macOS: `~/Library/Android/GNUstep`
43+
* Linux: `~/Android/GNUstep`
44+
45+
46+
Using the Toolchain
47+
-------------------
3148

32-
* NDK (Side by side) _– version 22.1.7171670 (r22b)_
49+
The [android-examples](https://github.com/gnustep/android-examples) repository contains Android Studio and Qt example projects using this project that can be used as templates for integrating Objective-C code into new or existing Android projects.
3350

34-
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.
51+
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.:
3552

36-
Additionally, the following packages are required depending on your system.
53+
* `gnustep-config --variable=CC`
54+
* `gnustep-config --objc-flags` (or `--debug-flags`)
55+
* `gnustep-config --base-libs`
56+
57+
Call `gnustep-config --help` to obtain the full list of available variables.
58+
59+
60+
Status and Known Issues
61+
-----------------------
62+
63+
The toolchain is being used in production in an award-winnning music app available on Google Play.
64+
65+
Following are some notes and known issues about using GNUstep on Android.
66+
67+
* 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 on `dispatch_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.
68+
* GNUstep Base is integrated with Android’s [app-specific storage](https://developer.android.com/training/data-storage) and uses the path returned by `Context.getFilesDir()` as `NSHomeDirectory()` and when querying for directory paths (`NSLibraryDirectory`, `NSApplicationSupportDirectory`, etc.). It also uses `Context.getCacheDir()` as `NSTemporaryDirectory` and `NSCachesDirectory` (with `NSUserDomainMask`).
69+
* GNUstep Base is further integrated with the [Android asset manager](https://developer.android.com/reference/android/content/res/AssetManager), 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](https://developer.android.com/ndk/reference/group/asset) API for reading.
70+
* Note that NSDirectoryEnumerator is not able to enumerate directories in the app’s main bundle due to a [limitation](https://issuetracker.google.com/issues/140538113) of the AAssetDir API.
71+
* The app must call `GSInitializeProcessAndroid()` (defined in `NSProcessInfo.h`) on launch in order to initialize the above Android-specific functionality in GNUstep.
72+
* 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.
73+
* GNUstep Base will also currently not return the system locale as the current `NSLocale` on Android (the current locale will always default to `en_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.
74+
* 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.
75+
76+
For the last three points above please refer to [GSInitialize.m](https://github.com/gnustep/android-examples/blob/master/hello-objectivec/app/src/main/cpp/GSInitialize.m) in the examples for details.
77+
78+
79+
Prerequisites for Building
80+
--------------------------
81+
82+
The following packages are required for building the toolchain.
3783

3884
**macOS**
3985

@@ -55,17 +101,18 @@ git lfs install
55101

56102
Please note that you need to have CMake version 3.15.1 or later ([for libdispatch](https://github.com/apple/swift-corelibs-libdispatch/blob/master/CMakeLists.txt#L2)).
57103

58-
Usage
59-
-----
60104

61-
Run the [build.sh](build.sh) script to build the toolchain:
105+
Building the Toolchain
106+
----------------------
107+
108+
Run the [build.sh](build.sh) script to build the toolchain yourself:
62109

63110
```
64111
Usage: ./build.sh
65-
--prefix INSTALL_ROOT Install toolchain into given directory (default: ~/Library/Android/GNUstep)
112+
--prefix INSTALL_ROOT Install toolchain into given directory (default: see below)
66113
--dist-root DIST_ROOT Make toolchain relocatable to given path relative to home folder on other machines
67114
(use "HOME" as placeholder for home folder, e.g. "HOME/Library/Android/GNUstep")
68-
-n, --ndk NDK_PATH Path to existing Android NDK (default: ~/Library/Android/sdk/ndk/22.1.7171670)
115+
-n, --ndk NDK_PATH Path to existing Android NDK (default: ANDROID_NDK_ROOT)
69116
-a, --abis ABI_NAMES ABIs being targeted (default: "armeabi-v7a arm64-v8a x86 x86_64")
70117
-l, --level API_LEVEL Android API level being targeted (default: 23)
71118
-b, --build BUILD_TYPE Build type "Debug" or "Release" or "RelWithDebInfo" (default: RelWithDebInfo)
@@ -83,33 +130,6 @@ The toolchain builds and installs the GNUstep toolchain into the following locat
83130

84131
The build for each supported ABI is installed into its separate subfolder at that location (both libraries and header files differ per ABI).
85132

86-
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.
87-
88-
* `gnustep-config --variable=CC`
89-
* `gnustep-config --objc-flags` (or `--debug-flags`)
90-
* `gnustep-config --base-libs`
91-
92-
Call `gnustep-config --help` to obtain the full list of available variables.
93-
94-
Status and Known Issues
95-
-----------------------
96-
97-
* 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 on `dispatch_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.
98-
* GNUstep Base is integrated with Android’s [app-specific storage](https://developer.android.com/training/data-storage) and uses the path returned by `Context.getFilesDir()` as `NSHomeDirectory()` and when querying for directory paths (`NSLibraryDirectory`, `NSApplicationSupportDirectory`, etc.). It also uses `Context.getCacheDir()` as `NSTemporaryDirectory` and `NSCachesDirectory` (with `NSUserDomainMask`).
99-
* GNUstep Base is further integrated with the [Android asset manager](https://developer.android.com/reference/android/content/res/AssetManager), 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](https://developer.android.com/ndk/reference/group/asset) API for reading.
100-
* Note that NSDirectoryEnumerator is not able to enumerate directories in the app’s main bundle due to a [limitation](https://issuetracker.google.com/issues/140538113) of the AAssetDir API.
101-
* The app must call `GSInitializeProcessAndroid()` (defined in `NSProcessInfo.h`) on launch in order to initialize the above Android-specific functionality in GNUstep.
102-
* 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.
103-
* GNUstep Base will also currently not return the system locale as the current `NSLocale` on Android (the current locale will always default to `en_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.
104-
* 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.
105-
106-
For the last three points above please refer to [GSInitialize.m](https://github.com/gnustep/android-examples/blob/master/hello-objectivec/app/src/main/cpp/GSInitialize.m) in the examples for details.
107-
108-
109-
Examples
110-
--------
111-
112-
The [android-examples](https://github.com/gnustep/android-examples) repository contains example projects using this project.
113133

114134
Acknowledgements
115135
----------------

0 commit comments

Comments
 (0)