Specification for both library and project-level command-line scripts for Cordova platform libraries.

High-Level Organization

Library-level

    cordova-*
     `bin
       |-create
       `-check_reqs

Project-level

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

Anything additional 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:

Annotations

(./) = implemented

{X} = not implemented

/!\ = sort of implemented / possible

Library-level Script Specification

`check_reqs`

Checks that the current system meets the minimum requirements to create cordova-* applications. This includes cordova-specific requirements as well as any requirements by the native mobile platform SDK.

`create`

    create <directory> [package-name [app-name]]

Creates a cordova-* application, which is a standard native mobile application for the desired platform, with additional cordova-required bits on top. In addition, the script should copy all of the project-level scripts (see next section) into the /cordova folder inside the application project folder. Finally, it should copy the bin/check_reqs script into project/cordova as well.

Project-level Script Specification

Flow for Multiple Devices/Emulators

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

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:

`log`

Streams logs from a running cordova application.

Current implementations:

`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:

`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:

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.

`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.

`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.

`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.

`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.

`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.

`version`

    version

Returns the Cordova version.

CommandLineToolingDesign (last edited 2014-02-01 16:44:19 by BasBosman)