root
/
spring-boot
mirror of https://github.com/spring-projects/spring-boot.git
1
0
Fork 0
Code Issues Actions 4 Packages Projects Releases Wiki Activity

Edit spring-boot-cli.adoc 

See gh-10834
This commit is contained in:
Jay Bryant 2017-10-30 15:24:10 -05:00 committed by Andy Wilkinson
parent cf64580c87
commit f0901343bd
1 changed files with 106 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

202
spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc
View File

@ -3,9 +3,9 @@
[partintro]
--
The Spring Boot CLI is a command line tool that can be used if you want to quickly
develop with Spring. It allows you to run Groovy scripts, which means that you have a
familiar Java-like syntax, without so much boilerplate code. You can also bootstrap
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.
--
@ -13,8 +13,8 @@ a new project or write your own command for it.
[[cli-installation]]
== Installing the CLI
The Spring Boot CLI can be installed manually; using SDKMAN! (the SDK Manager)
or using Homebrew or MacPorts if you are an OSX user. See
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.
@ -22,8 +22,9 @@ 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`. If you run `spring`
without any arguments, a simple help screen is displayed:
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"]
----
@ -39,7 +40,8 @@ without any arguments, a simple help screen is displayed:
_... more command help is shown here_
----
You can use `help` to get more details about any of the supported commands. For example:
You can type `spring help` to get more details about any of the supported commands, as
shown in the following example:
[indent=0]
----
@ -64,7 +66,7 @@ You can use `help` to get more details about any of the supported commands. For
----
The `version` command provides a quick way to check which version of Spring Boot you are
using.
using, as follows:
[indent=0,subs="verbatim,quotes,attributes"]
----
@ -75,11 +77,11 @@ using.
[[cli-run]]
=== Running applications using the CLI
You can compile and run Groovy source code using the `run` command. The Spring Boot CLI
is completely self-contained so you don't need any external Groovy installation.
=== 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 don't need any external Groovy installation.
Here is an example "`hello world`" web application written in Groovy:
The following example shows a "`hello world`" web application written in Groovy:
.hello.groovy
[source,groovy,indent=0,subs="verbatim,quotes,attributes"]
@ -95,22 +97,23 @@ Here is an example "`hello world`" web application written in Groovy:
}
----
To compile and run the application type:
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, you need to use a `--` to separate
them from the "`spring`" command arguments, e.g.
To pass command-line arguments to the application, use a `--` 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, e.g.
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"]
----
@ -118,18 +121,19 @@ To set JVM command line arguments you can use the `JAVA_OPTS` environment variab
----
NOTE: When setting `JAVA_OPTS` on Microsoft Windows, make sure to quote the entire
instruction such as `set "JAVA_OPTS=-Xms256m -Xmx2048m"`. This will ensure the values
are passed properly to the process.
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 allows you to declare dependencies
on a third-party libraries. This useful technique allows Groovy to download jars in the
same way as Maven or Gradle would, but without requiring you to use a build tool.
==== 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 will attempt to deduce which libraries
to "`grab`" based on your code. For example, since the `WebApplication` code above uses
`@RestController` annotations, "`Tomcat`" and "`Spring MVC`" will be grabbed.
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`":
@ -183,11 +187,11 @@ in the Spring Boot CLI source code to understand exactly how customizations are
[[cli-default-grab-deduced-coordinates]]
==== Deduced "`grab`" coordinates
Spring Boot extends Groovy's standard `@Grab` support by allowing you to specify a dependency
without a group or version, for example `@Grab('freemarker')`. This will consult Spring Boot's
==== 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 that the default
metadata is tied to the version of the CLI that you're using – it will only change when you move
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>>.
@ -195,19 +199,19 @@ metadata can be found in the <<appendix-dependency-versions, appendix>>.
[[cli-default-import-statements]]
==== Default import statements
==== Default Import Statements
To help reduce the size of your Groovy code, several `import` statements are
automatically included. Notice how the example above refers to `@Component`,
`@RestController` and `@RequestMapping` without needing to use
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 will work without using `import` statements. Try running
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
==== 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
@ -216,25 +220,25 @@ Unlike the equivalent Java application, you do not need to include a
[[cli-default-grab-deduced-coordinates-custom-dependency-management]]
==== 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, that will override
the default dependency management, can be configured using the `@DependencyManagementBom`
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, the following declaration:
For example, consider the following declaration:
[source,groovy,indent=0]
----
@DependencyManagementBom("com.example.custom-bom:1.0.0")
----
Will pick up `custom-bom-1.0.0.pom` in a Maven repository under
The preceding declaration picks up `custom-bom-1.0.0.pom` in a Maven repository under
`com/example/custom-versions/1.0.0/`.
When multiple BOMs are specified they are applied in the order that they're declared.
For example:
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]
----
@ -242,22 +246,26 @@ For example:
"com.example.another-bom:1.0.0"])
----
indicates that dependency management in `another-bom` will override the dependency
management in `custom-bom`.
The preceding example indicates that 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 only use
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 (that is a superset of Spring Boot's dependency management) is the
http://platform.spring.io/[Spring IO Platform], e.g.
`@DependencyManagementBom('io.spring.platform:platform-bom:1.1.2.RELEASE')`.
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. This allows you
to easily use multiple files from a single directory, e.g.
=== 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]
----
@ -267,42 +275,42 @@ to easily use multiple files from a single directory, e.g.
[[cli-jar]]
=== Packaging your application
=== Packaging Your Application
You can use the `jar` command to package your application into a self-contained
executable jar file. For example:
executable jar file, as shown in the following example:
[indent=0]
----
$ spring jar my-app.jar *.groovy
----
The resulting jar will contain the classes produced by compiling the application and all
of the application's dependencies so that it can then be run using `java -jar`. The jar
file will also contain entries from the application's classpath. You can add explicit
paths to the jar using `--include` and `--exclude` (both are comma-separated, and both
accept prefixes to the values "`+`" and "`-`" to signify that they should be removed from
the defaults). The default includes are
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 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/**, *
----
and the default excludes are
The default excludes are as follows:
[indent=0]
----
.*, repository/**, build/**, target/**, **/*.jar, **/*.groovy
----
See the output of `spring help jar` for more information.
Type `spring help jar` on the command line for more information.
[[cli-init]]
=== Initialize a new project
The `init` command allows you to create a new project using https://start.spring.io
without leaving the shell. For example:
=== 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]
----
@ -311,9 +319,9 @@ without leaving the shell. For example:
Project extracted to '/Users/developer/example/my-project'
----
This creates a `my-project` directory with a Maven-based project using
`spring-boot-starter-web` and `spring-boot-starter-data-jpa`. You can list the
capabilities of the service using the `--list` flag
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]
----
@ -340,8 +348,8 @@ capabilities of the service using the `--list` flag
...
----
The `init` command supports many options, check the `help` output for more details. For
instance, the following command creates a gradle project using Java 8 and `war` packaging:
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]
----
@ -353,10 +361,10 @@ instance, the following command creates a gradle project using Java 8 and `war`
[[cli-shell]]
=== Using the embedded shell
Spring Boot includes command-line completion scripts for BASH and zsh shells. If you
don't use either of these shells (perhaps you are a Windows user) then you can use the
`shell` command to launch an integrated 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"]
----
@ -365,7 +373,7 @@ don't use either of these shells (perhaps you are a Windows user) then you can u
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:
From inside the embedded shell, you can run other commands directly:
[indent=0,subs="verbatim,quotes,attributes"]
----
@ -374,15 +382,16 @@ From inside the embedded shell you can run other commands directly:
----
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. Hitting `ctrl-c` will exit the
embedded shell.
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 using the `install` command. The command takes one
or more sets of artifact coordinates in the format `group:artifact:version`. For example:
=== 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"]
----
@ -390,21 +399,22 @@ or more sets of artifact coordinates in the format `group:artifact:version`. For
----
In addition to installing the artifacts identified by the coordinates you supply, all of
the artifacts' dependencies will also be installed.
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 `group:artifact:version`.
For example:
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 `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 will uninstall the artifacts identified by the coordinates you supply and their
It uninstalls the artifacts identified by the coordinates you supply and their
dependencies.
To uninstall all additional dependencies you can use the `--all` option. For example:
To uninstall all additional dependencies, you can use the `--all` option, as shown in the
following example:
[indent=0,subs="verbatim,quotes,attributes"]
----
@ -414,11 +424,11 @@ To uninstall all additional dependencies you can use the `--all` option. For exa
[[cli-groovy-beans-dsl]]
== Developing application with the 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 using the same format. This is sometimes a good way to include
external features like middleware declarations. For example:
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]
----
@ -445,12 +455,12 @@ external features like middleware declarations. For example:
----
You can mix class declarations with `beans{}` in the same file as long as they stay at
the top level, or you can put the beans DSL in a separate file if you prefer.
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
== 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:
@ -464,20 +474,20 @@ to configure Aether. The following configuration settings are honored by the CLI
** Repositories
* Active profiles
Please refer to https://maven.apache.org/settings.html[Maven's settings documentation] for
See https://maven.apache.org/settings.html[Maven's settings documentation] for
further information.
[[cli-whats-next]]
== What to read 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 will probably want to look
at converting your application to full Gradle or Maven built "`groovy project`". The
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>>_ that you can
"<<build-tool-plugins.adoc#build-tool-plugins, Build tool plugins>>", which you can
use with Gradle or Maven.