Stack Manager

The stack manager is a tool to manage your vert.x distribution.

It maintains the set of jar files contained in the lib directory. The stack manager takes as input a YAML file describing the dependencies that should be included in the stack. Then, during the resolution it resolves new dependencies and delete the files that are not used anymore.

If you have downloaded a vert.x distribution, it comes with a vertx-stack.json in the root directory. This file contains all the official dependencies you can add. By default it includes only the minimal stack.

Adding artifacts

To add an artifact to your stack, just add the dependency if not there already, and set the included value to true:

{
 "groupId": "io.vertx",
 "artifactId": "vertx-sync",
 "version": "${vertx.version}",
 "included": true
}

The dependency is described using the Maven coordinates. The groupId, artifactId and versions attributes are mandatory. You can also set the type (jar by default) and classifier (none by default).

Removing artifacts

To remove an artifact, remove the dependency or set the included attribute to false:

{
 "groupId": "io.vertx",
 "artifactId": "vertx-sync",
 "version": "${vertx.version}",
 "included": false
}

During the resolution, all files that are not associated to a dependency (or a transitive dependency) are removed. That means don’t add files manually, they are going to be deleted.

Launching the resolution

To launch the resolution, launch:

./bin/vertx resolve --dir=lib

The resolve command supports a set of options:

  • --dir <value> - The directory containing the artifacts composing the stack. Defaults to the ./lib directory

  • --fail-on-conflict - Set whether or not the resolver should fail or conflict or just log a warning. Disabled by default.

  • --http-proxy <value> - Set the HTTP proxy address if any.

  • --https-proxy <value> - Set the HTTPS proxy address if any.

  • --local-repo <value> - Set the path to the local Maven repository. Defaults to ~/.m2/repository

  • --remote-repo <value> - Set the path to a remote Maven repository. Can be set multiple times

  • <vertx-stack.json> - The path to the stack descriptor. Defaults to vertx-stack.json.

  • --no-cache - Disable the resolver cache

  • --no-cache-for-snapshots - Disable the caching of snapshot resolution

If you have set VERTX_HOME as environment variable (or system variable), it uses: $VERTX_HOME/lib and $VERTX_HOME/vertx-stack.json.

Exclusions and Transitives

Each dependency can declare a set of exclusions that won’t be resolved during the resolution process:

{
 "groupId": "org.acme",
 "artifactId": "acme-lib",
 "version": "1.0.0",
 "included": true,
 "exclusions": [{
   "groupId": "org.acme",
   "artifactId": "acme-not-required"
 }]
}

You can also set the transitive attribute to false on a dependency to not resolve the transitive dependencies. This is useful when using fat jars or shaded artifacts:

{
 "groupId": "io.vertx",
 "artifactId": "vertx-web-templ-thymeleaf",
 "version": "${vertx.version}",
 "included": true,
 "classifier": "shaded",
 "transitive": false
}

Using variables

The stack definition allows you to declare variables:

{
"variables": {
  "vertx.version": "3.9.5-SNAPSHOT"
}

Then your dependency can uses this variable using the ${} notation.

Variables can be set or overridden using system variables. System variables can be set with -D

A note about the JSON format

The descriptor format supports:

  • comments using //

  • non quoted keys (such as groupId : "org.acme")

  • single quotes for values (such as groupId : 'org.acme')