From 2ecd1164706ccd3a3ef927966b9a57a4ab2270c2 Mon Sep 17 00:00:00 2001 From: Jay Bryant Date: Mon, 30 Oct 2017 15:51:30 -0500 Subject: [PATCH 1/2] 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. From 56fde15fcbf09f4aad679ee291c7bb856cf31d0f Mon Sep 17 00:00:00 2001 From: Andy Wilkinson Date: Tue, 31 Oct 2017 12:51:18 +0000 Subject: [PATCH 2/2] Wrap build-tool-plugins.adoc at 90 characters Closes gh-10835 --- .../src/main/asciidoc/build-tool-plugins.adoc | 69 +++++++++---------- 1 file changed, 33 insertions(+), 36 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 2a7fe2e34d..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,10 +3,10 @@ [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. -- @@ -19,8 +19,8 @@ The {spring-boot-maven-plugin-site}/[Spring Boot Maven Plugin] provides Spring B 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: See 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. @@ -55,9 +55,9 @@ section of your `pom.xml`, as shown in the following example: ---- -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: +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] ---- @@ -68,8 +68,7 @@ original jar in the `target` directory: 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: +can run the plugin on its own (but only if the package goal is used as well). For example: [indent=0] ---- @@ -116,9 +115,9 @@ the usual `packaging` element, as shown in the following example: ---- 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 +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: @@ -156,8 +155,8 @@ following example: ---- -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]. @@ -166,10 +165,10 @@ 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, 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: +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]) @@ -181,8 +180,7 @@ later. Please refer to the plugin's documentation to learn more: == 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`, as shown in the following -example: +additional `spring-boot` namespace in your `build.xml`, as shown in the following example: [source,xml,indent=0] ---- @@ -206,8 +204,8 @@ 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: +Once the `spring-boot-antlib` namespace has been declared, the following additional tasks +are available: * <> * <> @@ -241,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. |==== @@ -344,8 +342,7 @@ To repackage an existing archive so that it becomes a self-contained executable 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. @@ -362,9 +359,9 @@ If your archive already includes libraries, you can use `Libraries.NONE`. [[build-tool-plugins-find-a-main-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. +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. @@ -391,7 +388,7 @@ The following listing shows a typical example repackage: == 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 +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