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

Merge pull request #10835 from Jay Bryant 

* gh-10835:
  Wrap build-tool-plugins.adoc at 90 characters
  Edit build-tool-plugins.adoc
This commit is contained in:
Andy Wilkinson 2017-10-31 12:52:11 +00:00
parent c49afc3545 56fde15fcb
commit de080165ec
1 changed files with 88 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

174
spring-boot-project/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc
View File

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