A version of this article was originally published as part of the Intel® XDK documentation book.
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 your Intel® XDK Mobile App to PhoneGap* Build or 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.js, Cordova 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).
IMPORTANT: Building for iOS requires macOS and Xcode; building for Windows requires Microsoft 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.
The instructions in the Create your first Cordova app documentation page provide 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 the following, we will install the latest version of Node 6.x and Cordova CLI 6.5.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 install and manage multiple versions of Node.js.
Assuming you are NOT using Node Version Manager, use the following instructions to install Node.js on your system.
Installing Node.js on Windows or Mac
For Windows or Mac, go to the Node 6.x latest distribution folder and download the Windows MSI installer or the macOS PKG installer. For example, at the time this article was written, the latest version of Node 6.x was 6.11.2. So the following installers were available to downloaded in the Node 6.11.2 distribution folder:
- node-v6.11.2-x86.msi < for installation on Windows (32-bit or 64-bit)
- node-v6.11.2.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.
Installing Node.js on Debian or Ubuntu
To install the latest version of Node 6.x on a recent Debian or Ubuntu system, use the following command-line:
$ curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash - $ sudo apt-get install -y nodejs
For help with installing Node.js on other Linux systems, see this useful GitHub repo > https://github.com/nodesource/distributions.
Testing your Node.js Installation
To test your installation of Node.js on any OS, type the following at a command-line:
> node --version v6.11.2
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 Softwarebefore installing Cordova CLI. You can use then use "cvm" to to install and switch between multiple versions of Cordova CLI.
If you are not using Version Manager for Cordova, follow these instructions to install Cordova CLI 6.5.0 on your development system.
> npm -g install cordova@6.5.0
This will force the installation of Cordova CLI 6.5.0.
IMPORTANT: If you want to match the CLI 6.2.0 option that was in the retired Intel XDK build settings, specify "cordova@6.2.0" instead of "cordova@6.5.0" in the above command line.
To test your installation of Cordova CLI, type the following at the command-line:
> cordova --version 6.5.0
If you see a result identical to the above, you have successfully installed Cordova CLI 6.5.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 config.xml file exported by the Intel XDK.
For best results building your Intel XDK mobile app with Cordova CLI we recommend that you install Cordova CLI 6.2.0 or 6.5.0.
Version 6.2.0 of Cordova CLI will give the same build results as that used by the retired Intel XDK build system, if you had selected the CLI 6.2.0 option in the Build Settings section of the Projects tab. For additional help with CLI versions, see this Intel XDK FAQ.
You can install CLI 6.2.0 using the following npm command:$ npm -g install cordova@6.2.0
Test Your Node and Cordova CLI Installation
You can use this simple command-line 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 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, especially 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 you type 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 target platform. - Perform a
cordova build <platform-name>for each target 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 build a debuggable version of your app.
The Cordova CLI documentation provides instructions regarding how to:
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:
You do not need to transfer your iOS signing certificates or mobile provisioning files from the Intel XDK to PhoneGap Build!!
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, and only if, you have published an APK to an Android store, using the Intel XDK, you should continue to use the same Android signing certificate to publish updates to your app. This means you may want to 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 (the precise name of the certificate's alias will probably be different than what is shown in the image below):
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 32-bit Crosswalk libraries for both x86 and ARM mobile devices in a single APK file. The xwalkMultipleApk tag is necessary because PhoneGap Build returns only a single APK file when it performs a Crosswalk build, unlike the retired Intel XDK build system, which returned a ZIP file that contained two APK files, one for x86 and one for ARM.
If you unzip a multi-architecture APK you can see both Crosswalk libraries included in the package.
Since you are using Cordova CLI to build your app, and not PhoneGap Build, you can, optionally, change the value of this preference tag. 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 the Simulate tab) you can 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 macOS 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 macOS, other operating systems may display links differently). If we look at the command-line we see something like this (again shown on an macOS 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.xmlfile using the Create Cordova Package tool or thexdk-to-cliscript. - Copy the
config.xmlfile into the mirror CLI folder (e.g.,my-project-cli). - Create links to the
wwwandpackage-assetsfolders 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
wwwandpackage-assetsfolders.
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 …andcordova plugin remove …commands. - Use the
cordova preparecommand to have CLI automatically add plugins per changes to theconfig.xmlfile — unfortunately, this procedure will not automatically remove plugins that have been removed from theconfig.xmlfile, those you will have to remove by hand using thecordova plugin remove …command. - Delete the
pluginsfolder in your slave CLI project and use thecordova preparecommand to automatically add back the plugins found in the newconfig.xmlfile. - Delete the
pluginsand theplatformsfolders in your CLI slave project and perform acordova platform add …operation, which will simultaneously add the plugins listed in the newconfig.xmlfile.
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.