Add Cordova CLI Options in the Additions File

The Intel® XDK Cordova build system is based directly on the Apache* Cordova* CLI build system. Quoting directly from the Cordova documentation Overview:

“Cordova is an open-source mobile development framework. It allows you to use standard web technologies such as HTML5, CSS3, and JavaScript for cross-platform development, avoiding each mobile platforms' native development language. Applications execute within wrappers targeted to each platform, and rely on standards-compliant API bindings to access each device's sensors, data, and network status.”

When you use the Intel XDK to build a Cordova application your HTML5 app sources are pushed to the Intel XDK cloud-based build system, where they are merged into a Cordova CLI build server that packages your app with the native code components needed to deliver a platform-specific mobile app that can be submitted to an app store for download and installation onto a phone or tablet.

Configuring Cordova Hybrid Mobile Applications

The details required to build your application on the Intel XDK Cordova CLI server are controlled by directives located inside a special build file that is commonly referred to as a config.xml file (the name used in a local Cordova CLI build system).

A build config file is automatically generated for each Cordova build target, or build platform, that is available on the Intel XDK build server. The build config files include the name of the Cordova build platform; for example, intelxdk.config.android.xml. If you inspect the contents of these build configuration files (they are XML formatted text files) and compare them with a typical Cordova config.xml file, you will see many similarities. These build configuration files share many options with the Cordova CLI config.xml file(s) you will find in a local Cordova CLI build environment. The options used in the Intel XDK build configuration files are a superset of those used in the Cordova CLI config.xml file.

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 files and that used by PhoneGap Build, but they are not directly compatible or interchangeable. You can, however, convert the Intel XDK configuration files into a config.xml file that is compatible with PhoneGap Build and Cordova CLI. See Build with PhoneGap* Build and Cordova* CLI for instructions on how to export and build your mobile app using these external tools.

For each HTML5+Cordova project, you can select the Cordova CLI version under Build Settings in the Projects tab. As of release 3972 of the Intel XDK, the default and recommended version of CLI is 6.2.0. 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 the CLI versions that are presented by the Intel XDK can be found in this FAQ.

These build config files are generated automatically; thus, changes you make to the intelxdk.config.<platform>.xml files will be overwritten. To allow for the inclusion of build directives that are not addressed by the options provided by the Intel XDK Projects tab, a special build configuration, the “Additions File” (aka the intelxdk.config.additions.xml file), can be used to augment these auto-generated build configuration files. The intelxdk.config.additions.xml file is optional and not strictly required to be present in your project folder in order to create a PhoneGap Build or Cordova CLI compatible config.xml file.

Using the "Additions File"

There are many Cordova config.xml options that are not addressed directly by the Intel XDK Projects tab. Most are unusual or obscure options that the typical application does not require, or for which the default value associated with that option is sufficient. However, in those instances where you do need to provide additional Cordova config.xml options the intelxdk.config.additions.xml file is your best friend!

An example of an intelxdk.config.additions.xml file is shown in the image below. This file is created by you, the developer, and must be located in the same directory that contains the auto-generated intelxdk.config.<platform>.xml files (the top-level project directory for your app, denoted as the "Project Path" on the Projects tab).

The directives you might place in the intelxdk.config.additions.xml file can be found in the documentation for the intelxdk.config.xml file, in the Cordova documentation pages and in the plugin documentation pages for the Cordova plugins you include as part of your application (most Cordova plugins do not require special Cordova config.xml options).

The "debuggable" directive shown in the image above is obsolete. It was a special directive used by the now retired Intel XDK build system to create an APK that could be remotely debugged using Google* Chrome DevTools on Android. The rest of the directives in this example control options for the Cordova Status Bar plugin; these options are being included here to override this plugin’s default behavior.

The directives in this file will be added to all intelxdk.config.<platform>.xml files, unless you indicate that they are to be included only in a specific platform (details follow). In most cases, directives that affect only one platform can be safely included in all intelxdk.config.<platform>.xml files.

The image below shows the auto-generated intelxdk.config.android.xml file after adding the directives that are inside the intelxdk.config.additions.xml file. The Intel XDK automatically read the contents of the intelxdk.config.additions.xml file and added them to the end of the intelxdk.config.android.xml file that was created from the data provided in the applications’ Projects tab.

HINT: to get a clear view of an intelxdk.config.<platform>.xml file you may have to use “Beautify” on the “Edit” menu. If you do not see “Beautify” use the “Extension Manager…” (on the “File” menu) to include the editor’s “Beautify” plugin.

The "Additions File" Format

The {+|-}[configuration-name] feature described below does not work with the Cordova Package Build export tool. It will work with the xdk-to-cli Node.js script that is an alternate tool for generating a PhoneGap Build and Cordova CLI config.xml file to build your application.

The “Additions File” modifies the contents of the automatically generated intelxdk.config.<platform>.xml files. This file allows the addition and removal of config file elements from the automatically generated intelxdk.config.<platform>.xml files. This file must be named intelxdk.config.additions.xml and must be located in your project’s top-level directory (in the same location as the automatically generated intelxdk.config.<platform>.xml files).

Each line in the additions file consists of an optional comment element followed by a normal XML element. The comment element specifies element-instructions for the immediately following XML element.

No white space is allowed between the comment element (element instructions) and the immediately following XML element to which the comment element applies!

The syntax for element-instructions is:

{+|-}[configuration-name]

Where:

‘+’ directs the following element to be added to the end of the intelxdk.config.<platform>.xml file, verbatim.

‘-‘ directs all elements which match the following element’s name and any provided attribute values to be removed from the intelxdk.config.<platform>.xml file.

configuration-name is optional and, if specified, the instructions apply only to the named build configuration. If configuration-name is omitted, the instructions apply to all build configurations. The predefined configuration names are: Android, Android-Crosswalk, iOS and Windows8. These names must be used with the exact case shown here.

The configuration-names are predefined and constant (there are no user-defined configuration names).

Omitting element-instructions is equivalent to specifying ‘+’. That is, a line with no element-instructions is added to all build configurations.

If an element-instruction is included, it must on the same line as the directive to which it applies and must have no intervening white space between itself and the following directive. See the examples below.

Examples of the intelxdk.config.additions.xml File Directive Syntax

Add an additional preference to all build configurations:

Uses no element-instructions.

<preference name="Fullscreen" value="true" />

Add an icon and preference to the “android” build configuration only:

Prefix the lines with <!-- +Android -->.

<!-- +Android --><icon platform="android" src="package-assets/icon-l.png" density="ldpi" />
<!-- +Android --><preference name="Fullscreen" value="true" />

Remove a plugin from the “ios” build configuration:

Prefix the line with <!-- -iOS -->.

<!-- -iOS --><intelxdk:plugin intelxdk:name="Contacts" />

Remove all icons from the “windows8” build configuration:

Prefix the line with <!-- -Windows8 -->.

<!-- -Windows8 --><icon />

Add an iOS 6 icon to your iOS build:

Prefix the line with <!-- +iOS -->.

<!-- +iOS --><icon platform="ios" src="package-assets/57x57.png" width="57" height="57" />

Note that icons and splash screen images must be placed in the package-assets folder in the root of your project folder. Technically, since this directive specifies the target platform as part of the directive, it is not actually required to include the <!-- +iOS --> prefix, because it will be ignored by the other platforms.

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