= Plumage =

Plumage is a package manager for the Parrot VM module ecosystem. With it, you can perform tasks such as searching,
installing, and testing modules in the ecosystem.

The ecosystem currently includes various compilers targeting Parrot, libraries, language bindings, and more.

= Getting Plumage =

The Plumage repository is hosted on [https://github.com/parrot/plumage Github]. You can obtain a copy of the
source code by running `git clone git://github.com/parrot/plumage.git`.
To install Plumage, run the following sequence of commands:

{{{
parrot setup.pir build      # Builds executable
parrot setup.pir test       # Optional, runs test suite
parrot setur.pir install    # Installs executable
}}}

If you received an error message in the last step that's similar to:

{{{
Can't mkdir '/usr/local/lib/parrot/[version]/library/Plumage' (Permission denied)
}}}

Where `[version]` is the version of Parrot installed, you need root access to complete the installation. Try prefixing the last
command with `sudo` or `su -c`.

Plumage is installed to the same directory that Parrot was installed to. This is `/usr/local/bin` by default. If you want to change this,
you need to re-install Parrot. Use the `--prefix` switch when running `Configure.pl`. For example, 
`perl Configure.pl --prefix=/foo/bar/baz`.

Once the above steps have been completed, you can then begin using Plumage.

''NOTE FOR WINDOWS USERS'': Since Parrot 3.0.0, Plumage is shipped with the Parrot binaries at [http://sourceforge.net/projects/parrotwin32/].

= Usage =

To show the list of projects that are in the ecosystem, run `plumage projects`. After choosing the one you want to install, simply
run `plumage install <project>`. This will build, test, and install the desired project into the Parrot
directory tree.

For example, if you want to install `partcl` (an implementation of Tcl), run:

{{{
plumage install partcl
}}}

Just like when installing Plumage, root access may be required depending on where the default installation directory is. If
that is the case, you will be prompted to enter your password.

If you decide that you no longer need a particular package, you can remove it with the `uninstall` command. Using `partcl` as an example again, run:

{{{
plumage uninstall partcl
}}}

Plumage is able to resolve package dependencies. If package `Foo` depends on package `Bar`, installing `Foo` will also silently install `Bar`.

For more usage information, run `plumage help`.