You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by ti...@apache.org on 2013/04/15 20:52:22 UTC
[35/54] [abbrv] git commit: updated futures README with some minor
tweaks to the spec and kept track of outstanding issues in JIRA
updated futures README with some minor tweaks to the spec and kept track of outstanding issues in JIRA
Project: http://git-wip-us.apache.org/repos/asf/cordova-plugman/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugman/commit/65bc2623
Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugman/tree/65bc2623
Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugman/diff/65bc2623
Branch: refs/heads/future
Commit: 65bc262357f6a53351c4a60f5f49cbb705d8f82f
Parents: a490dcc
Author: Fil Maj <ma...@gmail.com>
Authored: Tue Mar 26 17:17:06 2013 -0700
Committer: Tim Kim <ti...@adobe.com>
Committed: Tue Apr 9 13:44:02 2013 -0700
----------------------------------------------------------------------
README.md | 91 ++++++++++++++++++++++++++------------------------------
1 files changed, 42 insertions(+), 49 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-plugman/blob/65bc2623/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 7554906..1e9fce9 100644
--- a/README.md
+++ b/README.md
@@ -95,36 +95,6 @@ foo-plugin/
This structure is suggested, but not required.
-
-## Plugin Javascript Code Installation
-
-A typical plugin includes one or more Javascript files. Rather than have the user of your plugin add `<script>` tags for your Javascript to their HTML file(s) manually, you should use `<js-module>` tags for your Javascript files.
-
-### `<js-module>` tags
-
-`<asset>` tags are a dumb copy: copy a file from the plugin subdirectory to `www`.
-
-In contrast, `<js-module>` tags are much more sophisticated. They look like this:
-
- <js-module src="socket.js" name="Socket">
- <clobbers target="chrome.socket" />
- </js-module>
-
-For each file with a `<js-module>` tag, the `plugman --prepare` call will copy the file to `www/plugins/my.plugin.id/path/to/myfile.js`. Further, it will add an entry for this plugin to `www/cordova_plugins.json`. At load time, code in `cordova.js` will use an XHR to read this file, inject a `<script>` tag for each Javascript file, and add a mapping to clobber or merge as appropriate (see below).
-
-DO NOT wrap the file with `cordova.define`; this will be added automatically. Your module will be wrapped in a closure, and will have `module`, `exports` and `require` in scope, as normal for AMD modules.
-
-Details for the `<js-module>` tag:
-
-* The `src` points to a file in the plugin directory.
-* The `name` gives the last part of the module name. It can generally be whatever you like, and it only matters if you want to use `cordova.require` to import other parts of your plugins in your Javascript code. The module name for a `<js-module>` is your plugin's `id` followed by the value of `name`. For the example above, with an `id` of `chrome.socket`, the module name is `chrome.socket.Socket`.
-* Inside the `<js-module>` tag there are three legal sub-tags:
- * `<clobbers target="some.value" />` indicates that the `module.exports` will be inserted into the `window` object as `window.some.value`. You can have as many `<clobbers>` as you like.
- * `<merges target="some.value" />` indicates that your module should be merged with any existing value at `window.some.value`. If any key already exists, you module's version overrides the original. You can have as many `<merges>` as you like.
- * `<runs />` means that your code should be `cordova.require`d, but not installed on the `window` object anywhere. This is useful for initializing the module, attaching event handlers or otherwise. You can only have 0 or 1 `<runs />` tags. Note that including a `<runs />` with `<clobbers />` or `<merges />` is redundant, since they also `cordova.require` your module.
- * An empty `<js-module>` will still be loaded and can be `cordova.require`d in other modules.
-
-
## plugin.xml Manifest Format
The `plugin.xml` file is an XML document in the plugins namespace -
@@ -164,7 +134,7 @@ style regular expression:
^\d+[.]\d+[.]\d+$
-### <engines> element
+### <engines> and <engine> elements
The child elements of the `<engines>` element specify versions of
Apache Cordova-based frameworks that this plugin supports. An example:
@@ -192,7 +162,7 @@ maintenance when the underlying platform is updated. A minimum of `>`, `>=`,
plugman will abort plugin installation if the target project does not meet the engine constraints.
-
+If no `<engine>` tags are specified, plugman will attempt to install into the specified cordova project directory blindly.
### <name> element
@@ -201,8 +171,7 @@ the name of the plugin. An example:
<name>Foo</name>
-This element does not yet handle localization.
-
+This element does not (yet) handle localization.
### <asset> element
@@ -233,8 +202,33 @@ Assets can be targeted to subdirectories - for instance:
would create the `js/experimental` directory in the `www` directory, if not
present, and then copy the file `new-foo.js` as `foo.js` into that directory.
-If a file exists at the target location, tools based on this specification
-should stop the installation process and notify the user of the conflict.
+If a file exists at the target location, plugman will stop the installation process and notify the user of the conflict.
+
+### `<js-module>` element
+
+A typical plugin includes one or more Javascript files. Rather than have the user of your plugin add `<script>` tags for your Javascript to their HTML file(s) manually, you should use `<js-module>` tags for your Javascript files.
+
+`<asset>` tags are a dumb copy: copy a file from the plugin subdirectory to `www`.
+
+In contrast, `<js-module>` tags are much more sophisticated. They look like this:
+
+ <js-module src="socket.js" name="Socket">
+ <clobbers target="chrome.socket" />
+ </js-module>
+
+For each file with a `<js-module>` tag, the `plugman --prepare` call will copy the file to `www/plugins/my.plugin.id/path/to/myfile.js`. Further, it will add an entry for this plugin to `www/cordova_plugins.json`. At load time, code in `cordova.js` will use an XHR to read this file, inject a `<script>` tag for each Javascript file, and add a mapping to clobber or merge as appropriate (see below).
+
+DO NOT wrap the file with `cordova.define`; this will be added automatically. Your module will be wrapped in a closure, and will have `module`, `exports` and `require` in scope, as normal for AMD modules.
+
+Details for the `<js-module>` tag:
+
+* The `src` points to a file in the plugin directory.
+* The `name` gives the last part of the module name. It can generally be whatever you like, and it only matters if you want to use `cordova.require` to import other parts of your plugins in your Javascript code. The module name for a `<js-module>` is your plugin's `id` followed by the value of `name`. For the example above, with an `id` of `chrome.socket`, the module name is `chrome.socket.Socket`.
+* Inside the `<js-module>` tag there are three legal sub-tags:
+ * `<clobbers target="some.value" />` indicates that the `module.exports` will be inserted into the `window` object as `window.some.value`. You can have as many `<clobbers>` as you like.
+ * `<merges target="some.value" />` indicates that your module should be merged with any existing value at `window.some.value`. If any key already exists, you module's version overrides the original. You can have as many `<merges>` as you like.
+ * `<runs />` means that your code should be `cordova.require`d, but not installed on the `window` object anywhere. This is useful for initializing the module, attaching event handlers or otherwise. You can only have 0 or 1 `<runs />` tags. Note that including a `<runs />` with `<clobbers />` or `<merges />` is redundant, since they also `cordova.require` your module.
+ * An empty `<js-module>` will still be loaded and can be `cordova.require`d in other modules.
### <platform>
@@ -278,8 +272,7 @@ into a project. A couple of examples:
<!-- ios -->
<source-file src="CDVFoo.m" />
-As with assets, if a `source-file` would overwrite an existing file, tools
-should notify the user and stop, like, right away.
+As with assets, if a `source-file` would overwrite an existing file, plugman will notify the user and stop, like, right away.
#### src (required)
@@ -328,7 +321,7 @@ the config file.
### <plugins-plist>
-This is OUTDATED. Only applies to Cordova 2.2.0 and below). Use <config-file> tag (same as Android) for newer versions of Cordova.
+This is OUTDATED. Only applies to cordova-ios 2.2.0 and below. Use <config-file> tag (same as Android) for newer versions of Cordova.
Example:
@@ -428,6 +421,7 @@ the `CFBundleIdentifier` on iOS or the `package` attribute of the top-level
`manifest` element in an `AndroidManifest.xml` file.
## Project Directory Structure
+
TODO: show how the foo plugin example from above will have its files placed in a cordova project after running plugman
## Authors
@@ -440,8 +434,7 @@ TODO: show how the foo plugin example from above will have its files placed in a
## Contributors
-Michael Brooks
-
+* Michael Brooks
## License
@@ -453,14 +446,14 @@ These apply to plugman as well as cordova-cli. Keep the two in step, they both h
These are in rough order of priority, most urgent at the top.
-* Remove expectation that source, header and resource files are found relative to `src/<platform>`. The `src` parameter should be relative to `plugin.xml` like the others.
-* Fix all the tests, including the www-only tests, which expect the old `www` platform that has been removed. Note that most of the tests will need some rewiring because of the separation of `--fetch` and `--install`.
-* Add tests for the `cordova_plugins.json` creation and copying of plugin Javascript files into `www/plugins/my.plugin/**`.
-* Make sure (I think it's already so) that `--uninstall` uses the local cache to uninstall a plugin, rather than fetching another. This avoids problems with the list of files changing upstream.
-* Add `cordova plugin add ../path/to/my/plugin --link` (and similarly for `plugman --fetch`), that symlinks the plugin rather than copying, so that it updates in real time on every `prepare`. This may have problems with native code until we can make that part of a `prepare` as well.
-* Make sure that when a new platform is `cordova platform add`ed that it gets all the currently loaded plugins installed.
-* Implement a `cordova watch` a la `grunt watch` that will re-run `cordova prepare` every time the installed plugins change (including those installed with `--link`). This is definitely a stretch goal, but it would be awesome.
-
+* Remove expectation that source, header and resource files are found relative to `src/<platform>`. The `src` parameter should be relative to `plugin.xml` like the others. [CB-2813](http://issues.corodva.io/2813). Assigned to Braden.
+* Fix all the tests, including the www-only tests, which expect the old `www` platform that has been removed. Note that most of the tests will need some rewiring because of the separation of `--fetch` and `--install`. [CB-2814](http://issues.cordova.io/2814). Assigned to Fil.
+* Add tests for the `cordova_plugins.json` creation and copying of plugin Javascript files into `www/plugins/my.plugin/**`. [CB-2815](http://issues.cordova.io/2815). Assigned to Braden.
+* Make sure (I think it's already so) that `--uninstall` uses the local cache to uninstall a plugin, rather than fetching another. This avoids problems with the list of files changing upstream. [CB-2816](http://issues.cordova.io). Assigned to Fil.
+* Add `cordova plugin add ../path/to/my/plugin --link` (and similarly for `plugman --fetch`), that symlinks the plugin rather than copying, so that it updates in real time on every `prepare`. This may have problems with native code until we can make that part of a `prepare` as well. [CB-2817](http://issues.cordova.io/2817). Assigned to Braden.
+* Make sure that when a new platform is `cordova platform add`ed that it gets all the currently loaded plugins installed. [CB-2818](http://issues.cordova.io/2818). Assigned to Fil.
+* Implement a `cordova watch` a la `grunt watch` that will re-run `cordova prepare` every time the installed plugins change (including those installed with `--link`). This is definitely a stretch goal, but it would be awesome. Not assigned but tracked at [CB-2819](http://issues.cordova.io/2819).
I (Braden) am willing to do all of these, and my employer has the will to allocate me to them for as long as they take.
+Fil, Anis, and Tim are all available resources for cordova-plugman and cordova-cli work! USE US, BRADEN!