Build for Android

Our apps run on Android. Here we describe how to build an uploadable ".apk" for a given application. On github, we distribute the material to build the pmx and g4exa applications, then you can train on these. (It is better to start with pmx which is much more lighter than g4exa).

Note that under our github, there is also the inexlib_android repository with two little apps doing some GL-ES by using the "native way" (quite no java here too).

Have an Android SDK and a NDK

You have first to install an Android "SDK" (Software Development Kit) and a "NDK" (Native Development Kit). Here we refer to the web to install these. What we did to work on macOS had been to install a SDK android-sdk_r16-macosx (some time ago), and a android-ndk-r17 that had been installed under /usr/local/Android :

    /usr/local/Android/android-sdk_r16-macosx
    /usr/local/Android/android-ndk-r17    

The "source setup" scripts bush/setup/android-r17[.csh,.sh] are tuned to set properly the PATH variable for these kits so that programs as "ndk-build", "android" are found. You have to provide some similar setup scripts according your SDK and NDK versions. After having "source setup" one of them according your shell, executing "android" will launch the "Android SDK Manager" that may permit you to update your installation to the latest "Android SDK Tools" and "API" (24.0.2 and API 28 for us) from the main panel :

    macOS> cd <some_path>/<app>/<app>/Android
      csh> source ../../bush/setup/android-<version>.csh
     ( sh> . ../../bush/setup/android-<version>.sh)
    macOS> android
    <update your SDK Tools and API>

To build an app

To build an app on macOS :

    macOS> <install a SDK and a NDK>
    macOS> <if needed, create a bush/setup/android-<version> setup script>
    macOS> cd <some_path>/<app>/<app>/Android
      csh> source ../../bush/setup/android-<version>.csh
     ( sh> . ../../bush/setup/android-<version>.sh)
    macOS> <if needed, edit ant.properties to adapt java.target and java.source to your java version>
    macOS> <if needed, edit project.properties to adapt target to your NDK version>
    macOS> <if needed, edit jni/Application.mk to adapt APP_PLATFORM to the minimal API you want>
    macOS> <if needed, edit AndroidManifest.xml to adapt android:minSdkVersion to the minimal API you want>
    macOS> ./genkey # to produce a <app>.jks key file with your own password by using the keytool app.

when done :

    macOS> ../../bush/and_build

At some point, it will prompt you twice for you key password to sign the .apk. If the build went fine, it produces a :

    ./bin/<app>-release.apk

ready to be uploaded on your device.

If no Android device is connected to your computer, as and_build attempts by default to upload the .apk by using the "adb install" command, you should see a list of :

    - waiting for device -
    ...
    - waiting for device -

You have to stop and_build with CTRL-C.

To upload to an Android device, you have first to activate the "development options" for this device. It is oftenly found within the Settings menu, but as the way to activate them may vary from one version of Android to another, you have to find by yourself on the web how to do that for your own device. When done, and if having connected your device to your computer, the and_build should finish with somethings as :

    7890 KB/s (21835291 bytes in 2.702s)
            pkg: /data/local/tmp/<app>-release.apk
    Success

If so, jump on your device and activate the app ! :-). (Obviously, upper numbers depend of the app).

Notes

Recent SDK/NDK build for a lot of architectures (arm64-v8a, armeabi-v7a, x86, x86_64 for us). This may take a lot of time (especially with Geant4 related apps), and if being in a development phase (not for distribution), it is better to build only for the architecture corresponding to your development device. For example, if being a "arm64-v8a", as for the Galaxy Note 8, then you can set in :

    jni/Application.mk

the APP_ABI to :

    APP_ABI := arm64-v8a 

(the default being "all"). Then and_build will build only arm64-v8a binaries and put only these in the .apk.

WARNING : if touching a jni/.mk file, the Android build system will recompile all files !

To upload/install only :

    macOS> ../../bush/and_build -install

To build only the java part and the .apk :

    macOS> ../../bush/and_build -no_ndk

To be verbose when compiling :

    macOS> ../../bush/and_build -v

To have some traceback on your computer when lauching the app whilst your device is still connected :

    macOS> adb logcat
    <launch app on your device>

Why not using bush ?

bush scripts contain material to compile C/C++ files with the compiler coming with a NDK, but they are tuned for the moment to work with android-ndk-r10e and for the lonly armv5te architecture. Moreover the java part and the "build .apk" part use anyway ant, the <app>/Android/build.xml, [ant,local,project].properties and build files of the Android SDK. Then, for the moment, bush scripts are not standalone relative to the SDK build system and for consistency reasons we still promote to build by using the Android SDK build/make system as described upper.

If anyway you want to attemtp to build with bush, you have to customize scripts to build for a particular SDK/NDK and architecture. The files to customize are bush/[use_cc, use_cpp, use_sys, plugin] by tuning what is under "if build_sdk_android". When done, to trigger a build with bush, then do :

    macOS> cd <some_path>/<app>/<app>/mgr   # mgr and not Android
    macOS> ./build -android

At end you should have a .apk in :

    ./bin_sdk_android/<app>-release.apk

On a platform having "parallel", a "./build -android -parallel" may be much faster than using the Android SDK make system.