490 lines
15 KiB
Plaintext
490 lines
15 KiB
Plaintext
[[cli]]
|
|
= Spring Boot CLI
|
|
|
|
[partintro]
|
|
--
|
|
The Spring Boot CLI is a command line tool that you can use if you want to quickly develop
|
|
a Spring application. It lets you run Groovy scripts, which means that you have a familiar
|
|
Java-like syntax without so much boilerplate code. You can also bootstrap a new project or
|
|
write your own command for it.
|
|
--
|
|
|
|
|
|
|
|
[[cli-installation]]
|
|
== Installing the CLI
|
|
The Spring Boot CLI (Command-Line Interface) can be installed manually by using SDKMAN!
|
|
(the SDK Manager) or by using Homebrew or MacPorts if you are an OSX user. See
|
|
_<<getting-started.adoc#getting-started-installing-the-cli>>_ in the "`Getting started`"
|
|
section for comprehensive installation instructions.
|
|
|
|
|
|
|
|
[[cli-using-the-cli]]
|
|
== Using the CLI
|
|
Once you have installed the CLI, you can run it by typing `spring` and pressing Enter at
|
|
the command line. If you run `spring` without any arguments, a simple help screen is
|
|
displayed, as follows:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ spring
|
|
usage: spring [--help] [--version]
|
|
<command> [<args>]
|
|
|
|
Available commands are:
|
|
|
|
run [options] <files> [--] [args]
|
|
Run a spring groovy script
|
|
|
|
_... more command help is shown here_
|
|
----
|
|
|
|
You can type `spring help` to get more details about any of the supported commands, as
|
|
shown in the following example:
|
|
|
|
[indent=0]
|
|
----
|
|
$ spring help run
|
|
spring run - Run a spring groovy script
|
|
|
|
usage: spring run [options] <files> [--] [args]
|
|
|
|
Option Description
|
|
------ -----------
|
|
--autoconfigure [Boolean] Add autoconfigure compiler
|
|
transformations (default: true)
|
|
--classpath, -cp Additional classpath entries
|
|
-e, --edit Open the file with the default system
|
|
editor
|
|
--no-guess-dependencies Do not attempt to guess dependencies
|
|
--no-guess-imports Do not attempt to guess imports
|
|
-q, --quiet Quiet logging
|
|
-v, --verbose Verbose logging of dependency
|
|
resolution
|
|
--watch Watch the specified file for changes
|
|
----
|
|
|
|
The `version` command provides a quick way to check which version of Spring Boot you are
|
|
using, as follows:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ spring version
|
|
Spring CLI v{spring-boot-version}
|
|
----
|
|
|
|
|
|
|
|
[[cli-run]]
|
|
=== Running Applications with the CLI
|
|
You can compile and run Groovy source code by using the `run` command. The Spring Boot CLI
|
|
is completely self-contained, so you do not need any external Groovy installation.
|
|
|
|
The following example shows a "`hello world`" web application written in Groovy:
|
|
|
|
.hello.groovy
|
|
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
@RestController
|
|
class WebApplication {
|
|
|
|
@RequestMapping("/")
|
|
String home() {
|
|
"Hello World!"
|
|
}
|
|
|
|
}
|
|
----
|
|
|
|
To compile and run the application, type the following command:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ spring run hello.groovy
|
|
----
|
|
|
|
To pass command-line arguments to the application, use `--` to separate the commands
|
|
from the "`spring`" command arguments, as shown in the following example:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ spring run hello.groovy -- --server.port=9000
|
|
----
|
|
|
|
To set JVM command line arguments, you can use the `JAVA_OPTS` environment variable, as
|
|
shown in the following example:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ JAVA_OPTS=-Xmx1024m spring run hello.groovy
|
|
----
|
|
|
|
NOTE: When setting `JAVA_OPTS` on Microsoft Windows, make sure to quote the entire
|
|
instruction, such as `set "JAVA_OPTS=-Xms256m -Xmx2048m"`. Doing so ensures the values
|
|
are properly passed to the process.
|
|
|
|
[[cli-deduced-grab-annotations]]
|
|
==== Deduced "`grab`" Dependencies
|
|
Standard Groovy includes a `@Grab` annotation, which lets you declare dependencies on
|
|
third-party libraries. This useful technique lets Groovy download jars in the same way as
|
|
Maven or Gradle would but without requiring you to use a build tool.
|
|
|
|
Spring Boot extends this technique further and tries to deduce which libraries to "`grab`"
|
|
based on your code. For example, since the `WebApplication` code shown previously uses
|
|
`@RestController` annotations, Spring Boot grabs "Tomcat" and "Spring MVC".
|
|
|
|
The following items are used as "`grab hints`":
|
|
|
|
|===
|
|
| Items | Grabs
|
|
|
|
|`JdbcTemplate`, `NamedParameterJdbcTemplate`, `DataSource`
|
|
|JDBC Application.
|
|
|
|
|`@EnableJms`
|
|
|JMS Application.
|
|
|
|
|`@EnableCaching`
|
|
|Caching abstraction.
|
|
|
|
|`@Test`
|
|
|JUnit.
|
|
|
|
|`@EnableRabbit`
|
|
|RabbitMQ.
|
|
|
|
|`@EnableReactor`
|
|
|Project Reactor.
|
|
|
|
|extends `Specification`
|
|
|Spock test.
|
|
|
|
|`@EnableBatchProcessing`
|
|
|Spring Batch.
|
|
|
|
|`@MessageEndpoint` `@EnableIntegration`
|
|
|Spring Integration.
|
|
|
|
|`@Controller` `@RestController` `@EnableWebMvc`
|
|
|Spring MVC + Embedded Tomcat.
|
|
|
|
|`@EnableWebSecurity`
|
|
|Spring Security.
|
|
|
|
|`@EnableTransactionManagement`
|
|
|Spring Transaction Management.
|
|
|===
|
|
|
|
TIP: See subclasses of
|
|
{sc-spring-boot-cli}/compiler/CompilerAutoConfiguration.{sc-ext}[`CompilerAutoConfiguration`]
|
|
in the Spring Boot CLI source code to understand exactly how customizations are applied.
|
|
|
|
|
|
|
|
[[cli-default-grab-deduced-coordinates]]
|
|
==== Deduced "`grab`" Coordinates
|
|
Spring Boot extends Groovy's standard `@Grab` support by letting you specify a dependency
|
|
without a group or version (for example, `@Grab('freemarker')`). Doing so consults Spring
|
|
Boot's default dependency metadata to deduce the artifact's group and version.
|
|
|
|
NOTE: The default metadata is tied to the version of the CLI that you use. it changes only
|
|
when you move to a new version of the CLI, putting you in control of when the versions of
|
|
your dependencies may change. A table showing the dependencies and their versions that are
|
|
included in the default metadata can be found in the <<appendix-dependency-versions,
|
|
appendix>>.
|
|
|
|
|
|
|
|
[[cli-default-import-statements]]
|
|
==== Default Import Statements
|
|
To help reduce the size of your Groovy code, several `import` statements are automatically
|
|
included. Notice how the preceding example refers to `@Component`, `@RestController`, and
|
|
`@RequestMapping` without needing to use fully-qualified names or `import` statements.
|
|
|
|
TIP: Many Spring annotations work without using `import` statements. Try running your
|
|
application to see what fails before adding imports.
|
|
|
|
|
|
|
|
[[cli-automatic-main-method]]
|
|
==== Automatic Main Method
|
|
Unlike the equivalent Java application, you do not need to include a
|
|
`public static void main(String[] args)` method with your `Groovy` scripts. A
|
|
`SpringApplication` is automatically created, with your compiled code acting as the
|
|
`source`.
|
|
|
|
|
|
|
|
[[cli-default-grab-deduced-coordinates-custom-dependency-management]]
|
|
==== Custom Dependency Management
|
|
By default, the CLI uses the dependency management declared in `spring-boot-dependencies`
|
|
when resolving `@Grab` dependencies. Additional dependency management, which overrides
|
|
the default dependency management, can be configured by using the
|
|
`@DependencyManagementBom` annotation. The annotation's value should specify the
|
|
coordinates (`groupId:artifactId:version`) of one or more Maven BOMs.
|
|
|
|
For example, consider the following declaration:
|
|
|
|
[source,groovy,indent=0]
|
|
----
|
|
@DependencyManagementBom("com.example.custom-bom:1.0.0")
|
|
----
|
|
|
|
The preceding declaration picks up `custom-bom-1.0.0.pom` in a Maven repository under
|
|
`com/example/custom-versions/1.0.0/`.
|
|
|
|
When you specify multiple BOMs, they are applied in the order in which you declare them,
|
|
as shown in the following example:
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
@DependencyManagementBom(["com.example.custom-bom:1.0.0",
|
|
"com.example.another-bom:1.0.0"])
|
|
----
|
|
|
|
The preceding example indicates that the dependency management in `another-bom` overrides
|
|
the dependency management in `custom-bom`.
|
|
|
|
You can use `@DependencyManagementBom` anywhere that you can use `@Grab`. However, to
|
|
ensure consistent ordering of the dependency management, you can use
|
|
`@DependencyManagementBom` at most once in your application. A useful source of dependency
|
|
management (which is a superset of Spring Boot's dependency management) is the
|
|
http://platform.spring.io/[Spring IO Platform], which you might include with the following
|
|
line:
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
@DependencyManagementBom('io.spring.platform:platform-bom:1.1.2.RELEASE')
|
|
----
|
|
|
|
|
|
[[cli-multiple-source-files]]
|
|
=== Applications with Multiple Source Files
|
|
You can use "`shell globbing`" with all commands that accept file input. Doing so lets
|
|
you use multiple files from a single directory, as shown in the following example:
|
|
|
|
[indent=0]
|
|
----
|
|
$ spring run *.groovy
|
|
----
|
|
|
|
|
|
|
|
[[cli-jar]]
|
|
=== Packaging Your Application
|
|
You can use the `jar` command to package your application into a self-contained executable
|
|
jar file, as shown in the following example:
|
|
|
|
[indent=0]
|
|
----
|
|
$ spring jar my-app.jar *.groovy
|
|
----
|
|
|
|
The resulting jar contains the classes produced by compiling the application and all of
|
|
the application's dependencies so that it can then be run by using `java -jar`. The jar
|
|
file also contains entries from the application's classpath. You can add and remove
|
|
explicit paths to the jar by using `--include` and `--exclude`. Both are comma-separated,
|
|
and both accept prefixes, in the form of "`+`" and "`-`", to signify that they should be
|
|
removed from the defaults. The default includes are as follows:
|
|
|
|
[indent=0]
|
|
----
|
|
public/**, resources/**, static/**, templates/**, META-INF/**, *
|
|
----
|
|
|
|
The default excludes are as follows:
|
|
|
|
[indent=0]
|
|
----
|
|
.*, repository/**, build/**, target/**, **/*.jar, **/*.groovy
|
|
----
|
|
|
|
Type `spring help jar` on the command line for more information.
|
|
|
|
|
|
|
|
[[cli-init]]
|
|
=== Initialize a New Project
|
|
The `init` command lets you create a new project by using https://start.spring.io without
|
|
leaving the shell, as shown in the following example:
|
|
|
|
[indent=0]
|
|
----
|
|
$ spring init --dependencies=web,data-jpa my-project
|
|
Using service at https://start.spring.io
|
|
Project extracted to '/Users/developer/example/my-project'
|
|
----
|
|
|
|
The preceding example creates a `my-project` directory with a Maven-based project that
|
|
uses `spring-boot-starter-web` and `spring-boot-starter-data-jpa`. You can list the
|
|
capabilities of the service by using the `--list` flag, as shown in the following example:
|
|
|
|
[indent=0]
|
|
----
|
|
$ spring init --list
|
|
=======================================
|
|
Capabilities of https://start.spring.io
|
|
=======================================
|
|
|
|
Available dependencies:
|
|
-----------------------
|
|
actuator - Actuator: Production ready features to help you monitor and manage your application
|
|
...
|
|
web - Web: Support for full-stack web development, including Tomcat and spring-webmvc
|
|
websocket - Websocket: Support for WebSocket development
|
|
ws - WS: Support for Spring Web Services
|
|
|
|
Available project types:
|
|
------------------------
|
|
gradle-build - Gradle Config [format:build, build:gradle]
|
|
gradle-project - Gradle Project [format:project, build:gradle]
|
|
maven-build - Maven POM [format:build, build:maven]
|
|
maven-project - Maven Project [format:project, build:maven] (default)
|
|
|
|
...
|
|
----
|
|
|
|
The `init` command supports many options. See the `help` output for more details. For
|
|
instance, the following command creates a Gradle project that uses Java 8 and `war`
|
|
packaging:
|
|
|
|
[indent=0]
|
|
----
|
|
$ spring init --build=gradle --java-version=1.8 --dependencies=websocket --packaging=war sample-app.zip
|
|
Using service at https://start.spring.io
|
|
Content saved to 'sample-app.zip'
|
|
----
|
|
|
|
|
|
|
|
[[cli-shell]]
|
|
=== Using the Embedded Shell
|
|
Spring Boot includes command-line completion scripts for the BASH and zsh shells. If you
|
|
do not use either of these shells (perhaps you are a Windows user), you can use the
|
|
`shell` command to launch an integrated shell, as shown in the following example:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ spring shell
|
|
*Spring Boot* (v{spring-boot-version})
|
|
Hit TAB to complete. Type \'help' and hit RETURN for help, and \'exit' to quit.
|
|
----
|
|
|
|
From inside the embedded shell, you can run other commands directly:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ version
|
|
Spring CLI v{spring-boot-version}
|
|
----
|
|
|
|
The embedded shell supports ANSI color output as well as `tab` completion. If you need to
|
|
run a native command, you can use the `!` prefix. To exit the embedded shell, press
|
|
`ctrl-c`.
|
|
|
|
|
|
|
|
[[cli-install-uninstall]]
|
|
=== Adding Extensions to the CLI
|
|
You can add extensions to the CLI by using the `install` command. The command takes one
|
|
or more sets of artifact coordinates in the format `group:artifact:version`, as shown in
|
|
the following example:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ spring install com.example:spring-boot-cli-extension:1.0.0.RELEASE
|
|
----
|
|
|
|
In addition to installing the artifacts identified by the coordinates you supply, all of
|
|
the artifacts' dependencies are also installed.
|
|
|
|
To uninstall a dependency, use the `uninstall` command. As with the `install` command, it
|
|
takes one or more sets of artifact coordinates in the format of `group:artifact:version`,
|
|
as shown in the following example:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ spring uninstall com.example:spring-boot-cli-extension:1.0.0.RELEASE
|
|
----
|
|
|
|
It uninstalls the artifacts identified by the coordinates you supply and their
|
|
dependencies.
|
|
|
|
To uninstall all additional dependencies, you can use the `--all` option, as shown in the
|
|
following example:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ spring uninstall --all
|
|
----
|
|
|
|
|
|
|
|
[[cli-groovy-beans-dsl]]
|
|
== Developing Applications with the Groovy Beans DSL
|
|
Spring Framework 4.0 has native support for a `beans{}` "`DSL`" (borrowed from
|
|
http://grails.org/[Grails]), and you can embed bean definitions in your Groovy application
|
|
scripts by using the same format. This is sometimes a good way to include external
|
|
features like middleware declarations, as shown in the following example:
|
|
|
|
[source,groovy,indent=0]
|
|
----
|
|
@Configuration
|
|
class Application implements CommandLineRunner {
|
|
|
|
@Autowired
|
|
SharedService service
|
|
|
|
@Override
|
|
void run(String... args) {
|
|
println service.message
|
|
}
|
|
|
|
}
|
|
|
|
import my.company.SharedService
|
|
|
|
beans {
|
|
service(SharedService) {
|
|
message = "Hello World"
|
|
}
|
|
}
|
|
----
|
|
|
|
You can mix class declarations with `beans{}` in the same file as long as they stay at
|
|
the top level, or, if you prefer, you can put the beans DSL in a separate file.
|
|
|
|
|
|
|
|
[[cli-maven-settings]]
|
|
== Configuring the CLI with `settings.xml`
|
|
The Spring Boot CLI uses Aether, Maven's dependency resolution engine, to resolve
|
|
dependencies. The CLI makes use of the Maven configuration found in `~/.m2/settings.xml`
|
|
to configure Aether. The following configuration settings are honored by the CLI:
|
|
|
|
* Offline
|
|
* Mirrors
|
|
* Servers
|
|
* Proxies
|
|
* Profiles
|
|
** Activation
|
|
** Repositories
|
|
* Active profiles
|
|
|
|
See https://maven.apache.org/settings.html[Maven's settings documentation] for further
|
|
information.
|
|
|
|
|
|
|
|
[[cli-whats-next]]
|
|
== What to Read Next
|
|
There are some {github-code}/spring-boot-project/spring-boot-cli/samples[sample groovy
|
|
scripts] available from the GitHub repository that you can use to try out the Spring Boot
|
|
CLI. There is also extensive Javadoc throughout the {sc-spring-boot-cli}[source code].
|
|
|
|
If you find that you reach the limit of the CLI tool, you probably want to look at
|
|
converting your application to a full Gradle or Maven built "`Groovy project`". The
|
|
next section covers Spring Boot's "<<build-tool-plugins.adoc#build-tool-plugins, Build
|
|
tool plugins>>", which you can use with Gradle or Maven.
|