[Cordova Wiki] Update of "CommandLineToolingDesign" by FilMaj

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cordova Wiki" for change notification.

The "CommandLineToolingDesign" page has been changed by FilMaj:
http://wiki.apache.org/cordova/CommandLineToolingDesign?action=diff&rev1=6&rev2=7

Comment:
detailing project-level command line scripts

- This documentation has merged into https://github.com/apache/incubator-cordova-labs/tree/cordova-client
+ Proposal for project-level, cross-platform, available in each cordova implementation, command-line scripts.
  
+ = High-Level Organization =
+ 
+ {{{
+     myapp
+      `cordova
+        |-clean
+        |-log
+        |-build
+        |-run
+        `-lib
+           |-start-emulator
+           |-deploy-device
+           |-deploy-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`.
+ 
+ Any scripts that are not implementable for certain platforms should simply exit with a non-zero exit code / error out.
+ 
+ = Specification =
+ 
+ (./) = implemented
+ 
+ {X} = 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 `deploy` 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. `deploy-device` should not look at emulators, and the converse case for `deploy-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.
+ 
+ == `clean` ==
+ 
+ Removes/deletes any build artifacts.
+ 
+ Current implementations:
+ 
+  * (./) Android: `ant clean`, which boils down to `rm -rf bin gen`
+  * {X} iOS: if memory serves, running `rm -rf build` should do it
+  * /!\ BlackBerry: available via `ant TARGET clean`
+  * {X} WP7
+  * {X} WP8
+ 
+ == `log` ==
+ 
+ Streams logs from a running cordova application.
+ 
+ Current implementations:
+ 
+  * (./) Android: `adb logcat`
+  * (./) iOS: `tail -f "$CORDOVA_PATH/console.log"`
+  * {X} BlackBerry: no support at this time. Web Inspector direct on device or simulator available, though.
+  * {X} WP7
+  * {X} WP8
+ 
+ {{{#!wiki caution
+ '''Outstanding Issues'''
+ 
+ For the `log` command
+ }}}
+ 
+  * Does the current iOS implementation only work for simulator, or device, or either, or neither?
+  * 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.
+ 
+ Current implementations:
+ 
+  * (./) Android w/ `--debug`: `ant debug`
+  * /!\ Android w/ `--release`: `ant release` (but currently implemented as a separate `release` script)
+  * (./) iOS w/ `--debug`
+  * /!\ iOS w/ `--release` (currently implemented as a separate `release` script)
+  * /!\ BlackBerry w/ `--debug` (currently implemented as a separate `debug` script)
+  * {X} BlackBerry w/ `--release`: not implemented but feasible by tweaking the build.xml to set `code.sign` to true
+  * {X} WP7
+  * {X} WP8
+ 
+ {{{#!wiki caution
+ '''Outstanding Issues'''
+ 
+ For the `build` command
+ }}}
+ 
+  * What happens when a user specifies both `--debug` and `--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. 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 fruitstrap at install-time to do device deployment.
+  * /!\ BlackBerry: rudimentary support. Interactive input required to specify whether to load to device or simulator.
+  * {X} WP7
+  * {X} 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`.
+ 
+  * {X} Not Implemented
+  * /!\ Android: rudimentary support (can use `android list avd` and parse that).
+ 
+ === `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`.
+ 
+  * {X} Not Implemented
+  * /!\ 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`.
+ 
+  * {X} Not Implemented
+  * (./) Android (`adb devices`)
+ 
+ === `deploy-emulator` ===
+ 
+ {{{
+     deploy-emulator [--target=id]
+ }}}
+ 
+ Deploys a build of the app to an available emulator. If `--target` is specified, attempts to deploy 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). Implicitly calls `build` first.
+ 
+  * (./) Android
+  * (./) iOS
+  * (./) BlackBerry
+  * {X} WP7
+  * {X} WP8
+ 
+ === `deploy-device` ===
+ 
+ {{{
+     deploy-device [--target=id]
+ }}}
+ 
+ Deploys a build of the app to an available device. If `--target` is specified, attempts to deploy 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). Implicitly calls `build` first.
+ 
+  * (./) Android
+  * (./) iOS
+  * (./) BlackBerry
+  * {X} WP7
+  * {X} 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.
+ 
+  * (./) Android
+  * (./) iOS
+  * (./) BlackBerry
+  * {X} WP7
+  * {X} WP8
+