Grunt: Phonegap

A Grunt plugin to provide local 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

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

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

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);
      },

      // 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'
        }
      },

      // Set a splash screen at various sizes (optional)
      // Only works for Android now
      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'
        }
      },

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

Dynamic config.xml

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

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 only supports Android and Windows Phone 8.

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'
        }
      }
      // ...
    }
  }

versionCode

The config-xml documentation from Phonegap Build (the hosted 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

Tasks

phonegap:build

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

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.

Running the test suite

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

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.

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

Release History

0.8.0

• Adds configuration for Android splash screens. (thanks @arthurgeek)

0.7.0

The icon configuration API has changed to permit multiple platforms. If you used this feature before v0.7.0, please update your Gruntfile as per the updated example in README.md.

• Adds app icon management for Windows Phone 8 (thanks @kombucha)
• FIX: Cordova hook file permissions are now preserved (#13)
• FIX: Release keystore file path can lead to unexpected escaped characters (Windows) (#15)
• FIX: No longer inadvertantly attempt a device deploy instead of an emulator deploy when the emulator option is passed to phonegap:run (#17)
• Reorganizes tests into an improved file structure based on platforms and features
• Removes indirect references to Grunt's deprecated external (lodash & async) libraries
• Updates devDependencies grunt-contrib-coffee, grunt-contrib-copy and grunt-bump to their latest versions.

0.6.1

• FIX: fixAndroidVersionCode not handling the config.versionCode correctly

0.6.0

• Adds configurable versionCode for Android applications

0.5.1

• Allows you to set the maxBuffer size for child processes

0.5.0

• Adds app icon management for Android

0.4.2

• Fixes a regression in 0.4.1 that causes the apk copied into the release directory to contain 0 bytes

0.4.1

• Adds option to process custom config.xml as a template

0.4.0

• Adds release:android task to build a releases/ directory containing a signed APK for distribution.
• Includes compiled tasks/ directory in source countrol
• Removes phonegap npm dependency - install it globally with -g instead.

0.3.0

• Fixes issue #2 "Test not completing" (thanks @skarjalainen and @jrvidal)
• Removed default 'device' flag (thanks @robwalch)

0.2.0

• Adds 'config' option for specifying a custom path to 'config.xml'.

0.1.0

• Initial release

License

Copyright (c) 2013-2014 Logan Koester. Released under the MIT license. See LICENSE-MIT for details.