Split up adoc files
Closes gh-23254
This commit is contained in:
Phillip Webb
@@ -0,0 +1,148 @@
|
||||
[[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 <directory containing spring-boot-antlib-{spring-boot-version}.jar>
|
||||
----
|
||||
|
||||
TIP: The "`Using Spring Boot`" section includes a more complete example of <<using#using.build-systems.ant, using Apache Ant with `spring-boot-antlib`>>.
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.antlib.tasks]]
|
||||
=== Spring Boot Ant Tasks
|
||||
Once the `spring-boot-antlib` namespace has been declared, the following additional tasks are available:
|
||||
|
||||
* <<build-tool-plugins#build-tool-plugins.antlib.tasks.exejar>>
|
||||
* <<build-tool-plugins#build-tool-plugins.antlib.findmainclass>>
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.antlib.tasks.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.
|
||||
|====
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.antlib.tasks.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>
|
||||
----
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.antlib.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)_
|
||||
|====
|
||||
|
||||
|
||||
|
||||
[[build-tool-plugins.antlib.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" />
|
||||
----
|
||||
@@ -0,0 +1,8 @@
|
||||
[[build-tool-plugins.gradle]]
|
||||
== 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.8 or 7.x.
|
||||
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]
|
||||
@@ -0,0 +1,9 @@
|
||||
[[build-tool-plugins.maven]]
|
||||
== 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]
|
||||
@@ -0,0 +1,51 @@
|
||||
[[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 "`<<executable-jar#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.other-build-systems.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.other-build-systems.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.other-build-systems.finding-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.other-build-systems.example-repackage-implementation]]
|
||||
=== Example Repackage Implementation
|
||||
The following example shows a typical repackage implementation:
|
||||
|
||||
[source,java,pending-extract=true,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));
|
||||
}
|
||||
});
|
||||
----
|
||||
@@ -0,0 +1,6 @@
|
||||
[[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 <<executable-jar#executable-jar,the appendix>>.
|
||||
|
||||
If you have specific build-related questions, you can check out the "`<<howto#howto, how-to>>`" guides.
|
||||
Reference in New Issue
Block a user