Skip to content

RFC: CLI cleanup

Jump to bottom
Thomas Segismont edited this page Jun 15, 2023 · 1 revision

Introduction

The vertx CLI will be removed starting from Vert.x 5. We want to focus on the use case of the typical Vert.x application: compiled and optionally packaged as an executable uber-jar.

This document describes proposed changes and consequences for both Vert.x 5 and Vert.x 4.

Main goals

  • Stop publishing the CLI artifact.
  • Continue to support command line processing for applications started with the Launcher.

Proposal

Artifact removal

The vertx CLI is published to:

We shall stop publishing new versions there.

Mentions of the CLI must be removed from the documentation and from the vertx-examples repository. In order to discourage new users from using the CLI, both the Vert.x 4 and Vert.x 5 docs and examples will be updated.

Supporting applications started with the Launcher

The Launcher is a class that extends the CLI entry point, VertxCommandLauncher.

The CLI is implemented using an extensible set of commands:

  • start: start an application in a separate JVM
  • stop: stop a running application
  • run: run an application in the same JVM
  • bare: starts a Vert.x node without running an application
  • list: list running applications
  • version: prints the current Vert.x version

The typical Vert.x application started with the Launcher executes only the run command. The other commands shall be removed.

The run command supports several arguments. These will be removed:

  • cwd: setting the current working directory only makes sense for background applications
  • systemProperty: given the application runs in the same JVM, system properties can be defined with -D
  • cp: extra classpath is only useful when a verticle requires classes/resources not bundled with the CLI
  • redeploy, on-redeploy, redeploy-scan-period, redeploy-grace-period, redeploy-termination-period: redeployment does not make sense for compiled applications

Redeployment support could be moved to the Vert.x Maven and Gradle plugins (sharing change detection implementation in a separate project).

Vert.x Unit

Vert.x Unit provides a CLI command for running a test suite. This command shall be removed as it was mostly useful for testing code implemented with interpreted languages.

Regarding Picocli

At the time of writing, Picocli is the de-facto standard for CLI implementations in Java. Picocli provides features not supported in the Vert.x CLI, like colors or completion.

But this comes at the expense of adding a dependency. Besides, the Vert.x Shell project and other community projects (e.g. es4x, konduit-serving) rely on the CLI framework.

Consequently, it seems safer to keep the CLI framework, without documentation (other than Javadoc).

Removing source file compilation

Starting Vert.x applications from source with the CLI made most sense when Vert.x supported interpreted languages. Besides, when the Vert.x CLI was created many years ago, running a Java source file wasn't possible. But now, there are alternatives like jbang or running Java source files with JDK 11+.

For these reasons, we will remove the Java source verticle support (i.e compiling classloader and friends).

Clone this wiki locally