Quarkus コマンドラインインターフェイス (CLI) を使用した Quarkus アプリの構築
quarkus
コマンドを使用すると、プロジェクトの作成、エクステンションの管理、基盤となるプロジェクトビルドツールを使用したビルドと開発の必須タスクを行うことができます。
CLI のインストール
Quarkus CLI は、以下のようないくつかの開発者向けのパッケージマネージャーで利用できます。
これらのツールのいずれかをすでに使用している (または使用したい) 場合、これは Quarkus CLI をインストールして最新の状態に保つ最も簡単な方法です。
これらのパッケージマネージャーに加えて、Quarkus CLI は JBang からもインストールできます。自分にとって最も役立つ方法をご利用下さい。
-
JBang - Linux、macOS、および Windows 向け
-
SDKMAN! - Linux および macOS 向け
-
Homebrew - Linux および macOS 向け
-
Chocolatey - Windows 向け
-
Scoop - Windows 向け
CLI の使用
--help
を使用して、使用可能なすべてのコマンドと共にヘルプ情報を表示します。
quarkus --help
Usage: quarkus [-ehv] [--refresh] [--verbose] [--config=CONFIG]
[-D=<String=String>]... [COMMAND]
Options:
--refresh Refresh the local Quarkus extension registry cache
--config=CONFIG Configuration file
-h, --help Display this help message.
-v, --version Print CLI version information and exit.
-e, --errors Display error messages.
--verbose Verbose mode.
-D=<String=String> Java properties
Commands:
create Create a new project.
app Create a Quarkus application project.
cli Create a Quarkus command-line project.
extension Create a Quarkus extension project
build Build the current project.
dev Run the current project in dev (live coding) mode.
test Run the current project in continuous testing mode.
extension, ext Configure extensions of an existing project.
list, ls List platforms and extensions.
categories, cat List extension categories.
add Add extension(s) to this project.
remove, rm Remove extension(s) from this project.
image Build or push project container image.
build Build a container image.
docker Build a container image using Docker.
buildpack Build a container image using Buildpack.
jib Build a container image using Jib.
openshift Build a container image using Openshift.
push Push a container image.
deploy Deploy application.
kubernetes Perform the deploy action on kubernetes.
openshift Perform the deploy action on openshift.
knative Perform the deploy action on knative.
kind Perform the deploy action on minikube.
minikube Perform the deploy action on minikube.
registry Configure Quarkus registry client
list List enabled Quarkus registries
add Add a Quarkus extension registry
remove Remove a Quarkus extension registry
info Display project information and verify versions
health (platform and extensions).
update, up, upgrade Suggest recommended project updates with the
possibility to apply them.
version Display CLI version information.
plugin, plug Configure plugins of the Quarkus CLI.
list, ls List CLI plugins.
add Add plugin(s) to the Quarkus CLI.
remove Remove plugin(s) to the Quarkus CLI.
sync Sync (discover / purge) CLI Plugins.
completion bash/zsh completion: source <(quarkus completion)
このドキュメントは便利なリファレンスですが、最も信頼のおける情報源はクライアントヘルプです。 期待する出力が表示されない場合は、 |
新規プロジェクトの作成
新しいプロジェクトを作成するには、 create
コマンドを使用します( app
サブコマンドは、指定しない場合は暗黙で適用されます):
quarkus create
-----------
applying codestarts... 📚 java 🔨 maven 📦 quarkus 📝 config-properties 🔧 dockerfiles 🔧 maven-wrapper 🚀 resteasy-codestart
-----------
[SUCCESS] ✅ quarkus project has been successfully generated in:
--> /<output-dir>/code-with-quarkus
これにより、現在の作業ディレクトリに、デフォルトの groupId
、 artifactId
、 version
の値( groupId='org.acme'
、 artifactId='code-with-quarkus'
、 version='1.0.0-SNAPSHOT'
)を使用して、 code-with-quarkus
というフォルダが作成されます。
上記の絵文字は、正確に一致しない場合があります。絵文字の見え方は、使用するフォントや端末・環境によって異なる場合があります。例えば、IntelliJ IDEAでは、ターミナルでの絵文字の動作やレンダリングに関して、いくつかの長期にわたる問題が残されています。 |
コマンドラインから直接、 groupId
、 artifactId
、 version
を group:artifactId:version
の構文を使用して指定することができます。セグメントを選択的に省略して、デフォルト値を使用することができます:
# Create a project with groupId=org.acme, artifactId=bar, and version=1.0.0-SNAPSHOT
quarkus create app bar
# Create a project with groupId=com.foo, artifactId=bar, and version=1.0.0-SNAPSHOT
quarkus create app com.foo:bar
# Create a project with groupId=com.foo, artifactId=bar, and version=1.0
quarkus create app com.foo:bar:1.0
出力には、プロジェクトが作成されていることが表示されます。
-----------
applying codestarts... 📚 java 🔨 maven 📦 quarkus 📝 config-properties 🔧 dockerfiles 🔧 maven-wrapper 🚀 resteasy-codestart
-----------
[SUCCESS] ✅ quarkus project has been successfully generated in:
--> /<output-dir>/bar
-----------
Use the --help
option to display the options for creating projects:
quarkus create app --help quarkus create cli --help
Quarkus バージョンの指定
Both quarkus create
and quarkus extension list
allow you to explicitly specify a version of Quarkus in one of two ways:
-
Specify a specific Platform Release BOM
A Quarkus Platform release BOM is identified by
groupId:artifactId:version
(GAV) coordinates. When specifying a platform release BOM, you may use empty segments to fall back to default values (shown withquarkus create app --help
). If you specify only one segment (no:
), it is assumed to be a version.io.quarkus.platform
is the defaultgroupId
. Specifying-P :quarkus-bom:
is equivalent to-P io.quarkus.platform:quarkus-bom:3.4.1
. Note that you need to specify thegroupId
to work with a snapshot, e.g.-P io.quarkus::999-SNAPSHOT
is equivalent to-P io.quarkus:quarkus-bom:999-SNAPSHOT
.Default values are subject to change. Use the
--dry-run
option to see the computed value. -
Specify a Platform Stream
A platform stream operates against a remote 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.
エクステンションの使用
quarkus ext --help
エクステンションの一覧表示
The Quarkus CLI can be used to list Quarkus extensions.
quarkus ext ls
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.
Quarkusリリースのエクステンションのリストアップ
If you invoke the Quarkus CLI from outside of a project, Quarkus will list all 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 Specifying the Quarkus version.
This mode uses the --origins
format by default.
Quarkusプロジェクトのエクステンションのリストアップ
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 from the Quarkus platform the project is using.
You can narrow or filter the list using search (--search
or -s
).
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
JDBC Driver - MariaDB quarkus-jdbc-mariadb
JDBC Driver - Microsoft SQL Server quarkus-jdbc-mssql
JDBC Driver - MySQL quarkus-jdbc-mysql
JDBC Driver - Oracle quarkus-jdbc-oracle
JDBC Driver - Derby quarkus-jdbc-derby
Elytron Security JDBC quarkus-elytron-security-jdbc
Agroal - Database connection pool quarkus-agroal
プロジェクトのビルド
To build your project using the Quarkus CLI (using the default configuration in this example), use the build
command:
quarkus build [INFO] Scanning for projects...
[INFO]
[INFO] ---------------------< org.acme:code-with-quarkus >--------------------- [INFO] Building code-with-quarkus 1.0.0-SNAPSHOT [INFO] --------------------------------[ jar ]---------------------------------
[INFO]
... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 8.331 s [INFO] Finished at: 2021-05-27T10:13:28-04:00 [INFO] ------------------------------------------------------------------------
Output will vary depending on the build tool your project is using (Maven, Gradle, or JBang). |
Run quarkus build --clean to perform clean as part of the build.
|
開発モード
To start dev mode from the Quarkus CLI, use the dev
command:
quarkus dev [INFO] Scanning for projects...
[INFO]
[INFO] ---------------------< org.acme:code-with-quarkus >--------------------- [INFO] Building code-with-quarkus 1.0.0-SNAPSHOT [INFO] --------------------------------[ jar ]---------------------------------
[INFO]
...
Listening for transport dt_socket at address: 5005
__ ____ __ _____ ___ __ ____ ______
--/ __ \/ / / / _ | / _ \/ //_/ / / / __/
-/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2021-05-27 10:15:56,032 INFO [io.quarkus] (Quarkus Main Thread) code-with-quarkus 1.0.0-SNAPSHOT on JVM (powered by Quarkus 999-SNAPSHOT) started in 1.387s. Listening on: http://localhost:8080
2021-05-27 10:15:56,035 INFO [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
2021-05-27 10:15:56,035 INFO [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, resteasy-reactive, smallrye-context-propagation]
--
Tests paused, press [r] to resume
Output will vary depending on the build tool your project is using (Maven, Gradle, or JBang). |
Run quarkus dev --clean to perform clean as part of the build.
|
シェルのオートコンプリートとエイリアス
Automatic command completion is available for Bash and Zsh:
# Setup autocompletion in the current shell source <(quarkus completion)
If you choose to use an alias for the quarkus
command, adjust the command completion with the following commands:
# Add an alias for the quarkus command alias q=quarkus # Add q to list of commands included in quarkus autocompletion complete -F _complete_quarkus q
コンテナイメージ
The Quarkus CLI allows building container images without tampering with your project configuration (adding / removing container image extensions). To build the image for your project:
quarkus image build
The image build
command can be used directly, or a subcommand can be selected. The available subcommands are:
-
docker
-
buildpacks
-
jib
-
openshift
Each subcommand corresponds to an image building tool supported by Quarkus and gives access to specific configuration options.
For example, to use a Cloud Native Buildpack with a custom builder image, use the following:
quarkus image build buildpack --builder-image <your builder image>
CLIの拡張
The Quarkus CLI embeds a plugin system that can be used to dynamically add commands and subcommands to the CLI.
プラグインとは
A plugin can be any executable, jar or Java command that can be found locally or obtained remotely.
Plugins are classified as follows:
-
Plugins executed via shell
-
executable (any executable prefixed with
quarkus-
found locally) -
Plugins executed via jbang
-
jar (any runnable jar found locally)
-
jbang alias (any jbang alias prefixed with
quarkus-
installed locally or through the quarkusio catalog) -
maven (any maven coordinate in GACTV form pointing to a runnable jar)
プラグインの入手方法
Plugins can be found via multiple sources that are described below.
エクステンション
A Quarkus extension may define a list of cli-plugins
as part of its metadata. The list may contain GACTV string pointing to executable jars.
[WARNING] ==== At the moment, the CLI is able to obtain the list of available extensions, but is not very accurate on the exact version of the extension (it uses the version found in the extension catalog). ====
プラグインの管理
Plugins are managed using the following commands.
プラグインをリストアップ
The following command lists the installed plugins:
quarkus plugin list No plugins installed! To include the installable plugins in the list, append --installable to the command.
To list the available/installable plugins:
quarkus plugin list --installable
Name Type Scope Location Description
kill jbang user quarkus-kill@quarkusio
* fmt jbang user quarkus-fmt@quarkusio
greeter executable user /home/iocanel/bin/quarkus-greeter
'plugin add' サブコマンドを使用し、上記の任意のプラグインの場所、またはリモートプラグインを指すURL / GACTVの形で任意のリモートロケーションを渡します。
The output of the list
command may be filtered by type
using -t
or by name using -s
flag and a search pattern.
For instance, to list all the installable plugins starting with the letter k
, use the following command:
quarkus plugin list --installable -s "k*"
Name Type Scope Location Description
kill jbang user quarkus-kill@quarkusio
'plugin add' サブコマンドを使用し、上記の任意のプラグインの場所、またはリモートプラグインを指すURL / GACTVの形で任意のリモートロケーションを渡します。
プラグインの追加
To add any of the installable plugins, use quarkus plugin add <name or location>
:
quarkus plugin add kill
Added plugin:
Name Type Scope Location Description
* kill jbang user quarkus-kill@quarkusio
The command above installed a plugin by name
using the name as listed by quarkus plugin list --installable
.
The installed command can be now executed using quarkus kill
.
Users are not limited to the plugins discovered by quarkus plug list --installable .
Users may install plugins as long as they provide the URL or the Maven coordinates pointing to an executable jar or Java file.
|
You can install an executable jar as a plugin via Maven coordinates.
For instance, let’s use io.quarkiverse.authzed:quarkus-authzed-cli:runner:jar:0.2.0
which is a real executable jar that provides a CLI utility for the quarkus-authzed
extension.
quarkus plugin add io.quarkiverse.authzed:quarkus-authzed-cli:runner:jar:0.2.0 -d "Authzed CLI"
Added plugin:
Name Type Location Description
* authzed maven io.quarkiverse.authzed:quarkus-authzed-cli:runner:jar:0.2.0 Authzed CLI
It is also possible to set a description that will appear in the help output. |
quarkus --help
Usage: quarkus [-ehv] [--refresh] [--verbose] [--config=CONFIG]
[-D=<String=String>]... [COMMAND]
...
Commands:
...
plugin, plug Configure plugins of the Quarkus CLI.
list, ls List CLI plugins.
add Add plugin(s) to the Quarkus CLI.
remove Remove plugin(s) to the Quarkus CLI.
sync Sync (discover / purge) CLI Plugins.
completion bash/zsh completion: source <(quarkus completion)
authzed Authzed CLI
...
プラグインはどこに追加されるのですか?
Plugins are added in the plugin catalog that lives at: <user home>/.quarkus/cli/plugins/quarkus-cli-catalog.json
.
There is a second plugin catalog that is relative to the current project (if available): <project root>/.quarkus/cli/plugins/quarkus-cli-catalog.json
.
The effective catalog is the combination of both the user
and project
catalogs with the latter being able to override entries of the former (e.g. use a different version or location for a plugin).
If the project catalog is available, it will always be preferred, unless explicitly specified with the --user
flag.
The column scope
of the plugins table indicates where the plugin is/will be added.
プラグインの削除
Plugins are removed using quarkus plugin remove <plugin name>
.
quarkus plugin remove kill
Removed plugin:
Name Type Scope Location Description
kill jbang user quarkus-kill@quarkusio
プラグインの同期
To remove stale plugins or discover new plugins provided by extensions, the quarkus plugin sync
command is available. With this command binaries and JBang aliases that are added to the catalog but are no longer available will be purged.
Remote plugins that are explicitly added by the user using URL/Maven coordinates are excluded from the removal. |
The command is also executed implicitly through any of the CLI commands:
-
Weekly
-
If the project files have been updated since the last catalog update (limited to the module).