gmabuildtool

The gmabuildtool is a utility to create and test applications for an Android™ device.

Syntax

gmabuildtool command [option [...]]
  1. command can be one of the following:
    • updatesdk: updates the Android SDK, to download packages required by GMA.
    • scaffold: manages scaffold archives.
    • build: builds an APK package.
    • test: deploys and launches an app on the device or emulator.
  2. option can be a general or command-specific option, as described in Options.

Known issues

Important: When using gmabuildtool updatesdk on Microsoft™ Windows® platforms, the "tools" package of Android SDK cannot be updated due to an SDK manager bug. The workaround is to download and install a new Android SDK. This problem exists for example with Android SDK 26.0.2, and may be solved in higher SDK versions.

Options

Table 1. General gmabuildtool options
Option Short option Description
--android-sdk path -as The path to the Android SDK installation directory.

If not specified, it defaults to the ANDROID_SDK_ROOT environment variable. If ANDROID_SDK_ROOT is not defined, defaults to ANDROID_HOME.
--help -h Display the list of options.
--input-options path -i Path to the file containing gmabuildtool options.

Define all options in a file and pass the file to the gmabuildtool command with the --input-options argument.

The options file must use the following format:
option-name option-value
...
--java-home path -jh Java home path.

Default is JAVA_HOME.
--proxy-host host -ph Defines the proxy host.
--proxy-host port -pp Defines the proxy port.
--verbose-fine -v Verbose mode (level 1)
--verbose-finer -vv Verbose mode (level 2)
--verbose-finest -vvv Verbose mode (level 3) - shows all possible logs.
--version -V Display GMA build tool version.
Table 2. gmabuildtool updatesdk options
Option Short option Description
--accept-licenses -al Silently accept Android SDK licenses when the Android SDK is updated.
--no-install-extras -uN Avoid installation of extra SDK modules.
Table 3. gmabuildtool scaffold options
Option Short option Description
--install-plugins plugin-list -ip Install the specified plugins in the scaffold archive.

The pluging-list must be a comma-separated list of plugins.
--list-plugins -lp List the plugins available in the scaffold archive.
Table 4. gmabuildtool build options
Option Short option Description
--clean -c Cleans the intermediate build files before a rebuild.

Use the --clean option if the previous build was interrupted or has failed.

Note: The --clean option does not remove and replace the scaffold, as done by the --build-force-scaffold-update option.
--build-app-colors color-list -bc Define the Android color theme for the app (Android 5.0+ / SDK 21+)

The value must be a comma-separated list of four hexadecimal RGB colors: #F44336,#B71C1C,#EF9A9A,...

The position of the RGB value in the color list defines its purpose:
  1. colorPrimary: The main color used in the app.
  2. primaryDark: The color used for the status bar and the navigation bar.
  3. accent: The accent color used for widgets and table lines.
  4. actionBarText: The foreground color for the texts in the action bar.
  5. primaryText: The text color for items in the whole application.
  6. windowBackground: The window background color.
  7. navigationBarBackground: The background color of the bottom bar.
By default, the color theme is the Genero purple color.
--build-app-genero-program-main path -bgpm Relative path to the main module of the application (can be .xcf, .42m or .42r).

Defaults to main.42m
--build-app-genero-program path -bgp Defines the path to the application program files (.42m, .42f, etc)

The contents of this directory will be zipped and bundled inside APKs. This option can handle an already zipped Genero program archive.

If not specified, defaults to the current working directory.
Note: The path defined by this option is used as base directory for other options such as --build-project and application icon resources options.
--build-app-icon-hdpi path -bih Defines the path to application icon in hdpi.

Default is top-dir/gma/ic_app_hdpi.png, where top-dir is defined by the --build-app-genero-program option.
--build-app-icon-mdpi path -bim Defines the path to application icon in mdpi.

Default is top-dir/gma/ic_app_mdpi.png, where top-dir is defined by the --build-app-genero-program option.
--build-app-icon-xhdpi path -bixh Defines the path to application icon in xhdpi.

Default is top-dir/gma/ic_app_xhdpi.png, where top-dir is defined by the --build-app-genero-program option.
--build-app-icon-xxhdpi path -bixxh Defines the path to application icon in xxhdpi.

Default is top-dir/gma/ic_app_xxhdpi.png, where top-dir is defined by the --build-app-genero-program option.
--build-app-name app-name -bn Application name.

If not specified, the application name defaults to the current working directory.
--build-app-package-name name -bpn APK package name.

It is recommended to format the package name as "com.organization-name.app-name".

If not specified, the application package name defaults to com.example.current-working-directory
--build-app-permissions permissions -ba Android application permissions.

The list of permissions is provided as a comma separated list of android.permission.* identifiers.

For more details, see Android permissions.
--build-app-version-code version-code -bvc Application version code.

For example: 100915

The value of this option must be an integer (do not use decimal numbers).
--build-app-version-name version-name -bvn Application version name.

For example: 10.09.15

This will be the actual app version visible on devices.
--build-apk-outputs path -bo Defines the destination folder where the APK packages must be created.
--build-cordova cordova-plugin-names -bco

Defines Cordova plugins to be embedded in the app package.

When specifying multiple cordova plugins, use the comma (,) as separator.

The name of the plugin must match the Git repository name. It is case-sensitive.

Note: To get the list of available Cordova plugins, use the gmabuildtool scaffold --list-plugins command.

For further information, see Cordova plugins.
--build-force-scaffold-update -bfsu Forces to re-create the app project directory with the original GMA scaffold directory (defined by --build-project)
--build-jarsigner-alias alias -bja Jarsigner alias.

This is the alias provided to the keystore utility to build the keystore file to sign the app.

Used when APK artifacts are signed.
--build-jarsigner-keypass keypass -bjk Jarsigner keypass.Specifies the password used to protect the private key of the keystore entry addressed by the alias specified in the --build-jarsigner-alias option. The password is required when using jarsigner to sign a JAR file.

Used when APK artifacts are signed.
--build-jarsigner-keystore path -bjks Jarsigner keystore path.

This is the path to the keystore file generated by the keystore utility to sign the app.

Used when APK artifacts are signed.
--build-jarsigner-storepass storepass -bjs Jarsigner storepass. Specifies the password that is required to access the keystore.

Used when APK artifacts are signed.
--build-mode {release|debug} -bm Package build mode, to build a release version or a development/debug version.

Default: release
--build-output-apk-name name -ban Defines the prefix for the APK packages names.

By default, this prefix is "app".

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. When building a debug version, the -debug suffix,
  3. The .apk file extension.
For example, if the APK file name prefix is MyApp and is a debug package, the resulting APK file name will be: MyApp-debug.apk.
--build-project path -bp Defines the path to the directory containing the original GMA binary archive files (i.e. scaffolding), or the directory containing the Android Studio project, when building a customized GMA.

Default is top-dir/gma/project, where top-dir is defined by the --build-app-genero-program option.
--build-quietly -bq Forces a silent build, by answering yes to all questions asked during the build process.

By default, the user must answer to the build questions by yes/no.
--build-status-icon-hdpi path -bsh

Status icon path for hdpi (high dots per inch) size.

The default path is top-dir/gma/ic_status_hdpi.png, where top-dir is defined by the --build-app-genero-program option.

If this option is not specified, yet you provide default files under the gma directory named like those defined for the default path, your package will use these files. If you don't provide any status icon files, the default files are used.
--build-status-icon-mdpi path -bsm

Status icon path for mdpi (medium dots per inch) size.

The default path is top-dir/gma/ic_status_mdpi.png, where top-dir is defined by the --build-app-genero-program option.

If this option is not specified, yet you provide default files under the gma directory named like those defined for the default path, your package will use these files. If you don't provide any status icon files, the default files are used.
--build-status-icon-xhdpi path -bsxh

Status icon path for xhdpi (extra-high dots per inch) size.

The default path is top-dir/gma/ic_status_xhdpi.png, where top-dir is defined by the --build-app-genero-program option.

If this option is not specified, yet you provide default files under the gma directory named like those defined for the default path, your package will use these files. If you don't provide any status icon files, the default files are used.
Table 5. gmabuildtool test options
Option Short option Description
--test-apk path -ta Path to the APK file to deploy and launch for testing.