81c533c46f02c938e099452a9d8366e5b0e71d78
[cordova-plugman.git] / README.md
1 <!--
2 #
3 # Licensed to the Apache Software Foundation (ASF) under one
4 # or more contributor license agreements.  See the NOTICE file
5 # distributed with this work for additional information
6 # regarding copyright ownership.  The ASF licenses this file
7 # to you under the Apache License, Version 2.0 (the
8 # "License"); you may not use this file except in compliance
9 # with the License.  You may obtain a copy of the License at
10 #
11 # http://www.apache.org/licenses/LICENSE-2.0
12 #
13 # Unless required by applicable law or agreed to in writing,
14 # software distributed under the License is distributed on an
15 # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 #  KIND, either express or implied.  See the License for the
17 # specific language governing permissions and limitations
18 # under the License.
19 #
20 -->
21
22 # plugman
23
24 A command line tool to install and uninstall plugins for use with [Apache Cordova](http://cordova.io) projects.
25
26 This document defines tool usage.
27
28 ## Requirements
29
30 You must have `git` on your PATH to be able to install plugins directly from remote git URLs.
31
32 ## Plugin Specification
33
34 --&gt; [Available on docs.cordova.io](http://cordova.apache.org/docs/en/3.0.0/plugin_ref_spec.md) &lt;--
35
36 ## Quickstart
37
38     npm install -g plugman
39
40 ## Design Goals
41
42 * Facilitate programmatic installation and manipulation of plugins
43 * Detail the dependencies and components of individual plugins
44 * Allow code reuse between different target platforms
45
46 ## Supported Platforms
47
48 * Amazon Fire OS
49 * Android
50 * BlackBerry 10
51 * iOS
52 * Tizen
53 * Windows Phone 8
54 * Windows 8
55
56 ## Command Line Usage
57 Display all available plugman commands:
58
59     plugman help
60
61 ### Plugin Management
62
63 Install a plugin into a Cordova project: 
64
65     plugman install --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin <name|url|path> [--plugins_dir <directory>] [--www <directory>] [--variable <name>=<value> [--variable <name>=<value> ...]]
66
67 Uninstall a Plugin from a Cordova project:
68
69         plugman uninstall --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>]
70
71 For each command (install and uninstall), you must specify a platform and Cordova project location for that platform. You also must specify a plugin, with the different `--plugin` parameter forms being:
72
73   * `name`: The directory name where the plugin contents exist. This must be an existing directory under the `--plugins_dir` path (see below for more info) or a plugin in the Cordova registry.
74   * `url`: A URL starting with https:// or git://, pointing to a valid git repository that is clonable and contains a `plugin.xml` file. The contents of this repository would be copied into the `--plugins_dir`.
75   * `path`: A path to a directory containing a valid plugin which includes a `plugin.xml` file. This path's contents will be copied into the `--plugins_dir`.
76
77 Other parameters:
78
79 * `--plugins_dir` defaults to `<project>/cordova/plugins`, but can be any directory containing a subdirectory for each fetched plugin.
80 * `--www` defaults to the project's `www` folder location, but can be any directory that is to be used as cordova project application web assets.
81 * `--variable` allows to specify certain variables at install time, necessary for certain plugins requiring API keys or other custom, user-defined parameters. Please see the [plugin specification](plugin_spec.md) for more information.
82
83 ### Registry Search
84
85 Search the [Plugin registry](http://plugins.cordova.io) for plugin id's that match the given space separated list of keywords.
86
87     plugman search <plugin keywords>
88
89 ### Configuration Management:
90
91 Display the current list of configuration settings:
92
93         plugman config ls
94
95 Display the current repository endpoint:
96
97     plugman config get registry
98
99 Set the registry endpoint:
100
101     plugman config set registry <url-to-registry>
102
103 You should leave this set to http://registry.cordova.io, unless you want to use a third party plugin registry.
104
105 ## Node Module Usage
106 This section details how to consume Plugman as a node module and is only for Cordova tool authors and other hackers. You should not need to read this section if you are just using Plugman to manage a Cordova project.
107
108     node
109     > require('plugman')
110     { install: [Function: installPlugin],
111       uninstall: [Function: uninstallPlugin],
112       fetch: [Function: fetchPlugin],
113       search: [Function: search],
114       publish: [Function: publish],
115       unpublish: [Function: unpublish],
116       adduser: [Function: adduser],
117       prepare: [Function: handlePrepare],
118       create: [Function: create],
119       platform: [Function: platform] }
120
121 ### `install` method
122
123     module.exports = function installPlugin(platform, project_dir, id, plugins_dir, subdir, cli_variables, www_dir, callback) {
124
125 Installs a plugin into a specified cordova project of a specified platform.
126
127  * `platform`: one of `amazon-fireos`, `android`, `ios`, `blackberry10`, or `wp8`
128  * `project_dir`: path to an instance of the above specified platform's cordova project
129  * `id`: a string representing the `id` of the plugin, a path to a cordova plugin with a valid `plugin.xml` file, or an `https://` or `git://` url to a git repository of a valid cordova plugin or a plugin published to the Cordova registry
130  * `plugins_dir`: path to directory where plugins will be stored, defaults to `<project_dir>/cordova/plugins`
131  * `subdir`: subdirectory within the plugin directory to consider as plugin directory root, defaults to `.`
132  * `cli_variables`: an object mapping cordova plugin specification variable names (see [plugin specification](plugin_spec.md)) to values
133  * `www_dir`: path to directory where web assets are to be copied to, defaults to the specified project directory's `www` dir (dependent on platform)
134  * `callback`: callback to invoke once complete. If specified, will pass in an error object as a first parameter if the action failed. If not and an error occurs, `plugman` will throw the error
135
136 ### `uninstall` method
137
138     module.exports = function uninstallPlugin(platform, project_dir, id, plugins_dir, cli_variables, www_dir, callback) {
139
140 Uninstalls a previously-installed cordova plugin from a specified cordova project of a specified platform.
141
142  * `platform`: one of `amazon-fireos`, `android`, `ios`, `blackberry10`, or `wp8`
143  * `project_dir`: path to an instance of the above specified platform's cordova project
144  * `id`: a string representing the `id` of the plugin
145  * `plugins_dir`: path to directory where plugins are stored, defaults to `<project_dir>/cordova/plugins`
146  * `subdir`: subdirectory within the plugin directory to consider as plugin directory root, defaults to `.`
147  * `cli_variables`: an object mapping cordova plugin specification variable names (see [plugin specification](plugin_spec.md)) to values
148  * `www_dir`: path to directory where web assets are to be copied to, defaults to the specified project directory's `www` dir (dependent on platform)
149  * `callback`: callback to invoke once complete. If specified, will pass in an error object as a first parameter if the action failed. If not and an error occurs, `plugman` will throw the error
150
151 ### `fetch` method
152
153 Copies a cordova plugin into a single location that plugman uses to track which plugins are installed into a project.
154
155     module.exports = function fetchPlugin(plugin_dir, plugins_dir, link, subdir, git_ref, callback) {
156
157  * `plugin_dir`: path, URL to a plugin directory/repository or name of a plugin published to the Cordova registry.
158  * `plugins_dir`: path housing all plugins used in this project
159  * `link`: if `plugin_dir` points to a local path, will create a symbolic link to that folder instead of copying into `plugins_dir`, defaults to `false`
160  * `subdir`: subdirectory within the plugin directory to consider as plugin directory root, defaults to `.`
161  * `gitref`: if `plugin_dir` points to a URL, this value will be used to pass into `git checkout` after the repository is cloned, defaults to `HEAD`
162  * `callback`: callback to invoke once complete. If specified, will pass in an error object as a first parameter if the action failed. If not and an error occurs, `plugman` will throw the error
163
164 ### `prepare` method
165
166 Finalizes plugin installation by making configuration file changes and setting up a JavaScript loader for js-module support.
167
168     module.exports = function handlePrepare(project_dir, platform, plugins_dir) {
169
170  * `project_dir`: path to an instance of the above specified platform's cordova project
171  * `platform`: one of `amazon-fireos`, `android`, `ios`, `blackberry10`, or `wp8`
172  * `plugins_dir`: path housing all plugins used in this project
173
174 ## Registry related actions
175
176 ### `adduser` method
177
178 Adds a user account to the registry. Function takes no arguments other than a an optional callback
179
180     module.exports = function(callback) {
181
182 ### `publish` method
183
184 Publishes plugins to the registry. `plugin_paths` is an array of plugin paths to publish to the registry.
185
186     module.exports = function(plugin_paths, callback) {
187
188 ### `unpublish` method
189
190 unpublishes plugins from the registry. Can unpublish a version by specifying `plugin@version` or the whole plugin by just specifying `plugin`. `plugins` is an array of `plugin[@version]` elements.
191
192     module.exports = function(plugins, callback) {
193
194 ### `search` method
195
196 Searches plugins in the registry. `search_opts` is an array of keywords
197
198     module.exports = function(search_opts, callback) {
199
200 ### `config` method
201
202 Configures registry settings. `params` is an array that describes the action
203     /*
204     * var params = ['get', 'registry'];
205     * var params = ['set', 'registry', 'http://registry.cordova.io'];
206     * module.exports = function(params, callback) {
207     */
208
209 ## Create plugin related actions
210
211 ### `create` method
212
213 Creates basic scaffolding for a new plugin
214
215   module.exports = function create( name, id, version, pluginPath, options, callback ) {...}
216
217 * `name` : a name for the plugin
218 * `id` : an id for the plugin
219 * `version` : a version for the plugin
220 * `pluginPath` : a path to create the plugin in
221 * `options` : an array of options
222 * `callback` : callback to invoke once complete. If specified, will pass in an error object as a first parameter if the action failed. If not and an error occurs, `plugman` will throw the error
223
224 ### `platform` method
225
226 Add/Remove a platform from a newly created plugin
227
228   module.exports = function platform( { operation: operation, platform_name: cli_opts.platform_name } );
229
230 * `operation` : "add or remove"
231 * `platform_name` : ios, android
232
233 ## Example Plugins
234
235 - Google has a [bunch of plugins](https://github.com/MobileChromeApps/mobile-chrome-apps/tree/master/chrome-cordova/plugins) which are maintained actively by a contributor to plugman
236 - Adobe maintains plugins for its Build cloud service, which are open sourced and [available on GitHub](https://github.com/phonegap-build)
237 - BlackBerry has a [bunch of plugins](https://github.com/blackberry/cordova-blackberry/tree/master/blackberry10/plugins) offering deep platform integration
238 - Core and 3rd party plugins can be found on the [Cordova Registry](http://plugins.cordova.io).
239
240 ## Development
241
242 Basic installation:
243
244     git clone https://git-wip-us.apache.org/repos/asf/cordova-plugman.git
245     cd cordova-plugman
246     npm install -g
247
248 Linking the global executable to the git repo:
249
250     git clone https://git-wip-us.apache.org/repos/asf/cordova-plugman.git
251     cd cordova-plugman
252     npm install
253     sudo npm link
254
255 ### Running Tests
256
257     npm test
258
259 ## Plugin Directory Structure
260
261 A plugin is typically a combination of some web/www code, and some native code.
262 However, plugins may have only one of these things - a plugin could be a single
263 JavaScript file, or some native code with no corresponding JavaScript.
264
265 Here is a sample plugin named foo with android and ios platforms support, and 2 www assets.
266
267 ```
268 foo-plugin/
269 |- plugin.xml     # xml-based manifest
270 |- src/           # native source for each platform
271 |  |- android/
272 |  |  `- Foo.java
273 |  `- ios/
274 |     |- CDVFoo.h
275 |     `- CDVFoo.m
276 |- README.md
277 `- www/
278    |- foo.js
279    `- foo.png
280 ```
281
282 This structure is suggested, but not required.
283
284 ## Contributors
285
286 See the [package.json](package.json) file for attribution notes.
287
288 ## License
289
290 Apache License 2.0