Parent topic: Deploying mobile apps on Android devices
Deploying mobile apps / Deploying mobile apps on Android devices

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 APK packages like any other Android app. Genero provides a command line tool to build the APK package for your mobile application. For testing purposes, the tool can also deploy and automatically launch the app on a specific device or simulator. The tool has also an option to update the Android SDK.
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 developer site at https://developer.android.com.

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 on the computer to compile your program files.
  • The Java JDK must be installed. The minimum required version is 1.7.
  • The Android SDK must be installed (the buildtool uses the "Gradle" utility).
    Note: The first time the Android tools are called, they will automatically check for updates. Therefore, you need an internet connection.
  • All Android SDK packages required by GMA must be downloaded. In order to download the required Android SDK packages, execute 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.

  • The GMA buildtool and the GMA binary archive must be installed.

    The GMA buildtool and GMA binary archive are provided in the GMA distribution archive (fjs-gma-*.zip).

    To setup the GMA buildtool perform the following steps:
    1. Create a dedicated directory (gma-install-dir) and extract the content of the fjs-gma-*.zip. This will contain the gmabuildtool command. Add the gma-install-dir directory to your PATH environment variable.
    2. Create a directory (gma-scaffold-project) for the GMA binary archive, and extract gma-install-dir/artifacts/fjs-gma-*-android-scaffolding.zip into this directory. This direcory will be specified with the --build-project option of gmabuildtool.
  • Android specific app resources such as icons (in all required sizes) are required, along with the application program files.
  • 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 env settings (ANDROID_HOME, PATH)
  • Java JDK env 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 and downnload all Android SDK packages required by GMA, by executing the gmabuildtool updatesdk command:
gmabuildtool updatesdk
    --android-sdk /use/local/32bits/android-sdk/r22.6.2

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

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
    ...
Eventually, use the --no-install-extras option, to skip 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
    ...

Building and deploying with the GMA buildtool

The gmabuildtool build ... command creates the APK from a set of files, and according to the options passed as parameter.

gmabuildtool build
    ... build options ...

Once the APK file is created, use the gmabuildtool test --test-apk command to install the app on the Android device plugged to the computer, and start the app automatically.

gmabuildtool test
    --test-apk path-to-the-apk-file

For a complete description of command options, see gmabuildtool.

Cleaning the scaffold files

The build process is optimized to avoid a complete APK rebuild every time you invoke the GMA buildtool: When application program file changes are detected, the GMA buildtool will create archive files that can be reused in the next build if no changes are detected. However, files used for the optimized build might be corrupted, for example in case of user interruption or graddle build failure.

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

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

Using an options file

To simplify option speciciation, create an file with the list of options to be passed to the gmabuildtool with the --input-options argument. The options file must contain a line for each option/value peer:
$ cat myoptions.txt
--build-output-apk-name MyApp
--build-app-name MyApp
--build-app-package-name com.example.myapp
...
$ gmabuildtool --input-options ./myoptions.txt

Elements used to building the Android app

The gmabuildtool build command builds the Android APK package from the following:
  • The GMA binary archive, containing the GMA front end and the FGL runtime system.
    Note: You must unzip the fjs-gma-*-android-scaffolding.zip file.
  • The compiled application program and resource files (.42m, .42f, etc) (--build-app-genero-program* options),
  • The prefix for the APK 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* options).
  • Android app specifics (to sign the app, not required in development mode):
    • The keystore alias, used with the keytool to generate the keystore file (--build-jarsigner-alias option).
    • The keystore file, generated from keytool (for the --build-jarsigner-keystore option).

Generate the keystore file to sign your app

In order to build an APK that can be deployed on the market (Google Play), 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 jarsigner utility. These signing credentials are passed to the buildtool with the --build-jarsigner-keystore and --build-jarsigner-alias options.

For more details, see manual Android application signing.

Generated APK file name

The file name of the APK package is formed from:
  1. the APK file name prefix defined by the --build-output-apk-name option (by default, "app"),
  2. the target type (-arm or -x86),
  3. if building a debug version, the -debug suffix,
  4. the .apk file extension.
For example, if the APK file name prefix is MyApp and the target architecture is arm in debug mode, the resulting APK file name will be: MyApp-arm-debug.apk.

Default build directory structure

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

top-dir
|
|-- main.42m and other program files, as described in Directory structure for GMA apps
|
|-- gma
|   |-- project
|   |   ...
|   |-- temp
|   |   ...
|   |-- ic_app_hdpi.png
|   |-- ic_app_mdpi.png
|   |-- ic_app_xhdpi.png
|   |-- ic_app_xxhdpi.png
|   |   ...
In the above directory structure:
  1. top-dir is the top directory of the default structure. It will typically hold your application program files. The program files directory can be specified with the --build-app-genero option.
  2. top-dir/gma is the default directory containing the GMA binary archive, the temp directory and the app icons.
  3. top-dir/gma/project must contain the unzipped GMA binary archive (fjs-gma-*-android-scaffolding.zip). This directory can be specified with the --build-project option.

Android permissions

In order to use a device feature such as the camera, an Android app must be created by specifying the corresponding Android permissions. Furthermore, Android distinguishes "normal" and "dangerous" permissions. While both type of permissions just need to be specified when building the app, "dangerous" permissions require a user validation: A popup dialog will appear to let the user confirm that the dangerous feature can be accessed. Before Android 6, dangerous permissions defined by the app were asked at app installation. Starting with Android 6, dangerous permissions must be asked by the app code on demand.

Android permissions required for the built-in front calls are automatically set by GMA, which ask automatically user confirmation if the permission is dangerous. For example, if the app code makes a chooseContact front call, the GMA will automatically ask the user for the Android permission to access the contacts database, and set the corresponding permission on confirmation. When building your app, there is no need to specify permissions required for built-in front calls.

Other permissions (not involved by built-in front calls) need to be defined when building the app, and "dangerous" permissions need to be asked to the user when needed. In order to ask the user for a given permission, the app must use the askForPermission front call.

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,... \
    ...

Android permissions listed below are defined by default by GMA and therefore do not need to be specified when building your app. For "dangerous" permissions, the GMA will automatically ask the user to access the feature, when corresponding front call is performed:

Other permissions required by the app but not listed here need to be specified when building your app, and if the permission enters in the "dangerous" category, the app code must issue an askForPermission front call before using the feature. For a complete list of Android permissions, see Android's Manifest permissions.

Define app's color theme

Android apps can be created with a color theme defined by four basic colors to customize your app, that can be defined 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 color defines its purpose:
  1. Primary color: This is the main color used in the app.
  2. Primary dark color: This is the color used for the status bar and the navigation bar.
  3. Accent color: This is the color used for widgets and table lines.
  4. Action bar text color: This is the foreground color for the texts in the action 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" \
    ...

For more details about Android color shemes, see Android Colors

Debug and release versions

Android apps can be generated in a debug or release version. Release version are prepared 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 build 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:
  1. Create the root distribution directory (top-dir)
  2. Copy compiled program files (.42m, .42f, fglprofile, application images, web component files, etc) under top-dir.
  3. Copy the default English .42s compiled string resource file under top-dir.
  4. Create non-English langage directories (fr, ge, ...) under top-dir and copie the corresponding .42s files.
  5. Copy default application data files (database file for ex) under top-dir.
  6. Create the top-dir/gma directory.
  7. Copy Android app resources (icons) under top-dir/gma.
Once the build directory is prepared, issue the following commands to build the APK:
$ cd top-dir
$ gmabuildtool build \
    --android-sdk /home/mike/android/sdk \
    --build-project /home/mike/work/example/scaffold_project \
    --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
Important: The directory specified with the --build-project option must contain the unzipped GMA binary archive (fjs-gma-*-android-scaffolding.zip).

Building an app with GMA custom extensions

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

Before building the APK 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 APK 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 APK package, for testing purposes, you can deploy and launch your app from the command line with the gmabuildtool test command.
Note: The test command is provided for development only. To deploy your app in production for several devices, use the regular publication channel of Android apps.
In order to deploy and launch the app, you must provide:
  1. the path to the APK file

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

$ gmabuildtool test \
     --test-apk /home/mike/work/example/outputs/MyApp-arm-debug.apk
Parent topic: Deploying mobile apps on Android devices