Proposal for project-level, cross-platform, available in each cordova implementation, command-line scripts.

High-Level Organization

    myapp
     `cordova
       |-clean
       |-log
       |-build
       |-version
       |-run
       `-lib
          |-start-emulator
          |-install-device
          |-install-emulator
          |-list-devices
          |-list-emulator-images
          `-list-started-emulators

Anything that is necessary for a platform's basic CLI tooling (e.g. ApplicationInfo on Android) can be placed under cordova/lib.

Errors

The following exit codes should be considered standard:

• 1: not implemented / unsupported command

• 2: generic runtime error. Hopefully accompanied with stderr output.

Specification

= implemented

= not implemented

= sort of implemented / possible

Flow for Multiple Devices/Emulators

Several commands require determining a single target out of a potential for multiple targets. These scripts are:

• run

• the install sub-scripts

• start-emulator

• log

The flow for determining a single target out of many is as follows. Note that the distinction between emulator and device may not be applicable for certain commands (i.e. install-device should not look at emulators, and the converse case for install-emulator).

1. Are there any actual devices available? (use list-devices to determine this). If so, target the first one. If no, continue.

2. Are there any actual emulators available, i.e. started/running? (use list-started-emulators to determine this). If so, target the first one. If no, continue.

3. Are there any emulator images available to start? (use list-emulator-images to determine this). If so, call start-emulator <id> of the first available image, wait for it to become ready, then target it. If no, continue.

4. Fail horribly, and exit with code 2.

`clean`

Removes/deletes any build artifacts.

Current implementations:

• Android: ant clean, which boils down to rm -rf bin gen

• iOS

• BlackBerry: available via ant TARGET clean

• WP7

• WP8

`log`

Streams logs from a running cordova application.

Current implementations:

• Android: adb logcat

• iOS: tail -f "$CORDOVA_PATH/console.log", but only works for simulator

• BlackBerry: no support at this time. Web Inspector direct on device or simulator available, though.

• WP7

• WP8

• Does the multi-device flow (section above) apply correctly to the log case? It seems identifying whether the user's Cordova application is running on an emulator or device target would need to be figured out.

`build`

    build [--debug] [--release]

Builds the application and compiles to the platform's appropriate binary format. By default builds a debug release (--debug), but supports building a release (possibly signed) build using --release as well. Implicitly calls clean first. If both --release and --debug are specified, error out with exit code 2 and an appropriate error message.

Current implementations:

• Android w/ --debug: ant debug

• Android w/ --release: ant release (but currently implemented as a separate release script)

• iOS

• BlackBerry w/ --debug (currently implemented as a separate debug script)

• BlackBerry w/ --release: not implemented but feasible by tweaking the build.xml to set code.sign to true

• WP7

• WP8

`run`

    run [--target=<id>]

Deploys a build of the app to an available device or emulator. If --target is specified, attempts to deploy the app to the device or emulator identified by <id>. If the attempt fails, the script will error out with code 2. If no --target is specified, follows the multi-device flow as detailed above. Implicitly calls build first.

Current implementations:

• Android: rudimentary support. Explicitly has user choose an AVD via interactive input if no device available and no emulator running, and multiple AVDs defined.

• iOS: rudimentary support. Only deploys to simulator via ios-sim. Could install ios-deploy at install-time to do device deployment.

• BlackBerry: rudimentary support. Interactive input required to specify whether to load to device or simulator.

• WP7

• WP8

Helper Scripts

If we can also standardize on some of the helper scripts located under cordova/lib, that would be helpful!

`list-emulator-images`

Lists out available emulator image IDs. Its main use is passing into start-emulator. The script should print out, at a minimum, one emulator ID per line. If a description of the emulator image is available, each line should be in the form ID DESCRIPTION. Other tooling can then use the first space as a delimiter.

• Not Implemented

• Android: rudimentary support (can use android list avd and parse that).

• iOS: fixed image support (based on images available when installing Xcode 4.6/iOS 6).

`list-started-emulators`

Lists out running emulators. The script should print out, at a minimum, one emulator ID per line. If a description of the running emulator is available, each line should be in the form ID DESCRIPTION. Other tooling can then use the first space as a delimiter.

• Not Implemented

• iOS

• Android: rudimentary support available

`list-devices`

Lists out attached/connected devices. The script should print out, at a minimum, one device ID per line. If a description of the device is available, each line should be in the form ID DESCRIPTION. Other tooling can then use the first space as a delimiter.

• Not Implemented

• Android (adb devices)

`install-emulator`

    install-emulator [--target=id]

Installs a build of the app to an available emulator. If --target is specified, attempts to install the app to the emulator identified by <id>. If the attempt fails, the script will error out. If no --target is specified, follows the multi-device flow as detailed above (but only for emulators). If the application is not compiled/built yet, the script will error out and exit with code 2.

• Android

• iOS

• BlackBerry

• WP7

• WP8

`install-device`

    install-device [--target=id]

Installs a build of the app to an available device. If --target is specified, attempts to install the app to the device identified by <id>. If the attempt fails, the script will error out. If no --target is specified, follows the multi-device flow as detailed above (but only for devices). If the application is not compiled/built yet, the script will error out and exit with code 2.

• Android

• iOS - Could install using ios-deploy at install-time to do device deployment.

• BlackBerry

• WP7

• WP8

`start-emulator`

    start-emulator [id]

Starts an emulator image. If id is specified, will attempt to start the emulator image with the specified ID, or, if not available or unable to start, errors out. If no id is specified, it will try to start the first available emulator. If no emulator images are available, it will error out and exit with code 2.

• Android

• iOS

• BlackBerry

• WP7

• WP8

`version`

    version

Returns the Cordova version.

• Android

• iOS

• BlackBerry

• WP7

• WP8