[Cordova Wiki] Update of "CommandLineToolingDesign" by MikeReinstein

[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 MikeReinstein:
http://wiki.apache.org/cordova/CommandLineToolingDesign?action=diff&rev1=5&rev2=6

- = Command Line Tooling Design =
+ This documentation has merged into https://github.com/apache/incubator-cordova-labs/tree/cordova-client
  
- The command-line tool `cordova` will be provided which performs a number of functions, specified as 'subcommands' (similar to `npm` or `git`).  
- 
- The tools generally operate against a 'project', which is a directory that has been initialized via `cordova init` or `cordova create`.
- 
- The root project directory has a `.cordova` directory inside of it, and that directory identifies the parent as a cordova project.  Project directories may not be nested.  Commands other than `init` and `create` operate against the project directory itself, rather than the current directory - a search up the current directory's parents is made to find the project directory.  Thus, any command (other than `init` and `create`) can be used from any subdirectory whose parent is a cordova project directory (same as `git`).
- 
- Cordova will ship with some set of platforms and projects baked in, and some set of these (all?) will be pre-installed in the project directory during `cordova init`.  Additional platforms and projects can be installed, and removed, with the `cordova platform/plugin add/remove` subcommands.  The `add` versions of these subcommands take a URI as a parameter.  If the URI does not contain a protocol/scheme, it's assumed to be a 'backed in' platform/plugin.  Otherwise, it's assumed to be a URL to a gzipped tar archive of the platform/plugin, in the shape of an npm package.
- 
- Platforms and projects are expected to be "CommonJS packages" (loosely), similar to the way `npm` packages are structured.  The main requirement is that there be a `package.json` file available in the 'root directory' of the archive.  The `package.json` file will contain additional meta-data for platforms and plugins, including pointers to such things as native code that needs to be compiled/linked/added to the application during a build.
- 
- == Subcommands ==
- 
- {{{
- cordova init
- }}}
- 
- Initializes the current directory as a Cordova project directory.
- 
- {{{
- cordova create <directoryName>
- }}}
- 
- Creates the specified directory, then initializes it ala `cordova init`.
- 
- {{{
- cordova build
- }}}
- 
- Builds the project for all installed platforms.
- 
- {{{
- cordova platform ls
- }}}
- 
- Lists the platforms installed.
- 
- Add a platform to the project.
- 
- {{{
- cordova platform add <platformURI>
- }}}
- 
- Add a platform to the project.
- 
- {{{
- cordova platform remove <platformName>
- }}}
- 
- Remove a platform from the project.
- 
- {{{
- cordova plugin ls
- }}}
- 
- Lists the plugins installed.
- 
- {{{
- cordova plugin add <pluginURI>
- }}}
- 
- Add a plugin to the project.
- 
- {{{
- cordova plugin remove <pluginName>
- }}}
- 
- Remove a plugin from the project.
- 
- == File and Directory Structure ==
- 
- A project directory for Cordova is recognized as such when it has a `.cordova` directory.  Within the `.cordova` directory is meta-data used by the rest of the commands.
- 
- Besides the `.cordova` directory, a project directory contains a subdirectories named `platforms` and `plugins`.  Within each of those subdirectories are the platforms and plugins used in the project.
- 
- A project directory also contains a `www` directory, which contains the project's web artifacts, such as `.html`, `.css` and `.js` files.
- 
- Within the `.cordova` subdirectory will be the baked-in plugins and platforms.  
- 
- == Use Cases ==
- 
- === create a new project using a 3rd party plugin ===
- 
- {{{
- > cd MyProjects
- }}}
- 
- Traverse to the parent directory of where you want to create your project.
- 
- {{{
- > cordova create KewlApp
- }}}
- 
- Creates and initializes the directory `KewlApp` as a Cordova project directory, whose parent directory is `MyProjects`. eg
- 
-  * !MyProjects
-   * !KewlApp
-    * .cordova
-    * plugins
-    * platforms
-    * www
-     * index.html
- 
- {{{
- > cd KewlApp
- }}}
- 
- Set the current directory to your new Cordova project directory.
- 
- {{{
- > cordova platform add ios
- }}}
- 
- Adds the ios platform to the project - this platform is built-in.  The project directory now looks like this:
- 
-  * !KewlApp
-   * .cordova
-   * plugins
-   * platforms
-    * ios
-     * ...
-   * www
-    * index.html
- 
- {{{
- > cordova platform add android
- }}}
- 
- Adds the android platform to the project - this platform is built-in.  The project directory now looks like this:
- 
-  * !KewlApp
-   * .cordova
-   * plugins
-   * platforms
-    * android
-     * ...
-    * ios
-     * ...
-   * www
-    * index.html
- 
- {{{
- > cordova build
- }}}
- 
- Builds platform executables for ios and android, using the default web resources that were added during initialization (the existing Cordova 'hello world' app).
- 
- {{{
- [try the apps]
- }}}
- 
- They work!  Awesome!
- 
- {{{
- [edit / add resources in the `www` subdirectory]
- }}}
- 
- Edit the application.
- 
- {{{
- > cordova build
- }}}
- 
- Rebuild the apps.
- 
- {{{
- [try the apps]
- }}}
- 
- They still work!  Awesome!
- 
- {{{
- cordova plugin add http://example.org/Kewlio-1.2.3.tar.gz
- }}}
- 
- Install plugin from the specified URL.  The project directory now looks like this:
- 
-  * !KewlApp
-   * .cordova
-   * plugins
-    * Kewlio
-     * ...
-   * platforms
-    * android
-     * ...
-    * ios
-     * ...
-   * www
-    * index.html
- 
- {{{
- [edit / add resources in the `www` subdirectory]
- }}}
- 
- Edit the application to take advantage of the plugin you just added.
- 
- {{{
- > cordova build
- }}}
- 
- Rebuild the apps.
- 
- {{{
- [try the apps]
- }}}
- 
- They still work!  And now use the Kewlio plugin!  Awesome!
- 
- 
- == Etc ==
- 
- === Bash Completions ===
- 
- It would be useful to support Bash command-line completions, in the [[http://en.newinstance.it/2010/05/23/git-autocompletion-and-enhanced-bash-prompt/|same manner as git]].  Completions on subcommands, plugins, platforms, files, etc.
- 
-  1. it would be useful
-  2. it would force us into some consistency to maintain an easy completion script
- 
- == Rando, not-yet-integrated notes ==
- 
- === posted to the m/l by BrianL ===
- 
- 
- yah. there is tonnes of prior art for this stuff. I will update the
- wiki but quickly, this was stable:
- 
- https://github.com/brianleroux/Cordova/tree/b816aacfb7583174be9f44f71dc32c8465d13109
- 
- then other things happened. those scripts ended up in the mainline
- projects. the idea was a standard package format for a project and
- upgrading would consist only of swapping out the bin directory. the
- scripts would live local the project avoiding version hell between
- releases.
- 
- this new thinking is different. we now think the native project as it
- were should host its own scripts. upgrading not a consideration. maybe
- it should be. you're thinking of a master global script, which is cool
- and something I've always wanted, but the version thing needs to be
- considered. perhaps not an issue between releases if the native
- project (the target of www) deals with the version itself...
- 
- also check the old wiki and andrew lunny has a tool called
- plugin-install for ios/android
- 
- https://github.com/alunny/pluginstall
-