Building Android apps with Genero
Genero provides a command-line tool to create applications for Android™ devices.
Basics
- 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.
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.
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:- Create a dedicated directory (gma-install-dir)
- Extract the content of the fjs-gma-*.zip.
- 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
- 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
--accept-licenses
option to silently accept all Android SDK
licenses.gmabuildtool updatesdk
--accept-licenses
...
--proxy-host
and
--proxy-port
options:gmabuildtool updatesdk
--proxy-host amadeus --proxy-port 3232
...
--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
...
--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.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.
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 ...
--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
--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
--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 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 icons (all sizes)
(
- 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)
- The keystore alias (
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.
Generated AAB/APK file names
- 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.
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
| | ...
- 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 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.
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.
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.
--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
--build-app-colors
option.--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.
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.
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.
--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
- 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.
$ 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.
--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
...
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.
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).
$ bundletool build-apks \
--bundle=/MyApp/outputs/my_app.aab \
--output=/MyApp/outputs/my_app.apks
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