diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc index c9b0699713..a6c5fd96fa 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc @@ -3,31 +3,31 @@ [partintro] -- -Spring Boot provides build tool plugins for Maven and Gradle. The plugins offer a -variety of features, including the packaging of executable jars. This section provides -more details on both plugins, as well as some help should you need to extend an -unsupported build system. If you are just getting started, you might want to read +Spring Boot provides build tool plugins for Maven and Gradle. The plugins offer a variety +of features, including the packaging of executable jars. This section provides more +details on both plugins as well as some help should you need to extend an unsupported +build system. If you are just getting started, you might want to read "`<>`" from the -<> section first. +"`<>`" section first. -- [[build-tool-plugins-maven-plugin]] -== Spring Boot Maven plugin +== Spring Boot Maven Plugin The {spring-boot-maven-plugin-site}/[Spring Boot Maven Plugin] provides Spring Boot -support in Maven, allowing you to package executable jar or war archives and run an -application "`in-place`". To use it you must be using Maven 3.2 (or better). +support in Maven, letting you package executable jar or war archives and run an +application "`in-place`". To use it, you must use Maven 3.2 (or later). -NOTE: Refer to the {spring-boot-maven-plugin-site}/[Spring Boot Maven Plugin Site] -for complete plugin documentation. +NOTE: See the {spring-boot-maven-plugin-site}/[Spring Boot Maven Plugin Site] for complete +plugin documentation. [[build-tool-plugins-include-maven-plugin]] -=== Including the plugin -To use the Spring Boot Maven Plugin simply include the appropriate XML in the `plugins` -section of your `pom.xml` +=== Including the Plugin +To use the Spring Boot Maven Plugin, include the appropriate XML in the `plugins` +section of your `pom.xml`, as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- @@ -55,9 +55,9 @@ section of your `pom.xml` ---- -This configuration will repackage a jar or war that is built during the `package` phase of -the Maven lifecycle. The following example shows both the repackaged jar, as well as the -original jar, in the `target` directory: +The preceding configuration repackages a jar or war that is built during the `package` +phase of the Maven lifecycle. The following example shows both the repackaged jar as well +as the original jar in the `target` directory: [indent=0] ---- @@ -67,8 +67,8 @@ original jar, in the `target` directory: ---- -If you don't include the `` configuration as above, you can run the plugin on -its own (but only if the package goal is used as well). For example: +If you do not include the `` configuration as shown in the prior example, you +can run the plugin on its own (but only if the package goal is used as well). For example: [indent=0] ---- @@ -77,8 +77,8 @@ its own (but only if the package goal is used as well). For example: target/myproject-1.0.0.jar target/myproject-1.0.0.jar.original ---- -If you are using a milestone or snapshot release you will also need to add appropriate -`pluginRepository` elements: +If you use a milestone or snapshot release, you also need to add the appropriate +`pluginRepository` elements as shown in the following listing: [source,xml,indent=0,subs="verbatim,attributes"] ---- @@ -97,11 +97,11 @@ If you are using a milestone or snapshot release you will also need to add appro [[build-tool-plugins-maven-packaging]] -=== Packaging executable jar and war files -Once `spring-boot-maven-plugin` has been included in your `pom.xml` it will automatically -attempt to rewrite archives to make them executable using the `spring-boot:repackage` -goal. You should configure your project to build a jar or war (as appropriate) using the -usual `packaging` element: +=== Packaging Executable Jar and War Files +Once `spring-boot-maven-plugin` has been included in your `pom.xml`, it automatically +tries to rewrite archives to make them executable by using the `spring-boot:repackage` +goal. You should configure your project to build a jar or war (as appropriate) by using +the usual `packaging` element, as shown in the following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- @@ -114,10 +114,10 @@ usual `packaging` element: ---- -Your existing archive will be enhanced by Spring Boot during the `package` phase. The -main class that you want to launch can either be specified using a configuration option, -or by adding a `Main-Class` attribute to the manifest in the usual way. If you don't -specify a main class the plugin will search for a class with a +Your existing archive is enhanced by Spring Boot during the `package` phase. The main +class that you want to launch can either be specified by using a configuration option or +by adding a `Main-Class` attribute to the manifest in the usual way. If you do not specify +a main class, the plugin searches for a class with a `public static void main(String[] args)` method. To build and run a project artifact, you can type the following: @@ -128,8 +128,9 @@ To build and run a project artifact, you can type the following: $ java -jar target/mymodule-0.0.1-SNAPSHOT.jar ---- -To build a war file that is both executable and deployable into an external container you -need to mark the embedded container dependencies as "`provided`", e.g: +To build a war file that is both executable and deployable into an external container, you +need to mark the embedded container dependencies as "`provided`", as shown in the +following example: [source,xml,indent=0,subs="verbatim,attributes"] ---- @@ -154,8 +155,8 @@ need to mark the embedded container dependencies as "`provided`", e.g: ---- -TIP: See the "`<>`" section for more details on -how to create a deployable war file. +TIP: See the "`<>`" section for more details on how to +create a deployable war file. Advanced configuration options and examples are available in the {spring-boot-maven-plugin-site}/[plugin info page]. @@ -163,11 +164,11 @@ Advanced configuration options and examples are available in the [[build-tool-plugins-gradle-plugin]] -== Spring Boot Gradle plugin -The Spring Boot Gradle Plugin provides Spring Boot support in Gradle, allowing you to -package executable jar or war archives, run Spring Boot applications and use the -dependency management provided by `spring-boot-dependencies`. It requires Gradle 4.0 or -later. Please refer to the plugin's documentation to learn more: +== Spring Boot Gradle Plugin +The Spring Boot Gradle Plugin provides Spring Boot support in Gradle, letting you package +executable jar or war archives, run Spring Boot applications, and use the dependency +management provided by `spring-boot-dependencies`. It requires Gradle 4.0 or later. Please +refer to the plugin's documentation to learn more: * Reference ({spring-boot-gradle-plugin}/reference/html[HTML] and {spring-boot-gradle-plugin}/reference/pdf/spring-boot-gradle-plugin-reference.pdf[PDF]) @@ -176,10 +177,10 @@ later. Please refer to the plugin's documentation to learn more: [[build-tool-plugins-antlib]] -== Spring Boot AntLib module +== Spring Boot AntLib Module The Spring Boot AntLib module provides basic Spring Boot support for Apache Ant. You can -use the module to create executable jars. To use the module you need to declare an -additional `spring-boot` namespace in your `build.xml`: +use the module to create executable jars. To use the module, you need to declare an +additional `spring-boot` namespace in your `build.xml`, as shown in the following example: [source,xml,indent=0] ---- @@ -190,7 +191,8 @@ additional `spring-boot` namespace in your `build.xml`: ---- -You'll need to remember to start Ant using the `-lib` option, for example: +You need to remember to start Ant using the `-lib` option, as shown in the following +example: [indent=0,subs="verbatim,quotes,attributes"] ---- @@ -198,17 +200,19 @@ You'll need to remember to start Ant using the `-lib` option, for example: ---- TIP: The "`Using Spring Boot`" section includes a more complete example of -<> +<>. -=== Spring Boot Ant tasks -Once the `spring-boot-antlib` namespace has been declared, the following additional -tasks are available. +=== Spring Boot Ant Tasks +Once the `spring-boot-antlib` namespace has been declared, the following additional tasks +are available: +* <> +* <> - -==== spring-boot:exejar -The `exejar` task can be used to creates a Spring Boot executable jar. The following +[[spring-boot-ant-exejar]] +==== `spring-boot:exejar` +You can use the `exejar` task to create a Spring Boot executable jar. The following attributes are supported by the task: [cols="1,2,2"] @@ -235,14 +239,14 @@ The following nested elements can be used with the task: |Element |Description |`resources` -|One or more {ant-manual}/Types/resources.html#collection[Resource Collections] -describing a set of {ant-manual}/Types/resources.html[Resources] that should be added to -the content of the created +jar+ file. +|One or more {ant-manual}/Types/resources.html#collection[Resource Collections] describing +a set of {ant-manual}/Types/resources.html[Resources] that should be added to the content +of the created +jar+ file. |`lib` -|One or more {ant-manual}/Types/resources.html#collection[Resource Collections] -that should be added to the set of jar libraries that make up the runtime dependency -classpath of the application. +|One or more {ant-manual}/Types/resources.html#collection[Resource Collections] that +should be added to the set of jar libraries that make up the runtime dependency classpath +of the application. |==== @@ -273,11 +277,11 @@ classpath of the application. ---- - -=== spring-boot:findmainclass +[[spring-boot-ant-findmainclass]] +=== `spring-boot:findmainclass` The `findmainclass` task is used internally by `exejar` to locate a class declaring a -`main`. You can also use this task directly in your build if needed. The following -attributes are supported +`main`. You can also use this task directly in your build, if needed. The following +attributes are supported: [cols="1,2,2"] |==== @@ -320,52 +324,50 @@ attributes are supported [[build-tool-plugins-other-build-systems]] -== Supporting other build systems -If you want to use a build tool other than Maven, Gradle or Ant, you will likely need to +== Supporting Other Build Systems +If you want to use a build tool other than Maven, Gradle, or Ant, you likely need to develop your own plugin. Executable jars need to follow a specific format and certain entries need to be written in an uncompressed form (see the -_<>_ section +"`<>`" section in the appendix for details). The Spring Boot Maven and Gradle plugins both make use of `spring-boot-loader-tools` to -actually generate jars. You are also free to use this library directly yourself if you -need to. +actually generate jars. If you need to, you may use this library directly. [[build-tool-plugins-repackaging-archives]] -=== Repackaging archives -To repackage an existing archive so that it becomes a self-contained executable archive +=== Repackaging Archives +To repackage an existing archive so that it becomes a self-contained executable archive, use `org.springframework.boot.loader.tools.Repackager`. The `Repackager` class takes a single constructor argument that refers to an existing jar or war archive. Use one of the two available `repackage()` methods to either replace the original file or write to a new -destination. Various settings can also be configured on the repackager before it is -run. +destination. Various settings can also be configured on the repackager before it is run. [[build-tool-plugins-nested-libraries]] -=== Nested libraries -When repackaging an archive you can include references to dependency files using the -`org.springframework.boot.loader.tools.Libraries` interface. We don't provide any -concrete implementations of `Libraries` here as they are usually build system specific. +=== Nested Libraries +When repackaging an archive, you can include references to dependency files by using the +`org.springframework.boot.loader.tools.Libraries` interface. We do not provide any +concrete implementations of `Libraries` here as they are usually build-system-specific. -If your archive already includes libraries you can use `Libraries.NONE`. +If your archive already includes libraries, you can use `Libraries.NONE`. [[build-tool-plugins-find-a-main-class]] -=== Finding a main class -If you don't use `Repackager.setMainClass()` to specify a main class, the repackager will -use http://asm.ow2.org/[ASM] to read class files and attempt to find a suitable class -with a `public static void main(String[] args)` method. An exception is thrown if more -than one candidate is found. +=== Finding a Main Class +If you do not use `Repackager.setMainClass()` to specify a main class, the repackager +uses http://asm.ow2.org/[ASM] to read class files and tries to find a suitable class with +a `public static void main(String[] args)` method. An exception is thrown if more than one +candidate is found. [[build-tool-plugins-repackage-implementation]] -=== Example repackage implementation -Here is a typical example repackage: +=== Example Repackage Implementation +The following listing shows a typical example repackage: [source,java,indent=0] ---- @@ -383,11 +385,11 @@ Here is a typical example repackage: [[build-tool-plugins-whats-next]] -== What to read next -If you're interested in how the build tool plugins work you can -look at the {github-code}/spring-boot-project/spring-boot-tools[`spring-boot-tools`] module on GitHub. More -technical details of the <> are covered in the appendix. +== What to Read Next +If you are interested in how the build tool plugins work, you can +look at the {github-code}/spring-boot-project/spring-boot-tools[`spring-boot-tools`] +module on GitHub. More technical details of the executable jar format are covered in +<>. -If you have specific build-related questions you can check out the +If you have specific build-related questions, you can check out the "`<>`" guides.