From a009770fb14534811f82a3b171965ed7d7ebf924 Mon Sep 17 00:00:00 2001 From: Mike Reinstein Date: Wed, 5 Sep 2012 22:05:24 -0400 Subject: [PATCH 1/5] documentation merge --- README.md | 344 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 336 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 02614db..120a2bb 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,41 @@ # Pluginstall -> script to install Cordova plugins +A command line tool to distribute and package plugins for use with Apache Cordova, nee PhoneGap. It is based on the work done as part of the PhoneGap Build (https://build.phonegap.com) web service, where many of the tools and techniques have been implemented. -## Usage +This document defines tool usage and the plugin format specification. This is not an official document of the Apache Cordova project. Issues and pull requests are welcome, and can be submitted through GitHub. + + +## Design Goals +* facilitate programmatic installation and manipulation of plugins +* detail the dependencies and components of individual plugins +* allow code reuse between different target platforms + + +## Usage pluginstall PLATFORM PROJECT-PATH PLUGIN-PATH Example: pluginstall android . ~/plugins/ChildBrowser + +### Supported Platforms +* Android +* iOS +* www (copies plugin's www assets only, to PROJECT-PATH) + +> MikeR: www is a platform? + +### Supported Plugins +* __ChildBrowser__ + * https://github.com/alunny/ChildBrowser +* __PG-SQLite Plugin__ + * https://github.com/ApplicationCraft/PGSQLitePlugin + + + + ## Development git clone https://github.com/alunny/pluginstall.git @@ -19,18 +45,320 @@ Example: Then go! -## Supported Platforms -* Android -* iOS -* www (copies plugin's www assets only, to PROJECT-PATH) ## plugin.xml Format -see https://github.com/alunny/cordova-plugin-spec +A plugin is typically a combination of some web/www code, and some native code. +However, plugins may have only one of these things - a plugin could be a single +JavaScript, or some native code with no corresponding JavaScript. + +Assuming both web code and native code are present, the plugins should be +structured like so: + + foo-plugin # top-level directory + -- plugin.xml # xml-based manifest, described below + -- src # native source-code, to be compiled for a single platform + -- android + -- Foo.java + -- ios + -- CDVFoo.h + -- CDVFoo.m + -- www # assets to be copied into the www directory of the Cordova project + -- foo.js + -- foo.png + + +## Plugin Manifest Format + +The `plugin.xml` file is an XML document in the plugins namespace - +`http://www.phonegap.com/ns/plugins/1.0`. It contains a top-level `plugin` +element defining the plugin, and children that define the structure of the +plugin. + +A sample plugin element: + + + +> MikeR: no XML doctype declaration? + +### <plugin> element + +The `plugin` element is the top-level element of the plugin manifest. It has the +following attributes: + +#### xmlns (required) + +The plugin namespace - `http://www.phonegap.com/ns/plugins/1.0`. If the document +contains XML from other namespaces - for example, tags to be added ot the +AndroidManifest.xml file - those namespaces should also be included in the +top-level element. + +#### id (required) + +A reverse-domain style identifier for the plugin - for example, `com.alunny.foo` + +#### version (required) + +A version number for the plugin, that matches the following major-minor-patch +style regular expression: + + ^\d+[.]\d+[.]\d+$ + +### Child elements + +### <engines> element + +The child elements of the `` element specify versions of +Apache Cordova-based frameworks that this plugin supports. An example: + + + + + + + +Similarly to the `version` attribute for the `` element, +the version string specified should matcha a major-minor-patch string +conforming to the regular expression: + + ^\d+[.]\d+[.]\d+$ + +Engine elements may also have fuzzy matches to avoid repetition, and reduce +maintenance when the underlying platform is updated. A minimum of `>`, `>=`, +`<` and `<=` should be supported by tools, such as: + + + + + + +Tools may abort plugin installation if the target project does not meet the +engine constraints. + +> MikeR: This needs to be less general. E.g., "Pluginstall will abort plugin installation" + + +### <name> element + +A human-readable name for the plugin. The text content of the element contains +the name of the plugin. An example: + + Foo + +At this point in time, the tools prototyped for this format do not make use of +this element. If this document progresses, localization will also need to be +accounted for. + +> MikeR: maybe we should require utf-8 encoding for this document? + +### <asset> element + +One or more elements listing the files or directories to be copied into a +Cordova app's `www` directory. A couple of samples: + + + + + + +All assets tags require both a `src` attribute and a `target` attribute. + +#### src (required) + +Where the file or directory is located in the plugin package, relative to the +`plugin.xml` document. + +#### target (required) + +Where the file or directory should be located in the Cordova app, relative to +the `www` directory. + +Assets can be targeted to subdirectories - for instance: + + -Currently support the August 16 revision, more or less. +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. + +### <platform> + +Platform tags identify platforms that have associated native code. Tools using +this specification can identify supported platforms and install the code into +Cordova projects. + +A sample platform tag: + + + + + + + + +#### name (required) + +The `name` attribute identifies a platform as supported - it also associates the +element's children with that platform. + +Platform names should be all-lowercase. Platform names, as arbitrarily chosen, +are listed: + +* android +* ios + +Tools may accept alternate names for platforms. Whatever. + +### <source-file> + +`source-file` elements identify executable source code that should be installed +into a project. A couple of examples: + + + + + + +As with assets, if a `source-file` would overwrite an existing file, tools +should notify the user and stop, like, right away. + +#### src (required) + +Where the file is located, relative to the `plugin.xml` file. + +#### target-dir + +A directory where the files should be copied into, relative to the root of the +Cordova project. + +In practice, this is most important for Java-based platforms, where a file in +the package `com.alunny.foo` has be located under the directory +`com/alunny/foo`. For platforms where the source directory is not important, +plugin authors should omit this attribute. + +### <config-file> + +Identifies an XML-based configuration file to be modified, where in that +document the modification should take place, and what should be modified. + +At this stage in the spec, the `config-file` element only allows for appending +new children into an XML document. The children are XML literals that are the +to be inserted in the target document. + +Example: + + + + + + + + +#### target + +The file to be modified, and the path relative to the root of the Cordova +project. + +If this file does not exist, tools should self-destruct over a period of ten +minutes. Within the first five minutes, the self-destruct procedure MAY be +cancelled with the appropriate security clearance. After five minutes have +passed, the self-destruct procedure MUST complete. + +Or they could just stop. + +#### parent + +An absolute XPath selector pointing to the parent of the elements to be added to +the config file. + +### <plugins-plist> + +Specifies a key and value to append to the correct `AppInfo.plist` file in an +iOS Cordova project. Example: + + + +This may be an implementation detail leaking through, and could be merged with +the `config-file` element at some later point. + +### <resource-file> and <header-file> + +Like source files, but specifically for platforms that distinguish between +source files, headers, and resources (iOS) + +Examples: + + + + + +This is probably an implementation detail leaking through, and future versions of this document will likely merge these elements with `source-file`. + +### <framework> + +Identifies a framework (usually part of the OS/platform) that the plugin depends +on. Example: + + + +Tools should identify the framework through the `src` attribute and attempt to +add the framework to the Cordova project, in the correct fashion for a given +platform. + +## Variables + +In certain cases, a plugin may need to make configuration changes dependent on +the target application. For example, to register for C2DM on Android, an app +with package id `com.alunny.message` would need a permission like: + + + +In cases like this (where the content inserted from the `plugin.xml` file is +not known ahead of time), variables can be indicated by a dollar-sign and a +series of capital letters, digits and underscores. For the above example, the +`plugin.xml` file would include this tag: + + + +Tools using this specification should replace variable references with the +correct value, if specified, or the empty string otherwise. The value of the +variable reference may be detected (in this case, from the `AndroidManifest.xml` +file, or specified by the user of the tool; the exact process is dependent on +the particular tool. + +Certain variable names should be reserved - these are listed below. + +### $PACKAGE_NAME + +The reverse-domain style unique identifier for the package - corresponding to +the `CFBundleIdentifier` on iOS or the `package` attribute of the top-level +`manifest` element in an `AndroidManifest.xml` file. + + +## Authors + +Andrew Lunny +Fil Maj + +## Contributors + +Michael Brooks +Mike Reinstein ## License Apache + + +Copyright 2012 Andrew Lunny, Adobe Systems \ No newline at end of file From 51d4a7d5c33a7a76424f397c4f3832146812fc8e Mon Sep 17 00:00:00 2001 From: Mike Reinstein Date: Thu, 6 Sep 2012 09:19:40 -0400 Subject: [PATCH 2/5] another editing pass --- README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 120a2bb..2252322 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ A plugin is typically a combination of some web/www code, and some native code. However, plugins may have only one of these things - a plugin could be a single JavaScript, or some native code with no corresponding JavaScript. -Assuming both web code and native code are present, the plugins should be +Assuming both web code and native code are present, the plugins are structured like so: foo-plugin # top-level directory @@ -136,10 +136,9 @@ maintenance when the underlying platform is updated. A minimum of `>`, `>=`, -Tools may abort plugin installation if the target project does not meet the +Pluginstall will abort plugin installation if the target project does not meet the engine constraints. -> MikeR: This needs to be less general. E.g., "Pluginstall will abort plugin installation" ### <name> element @@ -149,9 +148,8 @@ the name of the plugin. An example: Foo -At this point in time, the tools prototyped for this format do not make use of -this element. If this document progresses, localization will also need to be -accounted for. +Currently, Pluginstall does not make use of +this element or handle localization. > MikeR: maybe we should require utf-8 encoding for this document? @@ -189,8 +187,7 @@ should stop the installation process and notify the user of the conflict. ### <platform> -Platform tags identify platforms that have associated native code. Tools using -this specification can identify supported platforms and install the code into +Platform tags identify platforms that have associated native code. Pluginstall can identify supported platforms and install the code into Cordova projects. A sample platform tag: @@ -215,6 +212,8 @@ are listed: Tools may accept alternate names for platforms. Whatever. +> MikeR: What's the deal with this line? + ### <source-file> `source-file` elements identify executable source code that should be installed @@ -310,9 +309,7 @@ on. Example: -Tools should identify the framework through the `src` attribute and attempt to -add the framework to the Cordova project, in the correct fashion for a given -platform. +Pluginstall identifies the framework through the `src` attribute and attempts to add the framework to the Cordova project, in the correct fashion for a given platform. ## Variables @@ -331,12 +328,15 @@ series of capital letters, digits and underscores. For the above example, the -Tools using this specification should replace variable references with the +Pluginstall replaces variable references with the correct value, if specified, or the empty string otherwise. The value of the variable reference may be detected (in this case, from the `AndroidManifest.xml` file, or specified by the user of the tool; the exact process is dependent on the particular tool. +> MikeR: I'm confused by "user of the tool" and "the particular tool" phrases. Are these referring to pluginstall, or is this referring to specific tools that are part of the build chain for different platforms like Android and IOS ? +> + Certain variable names should be reserved - these are listed below. ### $PACKAGE_NAME From 381f97195a64f061d6a7c44c1f73d1f26627db29 Mon Sep 17 00:00:00 2001 From: Mike Reinstein Date: Sun, 16 Sep 2012 18:33:45 -0400 Subject: [PATCH 3/5] added binary plist support --- package.json | 1 + platforms/ios.js | 20 ++++++++++++++++---- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/package.json b/package.json index 7212103..8e1dd6e 100644 --- a/package.json +++ b/package.json @@ -17,6 +17,7 @@ "ncp":"0.2.6", "mkdirp":"0.2.2", "xcode":"0.4.1", + "bplist-parser": "0.0.4", "plist":"git+https://github.com/joshfire/node-plist.git", "glob":"3.0.1" }, diff --git a/platforms/ios.js b/platforms/ios.js index 1b0fc7a..4f9270a 100644 --- a/platforms/ios.js +++ b/platforms/ios.js @@ -4,6 +4,7 @@ var path = require('path'), glob = require('glob'), xcode = require('xcode'), plist = require('plist'), + bplist = require('bplist-parser'), nCallbacks = require('../util/ncallbacks'), asyncCopy = require('../util/asyncCopy'), assetsDir = 'www'; // relative path to project's web assets @@ -30,6 +31,8 @@ exports.installPlugin = function (config, plugin, callback) { // grab and parse plist file glob(config.projectPath + '/**/{PhoneGap,Cordova}.plist', function (err, files) { + var pl; + if (!files.length) throw "does not appear to be a PhoneGap project"; files = files.filter(function (val) { @@ -39,11 +42,20 @@ exports.installPlugin = function (config, plugin, callback) { store.plistPath = files[0]; store.pluginsDir = path.resolve(files[0], '..', 'Plugins'); - plist.parseFile(store.plistPath, function (err, obj) { - store.plist = obj; - end(); + // determine if this is a binary or ascii plist and choose the parser + // NOTE: this is hopefully temporary, until TooTallNate can integrate + // binary plist parsing into his library + if(fileIsAscii( store.plistPath )) { + pl = plist; + } else { + pl = bplist; + } + + pl.parseFile(store.plistPath, function (err, obj) { + store.plist = obj; + end(); + }); }); - }); } function getRelativeDir(file) { From 1b80b5dee69727a64ff663528560d41e596485f6 Mon Sep 17 00:00:00 2001 From: Mike Reinstein Date: Sun, 16 Sep 2012 18:36:43 -0400 Subject: [PATCH 4/5] added missing function to detect binary file state --- platforms/ios.js | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/platforms/ios.js b/platforms/ios.js index 4f9270a..6f8da65 100644 --- a/platforms/ios.js +++ b/platforms/ios.js @@ -32,7 +32,7 @@ exports.installPlugin = function (config, plugin, callback) { // grab and parse plist file glob(config.projectPath + '/**/{PhoneGap,Cordova}.plist', function (err, files) { var pl; - + if (!files.length) throw "does not appear to be a PhoneGap project"; files = files.filter(function (val) { @@ -58,6 +58,17 @@ exports.installPlugin = function (config, plugin, callback) { }); } + // detect if a file is ascii by looking for an octet with a val > 127 + function fileIsAscii(filename) { + // Read the file with no encoding for raw buffer access. + var buf = fs.readFileSync(filename); + // as soon as we hit an octet > 127, we prob have binary + for (var i=0, len=buf.length; i 127) { return false; } + } + return true; + } + function getRelativeDir(file) { var targetDir = file.attrib['target-dir'], preserveDirs = file.attrib['preserve-dirs']; From 98899f86a31c93b3a7240f10731803ae0cb901fe Mon Sep 17 00:00:00 2001 From: Mike Reinstein Date: Mon, 17 Sep 2012 03:42:15 -0400 Subject: [PATCH 5/5] reverting the README back to what Andrew has since we're not merging docs --- README.md | 346 ++---------------------------------------------------- 1 file changed, 9 insertions(+), 337 deletions(-) diff --git a/README.md b/README.md index 2252322..3c68f81 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,15 @@ # Pluginstall -A command line tool to distribute and package plugins for use with Apache Cordova, nee PhoneGap. It is based on the work done as part of the PhoneGap Build (https://build.phonegap.com) web service, where many of the tools and techniques have been implemented. - - -This document defines tool usage and the plugin format specification. This is not an official document of the Apache Cordova project. Issues and pull requests are welcome, and can be submitted through GitHub. - - -## Design Goals -* facilitate programmatic installation and manipulation of plugins -* detail the dependencies and components of individual plugins -* allow code reuse between different target platforms - +> script to install Cordova plugins ## Usage + pluginstall PLATFORM PROJECT-PATH PLUGIN-PATH Example: pluginstall android . ~/plugins/ChildBrowser - -### Supported Platforms -* Android -* iOS -* www (copies plugin's www assets only, to PROJECT-PATH) - -> MikeR: www is a platform? - -### Supported Plugins -* __ChildBrowser__ - * https://github.com/alunny/ChildBrowser -* __PG-SQLite Plugin__ - * https://github.com/ApplicationCraft/PGSQLitePlugin - - - - ## Development git clone https://github.com/alunny/pluginstall.git @@ -45,320 +19,18 @@ Example: Then go! +## Supported Platforms +* Android +* iOS +* www (copies plugin's www assets only, to PROJECT-PATH) ## plugin.xml Format -A plugin is typically a combination of some web/www code, and some native code. -However, plugins may have only one of these things - a plugin could be a single -JavaScript, or some native code with no corresponding JavaScript. - -Assuming both web code and native code are present, the plugins are -structured like so: - - foo-plugin # top-level directory - -- plugin.xml # xml-based manifest, described below - -- src # native source-code, to be compiled for a single platform - -- android - -- Foo.java - -- ios - -- CDVFoo.h - -- CDVFoo.m - -- www # assets to be copied into the www directory of the Cordova project - -- foo.js - -- foo.png - - -## Plugin Manifest Format - -The `plugin.xml` file is an XML document in the plugins namespace - -`http://www.phonegap.com/ns/plugins/1.0`. It contains a top-level `plugin` -element defining the plugin, and children that define the structure of the -plugin. - -A sample plugin element: - - - -> MikeR: no XML doctype declaration? - -### <plugin> element - -The `plugin` element is the top-level element of the plugin manifest. It has the -following attributes: - -#### xmlns (required) - -The plugin namespace - `http://www.phonegap.com/ns/plugins/1.0`. If the document -contains XML from other namespaces - for example, tags to be added ot the -AndroidManifest.xml file - those namespaces should also be included in the -top-level element. - -#### id (required) - -A reverse-domain style identifier for the plugin - for example, `com.alunny.foo` - -#### version (required) - -A version number for the plugin, that matches the following major-minor-patch -style regular expression: - - ^\d+[.]\d+[.]\d+$ - -### Child elements - -### <engines> element - -The child elements of the `` element specify versions of -Apache Cordova-based frameworks that this plugin supports. An example: - - - - - - - -Similarly to the `version` attribute for the `` element, -the version string specified should matcha a major-minor-patch string -conforming to the regular expression: - - ^\d+[.]\d+[.]\d+$ - -Engine elements may also have fuzzy matches to avoid repetition, and reduce -maintenance when the underlying platform is updated. A minimum of `>`, `>=`, -`<` and `<=` should be supported by tools, such as: - - - - - - -Pluginstall will abort plugin installation if the target project does not meet the -engine constraints. - - - -### <name> element - -A human-readable name for the plugin. The text content of the element contains -the name of the plugin. An example: - - Foo - -Currently, Pluginstall does not make use of -this element or handle localization. - -> MikeR: maybe we should require utf-8 encoding for this document? - -### <asset> element - -One or more elements listing the files or directories to be copied into a -Cordova app's `www` directory. A couple of samples: - - - - - - -All assets tags require both a `src` attribute and a `target` attribute. - -#### src (required) - -Where the file or directory is located in the plugin package, relative to the -`plugin.xml` document. - -#### target (required) - -Where the file or directory should be located in the Cordova app, relative to -the `www` directory. - -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. +see https://github.com/alunny/cordova-plugin-spec -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. - -### <platform> - -Platform tags identify platforms that have associated native code. Pluginstall can identify supported platforms and install the code into -Cordova projects. - -A sample platform tag: - - - - - - - - -#### name (required) - -The `name` attribute identifies a platform as supported - it also associates the -element's children with that platform. - -Platform names should be all-lowercase. Platform names, as arbitrarily chosen, -are listed: - -* android -* ios - -Tools may accept alternate names for platforms. Whatever. - -> MikeR: What's the deal with this line? - -### <source-file> - -`source-file` elements identify executable source code that should be installed -into a project. A couple of examples: - - - - - - -As with assets, if a `source-file` would overwrite an existing file, tools -should notify the user and stop, like, right away. - -#### src (required) - -Where the file is located, relative to the `plugin.xml` file. - -#### target-dir - -A directory where the files should be copied into, relative to the root of the -Cordova project. - -In practice, this is most important for Java-based platforms, where a file in -the package `com.alunny.foo` has be located under the directory -`com/alunny/foo`. For platforms where the source directory is not important, -plugin authors should omit this attribute. - -### <config-file> - -Identifies an XML-based configuration file to be modified, where in that -document the modification should take place, and what should be modified. - -At this stage in the spec, the `config-file` element only allows for appending -new children into an XML document. The children are XML literals that are the -to be inserted in the target document. - -Example: - - - - - - - - -#### target - -The file to be modified, and the path relative to the root of the Cordova -project. - -If this file does not exist, tools should self-destruct over a period of ten -minutes. Within the first five minutes, the self-destruct procedure MAY be -cancelled with the appropriate security clearance. After five minutes have -passed, the self-destruct procedure MUST complete. - -Or they could just stop. - -#### parent - -An absolute XPath selector pointing to the parent of the elements to be added to -the config file. - -### <plugins-plist> - -Specifies a key and value to append to the correct `AppInfo.plist` file in an -iOS Cordova project. Example: - - - -This may be an implementation detail leaking through, and could be merged with -the `config-file` element at some later point. - -### <resource-file> and <header-file> - -Like source files, but specifically for platforms that distinguish between -source files, headers, and resources (iOS) - -Examples: - - - - - -This is probably an implementation detail leaking through, and future versions of this document will likely merge these elements with `source-file`. - -### <framework> - -Identifies a framework (usually part of the OS/platform) that the plugin depends -on. Example: - - - -Pluginstall identifies the framework through the `src` attribute and attempts to add the framework to the Cordova project, in the correct fashion for a given platform. - -## Variables - -In certain cases, a plugin may need to make configuration changes dependent on -the target application. For example, to register for C2DM on Android, an app -with package id `com.alunny.message` would need a permission like: - - - -In cases like this (where the content inserted from the `plugin.xml` file is -not known ahead of time), variables can be indicated by a dollar-sign and a -series of capital letters, digits and underscores. For the above example, the -`plugin.xml` file would include this tag: - - - -Pluginstall replaces variable references with the -correct value, if specified, or the empty string otherwise. The value of the -variable reference may be detected (in this case, from the `AndroidManifest.xml` -file, or specified by the user of the tool; the exact process is dependent on -the particular tool. - -> MikeR: I'm confused by "user of the tool" and "the particular tool" phrases. Are these referring to pluginstall, or is this referring to specific tools that are part of the build chain for different platforms like Android and IOS ? -> - -Certain variable names should be reserved - these are listed below. - -### $PACKAGE_NAME - -The reverse-domain style unique identifier for the package - corresponding to -the `CFBundleIdentifier` on iOS or the `package` attribute of the top-level -`manifest` element in an `AndroidManifest.xml` file. - - -## Authors - -Andrew Lunny -Fil Maj - -## Contributors - -Michael Brooks -Mike Reinstein +Currently support the August 16 revision, more or less. ## License -Apache - - -Copyright 2012 Andrew Lunny, Adobe Systems \ No newline at end of file +Apache \ No newline at end of file