The Intel® XDK Cordova build system is based directly on the Apache* Cordova* CLI build system. Quoting directly from the Cordova documentation:
“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).
NOTE: you do not need to install the Cordova CLI system onto your development machine in order to use the Intel XDK Cordova build system.
The beta release of the Intel XDK Cordova build system (versions 0876 and earlier of the Intel XDK) required that you create a special build config file (aka intelxdk.config.xml) and include it with your HTML5 mobile app sources before submitting your application to the Cordova build system. In the production release of the Intel XDK Cordova build system, this build config file is generated automatically, based on information you provide about your app in the Projects tab (an excerpt is shown in the image).
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.
At the time this article was written, there were four Cordova build targets available named: ‘android’, ‘crosswalk’, ‘ios’ and ‘windows8’.
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. Because the Intel XDK Cordova build system is based on the Cordova CLI open source project, 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.
NOTE: 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 neither compatible nor interchangeable. If you have an existing PhoneGap project you will need to create an Intel XDK configuration file using the Project tab in the Intel XDK before you can build your project with the Intel XDK Cordova build system.
At the time this document was written the Intel XDK Cordova build system was using Cordova 3.3.1-0.1.2.
Because these build config files are generated automatically, each time a build is submitted, you cannot modify the intelxdk.config.<platform>.xml files if you need to change or add to the build directives that are part of this file. 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 “Additions File” (aka intelxdk.config.additions.xml) can be used to augment the auto-generated build configuration files. In most cases the intelxdk.config.additions.xml file is not needed; this file is optional and is not required to be present in order to build an app using the Intel XDK Cordova build server.
Using an Intel XDK Build Configuration 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, or override the behavior of a specific option that is auto-generated by the Intel XDK, 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).
In the example shown above, the first directive adds a build option that creates a Cordova application for Android that can be remotely debugged using the Google* Chrome DevTools in your desktop Chrome* browser (Android 4.4+ devices only). The rest of the directives in this example control options for the Cordova Status Bar plugin; these options would normally not be included here unless you wanted to override this plugin’s default behavior.
Notice that the directives in this file will be added to all intelxdk.config.<platform>.xml files unless you indicate that they are to be included 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. For example, the “debuggable” directive shown above only applies to the Android platform; if it is also included in non-Android build config files it will be ignored by those non-Android platforms.
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 Build Configuration Additions File Format
The build configuration “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.
NOTE: 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="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="iconsSplashScreens/57x57.png" width="57" height="57" />
In the example above, the directive is actually an Intel XDK specific directive (rather than a Cordova CLI config.xml directive) documented in the Using the Intel® XDK Cordova Build Option. Note that the icons must be placed in your source directory (where your index.html file is located) or in a subdirectory of your source directory, and the path to the icon file is specified relative to your source directory. 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.
Add a third-party plugin, that requires parameters, to all builds (no platform prefix):
<intelxdk:plugin intelxdk:name="My Special Plugin" intelxdk:value="https://github.com/myplugin/my-special-plugin.git">
<intelxdk:param intelxdk:name="PLUGIN_PARM_1" intelxdk:value="123456789" />
<intelxdk:param intelxdk:name="PLUGIN_PARM_2" intelxdk:value="mySecondParameter" />
</intelxdk:plugin>
In this example the directive is an Intel XDK specific directive, not a Cordova CLI config.xml directive. Intel XDK specific directives are documented in Using the Intel® XDK Cordova Build Option. The names of the parameters and their acceptable values are defined by the plugin, not by the Intel XDK. Generally, you'll find this information in the plugin's documentation (typically in the form of a "plugin add https://github.com/myplugin/my-special-plugin.git --variable PLUGIN_PARM_1="123456789" --variable PLUGIN_PARM_2="mySecondParameter").