plugman
A command line tool to install and uninstall plugins for use with Apache Cordova projects.
This document defines tool usage.
Requirements
You must have git
on your PATH to be able to install plugins directly from remote git URLs.
Plugin Specification
--> Available on docs.cordova.io <--
Quickstart
npm install -g plugman
Design Goals
- Facilitate programmatic installation and manipulation of plugins
- Detail the dependencies and components of individual plugins
- Allow code reuse between different target platforms
Supported Platforms
- iOS
- Amazon Fire OS
- Android
- BlackBerry 10
- Tizen
- Windows Phone 8
- Windows 8
Command Line Usage
plugman help
-
Displays all available plugman commands
plugman install --platform <ios|amazon-fireos|android|blackberry10|wp8> --project --plugin <name|url|path> [--plugins_dir ] [--www ] [--variable = [--variable = ...]] plugman uninstall --platform <ios|amazon-fireos|android|blackberry10|wp8> --project --plugin [--www ] [--plugins_dir ]
-
Using minimum parameters, installs a plugin into a cordova project. 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: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.url
: A URL starting with https:// or git://, pointing to a valid git repository that is clonable and contains aplugin.xml
file. The contents of this repository would be copied into the--plugins_dir
.path
: A path to a directory containing a valid plugin which includes aplugin.xml
file. This path's contents will be copied into the--plugins_dir
.
-
--uninstall
: Uninstalls an already---install
'ed plugin from a cordova project. Specify the plugin ID.
Other parameters:
-
--plugins_dir
defaults to<project>/cordova/plugins
, but can be any directory containing a subdirectory for each fetched plugin. -
--www
defaults to the project'swww
folder location, but can be any directory that is to be used as cordova project application web assets. -
--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 for more information.plugman search
-
Search the Plugin registry for plugin id's that match the given space separated list of keywords.
plugman config set registry plugman config get registry
-
Get or set the URL of the current plugin registry that plugman is using. Generally you should leave this set at http://registry.cordova.io unless you want to use a third party plugin registry.
Node Module Usage
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.
node
> require('plugman')
{ install: [Function: installPlugin],
uninstall: [Function: uninstallPlugin],
fetch: [Function: fetchPlugin],
search: [Function: search],
publish: [Function: publish],
unpublish: [Function: unpublish],
adduser: [Function: adduser],
prepare: [Function: handlePrepare],
create: [Function: create],
platform: [Function: platform] }
install
method
module.exports = function installPlugin(platform, project_dir, id, plugins_dir, subdir, cli_variables, www_dir, callback) {
Installs a plugin into a specified cordova project of a specified platform.
platform
: one ofamazon-fireos
,android
,ios
,blackberry10
, orwp8
project_dir
: path to an instance of the above specified platform's cordova projectid
: a string representing theid
of the plugin, a path to a cordova plugin with a validplugin.xml
file, or anhttps://
orgit://
url to a git repository of a valid cordova plugin or a plugin published to the Cordova registryplugins_dir
: path to directory where plugins will be stored, defaults to<project_dir>/cordova/plugins
subdir
: subdirectory within the plugin directory to consider as plugin directory root, defaults to.
cli_variables
: an object mapping cordova plugin specification variable names (see plugin specification) to valueswww_dir
: path to directory where web assets are to be copied to, defaults to the specified project directory'swww
dir (dependent on platform)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
uninstall
method
module.exports = function uninstallPlugin(platform, project_dir, id, plugins_dir, cli_variables, www_dir, callback) {
Uninstalls a previously-installed cordova plugin from a specified cordova project of a specified platform.
platform
: one ofamazon-fireos
,android
,ios
,blackberry10
, orwp8
project_dir
: path to an instance of the above specified platform's cordova projectid
: a string representing theid
of the pluginplugins_dir
: path to directory where plugins are stored, defaults to<project_dir>/cordova/plugins
subdir
: subdirectory within the plugin directory to consider as plugin directory root, defaults to.
cli_variables
: an object mapping cordova plugin specification variable names (see plugin specification) to valueswww_dir
: path to directory where web assets are to be copied to, defaults to the specified project directory'swww
dir (dependent on platform)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
fetch
method
Copies a cordova plugin into a single location that plugman uses to track which plugins are installed into a project.
module.exports = function fetchPlugin(plugin_dir, plugins_dir, link, subdir, git_ref, callback) {
plugin_dir
: path, URL to a plugin directory/repository or name of a plugin published to the Cordova registry.plugins_dir
: path housing all plugins used in this projectlink
: ifplugin_dir
points to a local path, will create a symbolic link to that folder instead of copying intoplugins_dir
, defaults tofalse
subdir
: subdirectory within the plugin directory to consider as plugin directory root, defaults to.
gitref
: ifplugin_dir
points to a URL, this value will be used to pass intogit checkout
after the repository is cloned, defaults toHEAD
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
prepare
method
Finalizes plugin installation by making configuration file changes and setting up a JavaScript loader for js-module support.
module.exports = function handlePrepare(project_dir, platform, plugins_dir) {
project_dir
: path to an instance of the above specified platform's cordova projectplatform
: one ofamazon-fireos
,android
,ios
,blackberry10
, orwp8
plugins_dir
: path housing all plugins used in this project
Registry related actions
adduser
method
Adds a user account to the registry. Function takes no arguments other than a an optional callback
module.exports = function(callback) {
publish
method
Publishes plugins to the registry. plugin_paths
is an array of plugin paths to publish to the registry.
module.exports = function(plugin_paths, callback) {
unpublish
method
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.
module.exports = function(plugins, callback) {
search
method
Searches plugins in the registry. search_opts
is an array of keywords
module.exports = function(search_opts, callback) {
config
method
Configures registry settings. params
is an array that describes the action
/*
* var params = ['get', 'registry'];
* var params = ['set', 'registry', 'http://registry.cordova.io'];
* module.exports = function(params, callback) {
*/
Create plugin related actions
create
method
Creates basic scaffolding for a new plugin
module.exports = function create( name, id, version, pluginPath, options, callback ) {...}
name
: a name for the pluginid
: an id for the pluginversion
: a version for the pluginpluginPath
: a path to create the plugin inoptions
: an array of optionscallback
: 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
platform
method
Add/Remove a platform from a newly created plugin
module.exports = function platform( { operation: operation, platform_name: cli_opts.platform_name } );
operation
: "add or remove"platform_name
: ios, android
Example Plugins
- Google has a bunch of plugins which are maintained actively by a contributor to plugman
- Adobe maintains plugins for its Build cloud service, which are open sourced and available on GitHub
- BlackBerry has a bunch of plugins offering deep platform integration
- Core and 3rd party plugins can be found on the Cordova Registry.
Development
Basic installation:
git clone https://git-wip-us.apache.org/repos/asf/cordova-plugman.git
cd cordova-plugman
npm install -g
Linking the global executable to the git repo:
git clone https://git-wip-us.apache.org/repos/asf/cordova-plugman.git
cd cordova-plugman
npm install
sudo npm link
Running Tests
npm test
Plugin Directory Structure
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 file, or some native code with no corresponding JavaScript.
Here is a sample plugin named foo with android and ios platforms support, and 2 www assets.
foo-plugin/
|- plugin.xml # xml-based manifest
|- src/ # native source for each platform
| |- android/
| | `- Foo.java
| `- ios/
| |- CDVFoo.h
| `- CDVFoo.m
|- README.md
`- www/
|- foo.js
`- foo.png
This structure is suggested, but not required.
Contributors
See the package.json file for attribution notes.
License
Apache License 2.0