Understanding Intel XDK Cordova* Build Files

This document describes many of the directives you will see in the automatically generated Intel® XDK build config files in the root of your project directory. It can also be used to help you understand how to create an intelxdk.config.additions.xml file to modify build options that are set by the Projects tab's Build Settings and Plugins configuration panels. Adding Intel® XDK Cordova Special Build Options Using the Additions File describes that build config file.

The Intel® XDK build system uses special configuration files in your project directory to control its cloud-based Apache* Cordova CLI build system. Your application project files are submitted to a Cordova CLI system that is hosted and maintained on the Intel XDK build server; thus, there is no need to install the open source Cordova CLI system on your development system.

The Adobe* PhoneGap* CLI system and the Google* Mobile Chrome Apps project (aka cca) are based on the same Apache Cordova CLI open source project. The config.xml file used to direct the cloud-based Adobe* PhoneGap Build* environment is unique to PhoneGap Build; it is also a superset of the Cordova CLI config.xml file. You may find similarities between the Intel XDK configuration file and that used by PhoneGap Build, but they are neither compatible nor interchangeable. If you have an existing PhoneGap project you will need to import it into the Intel XDK and then configure your build options using the Intel XDK Projects tab.

Because this build system is derived directly from the Cordova CLI open source project, the Intel XDK build control files share many options with a local Cordova CLI config.xml file. The options used in the Intel XDK build configuration file are a superset of those used in the Cordova CLI config.xml file.

For each HTML5+Cordova project, you can specify the Cordova CLI version under Build Settings in the Projects tab. As of release 3088 of the Intel XDK, the default and recommended version of CLI is 5.4.1 and 5.1.1 is also available. This number refers to the Cordova CLI (command-line interface) version number, not the version of the Cordova device framework (see the Apache Cordova CLI 4.0 Release Notes for a coarse explanation of this version confusion). The precise Cordova platform versions that are “pinned” to CLI 5.1.1 can be found in the Apache Cordova CLI 5.1.1 Release Notes.

You cannot specify the precise version of the Cordova-Android platform framework to be included in your app when building for Android-Crosswalk, when using the CLI 4.1.2 system. The version of the Cordova Android framework that is included in your Crosswalk build is determined by the Crosswalk Project; that is, it is fixed by the Crosswalk version you select in the Build Settings section of the Projects tab. Crosswalk version 7 utilizes Cordova Android framework version 3.3.0 and Crosswalk versions 10 through 14 all are built with Cordova Android framework version 3.6.3 (Crosswalk packages built with the Cordova CLI 5.1.1 build system always use the Cordova-Android framework version 4.1.0).

The intelxdk.config.<platform>.xml File

The intelxdk.config.<platform>.xml file controls the behavior and application specific properties of the Intel XDK Cordova and Crosswalk build targets. This file follows the W3C Packaged Web Apps (Widgets) specification. The options used by the Intel XDK build system are subject to change.

intelxdk.config.<platform>.xml files are automatically generated by the Projects tab. A user-editable intelxdk.config.additions.xml configuration file is provided as a way to handle special case options that are not dealt with by the build GUI interface. The features described in this document can be used within that intelxdk.config.additions.xml configuration file.

The intelxdk Namespace

A namespace is required to designate this file for use by the Intel XDK. The following namespace entry must be present in the intelxdk.config.<platform>.xml files.

xmlns:intelxdk="http://xdk.intel.com/ns/v1"

Options Common to All Intel XDK Cordova Platforms

The settings described below are either modifications of or additions to the standard Cordova config.xml build options. Since the Intel XDK cloud-based build system is based on Cordova CLI, the standard Cordova config.xml build options can be used in addition to those described below. The options described below have been designed for use with the Intel XDK build system and will not work with other Cordova (or PhoneGap) build systems.

For a full list of Cordova supported settings see the Apache Cordova config.xml File Documentation.

See Adding and Managing Plugins for details on how to use third-party Cordova plugins as a way of extending your app's JavaScript API for access to unique device and platform features.

Including Cordova Plugins

Do not use this mechanism to include plugins as part of your application!! This element should not be used unless you are given specific instructions to do so by Intel support personnel in order to solve a specific problem with your project. Please see Adding and Managing Plugins for details and reasons why using the plugin management tool is the best way to work with plugins in the Intel XDK.

The Plugin tag provides information to the build system regarding which plugins have been added to your application. It is constructed as follows:

<intelxdk:plugin intelxdk:name="<NAME>" intelxdk:value="<VALUE>" intelxdk:version=”<VERSION>” />
where:
  • <NAME> is the description of the plugin.
  • <VALUE> is the package name or git repository representing the plugin.
  • <VERSION> is the [optional] version of the plugin (see next section for more info regarding plugin versions).
Some plugins may require, or optionally allow, parameters as part of their installation. Any parameters required by a plugin are specific to that plugin and are documented in that plugin’s documentation. Plugin parameters are indicated using the <param> tag:

<intelxdk:plugin intelxdk:name="<NAME>" intelxdk:value="<VALUE>" >
    <intelxdk:param intelxdk:name="<PARMNAME>" intelxdk:value="<PARMVALUE>" />
    .....
    <intelxdk:param intelxdk:name="<PARMNAME>" intelxdk:value="<PARMVALUE>" />
</intelxdk:plugin>
Specifying Custom Icons
The icon tag provides a mechanism to add launch (home screen) icons to your application.
<icon platform="<PLATFORM>" src="<SRC>" density="<DENSITY>" height="<HEIGHT>" width="<WIDTH>" />
where:
  • <PLATFORM> indicates for which platform the launch icon will be applied. Valid platforms are android, ios, windows8 and wp8. If this property is not supplied, a default icon is provided by the build system.
  • <SRC> indicates the path of the icon image file relative to the SOURCE DIRECTORY in your project (see the Projects tab in the Intel XDK).
  • <DENSITY> indicates the resolution of the icon image file. This property is required for and only used by Android. Valid values are xhdpi,hdpi, mdpi, and ldpi.
  • <HEIGHT> indicates the height of the icon image file in pixels. This property is required for iOS and optional for other platforms.
  • <WIDTH> indicates the width of the icon image file in pixels. This property is required for iOS and optional for other platforms.
Details regarding icon dimensions, sizes and image types can be found on the respective platform-specific pages (links provided below, in the next section).
Including Custom Splash Screens
The splash tag gives you a way to add a custom splash screen to your application. This static image will be displayed during app initialization for a preset period of time following initialization, or until your application calls the navigator.splashscreen.hide() function, whichever comes first.
<splash platform="<PLATFORM>" src="<SRC>" density="<DENSITY>" width="<WIDTH>" height="<HEIGHT>" orientation="<ORIENTATION>" />
where:
  • <PLATFORM> indicates for which platform the splash screen image will be applied. Valid platforms are android, ios, windows8, and wp8. If this property is not supplied, a default image is provided by the build system.
  • <SRC> indicates the path of the splash screen image file relative to the SOURCE DIRECTORY in your project (see the Projects tab in the Intel XDK).
  • <DENSITY> indicates the resolution of the splash screen image file. This property is required for and only used by Android. Valid values are xhdpi, hdpi, mdpi, and ldpi.
  • <WIDTH> indicates the width of the splash screen image file in pixels. This property is required for iOS and optional for other platforms.
  • <HEIGHT> indicates the height of the splash screen image file in pixels. This property is required for iOS and optional for other platforms.
  • <ORIENTATION> indicates the orientation of the splash screen image. Valid values are "portrait" and "landscape." This property is currently only used by Android platforms.
Details regarding splash screen image dimensions, sizes and file types can be found on the respective platform-specific pages (links provided below, in the next section).

Intel XDK Platform-Specific Options

Each Intel XDK Cordova build platform may have additional build options that can be added to the config file. These options are specific to that platform and have no impact on other target platforms.

Follow these links for details regarding the platform-specific build options:

Intel XDK "Android Crosswalk" Build Options

Adding Chromium-specific Command-line Options
This build option adds Chromium-specific command-line options to your Crosswalk build. See this List of Chromium Command Line Switches for a complete set of command-line switches (not all command-line switches work with all Crosswalk versions).
<preference name="xwalk-command-line" value="<OPTION>"/>
where:
  • <OPTION> specifies one or more Chromium command-line options separated by spaces.
This option works with either an embedded or shared model Crosswalk build. See Choosing Crosswalk* Build Options: Shared or Embedded for more details regarding the differences between these two build options.

Multiple instances of this preference are allowed in the build configuration file. Examples of the use of this preference:

<preference name="xwalk-command-line" value="--disable-pull-to-refresh-effect"/>
<preference name="xwalk-command-line" value="--show-fps-counter --ignore-gpu-blacklist" />
For more complete information about compiler optimizations, see our Optimization Notice.