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.html” from the “using.html” section first.

1. 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).

See the plugin’s documentation to learn more:

2. 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 7.x (7.5 or later). See the plugin’s documentation to learn more:

3. 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:

<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:

$ ant -lib <directory containing spring-boot-antlib-3.0.3.jar>
The “Using Spring Boot” section includes a more complete example of using Apache Ant with spring-boot-antlib.

3.1. Spring Boot Ant Tasks

Once the spring-boot-antlib namespace has been declared, the following additional tasks are available:

3.1.1. 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:

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:

Element Description

resources

One or more Resource Collections describing a set of Resources that should be added to the content of the created jar file.

lib

One or more Resource Collections that should be added to the set of jar libraries that make up the runtime dependency classpath of the application.

3.1.2. Examples

This section shows two examples of Ant tasks.

Specify start-class
<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
<exejar destfile="target/my-application.jar" classes="target/classes">
    <lib>
        <fileset dir="lib" />
    </lib>
</exejar>

3.2. 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:

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)

3.2.1. Examples

This section contains three examples of using findmainclass.

Find and log
<findmainclass classesroot="target/classes" />
Find and set
<findmainclass classesroot="target/classes" property="main-class" />
Override and set
<findmainclass mainclass="com.example.MainClass" property="main-class" />

4. 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 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.

4.1. 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.

4.2. 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.

4.3. Finding a Main Class

If you do not use Repackager.setMainClass() to specify a main class, the repackager uses 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.

4.4. Example Repackage Implementation

The following example shows a typical repackage implementation:

Java
import java.io.File;
import java.io.IOException;
import java.util.List;

import org.springframework.boot.loader.tools.Library;
import org.springframework.boot.loader.tools.LibraryCallback;
import org.springframework.boot.loader.tools.LibraryScope;
import org.springframework.boot.loader.tools.Repackager;

public class MyBuildTool {

    public void build() throws IOException {
        File sourceJarFile = ...
        Repackager repackager = new Repackager(sourceJarFile);
        repackager.setBackupSource(false);
        repackager.repackage(this::getLibraries);
    }

    private void getLibraries(LibraryCallback callback) throws IOException {
        // Build system specific implementation, callback for each dependency
        for (File nestedJar : getCompileScopeJars()) {
            callback.library(new Library(nestedJar, LibraryScope.COMPILE));
        }
        // ...
    }

    private List<File> getCompileScopeJars() {
        return ...
    }

}
Kotlin
import org.springframework.boot.loader.tools.Library
import org.springframework.boot.loader.tools.LibraryCallback
import org.springframework.boot.loader.tools.LibraryScope
import org.springframework.boot.loader.tools.Repackager
import java.io.File
import java.io.IOException

class MyBuildTool {

    @Throws(IOException::class)
    fun build() {
        val sourceJarFile: File? =  ...
        val repackager = Repackager(sourceJarFile)
        repackager.setBackupSource(false)
        repackager.repackage { callback: LibraryCallback -> getLibraries(callback) }
    }

    @Throws(IOException::class)
    private fun getLibraries(callback: LibraryCallback) {
        // Build system specific implementation, callback for each dependency
        for (nestedJar in getCompileScopeJars()!!) {
            callback.library(Library(nestedJar, LibraryScope.COMPILE))
        }
        // ...
    }

    private fun getCompileScopeJars(): List<File?>? {
        return  ...
    }

}

5. What to Read Next

If you are interested in how the build tool plugins work, you can look at the spring-boot-tools module on GitHub. More technical details of the executable jar format are covered in the appendix.

If you have specific build-related questions, see the “how-to” guides.