diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc index c90415ad5c8..faa1c00480d 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc @@ -3,27 +3,28 @@ [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 -a new project or write your own command for it. +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 can be installed manually; using SDKMAN! (the SDK Manager) -or using Homebrew or MacPorts if you are an OSX user. See -_<>_ -in the "`Getting started`" section for comprehensive installation instructions. +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 +_<>_ 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,18 @@ 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,31 +186,31 @@ 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 -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 -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 <>. +==== 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 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 <>. [[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 example above refers to `@Component`, -`@RestController` and `@RequestMapping` without needing to use -fully-qualified names or `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 will work without using `import` statements. Try running -your application to see what fails before adding imports. +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 +219,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` -annotation. The annotation's value should specify the coordinates -(`groupId:artifactId:version`) of one or more Maven BOMs. +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 +245,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 -`@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')`. +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. 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 +274,42 @@ to easily use multiple files from a single directory, e.g. [[cli-jar]] -=== Packaging your application -You can use the `jar` command to package your application into a self-contained -executable jar file. For example: +=== 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 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 +318,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 +347,9 @@ 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"] ---- @@ -373,16 +381,17 @@ From inside the embedded shell you can run other commands directly: 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. Hitting `ctrl-c` will exit the -embedded shell. +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 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: +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] ---- @@ -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,18 @@ 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 -further information. +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 -next section covers Spring Boot's -_<>_ that you can -use with Gradle or Maven. +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 "<>", which you can use with Gradle or Maven.