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.
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
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.
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 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;
| Tag | Description |
|---|
| <!--[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.
Tools
The Tools menu contains important setup inforamtino 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]
