In this article Elodie Eberhardt, explains how this feature can be used and how to setup the required environment.
As of Convertigo 7.2 Studio now supports local builds. This feature is very useful, for building mobile apps when access to cloud resources are difficult in a security restricted environment, for example. Also, local build gives more flexibility for building options.
Local Build architecture
Local build works by controlling the Cordova CLI (command line interface) directly from Convertigo Studio. This means that to use local build you must have installed on your workstation a full Cordova building system. Once this is done, you will be able to launch builds directly from Convertigo Studio. Also, as local build relies on Cordova, there are some restrictions about what you can build from what workstation. Please refer to the following table for Mobile Platforms/OS compatibility:
Windows Phone 7
Windows Phone 8
Mac OS X
|Cordova 3.6.3||Cordova 3.6.3|
|Cordova 3.6.3||Cordova 3.6.3|
|Cordova 3.6.3||Cordova 3.6.3||Cordova 3.6.3|
Setting up the environment
Local build needs a working Cordova environment setup. Local build in version Convertigo 7.2 is tested with Cordova 3.6.3. Other Cordova versions are not supported.
Your workstation should be able to run Cordova CLI. To do this follow these steps :
- Install Node.JS
- Install the Cordova utility. In Unix, prefixing the additional sudo command may be necessary to install development utilities in restricted directories:
$ sudo npm install -g email@example.com (For Linux; MacOS X workstations) or
C:\>npm install -g firstname.lastname@example.org (For Windows workstations)
Also, please refer to the Cordova installation guide for the platforms you want to build to install all the needed components for the target platforms.
- Do not install the Eclipse + ADT bundle. Install only the Standalone SDK
- Install API version 19.1 maximum
- You will also need ANT as specified in Cordova’s documentation
- Windows Phone 7
- Windows Phone 8
- Blackberry 10
Configuring Convertigo Studio for Local Build
As Convertigo Studio uses the Cordova’s CLI, you may have to configure various PATHs for the tools Cordova will use. To do this, use Studio’s Preferences:
Type In this field any PATH to tools required by Cordova separated by “;” (for Windows) or by “:” (for Linux or Mac OS)
Using local build
Local build menu is available by right clicking on a target platform under the MobileApplication folder in the Convertigo projects view. The ‘Cordova’ sub menu will give the following options:
- Run on emulator : Builds (In debug mode) and runs the selected platform on the emulator. Corodva will select the emulator according the SDKs configuration.
- Run on device : Builds (In debug mode) and runs the selected platform on a device connected to your workstation.
- Clear Cordova : Removes all this project’s Cordova environment. This can be useful for failed builds to restart from a fresh and clean Cordova environment.
- Remove platform : Removes the selected platform from the Cordova environment. This can be useful to clean a specific platform’s build environment.
- Local build (debug) : Builds locally in debug mode the selected platform without launching the app.
- Local build (release) : Builds locally in release mode the selected platform without launching the app.
A local build can not start if the property “Convertigo server endpoint” is not configured in the “Mobile_application” object. You should configure there the Convertigo Server’s URL your mobile app will call to run. If you build for development and debug, configure here your own studio’s URL (Be sure that your mobile can access your local machine using WIFI for example). This URL will have this pattern:
http://[my studio machine ip adress]:18080/convertigo
If you build for production or pre-release, configure here the Convertigo server’s production or pre-release url
https://[my domain name]/convertigo (For on premises deployment) or https://[my cloud name].convertigo.net/cems (for cloud deployements)
Local build process will start by asking you to create a Cordova environment for the current project. This environment will be created in the _private directory of your project. Click “Ok” to create the environment.
If the Cordova environment cannot be created, an error message will be displayed. Most probably this message will appear if Cordova is not yet installed on your system or if the Cordova command cannot be found in the PATH.
When a build is triggered, it will run as an Eclipse job, so you can run it in background. All the build progress will be displayed in the “engine log” view at INFO level. When the build is complete, a dialog box will display the build result (.APK, .XAP).
For iOS builds on MacOS X, the dialog box will display the path of the Xcode project, so you can have the opportunity to launch Xcode and “Archive” the project to generate the .IPA file with a selected provisioning profile and certificate.
During the build process, some resources such as Cordova libraries and plugins may be downloaded, be sure to have Internet access. Also, as Cordova uses NodeJS NPM engine, be sure to configure proxy access if needed by issuing the flowing commands in a command shell :
npm config set proxy http://mycompanyproxy:port npm config set https-proxy http://mycompanyproxy:port
Local build will automatically manage your Cordova plugins. Required plugins will be read from the target platform’s config.xml stored in :
Only new plugins, not already installed for this Cordova environment, will be downloaded from the Internet. The config.xml file plugin reference is identical to Phonegap build specifications. For example :
<gap:plugin name="com.phonegap.plugins.pushplugin" version="2.1.1" git="https://github.com/phonegap-build/PushPlugin.git">
- The name attribute represents the plugin id as referenced in the Cordova plugin registry at http://plugins.cordova.io/#/
- The version attribute is the optional plugin version. If possible set this to a fixed version to avoid using any latest plugin at each build.
- The git attribute is the optional GIT plugin’s repository url. If present, the git attribute will be used in priority over the name attribute. This is useful to reference a plugin that is officially registered on plugins.cordova.io but not yet on PhoneGap build.