Grunt: Phonegap

A Grunt plugin to provide build tasks for Phonegap applications

grunt-phonegap integrates Phonegap development with Grunt-based workflows by wrapping the Phonegap 3.0 command line interface.

Rather than polluting the top-level of your project, grunt-phonegap copies your files into a subdirectory containing the Phonegap project, which gets regenerated every time the task phonegap:build is executed.

Requirements

[Back To Top]

You will need the phonegap CLI tool installed globally to use grunt-phonegap.

npm install phonegap -g

You should also install whatever system dependencies are required by the platforms you intend to target.

For help with that, see Platform Guides from the Phonegap documentation.

Getting Started

[Back To Top]

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-phonegap --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-phonegap');

Overview

[Back To Top]

In your project's Gruntfile, add a section named phonegap to the data object passed into grunt.initConfig().

Point phonegap.config.root to the output of your other build steps (where your index.html file is located).

Point phonegap.config.config to your config.xml file.

phonegap.config.cordova should be the .cordova directory that is generated by phonegap create. It must contain a config.json file or your app cannot be built.

Options

grunt.initConfig({
  phonegap: {
    config: {
      root: 'www',
      config: 'www/config.xml',
      cordova: '.cordova',
      path: 'phonegap',
      plugins: ['/local/path/to/plugin', 'http://example.com/path/to/plugin.git'],
      platforms: ['android'],
      maxBuffer: 200, // You may need to raise this for iOS.
      verbose: false,
      releases: 'releases',
      releaseName: function(){
        var pkg = grunt.file.readJSON('package.json');
        return(pkg.name + '-' + pkg.version);
      },

      // Must be set for ios to work.
      // Should return the app name.
      name: function(){
        var pkg = grunt.file.readJSON('package.json');
        return pkg.name;
      },

      // Add a key if you plan to use the `release:android` task
      // See http://developer.android.com/tools/publishing/app-signing.html
      key: {
        store: 'release.keystore',
        alias: 'release',
        aliasPassword: function(){
          // Prompt, read an environment variable, or just embed as a string literal
          return('');
        },
        storePassword: function(){
          // Prompt, read an environment variable, or just embed as a string literal
          return('');
        }
      },

      // Set an app icon at various sizes (optional)
      icons: {
        android: {
          ldpi: 'icon-36-ldpi.png',
          mdpi: 'icon-48-mdpi.png',
          hdpi: 'icon-72-hdpi.png',
          xhdpi: 'icon-96-xhdpi.png'
        },
        wp8: {
          app: 'icon-62-tile.png',
          tile: 'icon-173-tile.png'
        },
        ios: {
          icon29: 'icon29.png',
          icon29x2: 'icon29x2.png',
          icon40: 'icon40.png',
          icon40x2: 'icon40x2.png',
          icon57: 'icon57.png',
          icon57x2: 'icon57x2.png',
          icon60x2: 'icon60x2.png',
          icon72: 'icon72.png',
          icon72x2: 'icon72x2.png',
          icon76: 'icon76.png',
          icon76x2: 'icon76x2.png'
        }
      },

      // Set a splash screen at various sizes (optional)
      // Only works for Android and IOS
      screens: {
        android: {
          ldpi: 'screen-ldpi-portrait.png'
          // landscape version
          ldpiLand: 'screen-ldpi-landscape.png'
          mdpi: 'screen-mdpi-portrait.png'
          // landscape version
          mdpiLand: 'screen-mdpi-landscape.png'
          hdpi: 'screen-hdpi-portrait.png'
          // landscape version
          hdpiLand: 'screen-hdpi-landscape.png'
          xhdpi: 'screen-xhdpi-portrait.png'
          // landscape version
          xhdpiLand: 'www/screen-xhdpi-landscape.png'
        },
        ios: {
          // ipad landscape
          ipadLand: 'screen-ipad-landscape.png',
          ipadLandx2: 'screen-ipad-landscape-2x.png',
          // ipad portrait
          ipadPortrait: 'screen-ipad-portrait.png',
          ipadPortraitx2: 'screen-ipad-portrait-2x.png',
          // iphone portrait
          iphonePortrait: 'screen-iphone-portrait.png',
          iphonePortraitx2: 'screen-iphone-portrait-2x.png',
          iphone568hx2: 'screen-iphone-568h-2x.png'
        }
      },

      // Android-only integer version to increase with each release.
      // See http://developer.android.com/tools/publishing/versioning.html
      versionCode: function(){ return(1) },

      // Android-only options that will override the defaults set by Phonegap in the
      // generated AndroidManifest.xml
      // See https://developer.android.com/guide/topics/manifest/uses-sdk-element.html
      minSdkVersion: function(){ return(10) },
      targetSdkVersion: function(){ return(19) },

      // iOS7-only options that will make the status bar white and transparent
      iosStatusBar: 'WhiteAndTransparent',

      // If you want to use the Phonegap Build service to build one or more
      // of the platforms specified above, include these options.
      // See https://build.phonegap.com/
      remote: {
        username: 'your_username',
        password: 'your_password',
        platforms: ['android', 'blackberry', 'ios', 'symbian', 'webos', 'wp7']
      },

      // Set an explicit Android permissions list to override the automatic plugin defaults.
      // In most cases, you should omit this setting. See 'Android Permissions' in README.md for details.
      permissions: ['INTERNET', 'ACCESS_COURSE_LOCATION', '...']
    }
  }
})

Dynamic config.xml

[Back To Top]

Beginning with v0.4.1, phonegap.config.config may be either a string or an object.

As a string, the file is copied directly, as with previous versions.

As an object with the keys template<String> and data<Object>, the file at template will be processed using grunt.template.

Example

Gruntfile.js

  // ...
  phonegap: {
    config: {
      config: {
        template: '_myConfig.xml',
        data: {
          id: 'com.grunt-phonegap.example'
          version: grunt.pkg.version
          name: grunt.pkg.name
        }
      }
  // ...

_myConfig.xml

<?xml version='1.0' encoding='utf-8'?>
<widget
  id="<%= id %>"
  version="<%= version %>"
  xmlns="http://www.w3.org/ns/widgets"
  xmlns:gap="http://phonegap.com/ns/1.0">

    <name><%= name %></name>

    <!-- ... -->
</widget>

App Icons

[Back To Top]

If you choose to set phonegap.config.icons with one or more icon sizes, these files will be copied into the appropriate directories to use as your app icon.

You may want to use this feature in conjunction with grunt-rasterize to generate the correctly sized icon files from an SVG source.

Currently this feature supports Android, Windows Phone 8, and iOS.

Example

  phonegap: {
    config: {
      // ...
      icons: {
      	android: {
          ldpi: 'icon-36-ldpi.png',
          mdpi: 'icon-48-mdpi.png',
          hdpi: 'icon-72-hdpi.png',
          xhdpi: 'icon-96-xhdpi.png'
        },
        wp8: {
          app: 'icon-62-tile.png',
          tile: 'icon-173-tile.png'
        },
        ios: {
          icon29: 'icon29.png',
          icon29x2: 'icon29x2.png',
          icon40: 'icon40.png',
          icon40x2: 'icon40x2.png',
          icon50: 'icon50.png',
          icon50x2: 'icon50x2.png',
          icon57: 'icon57.png',
          icon57x2: 'icon57x2.png',
          icon60: 'icon60.png',
          icon60x2: 'icon60x2.png',
          icon72: 'icon72.png',
          icon72x2: 'icon72x2.png',
          icon76: 'icon76.png',
          icon76x2: 'icon76x2.png'
        }
      }
      // ...
    }
  }

versionCode

[Back To Top]

The config-xml documentation from Phonegap Build (the remote build service) indicate that you can set a versionCode for your AndroidManifest.xml file inside your config.xml. However, phonegap local just ignores that property.

Google Play will not allow you to upload more than one APK with the same versionCode.

If you set a phonegap.config.versionCode value (function or literal), grunt phonegap:build will post-process the generated AndroidManifest.xml file and set it for you.

In most applications it should simply be an integer that you increment with each release.

See http://developer.android.com/tools/publishing/versioning.html

This option will be ignored for non-Android platforms or when using the remote build service.

minSdkVersion and targetSdkVersion

[Back To Top]

Some Android applications need to force a specific value for minSdkVersion and targetSdkVersion, for example to enable "quirks mode" in Android 4.4's Chrome-based WebView.

Supposedly, Phonegap Build supports this through a config.xml preference like this:

<preference name="android-targetSdkVersion" value="13" />

However, setting this preference appears to have no effect on the output during a local build.

If you set phonegap.config.minSdkVersion and/or phonegap.config.targetSdkVersion, grunt phonegap:build will post-process the generated AndroidManifest.xml file and set it for you.

This option will be ignored for non-Android platforms or when using the remote build service. For remote Android builds, instead try the android-targetSdkVersion preference mentioned above.

Android Permissions

[Back To Top]

If phonegap.config.permissions is omitted, plugin permissions will be set automatically by Phonegap. In most cases, this is what you want.

Ordinarily with Phonegap (local), permissions for the Android platform are written to AndroidManifest.xml based on the requirements of the plugins that you have added to your project, so you do not have to worry about them.

In some (perhaps unusual) situations, you may want to alter these permissions without modifying a plugin.

When you may want to do this:

To reserve not-yet-used permissions during development
To enable a plugin that does not require the right permissions for your target version of Android
While troubleshooting a permissions error in your app.
When using an advanced Grunt workflow to set your permissions for different builds dynamically (by specifying phonegap.config.permissions as a function)

If you need this feature, set phonegap.config.permissions to an array of permission basenames, such as ['ACCESS_NETWORK_STATE'].

When phonegap.config.permissions is set, all permissions added by Cordova + plugins will be removed, giving you complete control over the permission manifest.

This means you need to explicitely add any permissions required by plugins, or your app will not work.

Be careful to check any permissions your plugins need before adding this feature to your app, and remember to update it when adding additional plugins later.

If you are using the Phonegap Build cloud service for the Android platform, this setting will have no effect.

Application Name

[Back To Top]

If phonegap.config.androidApplicationName is a string or function, then it will be applied to the <application android:name /> attribute in your AndroidManifest.xml.

This option should almost always be left undefined. You will only need to set this if you are implementing a base plugin (a Java class extending from android.app.Application), for example to implement crash reporting with ACRA.

Phonegap Build

[Back To Top]

If you set phonegap.config.remote to a subset of phonegap.config.platforms, those platforms will be built remotely. This is still somewhat experimental, and may not integrate with all local features.

Tasks

[Back To Top]

phonegap:build[:platform]

Running phonegap:build with no arguments will...

Purge your phonegap.config.path
Copy your phonegap.config.cordova and phonegap.config.root files into it
Add any plugins listed in phonegap.config.plugins
..and then generate a Phonegap build for all platforms listed in phonegap.config.platforms

If you pass a specific platform as an argument (eg grunt phonegap:build:android), the phonegap.config.platforms array will be ignored and only that specific platform will be built.

phonegap:run[:platform][:device]

After a build is complete, the phonegap:run grunt task can be used to launch your app on an emulator or hardware device. It accepts two optional arguments, platform and device.

Example: grunt phonegap:run:android:emulator

If you are using the Android platform, you can see the list of connected devices by running adb devices.

The platform argument will default to the first platform listed in phonegap.config.platforms.

phonegap:release[:platform]

Create a releases/ directory containing a signed application package for distribution.

Currently android is the only platform supported by this task. You will need to create a keystore file at phonegap.config.key.store like this:

$ keytool -genkey -v -keystore release.keystore -alias release -keyalg RSA -keysize 2048 -validity 10000

The keytool command will interactively ask you to set store and alias passwords, which must match the return value of phonegap.config.key.aliasPassword and phonegap.config.key.storePassword respectively.

phonegap:login

Log into the Phonegap Build service with the credentials specified at phonegap.config.remote.username and phonegap.config.remote.password.

phonegap:logout

Log out of the Phonegap Build service.

Running the test suite

[Back To Top]

git clone https://github.com/logankoester/grunt-phonegap.git
cd grunt-phonegap
npm install
git submodule init
git submodule update
grunt

Note that not all tests can be run on all platforms. For example, tests depending on the Windows Phone SDK will be skipped if your OS is detected to be non-Windows.

Contributing

[Back To Top]

Fork the repo on Github and open a pull request. Note that the files in tasks/ and test/ are the output of CoffeeScript files in src/, and will be overwritten if edited by hand.

Likewise, README.md is the output of the grunt docs task, and will be overwritten. README updates should be made in the Markdown files under docs/.

Before running the included test suite, you must first run git submodule update on your local clone (see above).

Please run grunt build before submitting a pull request. The build output should be included with your changes.

Release History

[Back To Top]

You can find all the changelogs here.

Latest changelog is from v0.13.0.md:

v0.13.0

Platform SDK compatibility is now checked before attempting a local build
The directory specified at phonegap.config.path will now be created if it does not exist (thanks @breandr!)
Adds the option to make the iOS7 status bar white (thanks @gabrielpoca!)
Added missing icons for ios: 50/50@2x/60 (thanks @bendi!)
Allows plugman plugin name notation (thanks @jsanchezpando!)