mirror of
https://github.com/spring-projects/spring-boot.git
synced 2024-08-29 03:06:45 +08:00
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
commit
de080165ec
@ -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
|
||||
"`<<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]]
|
||||
== 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`
|
||||
</project>
|
||||
----
|
||||
|
||||
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 `<execution/>` 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 `<execution/>` 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:
|
||||
</project>
|
||||
----
|
||||
|
||||
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:
|
||||
</project>
|
||||
----
|
||||
|
||||
TIP: See the "`<<howto-create-a-deployable-war-file>>`" section for more details on
|
||||
how to create a deployable war file.
|
||||
TIP: See the "`<<howto-create-a-deployable-war-file>>`" 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`:
|
||||
</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"]
|
||||
----
|
||||
@ -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
|
||||
<<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
|
||||
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-ant-exejar>>
|
||||
* <<spring-boot-ant-findmainclass>>
|
||||
|
||||
|
||||
==== 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
|
||||
_<<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).
|
||||
|
||||
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 <<appendix-executable-jar-format.adoc#executable-jar, executable
|
||||
jar format>> 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
|
||||
<<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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user