Differences between revisions 21 and 22
Revision 21 as of 2014-02-01 16:44:19
Size: 8021
Editor: BasBosman
Comment: Removed some unwanted autolinking
Revision 22 as of 2017-03-13 23:18:31
Size: 0
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
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:

 * 1: not implemented / unsupported command
 * 2: generic runtime error. Accompanied with `stderr` output.

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

 * (./) Android
 * (./) iOS
 * (./) !BlackBerry
 * (./) WP7
 * (./) WP8

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

 * (./) Android
 * (./) iOS
 * (./) !BlackBerry
 * (./) WP7
 * (./) WP8

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

 * `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: `xcodebuild -alltargets clean && rm -rf build`
 * (./) !BlackBerry: `rm -rf build`
 * (./) WP7: `rm -rf obj && rm -rf Build`
 * (./) WP8: `rm -rf obj && rm -rf Build`

== `log` ==

Streams logs from a running cordova application.

Current implementations:

 * (./) Android: `adb logcat`
 * (./) iOS: `tail -f "$CORDOVA_PATH/console.log"` (only works for simulator)
 * {X} !BlackBerry: no support at this time. Web Inspector direct on device or simulator available, though.
 * {X} WP7
 * {X} WP8

== `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`
 * (./) iOS w/ `--debug`
 * (./) iOS w/ `--release`
 * (./) !BlackBerry w/ `--debug`
 * (./) !BlackBerry w/ `--release`
 * (./) WP7 w/ `--debug`
 * (./) WP7 w/ `--release`
 * (./) WP8 w/ `--debug`
 * (./) WP8 w/ `--release`

== `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
 * (./) iOS
 * (./) !BlackBerry
 * (./) 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.

 * (./) Android
 * (./) iOS
 * (./) !BlackBerry
 * (./) WP7
 * (./) WP8

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

 * (./) Android
 * (./) iOS
 * (./) !BlackBerry
 * {X} WP7
 * {X} WP8

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

 * (./) Android
 * (./) iOS
 * (./) !BlackBerry
 * (./) WP7
 * (./) WP8

=== `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
 * {X} !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
 * {X} !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
 * {X} WP7
 * {X} WP8

=== `version` ===

{{{
    version
}}}

Returns the Cordova version.

 * (./) Android
 * (./) iOS
 * (./) !BlackBerry
 * (./) WP7
 * (./) WP8