247 lines
8.2 KiB
Plaintext
247 lines
8.2 KiB
Plaintext
[[build-tool-plugins]]
|
|
= Build Tool Plugins
|
|
include::attributes.adoc[]
|
|
|
|
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.
|
|
|
|
|
|
|
|
[[build-tool-plugins-maven-plugin]]
|
|
== Spring Boot Maven Plugin
|
|
The Spring Boot Maven Plugin provides Spring Boot 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).
|
|
|
|
Please refer to the plugin's documentation to learn more:
|
|
|
|
* Reference ({spring-boot-maven-plugin-docs}[HTML] and {spring-boot-maven-plugin-pdfdocs}[PDF])
|
|
* {spring-boot-maven-plugin-api}[API]
|
|
|
|
|
|
[[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 6 (6.3 or later).
|
|
Gradle 5.6.x is also supported but this support is deprecated and will be removed in a future release.
|
|
Please refer to the plugin's documentation to learn more:
|
|
|
|
* Reference ({spring-boot-gradle-plugin-docs}[HTML] and {spring-boot-gradle-plugin-pdfdocs}[PDF])
|
|
* {spring-boot-gradle-plugin-api}[API]
|
|
|
|
|
|
|
|
[[build-tool-plugins-antlib]]
|
|
== 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:
|
|
|
|
[source,xml,indent=0]
|
|
----
|
|
<project xmlns:ivy="antlib:org.apache.ivy.ant"
|
|
xmlns:spring-boot="antlib:org.springframework.boot.ant"
|
|
name="myapp" default="build">
|
|
...
|
|
</project>
|
|
----
|
|
|
|
You need to remember to start Ant using the `-lib` option, as shown in the following example:
|
|
|
|
[indent=0,subs="verbatim,quotes,attributes"]
|
|
----
|
|
$ ant -lib <folder containing spring-boot-antlib-{spring-boot-version}.jar>
|
|
----
|
|
|
|
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`>>.
|
|
|
|
|
|
|
|
[[spring-boot-ant-tasks]]
|
|
=== 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-ant-exejar]]
|
|
==== Using the "`exejar`" Task
|
|
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"]
|
|
|====
|
|
| Attribute | Description | Required
|
|
|
|
| `destfile`
|
|
| The destination jar file to create
|
|
| Yes
|
|
|
|
| `classes`
|
|
| The root directory of Java class files
|
|
| Yes
|
|
|
|
| `start-class`
|
|
| The main application class to run
|
|
| No _(the default is the first class found that declares a `main` method)_
|
|
|====
|
|
|
|
The following nested elements can be used with the task:
|
|
|
|
[cols="1,4"]
|
|
|====
|
|
| Element | Description
|
|
|
|
| `resources`
|
|
| One or more {ant-docs}/Types/resources.html#collection[Resource Collections] describing a set of {ant-docs}/Types/resources.html[Resources] that should be added to the content of the created +jar+ file.
|
|
|
|
| `lib`
|
|
| One or more {ant-docs}/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.
|
|
|====
|
|
|
|
|
|
|
|
|
|
[[spring-boot-ant-exejar-examples]]
|
|
==== Examples
|
|
This section shows two examples of Ant tasks.
|
|
|
|
.Specify +start-class+
|
|
[source,xml,indent=0]
|
|
----
|
|
<spring-boot:exejar destfile="target/my-application.jar"
|
|
classes="target/classes" start-class="com.example.MyApplication">
|
|
<resources>
|
|
<fileset dir="src/main/resources" />
|
|
</resources>
|
|
<lib>
|
|
<fileset dir="lib" />
|
|
</lib>
|
|
</spring-boot:exejar>
|
|
----
|
|
|
|
.Detect +start-class+
|
|
[source,xml,indent=0]
|
|
----
|
|
<exejar destfile="target/my-application.jar" classes="target/classes">
|
|
<lib>
|
|
<fileset dir="lib" />
|
|
</lib>
|
|
</exejar>
|
|
----
|
|
|
|
|
|
|
|
[[spring-boot-ant-findmainclass]]
|
|
=== Using the "`findmainclass`" Task
|
|
The `findmainclass` task is used internally by `exejar` to locate a class declaring a `main`.
|
|
If necessary, you can also use this task directly in your build.
|
|
The following attributes are supported:
|
|
|
|
[cols="1,2,2"]
|
|
|====
|
|
| Attribute | Description | Required
|
|
|
|
| `classesroot`
|
|
| The root directory of Java class files
|
|
| Yes _(unless `mainclass` is specified)_
|
|
|
|
| `mainclass`
|
|
| Can be used to short-circuit the `main` class search
|
|
| No
|
|
|
|
| `property`
|
|
| The Ant property that should be set with the result
|
|
| No _(result will be logged if unspecified)_
|
|
|====
|
|
|
|
|
|
|
|
[[spring-boot-ant-findmainclass-examples]]
|
|
==== Examples
|
|
This section contains three examples of using `findmainclass`.
|
|
|
|
.Find and log
|
|
[source,xml,indent=0]
|
|
----
|
|
<findmainclass classesroot="target/classes" />
|
|
----
|
|
|
|
.Find and set
|
|
[source,xml,indent=0]
|
|
----
|
|
<findmainclass classesroot="target/classes" property="main-class" />
|
|
----
|
|
|
|
.Override and set
|
|
[source,xml,indent=0]
|
|
----
|
|
<findmainclass mainclass="com.example.MainClass" property="main-class" />
|
|
----
|
|
|
|
|
|
|
|
[[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 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 in the appendix for details).
|
|
|
|
The Spring Boot Maven and Gradle plugins both make use of `spring-boot-loader-tools` 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, 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.
|
|
|
|
|
|
|
|
[[build-tool-plugins-nested-libraries]]
|
|
=== 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`.
|
|
|
|
|
|
|
|
[[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 https://asm.ow2.io/[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
|
|
The following example shows a typical repackage implementation:
|
|
|
|
[source,java,indent=0]
|
|
----
|
|
Repackager repackager = new Repackager(sourceJarFile);
|
|
repackager.setBackupSource(false);
|
|
repackager.repackage(new Libraries() {
|
|
@Override
|
|
public void doWithLibraries(LibraryCallback callback) throws IOException {
|
|
// Build system specific implementation, callback for each dependency
|
|
// callback.library(new Library(nestedFile, LibraryScope.COMPILE));
|
|
}
|
|
});
|
|
----
|
|
|
|
|
|
|
|
[[build-tool-plugins-whats-next]]
|
|
== What to Read Next
|
|
If you are interested in how the build tool plugins work, you can look at the {spring-boot-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#executable-jar,the appendix>>.
|
|
|
|
If you have specific build-related questions, you can check out the "`<<howto.adoc#howto, how-to>>`" guides.
|