From 2ecd1164706ccd3a3ef927966b9a57a4ab2270c2 Mon Sep 17 00:00:00 2001 From: Jay Bryant Date: Mon, 30 Oct 2017 15:51:30 -0500 Subject: [PATCH] Edit build-tool-plugins.adoc See gh-10835 --- .../src/main/asciidoc/build-tool-plugins.adoc | 139 +++++++++--------- 1 file changed, 72 insertions(+), 67 deletions(-) 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..2a7fe2e34d 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 @@ -5,29 +5,29 @@ -- 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 +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] +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,9 @@ 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 +78,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 +98,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 +115,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 +129,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"] ---- @@ -163,9 +165,9 @@ 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 +== 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: @@ -176,10 +178,11 @@ 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 +193,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 +202,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 +=== Spring Boot Ant Tasks Once the `spring-boot-antlib` namespace has been declared, the following additional -tasks are available. +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"] @@ -273,11 +279,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,22 +326,21 @@ 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 @@ -345,27 +350,27 @@ 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 +=== 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 +388,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 formate 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.