[Cordova Wiki] Update of "CommandLineToolingDesign" by PatrickMueller

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

  = Command Line Tooling Design =
  
- TBD
+ 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 ==
  
- TBD
+ {{{
+ 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 ==
  
-  * render the documentation to desired format (e.g. HTML)
+ === 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 ==