Skip to content
Permalink
Browse files
CB-7894 - Updated docs (closes #80)
Removed --uninstall, added docs for owner and some other cleanups

Signed-off-by: Shazron Abdullah <shazron@apache.org>
  • Loading branch information
johnwargo authored and shazron committed Oct 31, 2014
1 parent 6abb187 commit 8058b082f1dfa4feeb586a41ea0a3b52ec473951
Show file tree
Hide file tree
Showing 2 changed files with 96 additions and 39 deletions.
@@ -45,45 +45,62 @@ You must have `git` on your PATH to be able to install plugins directly from rem

## Supported Platforms

* iOS
* Amazon Fire OS
* Android
* BlackBerry 10
* iOS
* Tizen
* Windows Phone 8
* Windows 8

## Command Line Usage
Display all available plugman commands:

plugman help

* Displays all available plugman commands
### Plugin Management

Install a plugin into a Cordova project:

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> ...]]
plugman uninstall --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>]

* 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:
Uninstall a Plugin from a Cordova project:

plugman uninstall --platform <ios|amazon-fireos|android|blackberry10|wp8> --project <directory> --plugin <id> [--www <directory>] [--plugins_dir <directory>]

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:

* `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 a `plugin.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 a `plugin.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's `www` 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](plugin_spec.md) for more information.

### Registry Search

Search the [Plugin registry](http://plugins.cordova.io) for plugin id's that match the given space separated list of keywords.

plugman search <plugin keywords>

* Search the [Plugin registry](http://plugins.cordova.io) for plugin id's that match the given space separated list of keywords.
### Configuration Management:

Display the current list of configuration settings:

plugman config ls

Display the current repository endpoint:

plugman config set registry <url-to-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.
Set the registry endpoint:

plugman config set registry <url-to-registry>

You should leave this set to 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.
@@ -3,6 +3,21 @@ plugman manages plugin.xml-compatible cordova plugins into cordova-generated pro
Usage
=====

To display this help file, use one of the following:

$ plugman --help
$ plugman -h

To display the plugman version, use one of the following:

$ plugman --version
$ plugman -v

Optional flags
--------------

--debug|-d : Verbose mode

Install a plugin
----------------

@@ -15,30 +30,24 @@ Parameters:
- plugin <plugin>: One of a path reference to a local copy of a plugin, or a remote https: or git: URL pointing to a cordova plugin (optionally append #branch:subdir) or a plugin ID from http://plugins.cordova.io
- variable NAME=VALUE: Some plugins require install-time variables to be defined. These could be things like API keys/tokens or other app-specific variables.

Uninstall a plugin
------------------

$ plugman uninstall --platform <platform> --project <directory> --plugin <plugin-id>

Parameters:
- plugin <plugin-id>: The plugin to remove, identified by its id (see the plugin.xml's <plugin id> attribute)

Optional parameters
-------------------
Optional parameters:

- www <directory>: www assets for the plugin will be installed into this directory. Default is to install into the standard www directory for the platform specified
- plugins_dir <directory>: a copy of the plugin will be stored in this directory. Default is to install into the <project directory>/plugins folder
- searchpath <directory>: when looking up plugins by ID, look in this directory and each of its subdirectories for the plugin before hitting the registry.
Multiple search paths can be used by either specifying the flag multiple times, or by separating paths with a delimiter (: on 'nix, ; on Windows).

Optional flags
--------------
Uninstall a plugin
------------------

--debug|-d : Verbose mode
$ plugman uninstall --platform <platform> --project <directory> --plugin <plugin-id>

--help|-h : Displays this message
Parameters:

- platform <platform>: One of android, ios, blackberry10, wp8, or windows8
- project <directory>: Path reference to a cordova-generated project of the platform you specify
- plugin <plugin-id>: The plugin to remove, identified by its id (see the plugin.xml's <plugin id> attribute)

--version|-v : Displays version

Interacting with the registry
=============================
@@ -64,50 +73,81 @@ Search for a plugin
$ plugman search <keyword1 keyword2 ...>

Display plugin information
-----------------------
--------------------------

$ plugman info <pluginid>
$ plugman info <pluginID>

Manage registry configuration
-----------------------------
Display current configuration settings:

$ plugman config ls

Display the current registry URL:

$ plugman config set registry http://localhost:5984/registry/_design/app/_rewrite
$ plugman config get registry

Manage owners
Set registry URL:

$ plugman config set registry <url>

Example:

$ plugman config set registry http://localhost:5984/registry/_design/app/_rewrite

Manage Owners
-------------
Plugin owners are allowed to publish updates to a plugin. To display a list of owners for a plugin, use:

$ plugman owner ls <pluginID>

Example:

$ plugman owner ls org.apache.cordova.core.file

To add an owner to a plugin's in the repository, use:

$ plugman owner add <username> <pluginID>

Example:

$ plugman owner ls org.apache.cordova.file
$ plugman owner add username org.apache.cordova.file
$ plugman owner rm username org.apache.cordova.file
$ plugman owner add joeuser org.apache.cordova.core.file

To remove an owner from the plugin in the registry, use:

$ plugman owner rm <username> <pluginID>

Example:

$ plugman owner rm joeuser org.apache.cordova.core.file

Create A Plugin
---------------

$ plugman create --name <Plugin Name> --plugin_id <Plugin ID> --plugin_version <Plugin Version> [--path <Directory Path>] [--variable NAME=VALUE]
$ plugman create --name <pluginName> --plugin_id <pluginID> --plugin_version <version> [--path <directory>] [--variable NAME=VALUE]

Parameters:

- <Plugin Name>: A Name for a Plugin
- <Plugin ID>: An ID for the plugin, ex: org.bar.foo
- <Plugin Version>: A version for the plugin, ex: 0.0.0
- <pluginName>: The name of the plugin
- <pluginID>: An ID for the plugin, ex: org.bar.foo
- <version>: A version for the plugin, ex: 0.0.1
- <directory>: An absolute or relative path for the directory where the plugin project will be created
- variable NAME=VALUE: Extra variables such as description or Author

Add a Platform to a Plugin
--------------------------

$ plugman platform add --platform_name <Platform>
$ plugman platform add --platform_name <platform>

Parameters:

- <Platform>: One of android, ios
- <platform>: One of android, ios

Remove a Platform from a Plugin
-------------------------------

$ plugman platform remove --platform_name <Platform>
$ plugman platform remove --platform_name <platform>

Parameters:

- <Platform>: One of android, ios

- <platform>: One of android, ios

0 comments on commit 8058b08

Please sign in to comment.