The Android module contains special build rules to create an Android application from start to finish.

The first step when using the android module is to set the SDK version. Doing so will detect the appropriate NDK and SDK compilers and set up some architecture-specific items.

# This goes in the Jamfile.

android.SDK 19 ;

Next, some combination of the following rule calls (and any others described below) are needed to build a full Android .apk for installation and distribution.

local JAVA_SRCS =
    org/libsdl/app/SDLActivity.java
    org/jamplus/sdltest/sdltestActivity.java
;
android.SourcePaths : src sdl2/android-project/src ;
android.Application : $(JAVA_SRCS) ;
 
android.Assets : assets ;
android.UncompressedAssetExtensions : dat ;
android.NativeLibraries : sdl2main sdl2 ;
android.Sign : $(SUBDIR)/my-keystore.keystore keystorepassword keyalias keypassword ;
android.Package ;

An Android build is initiated with a C.TOOLCHAIN of android/CONFIG:

>jam C.TOOLCHAIN=android/release

android.Package creates some additional useful targets:

install:TARGET - Put this on the Jam command-line to install the .apk to the USB-connected Android device. uninstall:TARGET Put this on the Jam command-line to uninstall the .apk.

List of Rules

Rules

rule android.Application TARGET : SOURCES

Compiles SOURCES and links them into TARGET.

Parameters

TARGET	The target to link `SOURCES` into. The target name is given without extension. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of `.java` to link into the application. Object and compiled Windows resource files may also be passed with this list.

android.Application sdltest :
    org/libsdl/app/SDLActivity.java
    org/jamplus/sdltest/sdltestActivity.java
;

rule android.Assets TARGET : DIRECTORY

An Android application may contain user assets. The android.Assets rule allows specification of the directory to be recursed and stored within the Android .apk application package.

Call android.Assets before calling android.Package.

Parameters

TARGET	The target to attach the assets directory to.
DIRECTORY	The base directory to use for the assets. There can only be one directory specified.

# Store all files and directories found by recursing c:/mygame/all_of_the_assets
# within the Android package.
android.Assets : c:/mygame/all_of_the_assets ;

rule android.JarDirectories TARGET : DIRECTORIES

Specify paths to search when locating prebuilt JARs during the android.Library and android.Package rule calls.

Parameters

TARGET	The target to apply the JAR search `DIRECTORIES` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the directories are applied to every target needing them.
DIRECTORIES	The list of directories to use when searching for JAR files. If relative directories are specified, they are rooted against the current rule SubDir TOP d1...dn : SUBNAME.

# Search for extra prebuilt JARs within the $(SUBDIR)/libs directory.

android.JarDirectories : libs ;

rule android.Library TARGET : SOURCES : OPTIONS

android.Library takes a list of Java SOURCES and builds a Java library out of them. It takes into account the following:

Any directories given for .jar searching via rule android.JarDirectories TARGET : DIRECTORIES.

Any prebuilt .jar files listed via rule android.PrebuiltJars TARGET : LIBRARIES.

Any prebuilt .aar files listed via rule android.PrebuiltAars TARGET : LIBRARIES. Any AndroidManifest.xml files within the .aar files are merged into a final AndroidManifest.xml for rule android.Package TARGET [ : TOOLCHAINS [ : OPTIONS ] ].

The search paths for .java files specified with rule android.SourcePaths TARGET : DIRECTORIES.

An AndroidManifest.xml for the target whose target name is given with rule android.Manifest TARGET : MANIFEST.

A package name given with rule android.Package TARGET [ : TOOLCHAINS [ : OPTIONS ] ] or automatically derived from the target's AndroidManifest.xml.

An assets directory given via rule android.Assets TARGET : DIRECTORY.

A resources directory given by rule android.Resources TARGET : DIRECTORIES.

Dependencies are automatically derived, where possible, by looking at the contents of the .java files.

The resulting file is a .jar file.

Parameters

TARGET	The target to assign the `FLAGS` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
SOURCES	The list of `.java` and `.aidl` files to build into a `.jar`.
OPTIONS	Unused (except that rule android.Application TARGET : SOURCES just calls `android.Library` with `OPTIONS` of `application`).

android.Library MyGame :
    the.java
    list.java
    of.java
    files.java
;

rule android.LinkJars TARGET : LIBRARIES

Makes TARGET depend on Jam-generated .jar LIBRARIES and uses them during linking.

Parameters

TARGET	The target to link `LIBRARIES` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
LIBRARIES	The list of libraries to apply. These libraries are those generated from the rule android.Library TARGET : SOURCES : OPTIONS rule. They do not include prebuilt libraries. To link prebuilt libraries, use the rule android.PrebuiltJars TARGET : LIBRARIES rule.

android.LinkJars MyGame : MyLibrary ;

rule android.Manifest TARGET : MANIFEST

Assigns MANIFEST to be the "AndroidManifest.xml" file for this TARGET.

This rule is unneeded if MANIFEST is just an AndroidManifest.xml file found within $(SUBDIR).

Parameters

TARGET	The target to assign the `MANIFEST` to.
MANIFEST	The target name of the `AndroidManifest.xml`.

# Use an AndroidManifest.xml within $(SUBDIR).

android.Manifest MyGame : AndroidManifest.xml ;

rule android.NativeLibraries TARGET : NATIVE_LIBRARIES

Makes TARGET depend on Jam-generated NATIVE_LIBRARIES. These are packaged during the rule android.Package TARGET [ : TOOLCHAINS [ : OPTIONS ] ] process.

Parameters

TARGET	The target to package the `NATIVE_LIBRARIES` into. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
NATIVE_LIBRARIES	The list of libraries to apply. These are shared libraries are those generated from the rule C.Library TARGET : SOURCES [ : OPTIONS ] rule. They do not include prebuilt libraries. To package native prebuilt libraries, use the rule android.NativePrebuiltLibraries TARGET : NATIVE_PREBUILT_LIBRARIES rule.

C.Library MyNativeLibrary : blah.cpp : shared ;
android.NativeLibraries MyGame : MyNativeLibrary ;
android.Package ;

rule android.NativePrebuiltLibraries TARGET : NATIVE_PREBUILT_LIBRARIES

Makes TARGET depend on preexisting shared NATIVE_PREBUILT_LIBRARIES. These are packaged during the rule android.Package TARGET [ : TOOLCHAINS [ : OPTIONS ] ] process.

Parameters

TARGET	The target to package the `NATIVE_PREBUILT_LIBRARIES` into. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
NATIVE_PREBUILT_LIBRARIES	The list of native prebuilt shared libraries to apply. These libraries are shared libraries existing somewhere in the filesystem and are specified without an extension and without the leading 'lib' prefix. For shared libraries generated from the rule C.Library TARGET : SOURCES [ : OPTIONS ] rule, use the rule android.NativeLibraries TARGET : NATIVE_LIBRARIES rule.

# Packages libmain.so into the MyGame.apk.
android.NativePrebuiltLibraries MyGame : main ;
android.Package ;

rule android.NativePrebuiltLibraryDirectories TARGET : DIRECTORIES

For the given TARGET, search DIRECTORIES for any libraries requested via rule android.NativeLibraries TARGET : NATIVE_LIBRARIES. This rule must be called before rule android.Package TARGET [ : TOOLCHAINS [ : OPTIONS ] ].

Native libraries are searched for the following order:

Whatever SEARCH directories the user added.

The directories given through DIRECTORIES with an architecture appended. Current architectures are arm, armeabi-v7a, and x86.

Parameters

TARGET	The target to assign the native prebuilt library search `DIRECTORIES` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified. If `TARGET` is `*`, the defines are made available globally.
DIRECTORIES	The list of directories to apply. Absolute paths are used directly. Relative paths are local to `$(SUBDIR)`. That is, they are relative to the subdirectory specified via SubDir.

# Search for libmain.so in the current directory and in c:/some/directory/[architecture].
android.NativePrebuiltLibraryDirectories MyGame : c:/some/directory ;
android.NativePrebuiltLibraries MyGame : main ;
android.Package ;

rule android.Package TARGET [ : TOOLCHAINS [ : OPTIONS ] ]

In order to output a final .apk to be installed on an Android device, the android.Package rule must be called. If TOOLCHAINS is specified, those requested toolchain components are packaged into the .apk. The passed in OPTIONS include additional build instructions such as automatic installation on a USB-connected Android device.

android.Package should be the last rule called in a sequence of rule calls describing the build of an Android application.

Parameters

TARGET	The target to build.
TOOLCHAINS	(optional) The list of toolchains used to build multiple architectures for the package. The default toolchain is used if none are specified.
OPTIONS	The list of options applied when building the package.

install - Installs the .apk on the USB-connected Android device.

# Build a package for the current target using the active toolchain.
android.Package ;
 
# Build a package for the target MyGame using the active toolchain.
android.Package MyGame ;
 
# Build a package for the target MyGame using the active toolchain and install it to the USB-connected Android device.
android.Package MyGame : : install ;

rule android.PackageName TARGET : PACKAGE_NAME

Specify the package name for TARGET, generally in the form of com.module.submodule.

By default, this is read from the AndroidManifest.xml, so only call this if an override is needed.

Parameters

TARGET	The target to assign the link `FLAGS` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
PACKAGE_NAME	The package name to use.

android.PackageName MyGame : com.mycompany.mygame ;

android.Package

rule android.PackageOutputPath TARGET : PACKAGE_OUTPUT_PATH

Assigns the location to output the final .apk to. This rule must be called prior to android.Package.

Parameters

TARGET	The target to build.
PACKAGE_OUTPUT_PATH	The directory to output the final .apk to. If a relative path is provided, that path is rooted against `$(SUBDIR)`.

android.PackageOutputPath MyGame : package ;

android.Package ;

rule android.PrebuiltAars TARGET : LIBRARIES

List out .aar files that android.Library or android.Application need to link against. Makes TARGET depend on these preexisting .aar files.

By default, .aar files are searched for in $(SUBDIR)/libs.

Parameters

TARGET	The target to link the `LIBRARIES` into. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
LIBRARIES	The list of preexisting `.aar` files to use as part of the build, specified without the `.aar` extension.

android.PrebuiltAars :
        appcompat-v7-23.1.1
        internalexternalpaths
        play-services-base-8.3.0
        play-services-basement-8.3.0
        play-services-drive-8.3.0
        play-services-games-8.3.0
        play-services-nearby-8.3.0
        play-services-plus-8.3.0
        support-v4-23.1.1
        unityads-release
;

rule android.PrebuiltJars TARGET : LIBRARIES

List out the .jar files that android.Library or android.Application need to link against. Makes TARGET depend on these preexisting .jar files.

The LIBRARIES specified are, by default, searched for in $(SUBDIR).

Parameters

TARGET	The target to link the `LIBRARIES` into. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
LIBRARIES	The list of preexisting `.jar` files to use as part of the build, specified without the `.jar` extension.

android.PrebuiltJars :
        AndroidStore
        AndroidStoreAmazon
        in-app-purchasing-2.0.61
        SoomlaAndroidCore
        square-otto-1.3.2
        unity-classes
        UnityAndroidStore
        UnitySoomlaAndroidCore
;

rule android.ProductVersion TARGET : VERSION_NAME : VERSION_CODE

Sets the android.versionName and android.versionCode properties in a build.gradle file.

Parameters

VERSION_NAME	The version name to be put into the `AndroidManifest.xml`'s `android:versionName`.
VERSION_CODE	The version code to be put into the `AndroidManifest.xml`'s `android:versionCode`.

android.ProductVersion THE_TARGET : 1.0 : 5 ;

rule android.Resources TARGET : DIRECTORIES

Sets DIRECTORIES as the locations to search for Android resources at when TARGET is built.

Parameters

TARGET	The target to which the resource search `DIRECTORIES` should be applied. If not specified, `TARGET` defaults to the active target set via ActiveTarget.
DIRECTORIES	The list of directories to search for resources. Relative directories are rooted against `$(SUBDIR)`.

android.Resources :
        ../unity-android-resources/res
        res
;

rule android.SDK SDK_VERSION : ARCHITECTURE

Sets the Android SDK_VERSION and ARCHITECTURE for the toolchain. Call this before any other android.* rules.

android.SDK attempts detection number of Android-specific tools and SDKs:

If the variable NDKROOT is not specified, the location of the Android NDK is searched for in an OS-dependent fashion.

On Windows, c:/Program Files (x86)/Android and then c:/ is searched for a directory named android-ndk and a couple versioned derivatives.

Afterward, C.ARCHITECTURE is evaluated, and various compilation and linker flags are setup for use with the NDK.

Next, C.COMPILER is evaluated, and an NDK compiler toolchain is selected based on whether C.COMPILER is set to gcc or clang.

The Android SDK is detected next. If ANDROID_SDK_ROOT is set to a path, that path is assumed to be the root of the Android SDK toolchain. Otherwise, an OS-dependent default is chosen:

On Windows, c:/Program Files (x86)/Android/android-sdk is assumed to contain a properly installed Android SDK.

Parameters

SDK_VERSION	Defaults to `19`.
ARCHITECTURE	Defaults to `armv7-a`.

android.SDK 19 : armv7-a ;

rule android.SDKCompileVersion TARGET : SDK_COMPILE_VERSION

Sets the Android SDK_COMPILE_VERSION to build against. Corresponds to the android.compileSdkVersion property in a build.gradle file.

Parameters

SDK_COMPILE_VERSION Defaults to the version specified by rule android.SDK SDK_VERSION : ARCHITECTURE.

android.SDKCompileVersion THE_TARGET : 30 ;

rule android.SDKMinimumVersion TARGET : SDK_MINIMUM_VERSION

Sets the Android SDK_MINIMUM_VERSION to ensure a build against. Corresponds to the android.minSdkVersion property in a build.gradle file.

Parameters

SDK_MINIMUM_VERSION Defaults to the version specified by rule android.SDK SDK_VERSION : ARCHITECTURE.

android.SDKMinimumVersion THE_TARGET : 24 ;

rule android.Sign TARGET : KEYSTORE_PATH_PASSWORD_KEY

Sets up the keystore information for the Android package. android.Sign must be called before android.Package.

Parameters

TARGET	The target to sign. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
KEYSTORE_PATH_PASSWORD_KEY	This parameter contains 4 entries, the path to the keystore, the password of the keystore, the key to use when accessing the keystore, and the password.

android.Sign : $(SUBDIR)/my-keystore.keystore keystorepassword keyalias keypassword ;

rule android.SourcePaths TARGET : DIRECTORIES

Specify the source path for the Java files being built by TARGET. android.SourcePaths must be called before android.Application or android.Library.

Parameters

TARGET	The target to assign the Java search path `DIRECTORIES` to. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
DIRECTORIES	The list of directories to scan to find `.java` files. A given directory may either be absolute or relative. If relative, it is assumed to be based off of `$(SUBDIR)`.

# Find com/mycompany/mylibrary/file.java at $(SUBDIR)/org/com/mycompany/mylibrary/file.java.

android.SourcePaths MyGame : org ;

rule android.UncompressedAssetExtensions TARGET : UNCOMPRESSED_ASSET_EXTENSIONS

Specify extensions to leave uncompressed when building the .apk. This must be called before android.Package.

Parameters

TARGET	The target to leave the uncompressed file entries within. `TARGET` is optional if rule ActiveTarget TARGET has been specified.
UNCOMPRESSED_ASSET_EXTENSIONS	The list of extensions to leave uncompressed. Do not include a period in front of the extension.

# Leave .zip and .dat files uncompressed.

android.UncompressedAssetExtensions MyGame : zip dat ;