NOTE: Be warned, building C++ apps for android is much more complex than for Linux or Web. I recommend you to use Android Studio if you don't enjoy playing with build tools.
This readme is only here for fun and for developers that refuse to use the tools at their disposal.
If I was building a commercial app or anything that is published on the app store, I would use android studio instead. That being said, learning how to build an APK was kind-of fun, and I'm only doing these projects for fun.
To cross-compile raylib to Android, we can combine the instructions given by the conan and raylib docs:
In particular, I recommend the Raylib Wiki entry, it explains the minimal set of files and commands to generate an APK.
The raylib example is C++ code, but android runs java apps, right? Not quite, it turns out the android world is much more complex, but good news: your android app can run native binaries!
The android team provides an NDK, native development kit, which we can use to compile our C++ code for our desired phones. There are a few different things to consider when compiling with the NDK, like the phone's processor architecture, and the API level of the phone's Android version. This project uses conan to install the NDK and to configure those variables for us. Take a look at the conan profile for android.
Android can not run a native executable directly, instead we use the NDK to compile our raylib example as a shared library, that our app can load in. Take a look at how we make a shared library src/CMakeLists.txt from our example.
Note that our library has to use the native android APIs to manage the "window", get key inputs, and more, luckily raylib already implements this for us. We only have to add the native app glue that the NDK provides, for which we first need to find the NDK directory: CMakeLists.txt line 12. The app glue is then compiled into our shared library in src/CMakeLists.txt line 17.
Our native shared library can be loaded using a little bit of java, see our NativeLoader.java.
Then we only need two more things: an AndroidManifest.xml
that describes our app's metadata, and our app's icons in various resolutions.
Note that the icons need to follow this drawable-...dpi directory structure for android to find the right size icon
for your phone's homescreen.
Then we have all the components to build an android app. Building android apps is done using the android SDK. Let's see how, this diagram gives an overview of the life of an app:
In the diagram, our compiled libraylib_example.so is considered Native Code.
The icon's and any resources like models and our app icon are Resources.
And our small NativeLoader.java is part of the Source code.
We can see that the Source code goes through some ... steps, more precisely:
- We give the SDK tool
aaptour android manifest. This generates anR.javafile containing some basic code for our app. - We use the OpenJDK tool
javacto compile all our java code into JVM bytecode. - We use the SDK tool
d8to compile our JVM bytecode into Dalvik bytecode, also called "dex".
Then we have to zip all our dexed-code, native-code, and resource files into an APK, and voilà, an app that runs C++ 😎. Those steps can all be done by a little script package_apk.sh.
With all that explanation out of the way, here is the how to build the example app.
Conan can manage the NDK for us, but not the SDK.
The SDK download is hidden at the bottom of the studio download page,
the command line tools zip file. The easiest way to use the sdk is to put it in a path like: cmdline-tools/latest/.
For example:
$ ls ~/android/Sdk/cmdline-tools/latest/
bin lib NOTICE.txt source.propertiesTo install the desired SDK, use the sdk manager like:
~/android/Sdk/cmdline-tools/latest/bin/sdkmanager --install "platforms;android-34" "build-tools;34.0.0"And hit y to accept the terms and conditions.
If you use a different install path, or a different version, then please see the start of the package_apk script.
We need to generate a pair of keys for signing our development builds. I would highly recommend not using these keys for anything other than development builds.
And even then it's probably the best if you add this key store to your .gitignore file.
keytool -genkeypair -validity 1000 -dname "CN=raylib,O=Android,C=ES" -keystore raylib.keystore -storepass 'raylib' -keypass 'raylib' -alias projectKey -keyalg RSATo configure the NDK, please take a look at the android.profile.
We can then install our conan dependencies and build the shared library:
conan install -u -pr:b=default -pr:h=profiles/android.profile --build=missing --settings=build_type=Release .
# configure cmake
cmake -G Ninja --preset conan-android-release
# build for release
cmake --build --preset conan-android-releaseTo use the packaging script, please double-check that the environment variables at the top of the package_apk script are correct.
Then you should be able to run:
$ ./src/android/package_apk.shThe resulting APK is then ./game.apk.
You could send the resulting APK to your phone using any transfer method and install it from the phone.
Alternatively you can install it using the SDK tool adb.
First to install the platform tools and to start the daemon:
~/android/Sdk/cmdline-tools/latest/bin/sdkmanager --install "platform-tools"
sudo ~/android/Sdk/platform-tools/adb start-serverThen connect your phone to the PC see this for more information, check the connection with:
~/android/Sdk/platform-tools/adb devices -lAnd finally to install the APK run:
~/android/Sdk/platform-tools/adb install ./game.apkIf your APK can not be installed, or if your app crashes on startup, you could find more information in the logs using ADB.
~/Android/Sdk/platform-tools/adb logcat