Build using Cordova* CLI

Please see this updated article for the latest information regarding exporting to Cordova CLI > <

This document assumes that you have successfully exported your Intel XDK project using the Cordova Build Package export tool. For instructions on to export your project, see the doc page titled Export to PhoneGap Build and Cordova CLI.

Requirements to Build with Cordova CLI 6.x

Building your app locally (on your development system) with Cordova CLI 6.x requires installation of Node.jsCordova CLI and the appropriate vendor-specific development tools for the targets of interest (i.e, Android Studio* for Android, Apple* Xcode* for iOS and Microsoft* Visual Studio* for Windows).

Building for iOS requires OS X and Xcode; building for Windows requires Windows 8.1+ and Visual Studio; building for Android is supported on Windows, OS X and Linux.

Details regarding the necessary tools, versions and system requirements can be found on the following pages of the Cordova CLI 6.x documentation:

Installing Node.js and Cordova CLI 6.x

You must install the appropriate native development tools before you can use Cordova CLI on your development system! The instructions that follow do not explain how to install those native tools. It is best to install them first before installing Cordova CLI. See the links above for details and pointers to install those native development tools.

See the instructions in this Create your first Cordova app documentation page for a detailed discussion about how to create, build and test apps using Cordova CLI 6.x. The following sections will guide you through a typical installation. In this case, we will install the latest version of Node 6.x and Cordova CLI 6.2.0.

Installing Node.js

If you need to manage multiple versions of Node.js on your development system, install Node Version Manager first and then use it to install Node.js. This will allow you to easily install and switch between multiple versions of Node.js. Windows users can use Node Version Manager for Windows to manage multiple versions of Node.js.

Assuming you are NOT using Node Version Manager, follow these instructions to install Node.js on your system.

On Windows and Mac, go to the Node 6.x latest distribution folder and download the Windows MSI installer or the Mac PKG installer. For example, at the time this doc page was written, the latest version of Node 6.x was 6.11.0. So the following installers were available to downloaded from the Node 6.x latest distribution folder:

  • node-v6.11.0-x86.msi  <  for installation on Windows (32-bit or 64-bit)
  • node-v6.11.0.pkg  <  for installation on Mac OSX

Each of the above is a "runnable executable" for the respective platform. You can "double-click" the appropriate installer file that you have downloaded and it will install and configure Node.js 6.x for your system.

To install the latest version of Node 6.x on a recent Debian or Ubuntu system, use the following command-line:

$ curl -sL | sudo -E bash -
$ sudo apt-get install -y nodejs

For help with installing Node.js on other Linux systems, see this very useful GitHub repo >

To test your installation of Node.js, type the following at a command-line:

> node --version

If you see a result similar to the above, you have successfully installed Node.js 6.x.

Installing Cordova CLI 6.x

To manage multiple versions of Cordova CLI install Version Manager for Cordova Software before installing Cordova CLI. You can use then use "cvm" to to install and switch between multiple versions of Cordova CLI.

Assuming you are not using Version Manager for Cordova, follow these instructions to install Cordova CLI 6.2.0 on your development system.

> npm -g install cordova@6.2.0

This will force installation of Cordova CLI 6.2.0, which matches the CLI 6.2.0 option in the Intel XDK build settings. That is, this version of Cordova CLI will give the same build results as that used by the Intel XDK build system when you select the CLI 6.2.0 option in the Build Settings section of the Projects tab.

To test your installation of Cordova CLI, type the following at the command-line:

> cordova --version

If you see a result identical to the above, you have successfully installed Cordova CLI 6.2.0.

IMPORTANT: Versions of Cordova CLI prior to 6.x do not reliably add all the plugins listed in the config.xml file and Cordova CLI 7.x adds new requirements to project and plugin configuration files that may not be compatible with the configuration files exported by the Intel XDK. To get started we recommend you install Cordova CLI 6.2 or CLI 6.5. You can install CLI 6.5 using the following npm command:

$ npm -g install cordova@6.5.0

Test Your Node + CLI Installation

You can use this simple test to confirm that your Cordova CLI build environment is ready to use:

> cordova create test
> cd test
> cordova platform add android
> cordova prepare
> cordova build android

This example test assumes you are building for Android and using Cordova CLI 6.x.

If the test above failed at the "prepare" or the "build" step, try running the following command to get information on what might be missing:

> cordova requirements

Requirements check results for android:
Java JDK: installed 1.8.0
Android SDK: installed true
Android target: installed android-7,android-8,android-9,android-10,android-11,android-12,android-13,android-14,android-15,android-16,android-17,android-18,android-19,android-20,android-21,android-22,android-23,android-24,android-25,android-26
Gradle: installed 

The results shown above are for a working Android SDK and tools installation. When "cordova requirements" fails, it will look something like this:

> cordova requirements

Requirements check results for android:
Java JDK: installed .
Android SDK: installed
Android target: not installed
Android SDK not found. Make sure that it is installed. If it is not at the default location, set the ANDROID_HOME environment variable.
Gradle: not installed
Could not find gradle wrapper within Android SDK. Might need to update your Android SDK.
Looked here: C:\Users\<userid>\AppData\Local\Android\sdk\tools\templates\gradle\wrapper
Error: Some of requirements check failed

In that case, see this forum thread and the details in this forum post located within that thread for help resolving your Android SDK setup.

If you are building for iOS or Windows simply replace android with ios or windows in the lines above. Note that because Cordova CLI runs on Node.js, the commands are identical, regardless of your development machine’s operating system (OS).

Type cordova help for additional commands and see the cordova-cli GitHub* repo for a complete list of the Cordova CLI commands that are available.

Build the ZIP Project with Cordova CLI

Once all the necessary Cordova CLI build tools are in place you can build your app directly at the command line. See the Cordova documentation for complete details.

In essence, you will do the following to build a mobile app package with the contents of the exported ZIP project, using Cordova CLI:

  • Unzip the ZIP file you exported with the Create Cordova Package tile.
  • Perform a cordova platform add <platform-name> for each platform.
  • Perform a cordova build <platform-name> for each platform.

When you are ready to build a package to be submitted to an app store, you will need to add your signing certificates to the Cordova CLI project, so you can build a signed app. Otherwise, you can use the default signing certificate provided by Cordova CLI to debug your app.

The Cordova CLI documentation provides instructions regarding how to:

Once you have signing certificates in place (see the section below titled Transferring Signing Certificates to Cordova CLI for additional help), you can include them in your build process. In most cases the best option will be to create a build.json file that you can reference during the build (see the Cordova CLI Using build.json sections contained within the various sign an app links provided above).

If you encounter issues when building for iOS, especially an "error 65" message, you are probably experiencing app signing issues. This StackOverflow post may be of value. Likewise, employing this hook.js file by Darryl Pogue may be helpful. Finally, this guide to signing iOS apps may be of interest to the very curious.

The --debug and --release and --device Cordova CLI options are not well documented, but are essential for creating a "debug" or "release"iOS build and for directing Cordova to build an IPA package rather than a simulator image for use with the Xcode iOS simulator. See this forum post for help configuring and signing your iOS project for a successful build with the Cordova CLI tools.

See the cordova-cli GitHub* repo for a complete list of the Cordova CLI commands that are available.

See this forum post for help configuring and signing your iOS project for a successful build with the Cordova CLI tools.

Transferring Signing Certificates to Cordova CLI

iOS Signing Certificates:

It is much simpler to create a new set of iOS signing certificates, using the iOS signing instructions provided by PhoneGap Build, than it is to transfer existing iOS developer certificates stored in the Intel XDK build system to your Cordova CLI project.

If you have trouble creating your iOS signing certificates on a Mac (using the Mac instructions), use the Windows iOS signing certificate instructions, instead. The instructions to create an iOS signing certificate on a Windows PC will work on all platforms (Windows, Mac and Linux).

Windows Signing Certificates:

Likewise, it also simpler to create a new Windows signing certificate for use with PhoneGap Build using your Microsoft Developer Account. The process is explained in the PhoneGap Build signing instructions for Windows.

Android Signing Certificates:

IMPORTANT: if you have never published an APK to an Android store you can skip this section and create a new signing certificate by following the PhoneGap Build signing instructions for Android.

If you have published an APK to an Android store, using the Intel XDK, you must continue to use the same Android signing certificate to publish updates to your app. This means you must use your Intel XDK developer certificate to build and sign your APK when performing a release build with Cordova CLI (if you are only debugging your app you can use the default signing certificate that Cordova CLI automatically provides).

Find the developer certificate you have been using to sign your published apps, in the Intel XDK Certificate Management tool. From there download the certificate and use it to sign your Android app that you are building with Cordova CLI.

If the signing certificate you used to publish your APK is not in the Intel XDK Certificate Management tool, we cannot help you retrieve it, the only certificates stored by the Intel XDK build system are those that you can download directly from the Certificate Management tool, under the Account Settings icon, as shown above.

If you have never converted your Android "legacy" certificate you must first do so before you can download it using the Certificate Management tool; see this video for help with that process. If you are not seeing all the fields in the certificate management dialogs, please see this forum post for help.

When it comes time to build your Android app, with the signing certificate you retrieved from the Intel XDK, you will need both a certificate password and a keystore password. Any keystore file you created with the Intel XDK and downloaded from the Certificate Management tool contains a single certificate. When you created that keystore using the Intel XDK, if you chose to use a single password for both the certificate and the keystore, use that one password to unlock your signing certificate; otherwise, you must provide both passwords.

IMPORTANT! It is very important that you keep a copy of your keystore in a safe place and remember the password(s). Once deleted or lost, we cannot help you retrieve that information!

Building with Crosswalk

IMPORTANT: The Crosswalk project was retired in February, 2017. We recommend you change your Build Settings to build for Android 4.4 (minimum API level 19) and later and discontinue using Crosswalk unless your application truly requires it. Cordova applications that run on Android versions 5 and above will see little or no benefit from using Crosswalk, unless you are using APIs that are unique to the Crosswalk runtime. If you have been using Crosswalk and choose to stop using it, you may experience some issues with the Android "versionCode" number; see this article for help with Android versionCode issues.

If your project is configured to build for Crosswalk on Android, the exported config.xml file includes a preference tag that directs Cordova CLI to create a "multi-architecture" APK file. This is different than the cloud-based Intel XDK build system, which created two "single-architecture" APK files that were delivered in a single ZIP file. This behavior is caused by the following tag:

    <preference name="xwalkMultipleApk" value="false" />

A “multi-architecture” Crosswalk APK file contains both the x86 and the ARM Crosswalk 32-bit libraries in a single APK file. This tag is added to your config.xml file because PhoneGap Build will only return a single APK file when it performs a build.

You can unzip any multi-architecture APK you build to see both Crosswalk libraries included in the package.

Removing the xwalkMultipleApk tag from the config.xml file (or changing the tag “value” to “true”) and building with Cordova CLI will result in generating two APK files, but they will not be bundled into a single ZIP file.

Unfortunately, it is not obvious, when you look at the Cordova CLI build messages, that two APK files were generated. The two Crosswalk APK files are located inside your Cordova CLI project:

$ cd platforms/android/build/outputs/apk/
$ ls -al
total 395904
-rw-r--r--  1 username  staff    24M Mar 27 10:09 android-armv7-debug-unaligned.apk
-rw-r--r--  1 username  staff    24M Mar 27 10:09 android-armv7-debug.apk
-rw-r--r--  1 username  staff    46M Mar 27 10:06 android-debug-unaligned.apk
-rw-r--r--  1 username  staff    46M Mar 27 10:06 android-debug.apk
-rw-r--r--  1 username  staff    27M Mar 27 10:10 android-x86-debug-unaligned.apk
-rw-r--r--  1 username  staff    27M Mar 27 10:10 android-x86-debug.apk

See this forum post for a more detailed example.

[OPTIONAL] Integrating Cordova CLI with the Intel XDK

If you want to build your app using Cordova CLI, and continue to use the Intel XDK to edit and debug (e.g., using App Preview and the Simulate tab) you should create a mirror Cordova CLI project that links back to the Intel XDK project sources. The mirror CLI project contains links to the www and package-assets folders located in your Intel XDK project.

IMPORTANT: the technique described below assumes you are familiar with the use and concept of filesystem “links” and that you are comfortable using OS command-line tools (ln on OSX and Linux and mklink on Windows). If this is not the case you should not use this technique!!

For example, assume you have an Intel XDK project (the master project) named my-project and your mirror CLI project is (the slave project) named my-project-cli.

Here are the contents of the master Intel XDK project folder, named my-project:

And here are the contents of the new slave Cordova CLI project folder, named my-project-cli (before any Cordova commands have been executed):

The small arrows on the www and package-assets folders in the slave folder image indicate a symbolic link that points back to the same-named folders in the master project folder (these images are from OSX, other operating systems may display links differently). If we look at the command-line we see something like this (again shown on an OSX machine, other systems will display differently):

$ ls -gon
total 24
-rw-r--r--  1   1111 Feb  3 18:23 config.xml
lrwxr-xr-x  1     29 Feb  3 15:27 package-assets@ -> ../my-project/package-assets/
lrwxr-xr-x  1     17 Feb  3 15:26 www@ -> ../my-project/www

The following steps were taken to get to this state:

  • Create a mirror CLI folder (in this example: my-project-cli).
  • Generate a config.xml file using the Create Cordova Package tool or the xdk-to-cli script.
  • Copy the config.xml file into the mirror CLI folder (e.g., my-project-cli).
  • Create links to the www and package-assets folders in the master project folder (e.g., my-project).
  • If there are other important folders you need in the mirror project, create similar links to those folders. This is not likely, since Cordova CLI and the Intel XDK only need to share the www and package-assets folders.

Now perform the commands (assuming you will be building for Android):

$ cd my-project-cli
$ cordova platform add android
$ cordova prepare

Following the steps above, your my-project-cli folder should look something like this:

The platforms and plugins folders were created by the cordova platform add  and cordova prepare command(s) and contain the additional source and binaries files needed by Cordova CLI to perform a local build on your machine (assuming all of the necessary build tools have been installed onto your development machine).

Now you can rebuild your app in your my-project-cli folder with Cordova CLI after making changes to your app using the Intel XDK (which is operating on the master files in the my-project folder).

IMPORTANT: if you change Build Settings or add/remove plugins using the Projects tab of the Intel XDK, you must generate a new config.xml file and update that file and plugins within your mirror project.

Keeping plugins in-sync, between the master project and the CLI slave project, can be challenging; especially if you are making frequent changes to the plugins in your project using the Intel XDK Plugin Management tool on the Projects tab. There is no single “right way” to do this. Below are a few suggestions of how to handle this task, in no particular order:

  • Perform the same operation(s), by hand, in your mirror project, using the cordova plugin add  and cordova plugin remove  commands.
  • Use the cordova prepare command to have CLI automatically add plugins per changes to the config.xml file — unfortunately, this procedure will not automatically remove plugins that have been removed from the config.xml file, those you will have to remove by hand using the cordova plugin remove  command.
  • Delete the plugins folder in your slave CLI project and use the cordova prepare command to automatically add back the plugins found in the new config.xml file.
  • Delete the plugins and the platforms folders in your CLI slave project and perform a cordova platform add  operation, which will simultaneously add the plugins listed in the new config.xml file.

All of the above strategies have pros and cons, none is a perfect solution. What works best for you will only be determined through time and experience.

Using the ‘xdk-to-cli’ Node.js Script

If you are unable to successfully create a ZIP file using the Cordova Build Package tile, or you want more control over that process, you may need to use this xdk-to-cli Node.js script. Full instructions and requirements are provided in the script’s README file.

For more complete information about compiler optimizations, see our Optimization Notice.