CapeSoft.Com
Clarion Accessories
NetTalk
Doc Index
mBuild
CapeSoft Logo

CapeSoft NetTalk
mBuild

Download Latest Version
Installed Version Latest Version

mBuild

Introduction

mBuild is a utility which ships as part of NetTalk Apps.

It takes a disconnected web application as input, collects all the resources used by the application, then interfaces to the Adobe PhoneGap Build online platform. It uploads your resources, instructs PhoneGap build to build the project, and then downloads the result. The result is a native program, suitable for running on Android or iOS phone.

In addition mBuild generates files needed for your application to be a Progressive Web Application (PWA). This can be useful even if you are not building for Android or iOS, and hence are not using PhoneGap Build.

Installation

mBuild is installed by the NetTalk Apps installer. It is installed (by default) into the \clarion\accessory\bin\mbuild folder.
If necessary you can move it to any folder you like by simply moving all the files in the folder.

The data files for mBuild are located (by default) in C:\ProgramData\CapeSoft\NetTalk\mBuild
You can select an alternative folder for the data files if you prefer - this is done vial the Tools menu, Options, Data folder.
The location of the data folder is stored in C:\ProgramData\CapeSoft\NetTalk\mBuild\Settings.Ini

Running

To run mBuild click on the icon on the Clarion IDE Toolbar, or navigate to the appropriate folder and run the mbuild.exe file.


Command Line

In order to automate build processes mBuild can be run from the command line. The following commands are supported;
idThe command line ID for the project. This value is required.
/makeDo a Generate and a Build of the project.
/buildDo a Build of the project.
/generateDo a Generate of the project.
/doneClose the mBuild program when the process is complete (successfully or not.) The result will be written into mbuild.log.

Example

c:\clarion11\accessory\bin\mBuild.exe id=abc /make /done

Hybrid Applications

The applications created by mBuild, for Android and iOS are sometimes referred to as Hybrid applications. They are applications written in HTML / JavaScript / CSS and then wrapped in a native container for the appropriate platform. The result (APK, or IPA) can then be loaded on devices, or uploaded to the appropriate application store.

The primary advantage of hybrid applications is that they are cross platform, allowing a single code-base to be used on both operating systems. Because they are wrapped in a native container they have access to all aspects of the local device, including things like the camera, GPS, address book and so on.

The primary disadvantage is that as JavaScript code they run slower than programs written in a compiled language (Java or Swift). Slower is however a relative term, and even on under-powered hardware the performance is typically fast enough for the user not to notice. This is especially true for the kinds of applications which business users will typically want to deploy.

Because hybrid applications are HTML based they are very portable, and the same code can be used in a normal online web application, a hybrid application, and a progressive web application. This makes them very efficient to maintain, especially for small teams or individual developers.

Progressive Web Applications (PWA)

A complete discussion on the concept of Progress Web Apps is beyond the scope of this documentation, but a brief introduction is useful.

The essence of a PWA is packaging a web app in a specific way which allows the device to "install" the web app locally, with an icon on the home screen, to load instantly (even if the phone is offline) and to run without any browser frame around the app.

Progressive Web Apps can only be served on a secure (HTTPS) connection, which fortunately is a trivial (and free) thing to do now with NetTalk and LetsEncrypt.

From NetTalk's perspective you build a PWA exactly as you would build a hybrid application. It is designed to be completely self-contained, and work even if the device is offline. The user ultimately experiences the application in exactly the same way, and once installed it is hard (or impossible) to tell the difference between the two approaches.

PWA apps do not need to be distributed by the app store, and do not need to be installed by the user. The user simply accesses your app using their browser, and after a few usages will then be given the option to install it. They can choose not to and simply continue using it as a web app if they choose.

PWA apps have limited access to the underlying hardware. They can still access whatever hardware is exposed by the operating system (GPS and camera being the most important) but some other functionality (like address book) is hidden away.

Because PWA apps run in the browser, and because the user can have a modern browser (even on old versions of iOS or Android) the PWA is available to a wider audience of users - especially those with older phones.

With NetTalk and mBuild you can thus generate native (hybrid) apps for installation on devices, and PWA applications at the same time, with no extra effort. Your users can then decide which approach they prefer.

Additional Reading

Google has a nice introduction here;
https://developers.google.com/web/progressive-web-apps/

Wikipedia's article on it is here;
https://en.wikipedia.org/wiki/Progressive_Web_Apps

Phone Gap Build

To make use of mBuild to create Android or iOS apps, you will need to create a Developer Account at Adobe's PhoneGap Build service. You can create a free account (which limits you to a single, project) or use their Paid Plan (currently $9.99 per month) to allow for up to 25 projects at a time.

Once you have signed on to PhoneGap Build you will need to supply your login credentials to the mBuild program. This is done via the Tools menu, Options screen, Adobe PhoneGap Build tab. You will need your user name and password here. The password will be encrypted, base64 encoded, and stored in the settings.ini file.

Certificates / Keys

In order to create applications for the various operating systems, you need code-signing certificates for those platforms. It is possible to create Android apps without a certificate, for debugging and testing purposes, but this option is not available on the other platforms.

mBuild includes a Key Manager which helps you to create, upload and manage your development keys. You do not need an Apple computer to do this.

Projects

The heart of the mBuild system is the project file. You can access the Project list on the Projects tab.
From this tab you can Insert, Change and Delete projects. You can also trigger a Generate, PG Build, or Make option.

Project Settings

Each project contains the following settings. It is likely that these settings will grow fairly rapidly so keep an eye on this documentation for new settings.

Details Tab

Name
The name of the project. This must match the name in the PhoneGap Build system (or alternatively you will need to manually enter the PhoneGap build Project ID.)
Short Name
If the name of your project is long, then a short name can be entered here. This can make the app easier to identify on devices with small screens.
Description
A description for the project.
Build For
You can select one, or more, of Android, iOS and PWA (Progressive Web App) here.
Command Line ID
A unique ID for the project so that it can be built from the command line. You can put anything you like in here, as long as it's unique. No spaces or other punctuation is recommended.

Generate Tab

Server URL
This is the server from which you will get the resources .In other words, this is the URL of the server which will serve the disconnected web app.
PhoneGap Resources
This is a folder containing icons and splash screens for the different devices, and for different screen resolutions. Typically this is set to the same place where you created the resources using the Image Manager.
Deployment Folder
This is a temporary (empty) folder that will be used as a store for the data during the build process.
Zip Path & Name
PhoneGap Build takes in resources as a single file which is zipped together. All the files in the deployment folder will be zipped up into this file. This setting allows you to set the path, and name, of the output ZIP file. You are allowed to store this zip file inside the deployment folder (although you may just as easily store it in any other folder.) It is automatically deleted when a Generate takes place and so it is not included in itself.

Build Tab

Version
Enter a version number here. This is typically of the form n.n.n
Reverse ID
Enter the domain for the product, or company here, using reverse DNS notation. For example com.capesoft.mbuild
Default Icon (png)
The default icon will be used on any device where the specific icon resource needed is not identified in the config.xml. This file must be in PNG format, not ICO format.
Default Splash
The default splash graphic will be used here where the specified splash resource is not identified in the config.xml.
PhoneGap Build ID
If the name of your project in mBuild matches the name of the project in PhoneGap Build, then you can leave this item blank, it will be populated when the first PG Build or Make is done. If the names do not match then get the ID number from the PhoneGap Build interface and enter it here.

Keys Tab

You can set these separately for iOS and Android. Use the lookup button to select the appropriate key from the Key Manager. If your key is not in the Key Manager then you can enter the Key ID (as it is in PhoneGap Build) manually.

PWA Tab

One of the items required by a PWA is a Manifest file. This file contains information about the application. The necessary information can be entered on this tab.
Start URL
The URL, relative to your web site, which is the "start" URL for the app. this is almost always just /    
Scope
This defines the scope of the PWA, and again it is almost always just /  
Display
This determines how the app should display if the user starts it from their home screen. The most common option here is stand-alone.
Theme Color
If the app is presented in a browser (before, or after, it is installed) this tells the browser the primary theme color of your application and so what theme it should in turn adopt so that it looks good. You can enter any web color here. For example if your application is mostly green then you can set this to #0000FF.
Background Color
The same as the theme color, but for the background.
Language
The language of the application.
Orientation
the preferred orientation for the application.

Result Tab

Install Folder
The location where the APK and IPA files will be placed when done. This could be anywhere, but one possibility is the application's \web\install folder. Then users can download the APK or IPA from your site.
PWA Web Folder
The location where the PWA files will be placed when done. Typically this is the web folder for the app itself (since these files are served by the web folder).
Result File Android
When the build completes an APK file will be created. This APK will automatically be downloaded and saved to the location, and name, specified in this setting. Enter your desired location, and name, of the APK file here.
Result File iOS
When the build completes an IPA file will be created. This IPA will automatically be downloaded and saved to the location specified by the install folder. The resultant name will be shown here after the file is downloaded.
URL Android
The APK will be made available for direct download to your Android device by PhoneGap Build. The URL to this file will be fetched and placed into this field for you.
URL iOS
The IPA will be made available for direct download to your iOS device by PhoneGap Build. The URL to this file will be fetched and placed into this field for you.
QR Install Image
Since the Phone Gap build URL is likely to be long and complicated, a QR code is provided to this URL. This simplifies installation on the device.

Config.Xml Tab

Use Default
This loads the defaultconfig.xml file from the same folder as mBuild.Exe, into the config.xml field.
Config.XML
The config.xml file is used by PhoneGap Build as the place where all the settings regarding the build are set. A default config file ships with mBuild and can be used as a starting point. It is expected that there will be more functionality in mBuild in the near future to make setting the various items in the config.xml easier. For now the field can be edited by hand as required. Note that the following "tags" are already supported based on other settings in the project;
TagDescription
<!--[name]-->The project Name setting.
<!--[description]-->The project Description setting.
<!--[version]-->The project Version setting.
<!--[reverseid]-->The project Reverse ID setting.
<!--[ios]-->If the iOS checkbox in the project is on, then this adds <gap:platform name="ios" /> to the xml file.
<!--[android]-->If the Android checkbox in the project is on, then this adds <gap:platform name="android" /> to the xml file.
<!--[winphone]-->If the WinPhone checkbox in the project is on, then this adds <gap:platform name="winphone" /> to the xml file.


Building a Project

The build process takes place in two steps. mBuild provides a toolbar button for doing each step individually, (Generate and PG Build) as well as a button for doing both steps together (Make).

Generate

The first step consists of collecting all the resources for a project together, and then creating a ZIP file of them. This step uses the settings on the Generate tab of the Project settings.
Some of the resources are collected directly from a web server, while others are copied from a resources folder on the drive.
The files are collected together into the Deployment folder.
All the items in this folder are then zipped together into the zip file.

If additional files are placed in the deployment folder then they will also be included in the ZIP file.

PG Build

The second step uploads the ZIP file (created in Generate above) to the PhoneGap Build web service. A Build event is triggered there, and the service is monitored to see when the build has been completed. When the build is complete then the resultant file, or files, are downloaded to the current machine. This step uses the settings on the Build tab of the project settings.

Make

The Make option combines both steps into a single task. The Generate code is first done, then the PG Build code is done.

Stop

If you wish to stop a build once it has started, press the Stop button.

Log

A log will be created as the project is generated or built. The most recent log will be saved into the data folder (see About window) as mbuild.log

Tools

The Tools menu contains important setup information which you will need in order to use mBuild.

Options

Data Tab

Data Path
The data path for mBuild, where the mBuild data files will be stored.

Adobe PhoneGap Build Tab

Your Phone Gap build User ID and Password.

Apple Developer Tab

Your Apple Developer User ID and Password. This is used by mBuild to generate keys. If you already have keys you can manually upload them to PhoneGap build, add the ID to the Key Manager, and these details are not needed.

Certificate Data Tab

The usual information required when creating certificates. All these fields should contain something. (The exact contents is not verified.)

Key Manager

The Key Manager is located in the Tools menu. It allows you to generate keys for both Android an iOS and upload those keys to the Phonegap Build web service. You do not need an Apple computer to do this.

The Key Manager does make use of keytool.exe, which is part of the Java Runtime Environment. So if you are using the Key Manager to create keys for Android, you will need Java to be installed on the machine. (this is the JRE - The Java Runtime Environment, not the development SDK).

You can create as many keys as you like, and organize them with names. You can then assign one, or two keys to your projects as needed from your list of keys.

Image Manager

The Image Manager is located in the Tools menu. It allows you to generate a range of icons and splash screens from a single source icon, and single source splash screen. This delivers the best results in the final program regardless of the screen-size and resolution that the user is using.

Note: On mobile device "Icons" are not in the ICO format, but in PNG format.

The Image Manager will work file files of any size, but it's likely to do a better job down-scaling than up-scaling. For this reason the larger the source image the better. For icons the image is square, for splash screens it is typically an aspect ratio of 2.

[End of this document]
Return to NetTalk Documentation Index