Native Builder (CLI)

Introduction

The Native Builder (CLI) takes your Mendix project containing a native profile and packages a native mobile app for iOS and Android. To learn more about using the Native Builder, see How to Build a Mendix Native App in the Cloud.

The Native Builder uses MxBuild, GitHub, and App Center to build your applications. The tool automates the configuration of these processes to streamline your app building experience. The Native Builder allows you to create as many apps on GitHub as possible, as long as they are given unique app names using the --project-name parameter (for more information, see the Commands section below). Using the prepare and build command combination, the Native Builder packages your apps by doing the following:

1. Deploys your Mendix project locally.
2. Creates a new repository (named using the project name argument provided) employing the latest version of the Mendix Native Template repository which fits the Mendix version provided.
3. Creates a new branch in the new repository called build/{build number provided to the tool}.
4. Commits the required files and assets to the build branch in the new repository.
5. Configures your apps in App Center.
6. Starts a build for iOS and Android.
7. Provides progress information on the build.
8. Downloads the zipped app if the build succeeded, or the build log file if the build failed.

Commands

Command-line arguments provide information to the Native Builder, such as where your Mendix project is located. Commands are configured using parameters, shown below. Some of these parameters are required or strongly recommended. The rest of them are optional, and should be used when they pertain to your app. To compose a command with parameters — which will start your Native Builder when executed — do the following:

1. Open your command line program as an administrator by right-clicking its icon or .exe file and selecting Run as administrator.

2. Target your Native Builder’s directory by typing cd "{your Native Builder .exe location}" and pressing Enter:

   

Prepare

The Prepare command handles the creation of the app on both GitHub and App Center, sets up icon assets and splash images, and then verifies for Java, Mendix, and project paths. A configuration file is generated relative to the user folder to keep that information for later use. You can update this configuration by using the prepare command and passing the arguments you would like to update.

An example of a prepare command:

native-builder.exe prepare --github-access-token <token> --appcenter-api-token <token> --java-home <absolute-path> --mxbuild-path <absolute-path> --project-path <absolute-path-to-mpr-file> --projectName CoolApp --app-identifier "com.company.myapp" --app-name "My Cool App" --mendix-version 8.5.0

Build

Generating Apps for Distribution

The Build command builds the JavaScript bundles and assets, creates a build on GitHub, and initializes the build on App Center.

If you already ran prepare, this is an example of a build command:

native-builder.exe build --project-name "CoolApp" --app-version "1.0.0" --build-number 1

Generating Custom Developer Apps

When used, the build dev-app command will create a preview app much like the Make It Native app. However, the preview app it makes will be a custom developer app specific to both your project and your Studio Pro version. This command creates a develop branch on GitHub, and initializes the build on App Center. It also expects you to have run the prepare command at least once.

Here is an example of a command featuring build dev-app:

native-builder.exe build dev-app --project-name "CoolApp" --output-path "C:\bundles\developer"

Regenerate

The regenerate command recreates the project on GitHub with the latest version of Native Template, renames the previous app with a new name to preserve changes (if any), and then updates the build configuration of the App Center apps. Running regenerate also expects that prepare has been run at least once for the --project-name.

An example of a regenerate command:

native-builder.exe regenerate --project-name "CoolApp" --mendix-version 8.5.0

Creating an Over the Air Deployment Release

The push-update command handles generating a new JavaScript bundle and assets, and deploying that over the air (OTA) update.

Here is an example of a command featuring push-update:

native-builder.exe release push-update --project-name "CoolApp" --target-version "1.0.0" --build-number 1 --rollout-percentage 100

Updating an OTA Deployment Release’s Metadata

The patch-update command allows you to update the metadata of a published update that has not been rolled out to all users (in technical terms, an update which does not have a rollout-percentage value of 100).

Here is an example of a command featuring patch-update:

native-builder.exe release patch-update --project-name "CoolApp" --label "v4" --target-version  "1.0.1"

Rolling Back to a Previous Deployment Release

The rollback-update command allows you to revert to a previous deployment release with the same target version of your app. This command creates a new deployment using a previous deployment release specified with the --label argument.

Here is an example of a command featuring rollback-update:

native-builder.exe release rollback-update --project-name "CoolApp" --label "v4"

Be aware of the following:

• The --label parameter can point to a previous deployment release only
• If you rollback to a broken release, it will be deployed to the users. To fix this situation, you will then have to either do a new release or rollback to a working release.

Listing Deployment Releases

The list command displays a pretty-printed list of all deployed releases.

Here is an example of a command featuring list:

native-builder.exe release list --project-name "CoolApp"

Generating Only the App Bundles

When used, the bundle command will only run the MxBuild step (skipping GitHub configuration and the App Center build steps). This command outputs ZIP archives with the corresponding JavaScript bundle and resources for each platform.

Here is an example of a command featuring bundle:

native-builder.exe bundle --project-name "CoolApp" --output-path "C:\bundles"

iOS-Specific Configurations

Commands to modify the iOS configuration are grouped under the config ios command.

Adding and Removing Entitlements

To add or remove entitlements, use the add-entitlements or remove-entitlements commands:

native-builder.exe config ios add-entitlements --project-name "CoolApp" --entitlements notification nfc

Adding and Removing Background Modes

To add or remove background modes, use the add-background-modes or remove-background-modes commands:

native-builder.exe config ios add-background-modes --project-name "CoolApp" --modes notification

Expanded Parameter Explanations

–project-name

This parameter is the unique name of your app, and can contain any characters. This name is used to persist common parameter configurations like --github-access-token to your machine. This improves reusability with other commands that would need it. It is also used as the app’s name in GitHub and App Center.

–runtime-url

This parameter should point to the runtime you want to run your app against. If testing against a locally deployed app, use your machine’s IP address (for example, http://192.168.1.12:8080). If testing against a Mendix Cloud-deployed app, use the fully qualified runtime URL of your deployment server (for example, https://myapp.mendixcloud.com). The correct protocol needs to be appended, otherwise the URL will be prefixed by default with http://.

–appcenter-organization

In App Center you can be a member of one or more organizations. If the app needs to be built as part of an organization, then provide the name of that organization to Native Builder using --appcenter-organization. If you leave the command-line argument out, the app will be part of your personal App Center account.

–app-name

This parameter is the display name of your app, and can contain any characters you choose. You can see this name when users install your app on a device. For iOS apps this serves as the CFBundleDisplayName. For Android apps this serves as the android:label property of the application tag in the AndroidManifest.xml file.

–app-version

This parameter specifies the version of the app you want to build. See Semantic Versioning for more information on how to select a proper version number.

–app-identifier

This parameter serves as a unique identifier for your app, which must conform to Android’s application ID requirements as well as Apple’s CFBundleIdentifier requirements. Once your app is uploaded to the Apple App Store or the Play Store, the app’s identifier can no longer be modified. If you do modify the identifier after an app is published, it will be treated as a different app by both stores. An app identifier is specified as reverse DNS notation, for example {com.mendix.MyAwesomeApp}.

–platform

This parameter allows selective builds per specific platform or for both. By default, the Native Builder tries to build for both platforms but this parameter can limit a build to either iOS or Android only.

–skip-mxbuild

In rare cases, errors might occur after the bundling process has completed. This parameter will allow you to skip MxBuild during testing to save time.

–app-icon-path

This parameter specifies an app icon file. The image must be a .png file, and have a resolution of 1024x1024. Mendix will do the resizing for you. If a file path is not provided, default app icons will be provided by branch main.

–app-round-icon-path

This parameter specifies an app round icon file which is specific to Android. The image must be a .png file, and have a resolution of 1024x1024. Mendix will do the resizing for you. If a file path is not provided, default app icons will be provided by branch main.

–app-splash-screen-path

This parameter specifies an app splash file. The image must be a .png file, and have a resolution of 1440x2560. Mendix will do the resizing for you. If a file path is not provided, default app splash images will be provided by branch main.

–build-number

This unique configuration represents the version build number for the release builds for both Android and iOS. Every build that is scheduled for release should have a unique, incrementing number. This number will be used as the name of the branch name on App Center and GitHub.

For over-the-air updates, each build is associated with a particular release group (--deployment-target) which would get the update. By default, this value is set to Production and should usually be kept this way. If changed, the new value should be noted as only devices running on that environment would get updates.

The highest integer Android will allow is 2,147,483,647. Consider starting with 1 and incrementing by one with each release. Alternatively, you can use dates in the “YYmmddHHmm” format, such as {2007310950} for a build run on July 31, 2020 at 09:50.

–mendix-version

This parameter makes the Native Builder pick a compatible version of the Native Template based on your Mendix project’s Studio Pro version. This parameter needs to be a valid semantic version of Studio Pro, for example 8.5.1. The version provided needs to be as specific as possible, as even patch versions might include fixes that might not be compatible with all Native Templates available. To determine which Mendix version you are using check the About page or splash screen of your Mendix project’s version of Studio Pro.

–verbose

This parameter provides additional details when the Native Builder incurs errors. When --verbose is used and the Native Builder errors, the Native Builder will output a complete stack trace of the error. This is useful for cases where the Native Builder fails with an unknown error.

Advanced Usage

Custom Native Code

If you have custom native dependencies or code, you can include them in your app by merging your changes to the main branch of the GitHub repository which the Native Builder is making. Every build branches off from main and your changes will be included. Remember to synchronize your repository occasionally to get the latest changes from Mendix native template.

For more information on syncing your repository, see When to Regenerate Your Native Template below.

Custom App Center Configuration

In App Center you can configure your builds at the branch level. If no configuration is available for branch main, Native Builder will create a default configuration. If a configuration is already present, it will not be modified by the tool. When a branch for a build is initialized, the configuration of main is copied over. Consecutive builds will not alter this branch’s configuration. This is to avoid overriding your custom configuration unless the regenerate command is used.

Custom Developer App

As your Mendix app matures, you may want to expand its functionality (such as by introducing custom widgets or logic that will require new native dependencies). A custom developer app fills this role by serving as a replacement for the Make It Native app, and should be used when you have custom widgets and logic which are not supported by the Make It Native app. Custom developer apps are apps you can generate yourself using your current project structure, your custom modules, and any other requirements to test your evolving app. For more information, see How to Create a Custom Developer App

When to Regenerate Your Native Template

The Native Template is being continuously developed. This means new versions are regularly released to accommodate new features of the Mendix Platform or to fix issues. When a new version is available, the Native Builder will suggest you run regenerate to update your base template.

You should update your project’s template in the following scenarios:

• You app crashes unexpectedly even though all Studio Pro modules and resources are fully updated using the Mendix Marketplace
• You updated your Studio Pro version

The Native Template is tightly tied to the version of Studio Pro you are running. Therefore, every time your project is updated, consider running regenerate using the Native Builder to update your template.

Resolving Errors

GitHub Errors

Invalid Access Token — Your access token is invalid. Consult the GitHub Token section in How to Build a Mendix Native App in the Cloud and provide the access token to Native Builder.

Unable to Create the Repository: the Access Token Needs Access to the Repo Scope — Your access token is valid, but has too few permissions for Native Builder to work. Native Builder clones a template GitHub repository, creates a branch, and commits files. Consult the GitHub Token section in How to Build a Mendix Native App in the Cloud and provide the new access token to Native Builder.

Unable to Delete Branch Build/{build number} — Something went wrong while communicating with GitHub. Verify your connection, check that GitHub is available, and try running Native Builder again.

Unable to Create Branch Build/{build number} — Something went wrong while communicating with GitHub. Verify your connection, check that GitHub is available, and try running Native Builder again.

Unable to Commit {build number} — Something went wrong while communicating with GitHub. Verify your connection, check that GitHub is available, and try running Native Builder again.

App Center Errors

Invalid API Token — Your API token is invalid. Follow the App Center Token section in How to Build a Mendix Native App in the Cloud and provide the API token to Native Builder.

Unable to Configure Build:{explanation} — Something went wrong while communicating with App Center. Verify your connection, check that App Center is available, and try running Native Builder again.

Build {build number} for App {app number} Has Failed — The native build on App Center has failed. Read the log file that Native Builder has downloaded. The log file is named {AppName}-{BuildNumber}.log and is located in the same folder as your Native Builder executable.

The Build Configuration is Overridden with the Default — While Native Builder is checking to identify if the branch it is building has been manually configured, it may detect false positives. This could lead to your custom configuration getting overridden. If that happens, consider running the build directly using App Center and skip using the Native Builder for this branch.

Unknown Error — If you do not understand an error, you can sign in to App Center and delete the build configuration for the main branch. Then run Native Builder again. The tool will recreate the default build configuration for main and your branch.

Unknown Errors

If the Native Builder fails to complete a run and no error is provided, consider using the –verbose parameter to get a full stack trace of the error. When communicating an issue with support it is always handy to supply these extra logs, together with build logs, to achieve timely solutions.

Read More

• How to Build a Mendix Native App in the Cloud
• How to Get Started with Native Mobile
• How to Style Your Mendix Native Mobile App