Criar aplicações Quarkus com a interface de linha de comandos (CLI) do Quarkus
O comando quarkus permite que você crie projetos, gerencie extensões e realize tarefas essenciais de criação e desenvolvimento usando a ferramenta de criação de projetos subjacente.
Instalação do CLI
O Quarkus CLI está disponível em vários gestores de pacotes orientados para o desenvolvedor, tais como:
Se você já utiliza (ou pretende utilizar) uma destas ferramentas, esta é a forma mais simples de instalar o Quarkus CLI e de o manter atualizado.
Além desses gestores de pacotes, o Quarkus CLI também pode ser instalado via JBang. Escolha a alternativa que for mais prática para você:
-
JBang - para Linux, macOS e Windows
-
SDKMAN! - para Linux e macOS
-
Homebrew - para Linux e macOS
-
Chocolatey - para Windows
-
Scoop - para Windows
Usando o CLI
Use --help para exibir informações de ajuda com todos os comandos disponíveis:
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 Kind.
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)|
While this document is a useful reference, the client help is the definitive source. Se você não visualizar o resultado esperado, use |
Criando um novo projeto
Para criar um novo projeto, use o comando create
(o subcomando app estará implícito quando não é especificado):
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-quarkusIsso criará uma pasta chamada code-with-quarkus em seu diretório de trabalho atual usando os valores padrão groupId , artifactId e version
( groupId='org.acme' , artifactId='code-with-quarkus' e version='1.0.0-SNAPSHOT' ).
| Os emojis mostrados acima podem não corresponder exatamente. A aparência dos emojis pode variar de acordo com a fonte usada ou com o terminal/ambiente. O IntelliJ IDEA, por exemplo, tem vários problemas de longa data em aberto com relação ao comportamento/renderização de emojis no terminal. |
Você pode especificar groupId , artifactId e version usando a sintaxe de coordenadas group:artifactId:version diretamente da linha de comando. Você pode omitir segmentos seletivamente para usar os valores padrão:
# 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.0A saída mostrará seu projeto sendo criado:
-----------
applying codestarts...
📚 java
🔨 maven
📦 quarkus
📝 config-properties
🔧 dockerfiles
🔧 maven-wrapper
🚀 resteasy-codestart
-----------
[SUCCESS] ✅ quarkus project has been successfully generated in:
--> /<output-dir>/bar
-----------Use a opção --help para exibir as opções de criação de projetos:
quarkus create app --help
quarkus create cli --helpEspecificando a versão do Quarkus
Both quarkus create and quarkus extension list allow you to explicitly specify a version of Quarkus in one of two ways:
-
Forneça um Platform Release BOM específico
Um Quarkus Platform Release BOM é identificado pelas coordenadas
groupId:artifactId:version(GAV). Quando especificado um platform release BOM, você pode usar segmentos vazios para usar os valores padrões (mostrados comquarkus create app --help). Se você especificar apenas um segmento (sem:), ele será considerado uma versão.io.quarkus.platformé ogroupIdpadrão. Especificando-P :quarkus-bom:é equivalente a-P io.quarkus.platform:quarkus-bom:3.17.2. Note que é necessário especificar ogroupIdpara trabalhar com um snapshot, por exemplo,-P io.quarkus::999-SNAPSHOTé equivalente a-P io.quarkus:quarkus-bom:999-SNAPSHOT.Os valores padrão estão sujeitos a alterações. Use a opção
--dry-runpara ver o valor computado. -
Forneça um Plataform Stream
Um platform stream opera em um registro remoto. Cada registro define um ou mais platform stream, e cada fluxo define um ou mais arquivos do platform release BOM que definem como os projetos que usam esse fluxo devem ser configurados.
Streams são identificados usando a sintaxe
platformKey:streamId. Um stream específico pode ser especificado usando-S platformKey:streamId. Ao especificar um stream, os segmentos vazios serão substituídos por valores padrões descobertos, com base nas regras de resolução de recursos stream.
Trabalhando com extensões
quarkus ext --helpListando extensões
The Quarkus CLI can be used to list Quarkus extensions.
quarkus ext lsO formato do resultado pode ser controlado com uma das quatro opções:
-
--nameExibir apenas o nome (artifactId) -
--conciseExibir o nome (artifactId) e a descrição -
--fullExibe o formato conciso e as colunas relacionadas à versão/status. -
--originsExibe informação concisa segundo a origem da extensão na plataforma Quarkus.
O comportamento do quarkus ext ls varia de acordo com o contexto.
Listando extensões para uma versão do 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.
Você também pode listar as extensões de uma versão específica do Quarkus usando -P ou -S , conforme descrito em Especificando a versão do Quarkus .
This mode uses the --origins format by default.
Listando extensões para um projeto 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-agroalAdicionando extensões
O Quarkus CLI pode adicionar uma ou mais extensões ao seu projeto com o subcomando add:
quarkus ext add kubernetes health
[SUCCESS] ✅ Extension io.quarkus:quarkus-kubernetes has been installed
[SUCCESS] ✅ Extension io.quarkus:quarkus-smallrye-health has been installedYou can install all extensions which match a glob pattern:
quarkus ext add smallrye-*Build your project
Para compilar seu projeto usando o Quarkus CLI (usando a configuração padrão neste exemplo),
use o comando build:
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] ------------------------------------------------------------------------| A saída varia de acordo com a ferramenta de compilação que seu projeto está usando (Maven, Gradle ou JBang). |
Execute quarkus build --clean para efetuar a limpeza como parte da compilação.
|
Modo de desenvolvimento
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, rest, smallrye-context-propagation]
--
Tests paused, press [r] to resume| A saída varia de acordo com a ferramenta de compilação que seu projeto está usando (Maven, Gradle ou JBang). |
Execute quarkus build --clean para efetuar a limpeza como parte da compilação.
|
Autocompletar e atalhos do terminal
Automatic command completion is available for Bash and Zsh:
# Setup autocompletion in the current shell
source <(quarkus completion)Se você optar por usar um atalho (alias) para o comando quarkus, ajuste a terminação do comando da seguinte forma:
# Add an alias for the quarkus command
alias q=quarkus
# Add q to list of commands included in quarkus autocompletion
complete -F _complete_quarkus qImagens de Contêiner
A CLI do Quarkus permite criar imagens de containers sem interferir na configuração do projeto (adicionar/remover extensões de imagens de containers). Para criar a imagem do seu projeto:
quarkus image buildO comando image build pode ser usado diretamente ou um subcomando pode ser adicionado. Os subcomandos disponíveis são:
-
docker
-
buildpacks
-
jib
-
openshift
Cada subcomando corresponde a uma ferramenta de criação de imagens compatível com o Quarkus e dá acesso a opções de configuração específicas.
Por exemplo, para usar um Cloud Native Buildpack com uma imagem personalizada, use o seguinte:
quarkus image build buildpack --builder-image <your builder image>Ampliando o CLI
The Quarkus CLI embeds a plugin system that can be used to dynamically add commands and subcommands to the CLI.
O que é um plugin
A plugin can be any executable, jar or Java command that can be found locally or obtained remotely.
Plugins are classified as follows:
-
Plugins executados via terminal
-
executável (qualquer executável precedido de
quarkus-encontrado localmente) -
Plugins executados via jbang
-
jar (qualquer executável jar encontrado localmente)
-
jbang alias (qualquer atalho jbang precedido de
quarkus-instalado localmente ou via catálogo quarkusio) -
maven (qualquer coordenada maven no formato GACTV apontando para um jar executável)
Como obter plugins
Plugins can be found via multiple sources that are described below.
Extensões
Uma extensão Quarkus pode definir uma lista de cli-plugins como parte de seus metadados.
A lista pode conter uma cadeia de caracteres GACTV que aponta para jars executáveis.
|
No momento, o CLI pode obter a lista de extensões disponíveis, mas não é muito preciso quanto à versão exata da extensão (ele usa a versão encontrada no catálogo de extensões). |
Gerenciando plugins
Plugins are managed using the following commands.
Listando plugins
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.Para listar os plugins disponíveis/instaláveis:
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
Use the 'plugin add' subcommand and pass the location of any plugin listed above, or any remote location in the form of URL / GACTV pointing to a remote plugin.A saída do comando list pode ser filtrada por tipo usando -t ou por nome usando a flag -s e um padrão de pesquisa.
Por exemplo, para listar todos os plugins instaláveis que começam com a letra k, use o seguinte comando:
quarkus plugin list --installable -s "k*"
Name Type Scope Location Description
kill jbang user quarkus-kill@quarkusio
Use the 'plugin add' subcommand and pass the location of any plugin listed above, or any remote location in the form of URL / GACTV pointing to a remote plugin.Adicionando plugins
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@quarkusioO comando acima instalou um plugin usando o name conforme listado por quarkus plugin list --installable.
O comando instalado agora pode ser executado usando o quarkus kill.
Os usuários não estão limitados aos plugins encontrados pelo quarkus plug list --installable.
Os usuários podem instalar plugins desde que forneçam o URL ou as coordenadas Maven que apontem para um arquivo jar ou Java executável.
|
Você pode instalar um jar executável como um plugin via coordenadas Maven.
Por exemplo, vamos usar io.quarkiverse.authzed:quarkus-authzed-cli:runner:jar:0.2.0, que é um jar executável real que fornece um recurso CLI para a extensão quarkus-authzed.
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
É possível também definir uma descrição que será exibida na saída do help.
|
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
...Onde os plugins são instalados?
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.
Removendo plugins
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@quarkusioSincronizando plugins
Para remover plugins obsoletos ou descobrir novos plugins fornecidos por extensões, está disponível o comando quarkus plugin sync.
Com este comando, os binários e atalhos do JBang adicionados ao catálogo, mas que não estão mais disponíveis, serão eliminados.
| Os plugins remotos que são explicitamente adicionados pelo usuário usando URL/coordenadas Maven são excluídos da remoção. |
The command is also executed implicitly through any of the CLI commands:
-
Semanalmente
-
Se os arquivos do projeto tiverem sido atualizados desde a última atualização do catálogo (limitado ao módulo).
