incubator-callback-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fil...@apache.org
Subject [5/6] git commit: more editing
Date Tue, 11 Sep 2012 22:07:20 GMT
more editing


Project: http://git-wip-us.apache.org/repos/asf/incubator-cordova-labs/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-cordova-labs/commit/d9e361b2
Tree: http://git-wip-us.apache.org/repos/asf/incubator-cordova-labs/tree/d9e361b2
Diff: http://git-wip-us.apache.org/repos/asf/incubator-cordova-labs/diff/d9e361b2

Branch: refs/heads/cordova-client
Commit: d9e361b21ea6a382e0ef40534ead5595bbb161c5
Parents: 66dc3af
Author: Mike Reinstein <reinstein.mike@gmail.com>
Authored: Sun Sep 9 10:58:32 2012 -0400
Committer: Mike Reinstein <reinstein.mike@gmail.com>
Committed: Sun Sep 9 10:58:32 2012 -0400

----------------------------------------------------------------------
 README.md |  166 +++++++++++++++++++++++++++++++++++++-------------------
 1 files changed, 109 insertions(+), 57 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-cordova-labs/blob/d9e361b2/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index e151f14..640ffe9 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,24 @@
 # cordova-client
 
-> Build, deploy and manage [Cordova](http://cordova.io)-based applications.
+> The command line tool to build, deploy and manage [Cordova](http://cordova.io)-based
applications.
 
-## Supported Platforms
-
-- iOS
-- Android
 
 # Requirements
 
-cordova-client requires [nodejs](http://nodejs.org/).
-
-For every platform that Cordova supports and you want to use with
-cordova-client, you will need to install the SDK for that platform. See:
-
-- [iOS SDK](http://developer.apple.com)
-- [Android SDK](http://developer.android.com) - **NOTE** MAKE SURE YOU
+* [nodejs](http://nodejs.org/)
+* [git](https://help.github.com/articles/set-up-git)
+* SDKs for every platform you wish to support
+  - [iOS SDK](http://developer.apple.com)
+  - [Android SDK](http://developer.android.com) - **NOTE** MAKE SURE YOU
   HAVE THE LATEST _EVERYTHING_ !!!!!
 
-> MikeR: would be nice to elaborate on what "everything" means. And why it's important…has
it resulted in breakage? If so, what are some clues this might be the cause?
-
+```
+MikeR: vague but interesting. I'm guessing this has caused issues using parts of the tool.
More details would be helpful. Some clues on symptoms of everything not being up to date would
be helpful for people experiencing issues related to this.
+```
 
-> MikeR: possible to determine if SDKs are present, with compatible versions, and provide
descriptive errors if missing?
-> 
+```
+MikeR: possible to determine if SDKs are present, with compatible versions, and provide descriptive
errors if missing/out of date?
+```
 
 cordova-client has been tested on Mas OS X _only_. Sorry.
 
@@ -31,12 +27,12 @@ v2.1.0rc1 and above.
 
 
 
-# Getting Started
+# Install
 
-Eventually this will be available via npm but for now you must install manually:
+Eventually this will be available via npm. For now you must install manually:
 
 ```
-clone https://github.com/filmaj/cordova-client.git
+git clone https://github.com/filmaj/cordova-client.git
 cd cordova-client
 sudo npm install
 ```
@@ -44,16 +40,25 @@ sudo npm install
 You will be able to access the client interface
 via: ``` $ ./bin/cordova```
 
-## Creating A Cordova-Based Project
 
-    $ cordova create [directory]
-    $ cordova create [directory name]
-    $ cordova create [directory id name]
 
-Creates a Cordova application. You can optionally specify just a name
-for your application, or both an id (package name or reverse-domain
-style id) and a name.
+## Subcommands
 
+format | description 
+:------------ | :-------------
+`init` | initialize the current directory as a cordova project 
+`create [directory] [id] [name]` | create a new cordova project with optional name and id
+`platform [ls]` | list all platforms the project will build
+`platform add [platform]` | add a platform as a build target for the project
+`platform remove [platform]` | removes a platform as a build target for the project
+`plugin [ls]` | list all plugins added to the project
+`plugin add [path-to-plugin]` | add a plugin to the project
+`plugin remove [plugin]` | **NOT IMPLEMENTED!**
+`build` | compile the app for all platforms added to the project
+`emulate` | launch emulators for all platforms added to the project
+
+
+## File and Directory Structure
 A Cordova application built with cordova-client will have the following
 directory structure:
 
@@ -63,50 +68,62 @@ directory structure:
     |- plugins
     `- www
 
-- `.cordova`: contains meta-data related to your application
-- `platforms`: platforms added to your application will have the native
-  application project structures laid out within this directory
-- `plugins`: any added plugins will be extracted into this directory
-- `www`: your main application assets
+### .cordova/
+The .cordova directory contains the project's baked-in plugins and platforms, and meta-data
used by the rest of the commands. 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. A Cordova project directory is recognized as such when it has a .cordova
directory.  This data is generated when calling `cordova init`. It's modified when adding/removing
platforms or plugins to the project.
 
-From here, you have a Cordova-based project whose state you can
-manipulate using the below project-level commands.
 
-## Project-Level Commands
+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).
 
-Inside a Cordova-based project, you can use `cordova` with the
-`platform`, `plugin`, `build` and `emulate` sub-commands.
+### platforms/ and plugins/
+platforms added to your application will have the native
+ application project structures laid out within this directory
+  
+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.
 
-subcommand | description 
------------- | -------------
-`init` | initialize the current directory as a cordova project 
-`create [directory] --id --name` | create a new cordova project with optional name and id
-`platform [ls]` | list all platforms the project will build
-`platform add [platform]` | add a platform as a build target for the project
-`platform remove [platform]` | removes a platform as a build target for the project
-`build` | compile the app for all platforms added to the project
-`emulate` | launch emulators for all platforms added to the project
-`plugin [ls]` | list all plugins added to the project
-`plugin add [path-to-plugin]` | add a plugin to the project
-`plugin remove [plugin]` | **NOT IMPLEMENTED!**
+#### platforms/
+platforms added to your application will have the native
+ application project structures laid out within this directory
 
+#### plugins/
+any added plugins will be extracted into this directory
 
-### Managing Plugins
+### www/
+Contains the project's web artifacts, such as .html, .css and .js files. These are your main
application assets.
 
-Plugin integration hinges on:
 
-- You having the plugin code locally on your computer
-- The plugin code adheres to the [Cordova Plugin Specification](https://github.com/alunny/cordova-plugin-spec)
+# Examples
 
+## Creating a new cordova project
+This example shows how to create a project from scratch named KewlApp with iOS and android
platform support, and includes a plugin called Kewlio. the project will livein ~/MyProjects/KewlApp
 
+```
+$ cordova create ~/KewlApp
 
+$ cd ~/KewlApp
 
-# Examples
+$ cordova platform add ios
+
+$ cordova platform add android
+
+$ cordova plugin add http://example.org/Kewlio-1.2.3.tar.gz
 
-## Creating a sample project
+$ cordova build 
+```
+
+The directory structure of KewlApp now looks like this:
+* KewlApp/
+  * .cordova/
+  * plugins/
+  * platforms/
+  * android/
+    * …
+  * ios/
+    * …
+  * www
+    * index.html
 
-    $ cordova create ~/src/myNewApp
 
 # Contributing
 
@@ -121,11 +138,46 @@ start cloning any necessary Cordova libraries (which may take a while).
 Also note that the the `spec/helper.js` file contains all of the
 mocks/stubs that we override for testing purposes.
 
+## Managing Plugins
+
+Plugin integration hinges on:
+
+- You having the plugin code locally on your computer
+- The plugin code adheres to the [Cordova Plugin Specification](https://github.com/alunny/cordova-plugin-spec)
+
+
 ## TO-DO
 
 - installing only supported platforms for the app vs. the plugin (and
-  vice-versa).
-- figure out versioning. for now: 2.1.0 minimum.
+  vice-versa)
+- npm package
+- example demonstrating use of `cordova init`
+- figure out versioning. for now: 2.1.0 minimum
 - properly extracting info from config.xml
+- testing on machines other than Mac OS X
 - blackberry support
 - windows phone support
+
+### Bash Completions
+
+It would be useful to support Bash command-line completions, in the [same manner as git](http://en.newinstance.it/2010/05/23/git-autocompletion-and-enhanced-bash-prompt/).
Completions on subcommands, plugins, platforms, files, etc.
+
+- it would be useful
+- it would force us into some consistency to maintain an easy completion script
+
+### Random 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/b816aacfb7583174be9f44f71dc32c8465d1319]()
+
+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]()
+
+


Mime
View raw message