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 -
