PhoneGap Build

PhoneGap Build is a hosted service which wraps HTML5 applications into native applications. From their website -

1. Write your app using HTML, CSS and JavaScript
2. Upload it to the PhoneGap Build service
3. Get back app-store ready apps for Apple iOS, Google Android, Windows Phone 7, Palm, Symbian, Blackberry and more.

The service exposes a REST API allowing users to manage their keys and applications, trigger builds and download the native binaries. The plugin connects to this service, uploads the exploded WAR directory, waits for the builds to complete and then downloads the native binaries installing/deploying them as attached artifacts.

Installing the Plugin

To configure the plugin to run as part of your build, add the following to your pom -

<plugin>
	<groupId>com.github.chrisprice</groupId>
	<artifactId>phonegap-build-maven-plugin</artifactId>
	<version>0.0.7</version> 
	<executions>
		<execution>
			<id>phonegap-build</id>
			<goals>
				<goal>clean</goal>
				<goal>build</goal>
			</goals>
		</execution>
	</executions>
</plugin>

The above execution binds the clean and build plugin goals to their default lifecycle phases (which are pre-clean and package respectively). The clean goal ensures the the server copy of the project is cleaned when the local copy is cleaned. The build goal handles uploading the application (and keys) and then downloading and attaching the binaries.

N.B. The plugin will not work until you have configured the authentication and supplied a configuration file.

Authentication

To use the PhoneGap Build service you need to sign up for an account and then configure the plugin with your credentials. There are three different ways to do this. Since 0.0.2, the recommended way is to configure a server in your settings.xml (detailed instructions) -

<server>
	<id>phonegap-build</id>
	<username>[email protected]</username>
	<password>password</password> 
</server>

Then configure a property in your settings.xml with the id of the server (this id can also be set in the POM as a property or configuration parameter)-

<properties>
	<phonegap-build.server>phonegap-build</phonegap-build.server>
</properties>

Alternatively, they can be specified as properties in your setttings.xml -

<properties>
	<phonegap-build.username>[email protected]</phonegap-build.username>
	<phonegap-build.password>password</phonegap-build.password>
</properties>

Or on the command line as properties -

mvn clean install [email protected] -Dphonegap-build.password=password

N.B. The plugin will not work until you have supplied a configuration file.

PhoneGap Build Config File

PhoneGap Build requires a config.xml file which sets some basic application properties and some advanced per-platform settings. The PhoneGap Build config.xml documentation covers these settings in detail.

The plugin expects to find the configuration file for the project at src/main/phonegap-build/config.xml. However, this location can be customised using the configFile parameter -

<plugin>
	<groupId>com.github.chrisprice</groupId>
	<artifactId>phonegap-build-maven-plugin</artifactId>
	<version>0.0.7</version> 
	<executions>
		<execution>
			<id>phonegap-build</id>
			<goals>
				<goal>clean</goal>
				<goal>build</goal>
			</goals>
			<configuration>
				<configFile>src/main/resources/config.xml</configFile>
			</configuration>
		</execution>
	</executions>
</plugin>

PhoneGap zip intermediate File

PhoneGap zip your code in an intermediate file. You can change the intermediate file path.

<plugin>
	<groupId>com.github.chrisprice</groupId>
	<artifactId>phonegap-build-maven-plugin</artifactId>
	<version>0.0.7</version>
	<executions>
		<execution>
			<id>phonegap-build</id>
			<goals>
				<goal>clean</goal>
				<goal>build</goal>
			</goals>
			<configuration>
				<zipFile>phonegap-build-maven-plugin-0.0.8-SNAPSHOT.zip</zipFile>
			</configuration>
		</execution>
	</executions>
</plugin>

Platform Support

The plugin currently supports building for the following platforms -

• ios - Apple iOS (with signing keys, see Signing for iOS)
• android - Google Android (with signing keys, see Signing for Android)
• winphone - Windows Phone 7
• webos - Palm
• symbian - Symbian
• blackberry - Blackberry

To specify which platforms the plugin will try to build for use the platforms configuration parameter. If a platform is specified and that platform can not be built by the service then the build will fail. By default binaries for all platforms are built.

<configuration>
	<platforms>
		<platform>ios</platform>
		<platform>android</platform>
		<platform>winphone</platform>
		<platform>webos</platform>
		<platform>symbian</platform>
		<platform>blackberry</platform>
	</platforms>
</configuration>

Updating an Existing App/Using Existing Keys

Whilst the plugin currently supports managing the full process it can be useful to manage apps/keys manually for e.g. sharing them with collaborators or making more advanced use of the service. The following configuration properties can be used to specify app and key ids -

<configuration>
	<appId>12345</appId>
	<iOsKeyId>23456</iOsKeyId>
	<androidKeyId>23456</androidKeyId>
</configuration>

These ids will override any other app or key configuration and will not be deleted by the clean goal.

If you are unsure of how to get an id for a particular app or key, then the list goal might help (see below).

Utility Goals (list/scorch)

When the plugin is configured correctly it should take care of clearing up any remotely created keys and applications when it is finished with them (i.e. when you perform a clean). However, when first getting started, or if something does goes go wrong, then the list and scorch goals can come in handy.

List will enumerate all of the keys and applications available remotely and delete each one in turn. Once more to be clear, it will delete all keys and applications on the server, not just those that the plugin itself has created.

To run list execute the following -

mvn phonegap-build:list

Scorch will enumerate all of the keys and applications available remotely and delete each one in turn. Once more to be clear, it will delete all keys and applications on the server, not just those that the plugin itself has created.

To run scorch execute the following -

mvn phonegap-build:scorch