Galleon Documentation

Feature-packs are distributed as ZIP archives with the following root entries:

Where

Generally, feature-pack metadata contains the following information:

Here is an illustration of how it may look like in a feature-pack.xml file:

Feature-pack location is an expression that is used to resolve the feature-pack artifact from the remote repository and also identify the feature-pack among other feature-packs.

The general and complete feature-pack location format is producer@universe:channel/frequency#build

Some of the parts above are or could be optional. For example, a user could add a specific universe as the default one for the distribution (in its provisioning configuration) and then not include it explicitly into feature-pack locations for the feature-packs coming from that universe.

Frequency is, generally, also optional and could be omitted.

Feature-pack producer may configure a default channel, which makes the channel part optional for the feature-packs of that producer.

With the universe and frequency omitted the location becomes producer:channel#build

Here is an example of a full feature-pack location:

wildfly@maven(org.jboss.universe:community-universe):current/beta#17.0.0.Beta1

And a shortened version:

wildfly:current#17.0.0.Beta1

And assuming current is the default channel it becomes

wildfly#17.0.0.Beta1

Using Galleon CLI

and

will result in the exact same distribution. And to install the latest (final) version of wildfly a user can simply type

Packages are stored in the directories (named after the packages) under the feature-pack packages directory.

Package directory contains the following entries:

Here is an illustration of packages entry from a feature-pack archive containing packages p1, p2, p3 and p4:

Package metadata contains the following information:

Here is an illustration of how package.xml might look like:

Here package p1 declares dependencies on packages p2 and p3 that belong to the same feature-pack as p1 and packages p1 and p11 that belong to another feature-pack referenced by alias another-feature-pack.

Package dependency may be required or optional.

Required dependency means that a package cannot be installed unless all its required dependencies are satisfied, i.e. installed. If any required dependency cannot be satisfied (perhaps because a package that happens to be a required dependency has been explicitly excluded from the installation), the provisioning process will fail with an error.

Optional dependency means that the dependency does not have to be satisfied for the package to be installed. For example if package p1 declares an optional dependency on package p2 and p2 is explicitly excluded by the user, p1 will still be installed. An example of an optional dependency could be a package called documentation which declares an optional dependency on package examples. If a user is not interested in examples, the rest of documentation could still be installed.

Package dependencies are also used to determine the effective package set of a feature-pack to be installed described later.

Here is an example of how dependencies are expressed in the XML metadata:

A package may declare dependency on a package from the same or another feature-pack. During the dependency resolution, at first, the mechanism is trying to resolve the package dependency locally, i.e. in the current feature-pack. If the dependency could not be resolved locally, the mechanism will look for the package dependency in the feature-packs the current feature-pack depends on (in the order the feature-pack dependencies are listed in feature-pack.xml of the current feature-pack). The first found matching package will be used as the resolved dependency. If the package dependency could not be resolved, the mechanism will report an error.

Feature-pack may define a set of default packages. This set of default packages is installed when the user does not provide explicit instructions about which packages from the feature-pack to install.

Default packages are explicitly listed in feature-pack.xml file which is a part of the feature-pack archive. For example:

If this feature-pack is installed without further customizations, package1 and package2 will be installed by default, although the feature-pack above may still contain other packages (not listed as default) that may not get installed.

Feature-pack may contain packages that are not marked as default in its feature-pack.xml. Non-default packages can be installed either:

This chapter is dedicated to the effective package set of a feature-pack (without dependencies) that is going to be installed, how it is resolved by the mechanism and how it can be adjusted by a user.

As illustrated in the example above, the effective package set of the dependency contributes to the effective package set of the distribution. The feature-pack declaring the dependency, though, is allowed to customize the effective package set of the dependency (the package set it inherits) using the already mentioned in previous chapters include and exclude XML elements in its feature-pack.xml. For example:

Element packages under dependency in feature-pack.xml has exactly the same structure as element packages in the provisioning XML configuration file, mentioned earlier in the chaper describing the effective package set of a feature-pack.

Now the effective package set of a distribution provisioned from fp1 becomes:

The effective package set of a dependency is inherited by the feature-pack declaring the dependency. However, it is possible to declare the dependency without inheriting its default effective package set and simply pick the desired packages explicitly under dependency element (in other words, explicitly define the desired effective package set of the dependency).

Optional boolean attribute inherit of element packages controls whether package inheritance is enabled or disabled. In case the attribute is not explicitly specified, its value is assumed to be true. Here is an example of a dependency with disabled package inheritance:

Now the effective package set of the distribution provisioned from fp1 becomes:

Suppose feature-pack fp1 depends on feature-packs fp2 and fp3. Both fp2 and fp3 depend on their own custom package sets of feature-pack fp4. When fp1 is installed, the effective package set of fp4 will be a merge of the custom package sets of fp4 defined in fp2 and fp3 as their dependencies.

For example:

A distribution provisioned from fp1 without further customizations will include:

Let’s suppose we have the following two feature-packs:

If we provision a distribution from fp1 like this

its effective package set will include:

Now if we provision our distribution as

its effective package set will become:

Now let’s suppose we want to add another package from fp2 to our distribution but we want to start from the customized fp2 configuration defined by fp1. One way of achieving that would be

That works but is not very practical. We basically copied the customizations of fp2 from fp1 to our provisioning configuration. If the configuration was more sophisticated it wouldn’t be that easy. Here is an easier alternative:

It is possible to run into a version conflict when feature-packs on different dependency branches delcare dependencies on different versions of the same feature-pack. Here is an example

In this case, Galleon will pick version 1.2.0 of fp3 simply because it was processed first as the dependency of fp1.

The user can also resolve this kind of version conflict by either installing fp3 directly or specifying its desired version in the transitive element of the installation. E.g.

There is a provisioning property called version-convergence which can be set to fail to disable the dependency version convergence that happens when merging dependency branches.

Minimal configurable unit of the generic configuration model is called a feature. A feature is described by a feature specification (or feature spec further in the text). A feature spec describes how a feature can be configured, while a feature is a specific configuration of a feature spec.

Feature specs are identified by their names that must be unique in the scope of the feature-pack.

A feature spec describes

Feature specs are stored in spec.xml files in the directories named after the feature spec names under feature-pack’s features directory. For example

A feature spec represents a minimal configuration unit. When a configuration model reaches a certain level of complexity though, using and manipulating features to define the final configuration may become impractical. Feature groups allow to group a set of features that represent a certain part of the configuration together and then include them all into the final configuration as a group. For example

First, we defined a feature group named group1 which includes three features.

Feature groups are saved in the feature-pack’s feature_groups directory in XML files named after the feature groups (group1.xml in this example).

Then in the default configuration of the feature-pack we simply included group1, which is equivalent to including the mentioned three features into the config directly.

Besides features, feature groups may also include other feature groups. Continuing the example above:

The final configuration will now include all the four features.

The idea behind layers is to predefine certain technology or some other purpose specific complete configurations (that can be used individually or in combination) and expose them as a multichoice to users composing their desired configuration.

For example, let’s suppose we are provisioning an application server that supports multiple technologies such as EJB, Servlet, Messaging, etc. Those technologies could be viewed as components that make up the complete server but also, possibly, as a user’s choice at installation time, in case the user is actually interested only in a subset of those or perhaps simply one, or something that is not included into the default set.

Layers are defined in feature-pack archive’s layers directory. A layer is associated with a name but also, as configuration models, can be associated with a model. If a layer is associated with a model, its definition in the feature-pack archive will appear in layers/config_model/layer_name/layer-spec.xml file, otherwise it will end up in layers/layer_name/layer-spec.xml.

Layers may depend on other layers. If a configuration includes a layer that depends on another layer, that other layer will be included (unless explicitly excluded by the user) into the configuration as well (prior to the layer declaring the dependency on it).

Every configuration must be associated with at least one of the following attributes:

name and model attributes serve as the identity of the configuration. They are essential when customizing and merging configurations.

If a configuration is associated only with a name (and no model) then only the name will be used as the identity of the configuration.

If a configuration is associated with a name and a model then the combination of the name and the model will be used as the identity of the configuration.

Feature-pack may include predefined configurations in its configs directory whose structure can be described as

If a configuration is associated with a name but not a model then its definition will be located in configs/config_name/config.xml and start with the following root element:

If a configuration is associated only with a model then its definition will located in configs/config_model/model.xml and start with the following root element:

If a configuration is associated with both model and a name its definition will be located in configs/model_name/config_name/config.xml and start with the following root element:

Predefined configuration models can be referenced from feature-pack.xml file and customized (manipulated) in the provisioning configuration of the installation (which is also an XML file) using config elements. Every config element will include the corresponding name and possibly model attributes to specify the identity of the configuration it is targeting.

That means, when a feature-pack is installed, by default all the configurations referenced from its feature-pack.xml are installed. Users may explicitly specify though which configurations should the final distribution include and customize those and/or provide their own custom configurations in the provisioning configuration of the installation.

Here is an example of feature-pack.xml with config elements:

The simplest way to exclude configs from the installation is

inherit="false" attribute indicates that none of the configs should be included into the distribution by default. If the attribute is not present, its value is assumed to be true.

The example above excludes all the configs, if the goal however is to exclude onyl a specific one, it can be done by providing the identity of the config using exclude element. For example, if a configuration was associated with a name but not any model then it would look like this:

And if the configuration was associated with a name and a model, both of them will have to be specified, e.g.

In case there are multiple named configs that are associated with the same model, e.g.

They can be excluded altogether by specifying the model name, e.g.

This installation will include configs model2:config1 and model2:config2.

There are two scenarios when including a configuration could be necessary:

The first one of course assumes that the configuration is associated with both name and model. It could look like this:

The example above excludes all the model1 configurations except config1.

Here is an example for the second scenario

The example above picks only config1 and model1:config1 from all the default configurations to be included into the distribution.

It is also possible to include configurations of a specific model, e.g.

In this case, all the default configurations of model1 will be included into the distribution.

Configuration model merging is a way to integrate various products in the same installation. Lets suppose we want to add new product to an existing installation. Besides adding its filesystem content to the installation, normally, the configuration files of the existing installation will have to be adjusted to include the configuration of the product to be added.

In the provisioning terms, this scenarios can be described as:

How exactly the configuration of the new product is integrated into the existing installation will depend on every specific case but there are a few basic ways it can happen:

The first one is simple: we just need to create two separate configurations: one for the main installation and one for the product we integrate.

In the second case, we need to actually merge the configurations from the existing installation and the feature-pack which represents the new product into a single confguration.

The third one effectively means that we’ve got multiple configuration models some of which should be merged and some should remain standalone. The tricky part is to identify which one is which. This is where the configuration name and model attributes are useful.

The provisioned installation may contain only one configuration model of a specific identity (which is the product of config name and model attribute values).

config element is basically an extended version of feature-group element. Meaning that everything that is allowed in the body of feature-group (which is feature, feature-group and origin elements for explicit dependency origins) is allowed in config element.

Besides that config element supports already mentioned in an earlier chapter the config attributes and props element.

E.g. if feature-pack fp1 depends on feature-pack fp2 which includes configuration model m1 named n1. Element config with attributes model="m1" name="n1" added to fp1 will represent the corresponding configuration from fp2 (unless the configuration inheritance was explicitly disabled in fp1), i.e. the content of configuration m1:n1 from fp2 may be manipulated in config element in fp1 by excluding certain features or overwriting their parameters.

The same applies to config elements under installation element. If installation includes feature-packs fp3 and fp4, both of which include configs m1:n1, config element with attributes model="m1" name="n1" added under the installation element will represent the result of merging configs m1:n1 from feature-packs fp3 and fp4.

config elements may include feature-pack package dependencies. So that when a configuration is included into the installation, the relevant packages required by the configuration are automatically included as well. Package dependencies are configured using the same elements described in the feature-package dependencies. E.g.

Now every configuration of modelA will depend on and bring into the installation the specified packages.

When all the configuration models have been resolved by the provisioning mechanism, the plugins attached to the installed feature-packs are invoked to generate the final configuration files. The plugins will see the resolved configurations as a list. Certain configuration models though may depend on other configuration models being generated first. To eliminate the trouble of ordering the configurations according to their dependencies in the plugins, configuration dependencies can be expressed in config elements. E.g.

In the example above all the configurations of model host will appear in the resolved config list after all the configurations of model domain. config-dep id is used to identify the configuration dependencies when the configuration models are merged.

The example above illustrates a dependency on a configuration model. But config-dep may also include name attribute.

Resolved configuration models are meant to be further processed by the provisioning plugins that actually generate the final configuration files. A resolved configuration is basically a set of features and properties. Plugins simply iterate through the features in the resolved configuration and generate the corresponding configuration fragments for the installation.

The order in which features appear in the resolved configuration may be significant. By default the order of the features in the resolved configuration reflects the order in which the features were added to the configuration, i.e. the order in which the features appeared in the config element. Although, in case there are dependencies between features, the mechanism will re-order the features according to their dependencies, i.e. if feature F1 depends on feature F2, even if F1 was added to the configuration before F2, in the resolved configuration F2 will appear before F1.

Patch basically provides a new version of certain content and/or redefines some configuration from the feature-pack it targets. Here is what can be patched:

As it was mentioned earlier, it is possible to apply multiple patches for the same feature-pack. In case patches don’t overlap in terms of what they patch, the order in which they are applied is not significant. If patches do overlap, the order in which they are applied most probably becomes significant. Because the patch that is applied last will overwrite patches that were applied before it.

feature-pack element may include element patches which lists patches that should be installed for the feature-pack. E.g.

An installation may contain files and directories that are meant to be managed exclusively by feature-packs and the provisioning tools and not by users. For example, core system libraries of the installation. Such paths can be marked as system-paths in the feature-pack.xml.

If during an update a file matching a feature-pack’s system-path was found to be modified by a user, the provisioning mechanism will create a copy of the user-modified file adding the .glold suffix to it and replace the original one with the file provided by the feature-pack.

Provisioning options can be persistent and non-persistent.

Persistent options are persisted in the provisioning configuration file when the provisioning process has succesfully finished. E.g. if prod1 is installed with option1, the provisioned configuration will look like this

Now if the user installs prod2, option1 will still be effective during re-provisioning and the config will change to

Non-persistent options, on the other hand, are not automatically stored in the provisioning configuration. They are used only for the provisioning action they were specified for.

Provisioning options can be provided by the core provisioning mechanism itself and the product-specific provisioning plugins.

When building a feature-pack, the <feature-pack> XML element contained in the feature-pack.xml descriptor can include attributes to specify the default stability levels that will be enabled when using the feature-pack during provisioning. If no such stability levels exist, default level is assumed.

The stability attributes are:

It is possible to control the expected level of stability at provisioning time by means of the following Galleon options:

A key concept in galleon system is the notion of feature-pack. A feature-pack is a content container. It can be a full product (eg: wildfly) or part of a product (eg: a wildfly subsystem packaged as a feature-pack). With the tool you are going to install/uninstall/update/…​ feature-packs.
NB: A galleon installation can be composed of 1 or more feature-packs.

A feature-pack can be a file on your local file system or located inside a universe (a product catalog).

The tool helps you identify the feature-pack that you can use for the task you want to achieve. In order to take benefit of the full capabilities offered by the tool, one needs to understand how products are identified inside a universe.

A feature-pack location (FPL) is the way to identify a product inside a universe without actually expressing any build numbers. A lot to commands require that you provide FPL.

The main (non exhaustive) FPL syntax is: <product>[@universe]:[version]/[qualifier]
Some examples of FPL to identify wildfly products:

The things to notice:

For example, if one installs wildfly product using the following command:

install wildfly:current/alpha --dir=myInstallation

Then, later, when checking for updates or upgrading myInstallation directory, the latest build that is at least of quality alpha will be used to update. If a final release is available then it will be installed when upgrading.

NB: Products being unique inside an installation, some commands (eg: state update) only require the product part (<product>[@universe]) of an FPL. For example:

update --feature-packs=wildfly

A feature-pack id (FPID) is the way to identify a product inside a universe by expressing a build number. This is the syntax to use when you want to deal with specific builds of a product.

The FPID syntax is: <product>[@universe]:[version]#[buildID]
Some examples of FPID to identify wildfly products:

The things to notice:

For example, to retrieve the informations of alpha1 build:

feature-pack get-info wildfly:current#1.0.0-Alpha1

[/]$ list-feature-packs [--all-frequencies] [--universe=<universe id>]

This command lists all the final feature packs present in all the installed universes.
The command looks in the current directory and its parent hierarchy for a possible installation in which some universes would have been added. By default the builtin universe is used.
If --all-frequencies option is set, then the latest build of all frequencies are displayed.
If --universe option is set, the command lists the feature packs of this universe.

[/]$ find <pattern> [--universe=<universe id>] [--resolved-only]

This command searches for all the feature pack builds present in all the installed universes that match the provided pattern.
The command looks in the current directory and its parent hierarchy for a possible installation in which some universes would have been added. By default the builtin universe is used.
If --universe option is set, the command searches for feature packs inside this universe.
If --resolved-only option is set, the command only searches for feature packs installed in local repositories.

install <[FPL|FPID] | [--file=<path to fp zip file>]> [--dir=<installation dir>] [--verbose] [feature-pack specific options]

This creates a directory containing the installed feature-pack content (binaries, configs).

NB: Using completion, when an installation directory has been identified, the options that are specific to the feature-pack to install are proposed. When installing for the first time a feature-pack this can take some time (a matter of few seconds up to minutes if the feature-pack needs to be downloaded from a remote location).

You can retrieve the set of feature-pack specific options without relying on completion, to do so call:
feature-pack get-info <[FPL|FPID] | [--file=<path to fp zip file>]> --type=options
You can then use the listed options (if any) to customize your install command.

When installing a feature-pack, all its default configurations are installed. Use the --default-configs=<comma separated list of config_model/config_name> option to specify the subset of configurations to install.

The install command can be used to install a subset of feature-pack features. Such subset are called layers. When installing layers, a custom configuration is generated.

install <[FPL|FPID] | [--file=<path to fp zip file>]> [--dir=<installation dir>] [--layers=<comma separated list of layers>] [--config=<layers_model/configuration_name>]

In order to exclude an optional layer on which a layer from the list depends on, prefix the excluded layer with '-'. In order to un-exclude a layer already excluded in the current installation, prefix the layer with '+'.

NB: When installing layers, the existing provisioned installation (if any) is updated with the set of layers.

If no model name is provided, the CLI tries to identify the default model contained in the feature-pack. If no configuration name is provided, the <layers_model>.xml is used as the generated configuration file name.

You can retrieve the set of feature-pack defined layers without relying on completion, to do so call:
feature-pack get-info <[FPL|FPID] | [--file=<path to fp zip file>]> --type=layers
You can then use the listed layers (if any) to customize your install command.

uninstall [FPID] [--dir=<installation dir>] [--verbose] [feature-pack specific options]

This will remove the content installed by the feature-pack identified by the FPID. Some feature-pack specific options can be provided, they will be used when re-provisioning the remaining (if any) feature-packs.

NB: Completer proposes the FPID you can un-install from the installation (products and patches). Completion of feature-pack specific options are handled the same way as in the install command.

undo [--dir=<installation dir>] [--verbose]

This will revert the installation to the previous installed state.

Use the install command to patch an existing installation.

install <[FPL|FPID] | [--file=<path to patch zip file>]> [--dir=<installation dir>] [--verbose] [feature-pack specific options]

Use the uninstall command to remove a given patch or use state undo if the last provisioning command has been a patch installation.

check-updates [--dir=<installation dir>] [--include-all-dependencies] [--feature-packs=<list of feature-pack producers>]

If no products are provided, all installed products are checked for updates.

The update command allows to update an installation to the latest available versions of installed feature-packs.

update [--dir=<installation dir>] [--include-all-dependencies] [--yes] [--feature-packs=<list of feature-pack producers or locations>] [feature-pack specific options]

Display the list of available updates/patches then update. If --yes is provided, the command will proceed without asking for confirmation.

NB: If the option --feature-packs contains feature-pack locations with versions, then these versions are used to update the feature-packs.

NB: Using completion, when an installation directory has been identified, the options that are specific to the installed feature-pack(s) are proposed. When updating an installation for the first time this can take some time (a matter of few seconds up to minutes if the feature-pack needs to be downloaded from a remote location).

You can retrieve the set of feature-pack specific options without relying on completion, to do so call:
installation get-info [--dir=<installation dir>] --type=options
You can then use the listed options (if any) to customize your update command.

In order to visualize files you have added, removed or modified, use the command get-changes [--dir=<installation>].
In the CLI output added files are prefixed by '+', removed ones by '-' and modified ones by 'M'.

Installed feature-packs optionally support persistence of changes into the provisioning configuration. As an example, wildfly feature-packs persist configuration changes into the provisioning config.

Use the command persist-changes [--dir=<installation>] to persist the changes.

NB: If the installed feature-packs don’t support the ability to merge changes into the provisioning configuration, this operation has no side effect.

[my-dir]$ installation get-info [--dir=installation] --type=[all|configs|dependencies|layers|optional-packages|options|patches|universes]

Display the set of installed feature-packs FPID. In addition can display configurations, dependencies layers and patches.
NB: If some patches are applied, the applied patches information is displayed.

[my-dir]$ feature-pack get-info <[FPL|FPID] | [--file=<path to fp zip file>]> --type=[all|configs|dependencies|layers|optional-packages|options]

Display the FPID of a feature-pack. In addition can display dependencies, configurations, layers and options usable when installing/provisioning/upgrading.

When getting information on an installation or a feature-pack, using --type=optional-packages option, you can retrieve the list of optional packages. At installation time the set of optional packages installed is controlled by the option --optional-packages=<all|none|passive|passive+>.

There are 2 kind of optional packages. passive ones, that are installed only if all their dependencies are installed and optional ones that have no requirements on their dependencies. Generally passive optional packages shouldn’t be excluded from an installation. They are needed for the package to properly operate when the other packages on which it depends are provisioned. Optional packages that are not passive can be excluded if not needed (according to the execution context).

When installing a complete feature-pack or installing a default configuration, the default value for --optional-packages is all (all optional and passive packages are installed).

When installing layers with the install commands the default value for --optional-packages is passive+ (all optional and passive packages that have all their dependencies installed are installed).

You can override these default values by using the --optional-packages option. Use none value to not install any optional nor passive packages, passive value to only install passive packages that have all their dependencies installed.

When a feature-pack is internally resolved (at install time, to expose information, to retrieve plugin options, …​). The feature-pack is added to a local cache. This cache is re-used to speed-up future resolutions. The CLI cleanup un-used feature-pack from the cache that are older than one month.

You can import (and optionally install in the universe for later resolution) a feature-pack zip file in the cache.

[my-dir]$ feature-pack import <path to fp zip file> [--install-in-universe=<true|false>]

You can clear the cache fully (NB: this will have a performance impact for future resolution).

[my-dir]$ feature-pack clear-cache

[my-dir]$ installation export <new generated xml file> --dir=<installation>

[my-dir]$ provision <xml file> --dir=<target installation directory> [feature-pack specific options]

NB: Using completion, when an installation directory has been identified, the options that are specific to the feature-pack(s) located in the XML configuration file are proposed. When provisioning an installation for the first time this can take some time (a matter of few seconds up to minutes if the feature-pack needs to be downloaded from a remote location).

By default the history keeps the state of the last 100 provisioning operations. This should be enough to cover simple undo of provisioned state. Nevertheless you can increase/decrease this value by using the following command:

installation set-history-limit <history size limit> [--dir=<installation dir>]

To retrieve the history size limit do:

installation get-history-limit [--dir=<installation dir>]

A universe can be added/removed to/from an existing installation.

Add a named or default (without using the --name option) universe to an installation.
[/]$ installation add-universe [--dir=<installation dir>] [--name=<universe name>] --factory=<universe factory> --location=<universe location>

Remove a named or default (without using the --name option) universe from an installation.
[/]$ installation remove-universe [--dir=<installation dir>] [--name=<universe name>]

Some commands (eg: install, get-info, check-updates, …​) allow you to optionally provide a target directory thanks to the --dir=<path> option. If no directory is provided, the command will lookup for an existing installation in the current directory (that you can change with the cd command) and its parent directories hierarchy. If no installation exists, the command will abort.

There are some exceptions to this installation lookup. install and provision commands expect the current directory to be empty or to be the root of an installation. uninstall, undo and update commands expect the current directory to be the root of an installation.

The tool allows you to switch to a state edit mode in which you can observe and edit a provisioning state in memory (without actually impacting the installation files).

To explore an installation:
[my-dir]$ state edit [<installation dir>]
[!edit!my-dir!/]$
After this point, the tool switched to edit mode with a set of new commands available.

To explore a feature-pack:
[my-dir]$ state new
[!edit!/]$ add-dependency <[FPL|FPID] --default-configs-inherit --packages-inherit

Once exploring, prompt, ls, cd and pwd commands are bound to the feature-pack (or installation) exposed file-system.
Use leave-state to switch the tool back to its nominal mode.

[!edit!/]$ ls
configs
dependencies
feature-specs
packages
[!edit!/]$ leave-state
[my-dir]$

The fs is composed of:
/configs/final/<model>/<name>/<features>
/feature-specs/<origin>/<feature-specs>
/packages/<origin>/<packages>
Features and feature-specs are organized as a file system with containment.

When in edit mode, one can search for packages and features.

[!edit!/]$ search [--query=<some text> | --package=<package name>]

When searching with --query all packages and features are looked-up for a match. If packages are matched, the features that depend directly or indirectly on these packages will be shown in the result.

When searching with --package, the package completer can be used. The features that depend directly or indirectly on this package will be shown in the result.

This allow to start from an empty installation or re-use an installation and iteratively add/suppress content.

[my-dir]$ state new | state edit <path to installation dir | path to provisioning XML file>
[!edit!/]$ ls
configs
dependencies
feature-specs
packages

NB: Each action as the effect to build a runtime with the current state. The filesystem reflects the current state.

NB: Each action applied to a state in edition can be undone: undo.

NB: Use leave-state to leave the edit mode.

NB: The set of completer exposed commands is dynamic and is adjusted according to the current state.

In edit mode, one can export the provisioning XML file or directly provision from the current state:

[!edit!/]$ export [<path to generated xml file>]
[!edit!/]$ provision <dir of new installation>

[!edit!/]$ add-dependency <FPL|FPID> [--default-configs-inherit] [--packages-inherit]

By default nothing is inherited. Once at least one feature-pack has been added, configurations or packages can be handled.

[!edit!/]$ remove-dependency <FPL|FPID>

[!edit!/]$ include-config <model>/<name> [--origin=<fp origin>]

Origin is optional, by default will be included from all fp that expose it.

[!edit!/]$ remove-included-config <model>/<name> [--origin=<fp origin>]

The completer only proposes the set of configurations that have been previously included. Origin is optional, by default will be remove from all fp that include it.

[!edit!/]$ exclude-config <model>/<name> [--origin=<fp origin>]

Origin is optional, by default will be excluded from all feature-packs that expose it.

[!edit!/]$ remove-excluded-config <model>/<name> [--origin=<fp origin>]

The completer only proposes the set of configurations that have been previously excluded. Origin is optional, by default will be removed from all feature-packs that exclude it.

NB: Prior to be able to include layers into a configuration you need an included default or locally defined configuration. To define a new configuration call define-config --model=<config model> --name=<config name>

[!edit!/]$ include-layers <config model/config name> --layers=<comma separated list of layers>

NB: The completers for both configuration and layers propose you with the existing configurations and layers not already included.

[!edit!/]$ remove-included-layers <config model/config name> --layers=<comma separated list of included layers>

NB: You can only remove layers that have been explicitly included in your local configuration. Layers included in a default configuration can be excluded but their inclusion can’t be removed.

NB: Prior to be able to exclude layers from a configuration you need an included default or locally defined configuration that contain layers.

[!edit!/]$ exclude-layers <config model/config name> --layers=<comma separated list of layers>

NB: The completers for both configuration and layers propose you with the existing configurations and included layers.

[!edit!/]$ remove-excluded-layers <config model/config name> --layers=<comma separated list of excluded layers>

NB: You can only remove layers that have been explicitly excluded in your local configuration.

[!edit!/]$ reset-config <model>/<name>

The custom content of this configuration is removed.

NB: This has no effect on included/excluded configurations.

[!edit!/]$ include-package <fp origin>/<package name>

[!edit!/]$ remove-included-package <package name> [--origin=<fp origin>]

The completer only proposes the set of packages that have been previously included. The origin is optional, the package will be removed from all feature-packs that exclude it.

[!edit!/]$ exclude-package <fp origin>/<package name>

[!edit!/]$ remove-excluded-package <package name> [--origin=<fp origin>]

The completer only proposes the set of packages that have been previously excluded. The origin is optional, the package will be removed from all feature-packs that exclude it.

[!edit!/]$ add-feature <config model/name> <path to feature-spec> <dynamic set of feature param=<value>>

For example:
add-feature standalone/standalone.xml org.wildfly.core:wildfly-core-galleon-pack/interface --interface=toto --inet-address=127.0.0.1

NB: All parameters are exposed as command option.

NB: All parameters that are not nillable and have no default values are required. The command being aborted if there are missing required parameters.

NB: If the parameter is not present, its default value is injected when creating the feature.

NB: The current location (thanks to cd) is not yet taken into account when completing/adding the feature. That is a TODO.

NB: A feature with the same feature-id can’t exist. A single feature with the given feature-id per config.

[!edit!/]$ remove-feature <full path to feature inside a configuration>

For example:
remove-feature standalone/standalone.xml/interface/toto

A universe can be added/removed to/from a state.

Add a named or default (without using the --name option) universe to the state.
[!edit!/]$ add-universe [--name=<universe name>] --factory=<universe factory> --location=<universe location>

Remove a named or default (without using the --name option) universe from the state.
[!edit!/]$ remove-universe [--name=<universe name>]

In order to makes the cli to use a maven settings file call: maven set-settings-file <path to settings xml file> In order to remove the reference to the settings file call: maven reset-settings-file

NB: Advanced mirroring (eg: external:*) is not supported.
NB: Any other cli maven configuration items will be overridden when a settings xml file is set.
NB: If no local repository is set in settings file, the local repository (default or configured) is used.

The following default repositories are enabled if not already present in the enabled profiles:

NB: These default repositories can be mirrored by using their ids.

Use the following command to add new remote repositories:
maven add-repository --name=myrepo --url=http://foorepo [--release-update-policy=<policy>] [--snapshot-update-policy=<policy>] [--type=<type>] [--enable-release=[true|false] [--enable-snapshot=[true|false]

NB: The type, release update policy, snapshot update policy and enable/disable of snapshot/release are optional and have default values.

Daily update for releases, never update for snapshots.
Warn if checksum differs.

Snapshots are not resolved from remote repositories.
Releases are resolved from remote repositories.

Update polices can be changed by calling:
maven set-release-update-policy [<always|daily|interval:|never>]
maven set-snapshot-update-policy [<always|daily|interval:|never>]

Activation of snapshot/release resolution can be changed by calling:
maven enable-snapshot [<true|false>]
maven enable-release [<true|false>]

NB: A reset command can be called for any of these changes to set the value back to its default value.

Proxy, authentication and mirroring are only supported when setting a maven xml settings file.

By default the local maven repository is located in <user.home>/.m2/repository. You can change this directory by using the command: maven set-local-repository <path to your local repository directory>
In order to reset to the default local maven repository call: maven reset-local-repository

By default maven is in online mode. In order to switch to offline use the command maven enable-offline <true|false>
In order to reset to the default mode call: maven reset-offline

Call command: maven get-info

Any change made to the maven configuration makes the CLI to re-resolve universe(s). This means that stream resolution stays in sync with maven configuration.

When remote repositories are set, feature-packs are automatically downloaded at install time. You can download feature-pack explicitly to the local repository by using the command: maven resolve-feature-pack <feature-pack location> [--verbose]

When enabling "verbose" at installation and provisioning time, any artifact retrieved from a remote repository is advertised in the console. This also applies when fetching explicitly feature-packs.