diff --git a/devtools/cli/src/main/java/io/quarkus/cli/ProjectExtensionsList.java b/devtools/cli/src/main/java/io/quarkus/cli/ProjectExtensionsList.java index 3c3d7ef6fdb7d..a935c22c64ed2 100644 --- a/devtools/cli/src/main/java/io/quarkus/cli/ProjectExtensionsList.java +++ b/devtools/cli/src/main/java/io/quarkus/cli/ProjectExtensionsList.java @@ -18,17 +18,24 @@ import picocli.CommandLine; import picocli.CommandLine.Mixin; -@CommandLine.Command(name = "list", aliases = "ls", sortOptions = false, showDefaultValues = true, mixinStandardHelpOptions = false, description = "List platforms and extensions for this project.") +@CommandLine.Command(name = "list", aliases = "ls", sortOptions = false, showDefaultValues = true, mixinStandardHelpOptions = false, description = "%n" + + "List platforms and extensions for this project. ", footer = { "%n", + "project-mode: Active when invoked within a project unless an explicit release is specified. " + + "The current project configuration will determine what extensions are listed, " + + "with installed (available) extensions listed by default.%n", + "release-mode: Active when invoked outside of a project or when an explicit release is specified. " + + "All extensions for the specified release will be listed. " + + "The CLI release will be used if this command is invoked outside of a project and no other release is specified.%n" }) public class ProjectExtensionsList extends BaseBuildCommand implements Callable { @Mixin RunModeOption runMode; - @CommandLine.ArgGroup(order = 2, heading = "%nQuarkus version%n") + @CommandLine.ArgGroup(order = 2, heading = "%nQuarkus version (release-mode)%n") TargetQuarkusVersionGroup targetQuarkusVersion = new TargetQuarkusVersionGroup(); @CommandLine.Option(names = { "-i", - "--installable" }, defaultValue = "false", order = 2, description = "Display installable extensions.") + "--installable" }, defaultValue = "false", order = 2, description = "List extensions that can be installed (project-mode)") boolean installable = false; @CommandLine.Option(names = { "-s", diff --git a/devtools/cli/src/main/java/io/quarkus/cli/common/ListFormatOptions.java b/devtools/cli/src/main/java/io/quarkus/cli/common/ListFormatOptions.java index a61235279ff31..2e8f5a034c578 100644 --- a/devtools/cli/src/main/java/io/quarkus/cli/common/ListFormatOptions.java +++ b/devtools/cli/src/main/java/io/quarkus/cli/common/ListFormatOptions.java @@ -3,7 +3,7 @@ import picocli.CommandLine; public class ListFormatOptions { - @CommandLine.Option(names = { "--name" }, order = 4, description = "Display extension name only. (default)") + @CommandLine.Option(names = { "--name" }, order = 4, description = "Display extension name only.") boolean name = false; @CommandLine.Option(names = { "--concise" }, order = 5, description = "Display extension name and description.") diff --git a/docs/src/main/asciidoc/cli-tooling.adoc b/docs/src/main/asciidoc/cli-tooling.adoc index b6e43a946d470..d52578e8df038 100644 --- a/docs/src/main/asciidoc/cli-tooling.adoc +++ b/docs/src/main/asciidoc/cli-tooling.adoc @@ -141,12 +141,35 @@ We use both short and full names in this guide interchangeably. Use the help option to display options for creating projects: [source,shell] ----- +---- $ quarkus create app --help $ quarkus create cli --help ---- -Note: Use `--platform-bom=groupId:artifactId:version` to target a specific version of quarkus +[NOTE] +.Specifying the Quarkus version +==== +Both `quarkus create` and `quarkus extension list` allow you to explicitly specify a version of Quarkus in one of two ways: + +1. Specify a specific Platform Release BOM ++ +A https://quarkus.io/guides/platform#quarkus-platform-bom[Quarkus Platform release BOM] is identified by `groupId:artifactId:version` (GAV) coordinates. When specifying a platform release BOM, you may use empty segments to fallback to default values (groupId: `io.quarkus`, artifactId: `quarkus-bom`, version: cli version). If you specify only one segment (no `:`), it is assumed to be a version. ++ +For example: ++ +- Given the `2.0.0.Final` version of the CLI, specifying `-P :quarkus-universe-bom:` is equivalent to `-P io.quarkus:quarkus-universe-bom:2.0.0.Final`. +- Specifying `-P 999-SNAPSHOT` is equivalent to `-P io.quarkus:quarkus-bom:999-SNAPSHOT` + +2. Specify a Platform Stream ++ +Platform streams are new in Quarkus 2.0. ++ +A platform stream operates against the concept of a "registry". Each registry defines one or more platform streams, and each stream defines one or more platform release BOM files that define how projects using that stream should be configured. ++ +Streams are identified using `platformKey:streamId` syntax. A specific stream can be specified using `-S platformKey:streamId`. When specifying a stream, empty segments will be replaced with _discovered_ defaults, based on stream resource resolution rules. ++ +For `2.0.0.Final`, you must enable the registry client (`--registry-client`) explicitly to specify a stream. This will not be required in later releases. +==== == Dealing with extensions @@ -155,21 +178,43 @@ Note: Use `--platform-bom=groupId:artifactId:version` to target a specific versi $ quarkus ext --help ---- -The Quarkus CLI can obtain a list of the extensions in the project: +=== Listing extensions + +The Quarkus CLI can be used to list Quarkus extensions. [source,shell] ---- $ quarkus ext ls ---- -To get a list of available extensions to install use `--installable` or `-i`. +The format of the result can be controlled with one of four options: + +- `--name` Display the name (artifactId) only +- `--concise` Display the name (artifactId) and description +- `--full` Display concise format and version/status-related columns. +- `--origins` Display concise information along with the Quarkus platform release origin of the extension. + +The behavior of `quarkus ext ls` will vary depending on context. + +==== Listing Extensions for a Quarkus release -You can combine that with a search (`--search` or `-s`) and get a concise -list including description with `--concise`. +If you invoke the Quarkus CLI from outside of a project, Quarkus will list all of the extensions available for the Quarkus release used by the CLI itself. + +You can also list extensions for a specific release of Quarkus using `-P` or `-S`, as described in <>. + +This mode uses the `--origins` format by default. + +==== Listing Extensions for a Quarkus project + +When working with a Quarkus project, the CLI will list the extensions the current project has installed, using the `--name` format by default. + +Use the `--installable` or `-i` option to list extensions that can be installed (based on the Quarkus release the project is using). + +You can narrow or filter the list using search (`--search` or `-s`), and change the output format using an option like `--concise`. [source,shell] ---- -$ quarkus ext list -i --concise -s jdbc +$ quarkus ext list --concise -i -s jdbc JDBC Driver - DB2 quarkus-jdbc-db2 JDBC Driver - PostgreSQL quarkus-jdbc-postgresql JDBC Driver - H2 quarkus-jdbc-h2 @@ -182,7 +227,8 @@ Elytron Security JDBC quarkus-elytron-security-jdbc Agroal - Database connection pool quarkus-agroal ---- -== Adding extension(s) + +=== Adding extension(s) The Quarkus CLI can add Quarkus one or more extensions to your project with the 'add' command: @@ -194,7 +240,7 @@ $ quarkus ext add kubernetes health [SUCCESS] ✅ Extension io.quarkus:quarkus-smallrye-health has been installed ---- -== Removing extension(s) +=== Removing extension(s) The Quarkus CLI can add Quarkus one or more extensions to your project with the 'add' command: