Building Android apps with Genero

Genero provides a command-line tool to create applications for Android™ devices.

Basics

Genero mobile apps for Android are distributed as AAB or APK packages, like any other Android app.

AAB packages can by published on the Google Play Store. To install the app from an AAB package onto your development device or emulator, you need the bundletool utility.
APK packages (the former package format) can installed onto your development device or emulator. APK packages cannot be uploaded to the Google Play Store.

Genero provides the gmabuildtool command line tool, to build the AAB/APK packages for your mobile application.

For more details about Android packages and bundles, see https://developer.android.com/guide/app-bundle.

Important: You need to comply with some Google conditions before publishing your app on the Play Store. This topic describes how the gmabuildtool tool builds Google Play Store ready packages.

For testing purposes, the tool can deploy APK packages and automatically launch the app on a specific device or emulator.

The gmabuildtool has also an option to update the Android SDK and an option to manage scaffold archives.

Note: This documentation section implies that you are familiar with Android app programming concepts and requirements. For example, you will need the Android SDK tools to be installed (and up to date) to build your Android apps. For more details, visit the Android SDK tools download page.

Prerequisites

Before starting the command line tool to build or deploy the app, fulfill the following prerequisites:

The Genero BDL development environment (FGLDIR) must be installed to compile your program files.
The Java JDK must be installed.
Important:
JDK version 8 is required to build Android apps. For the latest information regarding supported Java versions, system requirements and Java support, please refer to the Supported platforms and databases document, available on the "Products" download page of the Four Js Web site.
The GMA software components must be installed.
The GMA buildtool and GMA binary archive are provided in the GMA distribution archive (fjs-gma-*.zip).
To set up the GMA installation directory, perform the following steps:
1. Create a dedicated directory (gma-install-dir)
2. Extract the content of the fjs-gma-*.zip.
3. Add the gma-install-dir directory to your PATH environment variable, in order to find the gmabuildtool command.
The gma-install-dir will contain the gmabuildtool command, and the original GMA scaffold archive (gma-install-dir/artifacts).
The Android SDK must be installed (an internet connection is required to download the SDK packages). For more details, see Install Genero Mobile for Android.
Download/upgrade the required Android SDK packages, by using the gmabuildtool updatesdk ... command.
Note: Execute the gmabuildtool updatesdk ... command every time a new version of the GMA buildtool and GMA binary archive is installed.
For more details, see Update the Android SDK with the GMA buildtool.
Android-specific app resources such as icons (in all required sizes) are required, along with the application program files.
To install AAB packages on your development device or emulator, get the bundletool utility (see https://github.com/google/bundletool/releases).
If you plan to publish your app on Google Play, register to Google Play as a developer and create a Google Play project.

Environment settings

Define the following environment variables before starting the command-line buildtool:

Android SDK environment settings (ANDROID_SDK_ROOT, PATH)
Java JDK environment settings (JAVA_HOME, PATH)

Update the Android SDK with the GMA buildtool

After a fresh installation of the GMA buildtool and GMA binary archive, upgrade the Android SDK, to download all required Android SDK packages, with the gmabuildtool updatesdk ... command.

The Android SDK installation directory is required for the SDK update, and is found in ANDROID_SDK_ROOT environment variable, or with the --android-sdk option:

gmabuildtool updatesdk
    --android-sdk /use/local/32bits/android-sdk/r22.6.2

Use the --accept-licenses option to silently accept all Android SDK licenses.

gmabuildtool updatesdk
    --accept-licenses
    ...

If you need to specify a proxy to download the Android SDK, use the --proxy-host and --proxy-port options:

gmabuildtool updatesdk
    --proxy-host amadeus --proxy-port 3232
    ...

Use the --no-install-extras option to skip the installation of extra SDK modules such as Google's driver for Windows® and the HAXM for Windows and OS X:

gmabuildtool updatesdk
    --no-install-extras
    ...

On Windows and Mac® extras may be installed if --no-install-extras option is not used. The installation is preceded by a prompt asking the user to continue with the installation. Use the --no-interactions option to skip user interaction. This option answers yes silently to the prompt for permission to install.

Note: This option also silently accepts licenses.

gmabuildtool
updatesdk --no-interactions

is the same as the command

gmabuildtool updatesdk
--no-interactions --accept
licenses

gmabuildtool updatesdk
    --no-interactions
    ...

Manage GMA scaffold archives

The GMA scaffold archives can be managed by the gmabuildtool scaffold ... command.

In order to get the list of plugins installed in the GMA development environment, use the --list-plugins option:

$ gmabuildtool scaffold --list-plugins
...
cordova-plugin-device-motion.aar
cordova-plugin-media.aar
...

To install additional plugins in the GMA installation directory, use the --install-plugins option, for example:

$ gmabuildtool scaffold --install-plugins path-to-plugin-sources

For more usage examples, see Cordova plugins.

Building AAB/APK packages

The gmabuildtool build ... command creates the AAB and APK packages from a set of files, using the build options passed as parameter:

gmabuildtool build
    ... build options ...

The process will be explained in details in the next sections of this topic.

For a complete description of the build command options, see gmabuildtool.

Gradle build cache

To build Android apps, the GMA buildtool uses the Gradle toolkit.

Gradle can speed up AAB/APK creation time, by reusing outputs saved in a cache produced from previous builds. The gmabuildtool command uses the Gradle build cache.

On Unix-like platforms, the gmabuildtool Gradle build cache is in the /tmp/gma directory. On Windows, it is in C:\tmp\gma.

Important: The Gradle build cache directory used by gmabuildtool (/tmp/gma or C:\tmp\gma) can grow to a significant size and consequently fill the disk. Take care to monitor the size of this cache and manually clean out the cache files, to ensure that it does not become too large in size.

Cleaning intermediate build files

The build process is optimized to avoid a complete AAB/APK package rebuild every time you invoke the GMA buildtool.

The GMA buildtool creates intermediate archive files, that can be reused in the next build, if no changes are detected in application program files. However, these files might be corrupted, in case of user interruption or gradle build failure.

In this situation, you can use the --clean option of the gmabuildtool build ... command, to clean up the scaffold build directory, and restart with a fresh build:

gmabuildtool build --clean
    ... build options ...

Force scaffold update during build

During the build process, if not yet done, the GMA buildtool will automatically unzip the original GMA scaffold archive (gma-install-dir/artifacts) into the --build-project directory. During next builds, the scaffold files present in the project build directory will be reused.

If needed (especially, when upgrading GMA), you can force an update of these scaffold files with the --build-force-scaffold-update option of the gmabuildtool build ... command:

gmabuildtool build --build-force-scaffold-update
    ... build options ...

Note: When using the --build-force-scaffold-update option, the GMA buildtool will ask for a confirmation to remove the scaffold files in your project directory. In order to build silently and answer yes to all questions asked during the build process, use the --build-quietly option:

gmabuildtool build --build-force-scaffold-update --build-quietly
    ... build options ...

Specifying the GBC for Universal Rendering

When your app uses Universal Rendering mode, use the --build-gbc-runtime option to specify which GBC has to be bundled with the app package:

gmabuildtool build --build-gbc-runtime gbc-archive ...

The gbc-archive parameter is the ZIP archive of the GBC front-end, to be created as described in the Create a runtime zip topic in the Genero Browser Client User Guide.

If the --build-gbc-runtime option is used, the embedded applications will implicitly be displayed with Universal Rendering. There is no need to set the gui.rendering option in the FGLPROFILE. However, if gui.rendering="native" is set, the native GUI mode will be used, even if the GBC option is specified during the build.

Using an options file

To simplify option specification, create a file with the list of options to be passed to the gmabuildtool with the --input-options argument. Each option must be specified in a dedicated line (note that the main command argument appears in the first line):

$ cat myoptions.txt
build
--build-output-apk-name MyApp
--build-app-name MyApp
--build-app-package-name com.example.myapp
...
$ gmabuildtool --input-options ./myoptions.txt

Elements used in building the Android app

The gmabuildtool build ... command builds the Android AAB/APK packages from the following:

The GMA binary archive, containing the GMA front-end and the FGLGWS runtime system. The original scaffold is provided in gma-install-dir/artifacts and unzipped/copied for app package builds into a directory defined by the --build-project option.
The GBC to be used for Universal Rendering (--build-gbc-runtime option)
The compiled application program and resource files (.42m, .42f, etc) (--build-app-genero-program* options)
The prefix for the app package file name to be generated (--build-output-apk-name option)
The name of the app (--build-app-name option)
The version code of the app (--build-app-version-code option)
The version name of the app (--build-app-version-name option)
Android app specific resources:
- Android app icons (all sizes) (--build-app-icon* and --build-status-icon-* options)
Android app specifics (to sign the app, not required in development mode):
- The keystore alias (--build-jarsigner-alias option)
- The keystore file (--build-jarsigner-keystore option)

Generate the keystore file to sign your app

In order to build an AAB package that can be deployed on the Google Play Store, you need to sign your Android app.

First, you need to generate a keystore file with the keytool Android utility.

The keystore file and keystore alias will be used by the gmabuildtool to sign the APK with the apksigner utility from Android SDK and to sign the AAB with the jarsigner utility from Java SDK. These signing credentials are passed to the buildtool with the --build-jarsigner-keystore and --build-jarsigner-alias options.

Important: There is critical information regarding app signing in the Android documentation. For example, in order to install new versions as updates to your app, each app package must use the same certificate: The signing key must not change during the lifetime of your app. Make sure that you read all details about Android app signing.

Generated AAB/APK file names

The file name of the app package is formed from:

The file name prefix defined by the --build-output-apk-name option (by default, "app"),
When building a debug version, the -debug suffix,
The .aab or .apk file extension.

For example, if the file name prefix is MyApp and is a debug package, the resulting package file names will be: MyApp-debug.aab and MyApp-debug.apk.

Default build directory structure

For convenience, the buildtool supports a default directory structure to find all files required to build the app package:

top-dir
|
|-- main.42m and other program files, as described in Directory structure for GMA apps
|
|-- gma
|   |-- project
|   |   ...
|   |-- ic_app_hdpi.png
|   |-- ic_app_mdpi.png
|   |-- ic_app_xhdpi.png
|   |-- ic_app_xxhdpi.png
|   |   ...

In the above directory structure:

top-dir is the top directory of the default structure. It typically holds your application program files. The program files directory can be specified with the --build-app-genero-program option.
top-dir/gma is the default directory containing the GMA binary archive and the app icons.
top-dir/gma/project contains the scaffold files copied automatically by gmabuildtool from gma-install-dir/artifacts. This directory can be specified with the --build-project option.

Android permissions

To use a mobile device feature such as the camera, an Android app must be created with the corresponding Android permission.

The permissions implemented in the APK/AAB package will be a merge of the permissions set by default (typically for mobile front calls), the permissions defined for the app with the gmabuildtool, and the permissions already implemented by external libraries required to build the GMA app. The manifest file used by the gmabuildtool may show less permissions than the APK/AAB package implements.

Android distinguishes "Normal Permissions" and "Dangerous Permissions": Dangerous Permissions require a user validation at runtime, the first time the device feature is used.

Note: Before Android 6, Dangerous Permissions defined by the app were set at app installation. Starting with version 6, Dangerous Permissions must be requested by the app code on demand.

Android permissions can be specified with the --build-app-permissions option of the gmabuildtool. Define the list of permissions as a single argument, by using the comma as separator.

For example:

gmabuildtool build \
    ...
    --build-app-permissions android.permission.READ_CALENDAR,... \
    ...

Assuming that the permission was specified when building the app package, a Dangerous Permission required for a core GMA feature (like internet access), or a built-in front call, will make the GMA automatically ask for user confirmation. For example, if the app code makes a chooseContact front call, the GMA will automatically request the user to access the contacts database.

Other permissions (not related to core GMA features or built-in front calls) need to be specified when building the app.

Note: Dangerous Permissions not related to core GMA features or built-in front calls, need to be enabled by the app code. To request the user for a specific permission, perform a askForPermission front call, before using the feature.

Several Android "Normal Permissions" required for core GMA app features and built-in mobile front calls are automatically defined in the app manifest file by gmabuildtool. To identify these default permissions, inspect the manifest file of the generated APK/AAB file.

The following list shows the Android "Dangerous Permissions", required for core GMA app features and built-in mobile front calls.

Important: Dangerous Permissions listed below are not set by default: They must be specified explicitly with the --build-app-permissions option, when building the app package.

android.permission.ACCESS_FINE_LOCATION: For getGeolocation front call.
android.permission.ACCESS_COARSE_LOCATION: For getGeolocation front call.
android.permission.READ_CONTACTS: For chooseContact front call.
android.permission.GET_ACCOUNTS: Only on Android 5.1 and lower (< API 23), for chooseContact front call.
android.permission.READ_PHONE_STATE: For feInfo (deviceid, iccid, imei) front calls. Starting with Android 10 (API level 29), to access deviceid, iccid and imei identifiers, the device must be configured manually by adding the READ_PRIVILEGED_PHONE_STATE privileged permission. To set this permission manually, you need an Android Enterprise Program with fully managed devices (devices are owned by your company). Third-party apps installed from the Google Play Store can't declare such privileged permissions. For more details, see Android documentation.
android.permission.WRITE_EXTERNAL_STORAGE: For importContact, takeVideo, takePhoto front calls.
android.permission.READ_EXTERNAL_STORAGE: For openFile, openFiles, chooseVideo, takeVideo, choosePhoto, takePhoto front calls.

For a complete list of Android permissions, see Android's Manifest permissions.

Define app's color theme

To customize your Android app, it can be created with a color theme defined by a list of colors. The colors are specified as a comma-separated list of RGB colors with the --build-app-colors option.

Note: This feature is only available with Android 5.0 / SDK 21 and higher. With older versions of Android, the colors specified with the --build-app-colors option will not take effect.

The value provided to the --build-app-colors option must be a comma-separated list of four hexadecimal RGB colors.

The position of the RGB value in the color list defines its purpose:

colorPrimary: The main color used in the app.
primaryDark: The color used for the status bar and the navigation bar.
accent: The accent color used for widgets and table lines.
actionBarText: The foreground color for the texts in the action bar.
primaryText: The text color for items in the whole application.
windowBackground: The window background color.
navigationBarBackground: The background color of the bottom bar.

By default, the color theme is the Genero purple color.

For example, to define a red color theme, use the following combination:

gmabuildtool build \
    ...
    --build-app-colors "#F44336,#B71C1C,#EF9A9A,#FFFFFF,#FF0000,#00AA00,#DDAA00" \
    ...

For more details, see Android material theme and Android color palette

Debug and release versions

Android apps can be generated in a debug or release version. Release versions meet the requirements for distribution on Google Play, while debug versions are used in development. In debug mode, the app installed on the device will listen on the debug TCP port to allow fgldb -m connections.

Debug or release mode can be controlled with the --build-mode option of the gmabuildtool command:

gmabuildtool build \
    --build-mode debug \
    ...

By default the app is built in release mode.

Building an Android app with gmabuildtool

Follow the next steps to setup a GMA app build directory in order to create an Android app, based on the default directory structure:

Create the root distribution directory (top-dir)
Copy compiled program files (.42m, .42f, fglprofile, application images, web component files, etc) under top-dir.
Copy the default English .42s compiled string resource file under top-dir.
Create non-English language directories (fr, ge, ...) under top-dir and copie the corresponding .42s files.
Copy default application data files (database file for ex) under top-dir.
Create the top-dir/gma directory.
Copy Android app resources (icons) under top-dir/gma.

Once the build directory is prepared, issue the following commands to build the app package:

$ cd top-dir
$ gmabuildtool build \
    --android-sdk /home/mike/android/sdk \
    --build-force-scaffold-update \
    --build-apk-outputs /home/mike/work/example/outputs \
    --build-output-apk-name MyApp \
    --build-app-name MyApp \
    --build-app-package-name com.example.myapp \
    --build-app-version-code 1002 \
    --build-app-version-name "10.02" \
    --build-jarsigner-alias android_alias \
    --build-jarsigner-keystore /home/mike/work/example/sign/android.keystore \
    --build-mode release \
    --build-app-permissions android.permission.ACCESS_WIFI_STATE,android.permission.CALL_PHONE

Building an app with GMA custom extensions

The gmabuildtool build ... command supports AAB/APK creation for applications using GMA custom extensions written in Java.

Before building the app package, create the custom GMA binary archive with your extensions, as described in Packaging custom Java extensions for GMA.

When your custom GMA binary archive is complete, build the app package with the gmabuildtool build ... command. Use the --build-project option to specify the path to the Android Studio project that was used to build your custom GMA binary archive:

$ gmabuildtool build
    ...
    --build-project /home/mike/android_project/mycustgma
    ...

Note: Other options have to be specified as for a regular build using the original standard GMI binary archive.

Deploy and launch the app

After building the app packages, you can deploy and launch your app for testing purpose, on your local mobile device or simulator.

Note: There must be only one Android device connected or running Android emulator.

Android App Bundle (AAB/.aab) packages cannot be installed directly on your local device or simulator (these are archives to be uploaded on the Google Play Store).

To install the app on your local device or simulator, you need first to produce an .apks for your device or simulator, by using the bundletool (assuming your device is connected or simulator is started):

$ bundletool build-apks \
     --bundle=/MyApp/outputs/my_app.aab \
     --output=/MyApp/outputs/my_app.apks

The .apks can then be used to install the app on you local device or simulator, with the following command:

bundletool install-apks --apks=/MyApp/outputs/my_app.apks

Alternatively, the APK/.apk packages can be installed and started with the gmabuildtool test ... command, by using the --test-apk option to specify the APK filename to be installed:

$ gmabuildtool test \
     --test-apk /MyApp/outputs/MyApp-arm-debug.apk