:toc:
:toc-placement!:

= Galleon Provisioning

ifdef::env-github[]
[link=https://travis-ci.org/aloubyansky/pm]
image:https://travis-ci.org/aloubyansky/pm.svg?branch=master["Build Status", link="https://travis-ci.org/aloubyansky/pm"]
endif::[]

toc::[]

= Project Modules

== Module `galleon-parent`

Defines main version and common dependencies of the project.

== Module `core`

General provisioning and feature-pack API. Which allows to provision the desired
installation specification at a specified location, install additional and/or
uninstall existing feature-packs, export the currently provisioned specification
to a file with the purpose to reproduce it at a different location.

== Module `cli`

Command line interface which allows to:

* Build feature-packs and install them into the Maven repository;
* Provision an installation by pulling the feature-packs from the
  Maven repository and installing them at the specified location.;
* View the currently provisioned installation specification;
* Export the currently provisioned installation specification to
  a file with goal to reproduce the installation later.

The Maven assembly plug-in is configured to create a single executable JAR
file which contains all the dependencies.

= CLI Commands

== FileSystem commands

The following filesystem commands are available:

* cd - change current work directory
* pwd - print current work directory
* mkdir - create a new directory if it does not already exist
* ls - list the content of a directory
* less - display the content of a file
* rm - remove a file

== provision-spec

[source,shell]
----
[workdir]$ provision-spec <spec-file-path> [--dir=<installation-dir>]
----

(Re-)Provisions the installation according to installation specification
provided in an XML file.

Arguments:

[source,shell]
----
<path>        - filesystem path to the XML file describing the desired
                installation specification.

--dir         - optional, target installation directory. If the argument is
                missing, the current work directory is assumed as the target.
----

== install

[source,shell]
----
[workdir]$ install <feature-pack-gav> [--dir=<installation-dir>]
----

Adds the feature-pack to the installation specification (or creates a new spec
if one does not exist yet) and (re-)provisions the target installation.

Arguments:

[source,shell]
----
<feature-pack-gav>  - groupId:artifactId:version of the feature-pack to install.

--dir         - optional, target installation directory. If the argument is
                missing, the current work directory is assumed as the target.
----

== uninstall

[source,shell]
----
[workdir]$ uninstall <feature-pack-gav> [--dir=<installation-dir>]
----

Removes the feature-pack from the installation specification and
(re-)provisions the target installation.

Arguments:

[source,shell]
----
<feature-pack-gav>  - groupId:artifactId:version of the feature-pack to
                      uninstall.

--dir         - optional, target installation directory. If the argument is
                missing, the current work directory is assumed as the target.
----

== provisioned-spec

=== provisioned-spec display

[source,shell]
----
[workdir]$ provisioned-spec display [--verbose] [--dir=<installation-dir>]
----

Displays the currently provisioned installation specification.

Arguments:

[source,shell]
----
--verbose(-v) - whether to include feature-packs not explicitly chosen by
                the user but installed as dependencies of other feature-packs.

--dir         - optional, target installation directory. If the argument is
                missing, the current work directory is assumed as the target.
----

=== provisioned-spec export

[source,shell]
----
[workdir]$ provisioned-spec export <file-path>
----

Exports the currently provisioned installation specification to the specified
file in the XML format. The resulting file can be used as an argument to
`provision-spec` command.

Arguments:

[source,shell]
----
<file-path>   - file path to store the provisioned specification to.
----

= Building and launching the tool
 
The tool can be built by executing the following Maven command:

[source,shell]
----
mvn clean install
----

The executable JAR will be built in `cli/target/galleon-cli.jar`

There is also a convenience `do.sh` script in the root directory
of the project. If executed w/o arguments, it'll build and launch the tool.

`./do.sh package` will only build the tool.
`./do.sh run` will only launch the already built tool.
