mirror of
https://github.com/spring-projects/spring-boot.git
synced 2024-09-03 04:26:12 +08:00
Rework title anchors for maven docs
Closes gh-26617
This commit is contained in:
Phillip Webb
parent
1702c9fc3d
commit
f0896c2de6
@ -94,7 +94,7 @@ public class DocumentPluginGoals extends DefaultTask {
|
||||
writer.println();
|
||||
writer.println();
|
||||
writer.printf("[[%s]]%n", sectionId);
|
||||
writer.printf("== `%s:%s`%n", plugin.getGoalPrefix(), mojo.getGoal());
|
||||
writer.printf("= `%s:%s`%n", plugin.getGoalPrefix(), mojo.getGoal());
|
||||
writer.printf("`%s:%s:%s`%n", plugin.getGroupId(), plugin.getArtifactId(), plugin.getVersion());
|
||||
writer.println();
|
||||
writer.println(mojo.getDescription());
|
||||
@ -108,7 +108,7 @@ public class DocumentPluginGoals extends DefaultTask {
|
||||
writer.println();
|
||||
writer.println();
|
||||
writer.printf("[[%s-required]]%n", parametersSectionId);
|
||||
writer.println("=== Required parameters");
|
||||
writer.println("== Required parameters");
|
||||
writeParametersTable(writer, detailsSectionId, requiredParameters);
|
||||
}
|
||||
List<Parameter> optionalParameters = parameters.stream().filter((parameter) -> !parameter.isRequired())
|
||||
@ -117,13 +117,13 @@ public class DocumentPluginGoals extends DefaultTask {
|
||||
writer.println();
|
||||
writer.println();
|
||||
writer.printf("[[%s-optional]]%n", parametersSectionId);
|
||||
writer.println("=== Optional parameters");
|
||||
writer.println("== Optional parameters");
|
||||
writeParametersTable(writer, detailsSectionId, optionalParameters);
|
||||
}
|
||||
writer.println();
|
||||
writer.println();
|
||||
writer.printf("[[%s]]%n", detailsSectionId);
|
||||
writer.println("=== Parameter details");
|
||||
writer.println("== Parameter details");
|
||||
writeParameterDetails(writer, parameters, detailsSectionId);
|
||||
}
|
||||
}
|
||||
@ -155,7 +155,7 @@ public class DocumentPluginGoals extends DefaultTask {
|
||||
writer.println();
|
||||
writer.println();
|
||||
writer.printf("[[%s-%s]]%n", sectionId, name);
|
||||
writer.printf("==== `%s`%n", name);
|
||||
writer.printf("=== `%s`%n", name);
|
||||
writer.println(parameter.getDescription());
|
||||
writer.println();
|
||||
writer.println("[cols=\"10h,90\"]");
|
||||
|
||||
@ -0,0 +1,46 @@
|
||||
|
||||
build-info=?
|
||||
getting-started=?
|
||||
goals=?
|
||||
help=?
|
||||
spring-boot-maven-plugin-documentation=?
|
||||
introduction=?.?
|
||||
integration-tests=integration-tests
|
||||
integration-tests-no-starter-parent=integration-tests.no-starter-parent
|
||||
integration-tests-example=integration-tests.examples
|
||||
integration-tests-example-random-port=integration-tests.examples.random-port
|
||||
integration-tests-example-jmx-port=integration-tests.examples.jmx-port
|
||||
integration-tests-example-skip=integration-tests.examples.skip
|
||||
build-image=build-image
|
||||
build-image-docker-daemon=build-image.docker-daemon
|
||||
build-image-docker-registry=build-image.docker-registry
|
||||
build-image-customization=build-image.customization
|
||||
build-image-examples=build-image.examples
|
||||
build-image-example-custom-image-builder=build-image.examples.custom-image-builder
|
||||
build-image-example-builder-configuration=build-image.examples.builder-configuration
|
||||
build-image-example-runtime-jvm-configuration=build-image.examples.runtime-jvm-configuration
|
||||
build-image-example-custom-image-name=build-image.examples.custom-image-name
|
||||
build-image-example-buildpacks=build-image.examples.buildpacks
|
||||
build-image-example-publish=build-image.examples.publish
|
||||
build-image-example-docker=build-image.examples.docker
|
||||
repackage=packaging
|
||||
repackage-layers=packaging.layers
|
||||
repackage-layers-configuration=packaging.layers.configuration=repackage-examples=packaging.examples
|
||||
repackage-example-custom-classifier=packaging.examples.custom-classifier
|
||||
repackage-example-custom-name=packaging.examples.custom-name
|
||||
repackage-example-local-artifact=packaging.examples.local-artifact
|
||||
repackage-example-custom-layout=packaging.examples.custom-layout
|
||||
repackage-example-exclude-dependency=packaging.examples.exclude-dependency
|
||||
repackage-layered-archive-tools=packaging.examples.layered-archive-tools
|
||||
repackage-layered-archive-additional-layers=packaging.examples.custom-layers-configuration
|
||||
run=run
|
||||
run-examples=run.examples
|
||||
run-example-debug=run.examples.debug
|
||||
run-example-system-properties=run.examples.system-properties
|
||||
run-example-environment-variables=run.examples.environment-variables
|
||||
run-example-application-arguments=run.examples.using-application-arguments
|
||||
run-example-active-profiles=run.examples.specify-active-profiles
|
||||
using=using
|
||||
using-parent-pom=using.parent-pom
|
||||
using-import=using.import
|
||||
using-overriding-command-line=using.overriding-command-line
|
||||
@ -1,5 +1,5 @@
|
||||
[[build-info]]
|
||||
== Integrating with Actuator
|
||||
= Integrating with Actuator
|
||||
Spring Boot Actuator displays build-related information if a `META-INF/build-info.properties` file is present.
|
||||
The `build-info` goal generates such file with the coordinates of the project and the build time.
|
||||
It also allows you to add an arbitrary number of additional properties, as shown in the following example:
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
[[getting-started]]
|
||||
== Getting Started
|
||||
= Getting Started
|
||||
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",tabsize=4]
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
[[goals]]
|
||||
== Goals
|
||||
= Goals
|
||||
The Spring Boot Plugin has the following goals:
|
||||
|
||||
include::goals/overview.adoc[]
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
[[help]]
|
||||
== Help Information
|
||||
= Help Information
|
||||
The `help` goal is a standard goal that displays information on the capabilities of the plugin.
|
||||
|
||||
include::goals/help.adoc[leveloffset=+1]
|
||||
|
||||
@ -20,25 +20,22 @@ Stephane Nicoll, Andy Wilkinson, Scott Frederick
|
||||
|
||||
|
||||
|
||||
[[introduction]]
|
||||
== Introduction
|
||||
The Spring Boot Maven Plugin provides Spring Boot support in https://maven.org[Apache Maven].
|
||||
It allows you to package executable jar or war archives, run Spring Boot applications, generate build information and start your Spring Boot application prior to running integration tests.
|
||||
include::introduction.adoc[leveloffset=+1]
|
||||
|
||||
include::getting-started.adoc[]
|
||||
include::getting-started.adoc[leveloffset=+1]
|
||||
|
||||
include::using.adoc[]
|
||||
include::using.adoc[leveloffset=+1]
|
||||
|
||||
include::goals.adoc[]
|
||||
include::goals.adoc[leveloffset=+1]
|
||||
|
||||
include::packaging.adoc[]
|
||||
include::packaging.adoc[leveloffset=+1]
|
||||
|
||||
include::packaging-oci-image.adoc[]
|
||||
include::packaging-oci-image.adoc[leveloffset=+1]
|
||||
|
||||
include::running.adoc[]
|
||||
include::running.adoc[leveloffset=+1]
|
||||
|
||||
include::integration-tests.adoc[]
|
||||
include::integration-tests.adoc[leveloffset=+1]
|
||||
|
||||
include::build-info.adoc[]
|
||||
include::build-info.adoc[leveloffset=+1]
|
||||
|
||||
include::help.adoc[]
|
||||
include::help.adoc[leveloffset=+1]
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
[[integration-tests]]
|
||||
== Running Integration Tests
|
||||
= Running Integration Tests
|
||||
While you may start your Spring Boot application very easily from your test (or test suite) itself, it may be desirable to handle that in the build itself.
|
||||
To make sure that the lifecycle of your Spring Boot application is properly managed around your integration tests, you can use the `start` and `stop` goals, as shown in the following example:
|
||||
|
||||
@ -11,14 +11,14 @@ include::../maven/integration-tests/pom.xml[tags=integration-tests]
|
||||
Such setup can now use the https://maven.apache.org/surefire/maven-failsafe-plugin[failsafe-plugin] to run your integration tests as you would expect.
|
||||
|
||||
NOTE: By default, the application is started in a separate process and JMX is used to communicate with the application.
|
||||
If you need to configure the JMX port, see <<integration-tests-example-jmx-port,the dedicated example>>.
|
||||
If you need to configure the JMX port, see <<integration-tests.examples.jmx-port,the dedicated example>>.
|
||||
|
||||
You could also configure a more advanced setup to skip the integration tests when a specific property has been set, see <<integration-tests-example-skip,the dedicated example>>.
|
||||
You could also configure a more advanced setup to skip the integration tests when a specific property has been set, see <<integration-tests.examples.skip,the dedicated example>>.
|
||||
|
||||
|
||||
|
||||
[[integration-tests-no-starter-parent]]
|
||||
=== Using Failsafe Without Spring Boot's Parent POM
|
||||
[[integration-tests.no-starter-parent]]
|
||||
== Using Failsafe Without Spring Boot's Parent POM
|
||||
Spring Boot's Parent POM, `spring-boot-starter-parent`, configures Failsafe's `<classesDirectory>` to be `${project.build.outputDirectory}`.
|
||||
Without this configuration, which causes Failsafe to use the compiled classes rather than the repackaged jar, Failsafe cannot load your application's classes.
|
||||
If you are not using the parent POM, you should configure Failsafe in the same way, as shown in the following example:
|
||||
@ -34,13 +34,13 @@ include::goals/stop.adoc[leveloffset=+1]
|
||||
|
||||
|
||||
|
||||
[[integration-tests-example]]
|
||||
=== Examples
|
||||
[[integration-tests.examples]]
|
||||
== Examples
|
||||
|
||||
|
||||
|
||||
[[integration-tests-example-random-port]]
|
||||
==== Random Port for Integration Tests
|
||||
[[integration-tests.examples.random-port]]
|
||||
=== Random Port for Integration Tests
|
||||
One nice feature of the Spring Boot test integration is that it can allocate a free port for the web application.
|
||||
When the `start` goal of the plugin is used, the Spring Boot application is started separately, making it difficult to pass the actual port to the integration test itself.
|
||||
|
||||
@ -55,8 +55,8 @@ You can now retrieve the `test.server.port` system property in any of your integ
|
||||
|
||||
|
||||
|
||||
[[integration-tests-example-jmx-port]]
|
||||
==== Customize JMX port
|
||||
[[integration-tests.examples.jmx-port]]
|
||||
=== Customize JMX port
|
||||
The `jmxPort` property allows to customize the port the plugin uses to communicate with the Spring Boot application.
|
||||
|
||||
This example shows how you can customize the port in case `9001` is already used:
|
||||
@ -70,8 +70,8 @@ TIP: If you need to configure the JMX port, make sure to do so in the global con
|
||||
|
||||
|
||||
|
||||
[[integration-tests-example-skip]]
|
||||
==== Skip Integration Tests
|
||||
[[integration-tests.examples.skip]]
|
||||
=== Skip Integration Tests
|
||||
The `skip` property allows to skip the execution of the Spring Boot maven plugin altogether.
|
||||
|
||||
This example shows how you can skip integration tests with a command-line property and still make sure that the `repackage` goal runs:
|
||||
|
||||
@ -0,0 +1,4 @@
|
||||
[[introduction]]
|
||||
= Introduction
|
||||
The Spring Boot Maven Plugin provides Spring Boot support in https://maven.org[Apache Maven].
|
||||
It allows you to package executable jar or war archives, run Spring Boot applications, generate build information and start your Spring Boot application prior to running integration tests.
|
||||
@ -1,5 +1,5 @@
|
||||
[[build-image]]
|
||||
== Packaging OCI Images
|
||||
= Packaging OCI Images
|
||||
The plugin can create an https://github.com/opencontainers/image-spec[OCI image] from a jar or war file using https://buildpacks.io/[Cloud Native Buildpacks] (CNB).
|
||||
Images can be built using the `build-image` goal.
|
||||
|
||||
@ -14,13 +14,13 @@ It is possible to automate the creation of an image whenever the `package` phase
|
||||
include::../maven/packaging-oci-image/pom.xml[tags=packaging-oci-image]
|
||||
----
|
||||
|
||||
TIP: While the buildpack runs from an <<repackage,executable archive>>, it is not necessary to execute the `repackage` goal first as the executable archive is created automatically if necessary.
|
||||
TIP: While the buildpack runs from an <<packaging,executable archive>>, it is not necessary to execute the `repackage` goal first as the executable archive is created automatically if necessary.
|
||||
When the `build-image` repackages the application, it applies the same settings as the `repackage` goal would, i.e. dependencies can be excluded using one of the exclude options, and Devtools is automatically excluded by default (you can control that using the `excludeDevtools` property).
|
||||
|
||||
|
||||
|
||||
[[build-image-docker-daemon]]
|
||||
=== Docker Daemon
|
||||
[[build-image.docker-daemon]]
|
||||
== Docker Daemon
|
||||
The `build-image` goal requires access to a Docker daemon.
|
||||
By default, it will communicate with a Docker daemon over a local connection.
|
||||
This works with https://docs.docker.com/install/[Docker Engine] on all supported platforms without configuration.
|
||||
@ -59,12 +59,12 @@ The following table summarizes the available parameters:
|
||||
| Path to certificate and key files for HTTPS (required if `tlsVerify` is `true`, ignored otherwise)
|
||||
|===
|
||||
|
||||
For more details, see also <<build-image-example-docker,examples>>.
|
||||
For more details, see also <<build-image.examples.docker,examples>>.
|
||||
|
||||
|
||||
|
||||
[[build-image-docker-registry]]
|
||||
=== Docker Registry
|
||||
[[build-image.docker-registry]]
|
||||
== Docker Registry
|
||||
If the Docker images specified by the `builder` or `runImage` parameters are stored in a private Docker image registry that requires authentication, the authentication credentials can be provided using `docker.builderRegistry` parameters.
|
||||
|
||||
If the generated Docker image is to be published to a Docker image registry, the authentication credentials can be provided using `docker.publishRegistry` parameters.
|
||||
@ -93,12 +93,12 @@ The following table summarizes the available parameters for `docker.builderRegis
|
||||
| Identity token for the Docker image registry user. Required for token authentication.
|
||||
|===
|
||||
|
||||
For more details, see also <<build-image-example-docker,examples>>.
|
||||
For more details, see also <<build-image.examples.docker,examples>>.
|
||||
|
||||
|
||||
|
||||
[[build-image-customization]]
|
||||
=== Image Customizations
|
||||
[[build-image.customization]]
|
||||
== Image Customizations
|
||||
The plugin invokes a {buildpacks-reference}/concepts/components/builder/[builder] to orchestrate the generation of an image.
|
||||
The builder includes multiple {buildpacks-reference}/concepts/components/buildpack[buildpacks] that can inspect the application to influence the generated image.
|
||||
By default, the plugin chooses a builder image.
|
||||
@ -182,21 +182,21 @@ Where `<options>` can contain:
|
||||
|
||||
NOTE: The plugin detects the target Java compatibility of the project using the compiler's plugin configuration or the `maven.compiler.target` property.
|
||||
When using the default Paketo builder and buildpacks, the plugin instructs the buildpacks to install the same Java version.
|
||||
You can override this behaviour as shown in the <<build-image-example-builder-configuration,builder configuration>> examples.
|
||||
You can override this behaviour as shown in the <<build-image.examples.builder-configuration,builder configuration>> examples.
|
||||
|
||||
For more details, see also <<build-image-examples,examples>>.
|
||||
For more details, see also <<build-image.examples,examples>>.
|
||||
|
||||
include::goals/build-image.adoc[leveloffset=+1]
|
||||
|
||||
|
||||
|
||||
[[build-image-examples]]
|
||||
=== Examples
|
||||
[[build-image.examples]]
|
||||
== Examples
|
||||
|
||||
|
||||
|
||||
[[build-image-example-custom-image-builder]]
|
||||
==== Custom Image Builder
|
||||
[[build-image.examples.custom-image-builder]]
|
||||
=== Custom Image Builder
|
||||
If you need to customize the builder used to create the image or the run image used to launch the built image, configure the plugin as shown in the following example:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
||||
@ -215,8 +215,8 @@ The builder and run image can be specified on the command line as well, as shown
|
||||
|
||||
|
||||
|
||||
[[build-image-example-builder-configuration]]
|
||||
==== Builder Configuration
|
||||
[[build-image.examples.builder-configuration]]
|
||||
=== Builder Configuration
|
||||
If the builder exposes configuration options using environment variables, those can be set using the `env` attributes.
|
||||
|
||||
The following is an example of {paketo-java-reference}/#configuring-the-jvm-version[configuring the JVM version] used by the Paketo Java buildpacks at build time:
|
||||
@ -236,8 +236,8 @@ include::../maven/packaging-oci-image/paketo-pom.xml[tags=paketo]
|
||||
|
||||
|
||||
|
||||
[[build-image-example-runtime-jvm-configuration]]
|
||||
==== Runtime JVM Configuration
|
||||
[[build-image.examples.runtime-jvm-configuration]]
|
||||
=== Runtime JVM Configuration
|
||||
Paketo Java buildpacks {paketo-java-reference}/#runtime-jvm-configuration[configure the JVM runtime environment] by setting the `JAVA_TOOL_OPTIONS` environment variable.
|
||||
The buildpack-provided `JAVA_TOOL_OPTIONS` value can be modified to customize JVM runtime behavior when the application image is launched in a container.
|
||||
|
||||
@ -250,8 +250,8 @@ include::../maven/packaging-oci-image/runtime-jvm-configuration-pom.xml[tags=run
|
||||
|
||||
|
||||
|
||||
[[build-image-example-custom-image-name]]
|
||||
==== Custom Image Name
|
||||
[[build-image.examples.custom-image-name]]
|
||||
=== Custom Image Name
|
||||
By default, the image name is inferred from the `artifactId` and the `version` of the project, something like `docker.io/library/${project.artifactId}:${project.version}`.
|
||||
You can take control over the name, as shown in the following example:
|
||||
|
||||
@ -272,8 +272,8 @@ The image name can be specified on the command line as well, as shown in this ex
|
||||
|
||||
|
||||
|
||||
[[build-image-example-buildpacks]]
|
||||
==== Buildpacks
|
||||
[[build-image.examples.buildpacks]]
|
||||
=== Buildpacks
|
||||
By default, the builder will use buildpacks included in the builder image and apply them in a pre-defined order.
|
||||
An alternative set of buildpacks can be provided to apply buildpacks that are not included in the builder, or to change the order of included buildpacks.
|
||||
When one or more buildpacks are provided, only the specified buildpacks will be applied.
|
||||
@ -315,8 +315,8 @@ An OCI image containing a https://buildpacks.io/docs/buildpack-author-guide/pack
|
||||
|
||||
|
||||
|
||||
[[build-image-example-publish]]
|
||||
==== Image Publishing
|
||||
[[build-image.examples.publish]]
|
||||
=== Image Publishing
|
||||
The generated image can be published to a Docker registry by enabling a `publish` option and configuring authentication for the registry using `docker.publishRegistry` parameters.
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
||||
@ -333,8 +333,8 @@ The `publish` option can be specified on the command line as well, as shown in t
|
||||
|
||||
|
||||
|
||||
[[build-image-example-docker]]
|
||||
==== Docker Configuration
|
||||
[[build-image.examples.docker]]
|
||||
=== Docker Configuration
|
||||
If you need the plugin to communicate with the Docker daemon using a remote connection instead of the default local connection, the connection details can be provided using `docker` parameters as shown in the following example:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
[[repackage]]
|
||||
== Packaging Executable Archives
|
||||
[[packaging]]
|
||||
= Packaging Executable Archives
|
||||
The plugin can create executable archives (jar files and war files) that contain all of an application's dependencies and can then be run with `java -jar`.
|
||||
|
||||
Packaging an executable archive is performed by the `repackage` goal, as shown in the following example:
|
||||
@ -12,7 +12,7 @@ include::../maven/packaging/repackage-pom.xml[tags=repackage]
|
||||
TIP: If you are using `spring-boot-starter-parent`, such execution is already pre-configured with a `repackage` execution ID so that only the plugin definition should be added.
|
||||
|
||||
The example above repackages a `jar` or `war` archive that is built during the package phase of the Maven lifecycle, including any `provided` dependencies that are defined in the project.
|
||||
If some of these dependencies need to be excluded, you can use one of the `exclude` options; see the <<repackage-example-exclude-dependency,dependency exclusion>> for more details.
|
||||
If some of these dependencies need to be excluded, you can use one of the `exclude` options; see the <<packaging.examples.exclude-dependency,dependency exclusion>> for more details.
|
||||
|
||||
The original (i.e. non-executable) artifact is renamed to `.original` by default but it is also possible to keep the original artifact using a custom classifier.
|
||||
|
||||
@ -39,8 +39,8 @@ The `layout` property defaults to a value determined by the archive type (`jar`
|
||||
|
||||
|
||||
|
||||
[[repackage-layers]]
|
||||
=== Layered Jar or War
|
||||
[[packaging.layers]]
|
||||
== Layered Jar or War
|
||||
A repackaged jar contains the application's classes and dependencies in `BOOT-INF/classes` and `BOOT-INF/lib` respectively.
|
||||
Similarly, an executable war contains the application's classes in `WEB-INF/classes` and dependencies in `WEB-INF/lib` and `WEB-INF/lib-provided`.
|
||||
For cases where a docker image needs to be built from the contents of a jar or war, it's useful to be able to separate these directories further so that they can be written into distinct layers.
|
||||
@ -71,8 +71,8 @@ include::../maven/packaging/disable-layers-pom.xml[tags=disable-layers]
|
||||
|
||||
|
||||
|
||||
[[repackage-layers-configuration]]
|
||||
==== Custom Layers Configuration
|
||||
[[packaging.layers.configuration=]]
|
||||
=== Custom Layers Configuration
|
||||
Depending on your application, you may want to tune how layers are created and add new ones.
|
||||
This can be done using a separate configuration file that should be registered as shown below:
|
||||
|
||||
@ -123,13 +123,13 @@ include::goals/repackage.adoc[leveloffset=+1]
|
||||
|
||||
|
||||
|
||||
[[repackage-examples]]
|
||||
=== Examples
|
||||
[[packaging.examples]]
|
||||
== Examples
|
||||
|
||||
|
||||
|
||||
[[repackage-example-custom-classifier]]
|
||||
==== Custom Classifier
|
||||
[[packaging.examples.custom-classifier]]
|
||||
=== Custom Classifier
|
||||
By default, the `repackage` goal replaces the original artifact with the repackaged one.
|
||||
That is a sane behavior for modules that represent an application but if your module is used as a dependency of another module, you need to provide a classifier for the repackaged one.
|
||||
The reason for that is that application classes are packaged in `BOOT-INF/classes` so that the dependent module cannot load a repackaged jar's classes.
|
||||
@ -170,8 +170,8 @@ include::../maven/packaging/jar-plugin-first-pom.xml[tags=jar-plugin-first]
|
||||
|
||||
|
||||
|
||||
[[repackage-example-custom-name]]
|
||||
==== Custom Name
|
||||
[[packaging.examples.custom-name]]
|
||||
=== Custom Name
|
||||
If you need the repackaged jar to have a different local name than the one defined by the `artifactId` attribute of the project, use the standard `finalName`, as shown in the following example:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
||||
@ -183,8 +183,8 @@ This configuration will generate the repackaged artifact in `target/my-app.jar`.
|
||||
|
||||
|
||||
|
||||
[[repackage-example-local-artifact]]
|
||||
==== Local Repackaged Artifact
|
||||
[[packaging.examples.local-artifact]]
|
||||
=== Local Repackaged Artifact
|
||||
By default, the `repackage` goal replaces the original artifact with the executable one.
|
||||
If you need to only deploy the original jar and yet be able to run your app with the regular file name, configure the plugin as follows:
|
||||
|
||||
@ -198,8 +198,8 @@ Only the original one will be installed/deployed.
|
||||
|
||||
|
||||
|
||||
[[repackage-example-custom-layout]]
|
||||
==== Custom Layout
|
||||
[[packaging.examples.custom-layout]]
|
||||
=== Custom Layout
|
||||
Spring Boot repackages the jar file for this project using a custom layout factory defined in the additional jar file, provided as a dependency to the build plugin:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
||||
@ -214,8 +214,8 @@ Layout factories are always ignored if an explicit <<goals-repackage-parameters-
|
||||
|
||||
|
||||
|
||||
[[repackage-example-exclude-dependency]]
|
||||
==== Dependency Exclusion
|
||||
[[packaging.examples.exclude-dependency]]
|
||||
=== Dependency Exclusion
|
||||
By default, both the `repackage` and the `run` goals will include any `provided` dependencies that are defined in the project.
|
||||
A Spring Boot project should consider `provided` dependencies as "container" dependencies that are required to run the application.
|
||||
|
||||
@ -243,8 +243,8 @@ include::../maven/packaging/exclude-artifact-group-pom.xml[tags=exclude-artifact
|
||||
|
||||
|
||||
|
||||
[[repackage-layered-archive-tools]]
|
||||
==== Layered Archive Tools
|
||||
[[packaging.examples.layered-archive-tools]]
|
||||
=== Layered Archive Tools
|
||||
When a layered jar or war is created, the `spring-boot-jarmode-layertools` jar will be added as a dependency to your archive.
|
||||
With this jar on the classpath, you can launch your application in a special mode which allows the bootstrap code to run something entirely different from your application, for example, something that extracts the layers.
|
||||
If you wish to exclude this dependency, you can do so in the following manner:
|
||||
@ -256,8 +256,8 @@ include::../maven/packaging/exclude-dependency-pom.xml[tags=exclude-dependency]
|
||||
|
||||
|
||||
|
||||
[[repackage-layered-archive-additional-layers]]
|
||||
==== Custom Layers Configuration
|
||||
[[packaging.examples.custom-layers-configuration]]
|
||||
=== Custom Layers Configuration
|
||||
The default setup splits dependencies into snapshot and non-snapshot, however, you may have more complex rules.
|
||||
For example, you may want to isolate company-specific dependencies of your project in a dedicated layer.
|
||||
The following `layers.xml` configuration shown one such setup:
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
[[run]]
|
||||
== Running your Application with Maven
|
||||
= Running your Application with Maven
|
||||
The plugin includes a run goal which can be used to launch your application from the command line, as shown in the following example:
|
||||
|
||||
[indent=0]
|
||||
@ -7,13 +7,13 @@ The plugin includes a run goal which can be used to launch your application from
|
||||
$ mvn spring-boot:run
|
||||
----
|
||||
|
||||
Application arguments can be specified using the `arguments` parameter, see <<run-example-application-arguments,using application arguments>> for more details.
|
||||
Application arguments can be specified using the `arguments` parameter, see <<run.examples.using-application-arguments,using application arguments>> for more details.
|
||||
|
||||
By default the application is executed in a forked process and setting properties on the command-line will not affect the application.
|
||||
If you need to specify some JVM arguments (i.e. for debugging purposes), you can use the `jvmArguments` parameter, see <<run-example-debug,Debug the application>> for more details.
|
||||
There is also explicit support for <<run-example-system-properties,system properties>> and <<run-example-environment-variables,environment variables>>.
|
||||
If you need to specify some JVM arguments (i.e. for debugging purposes), you can use the `jvmArguments` parameter, see <<run.examples.debug,Debug the application>> for more details.
|
||||
There is also explicit support for <<run.examples.system-properties,system properties>> and <<run.examples.environment-variables,environment variables>>.
|
||||
|
||||
As enabling a profile is quite common, there is dedicated `profiles` property that offers a shortcut for `-Dspring-boot.run.jvmArguments="-Dspring.profiles.active=dev"`, see <<run-example-active-profiles,Specify active profiles>>.
|
||||
As enabling a profile is quite common, there is dedicated `profiles` property that offers a shortcut for `-Dspring-boot.run.jvmArguments="-Dspring.profiles.active=dev"`, see <<run.examples.specify-active-profiles,Specify active profiles>>.
|
||||
|
||||
Although this is not recommended, it is possible to execute the application directly from the Maven JVM by disabling the `fork` property.
|
||||
Doing so means that the `jvmArguments`, `systemPropertyVariables`, `environmentVariables` and `agents` options are ignored.
|
||||
@ -54,7 +54,7 @@ It is also a helpful way of allowing your front end developers to work without n
|
||||
NOTE: A side effect of using this feature is that filtering of resources at build time will not work.
|
||||
|
||||
In order to be consistent with the `repackage` goal, the `run` goal builds the classpath in such a way that any dependency that is excluded in the plugin's configuration gets excluded from the classpath as well.
|
||||
For more details, see <<repackage-example-exclude-dependency,the dedicated example>>.
|
||||
For more details, see <<packaging.examples.exclude-dependency,the dedicated example>>.
|
||||
|
||||
Sometimes it is useful to include test dependencies when running the application.
|
||||
For example, if you want to run your application in a test mode that uses stub classes.
|
||||
@ -66,13 +66,13 @@ include::goals/run.adoc[leveloffset=+1]
|
||||
|
||||
|
||||
|
||||
[[run-examples]]
|
||||
=== Examples
|
||||
[[run.examples]]
|
||||
== Examples
|
||||
|
||||
|
||||
|
||||
[[run-example-debug]]
|
||||
==== Debug the Application
|
||||
[[run.examples.debug]]
|
||||
=== Debug the Application
|
||||
By default, the `run` goal runs your application in a forked process.
|
||||
If you need to debug it, you should add the necessary JVM arguments to enable remote debugging.
|
||||
The following configuration suspend the process until a debugger has joined on port 5005:
|
||||
@ -91,8 +91,8 @@ These arguments can be specified on the command line as well, make sure to wrap
|
||||
|
||||
|
||||
|
||||
[[run-example-system-properties]]
|
||||
==== Using System Properties
|
||||
[[run.examples.system-properties]]
|
||||
=== Using System Properties
|
||||
System properties can be specified using the `systemPropertyVariables` attribute.
|
||||
The following example sets `property1` to `test` and `property2` to 42:
|
||||
|
||||
@ -117,8 +117,8 @@ In the following example, the value for `property1` is `overridden`:
|
||||
|
||||
|
||||
|
||||
[[run-example-environment-variables]]
|
||||
==== Using Environment Variables
|
||||
[[run.examples.environment-variables]]
|
||||
=== Using Environment Variables
|
||||
Environment variables can be specified using the `environmentVariables` attribute.
|
||||
The following example sets the 'ENV1', 'ENV2', 'ENV3', 'ENV4' env variables:
|
||||
|
||||
@ -137,8 +137,8 @@ Environment variables defined this way take precedence over existing values.
|
||||
|
||||
|
||||
|
||||
[[run-example-application-arguments]]
|
||||
==== Using Application Arguments
|
||||
[[run.examples.using-application-arguments]]
|
||||
=== Using Application Arguments
|
||||
Application arguments can be specified using the `arguments` attribute.
|
||||
The following example sets two arguments: `property1` and `property2=42`:
|
||||
|
||||
@ -158,8 +158,8 @@ In the following example, two arguments are available: `property1` and `property
|
||||
|
||||
|
||||
|
||||
[[run-example-active-profiles]]
|
||||
==== Specify Active Profiles
|
||||
[[run.examples.specify-active-profiles]]
|
||||
=== Specify Active Profiles
|
||||
The active profiles to use for a particular application can be specified using the `profiles` argument.
|
||||
|
||||
The following configuration enables the `local` and `dev` profiles:
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
[[using]]
|
||||
== Using the Plugin
|
||||
= Using the Plugin
|
||||
Maven users can inherit from the `spring-boot-starter-parent` project to obtain sensible defaults.
|
||||
The parent project provides the following features:
|
||||
|
||||
@ -17,8 +17,8 @@ NOTE: Since the `application.properties` and `application.yml` files accept Spri
|
||||
|
||||
|
||||
|
||||
[[using-parent-pom]]
|
||||
=== Inheriting the Starter Parent POM
|
||||
[[using.parent-pom]]
|
||||
== Inheriting the Starter Parent POM
|
||||
To configure your project to inherit from the `spring-boot-starter-parent`, set the `parent` as follows:
|
||||
|
||||
[source,xml,indent=0,subs="verbatim,quotes,attributes"]
|
||||
@ -46,8 +46,8 @@ Browse the {version-properties-appendix}[`Dependency versions Appendix`] in the
|
||||
|
||||
|
||||
|
||||
[[using-import]]
|
||||
=== Using Spring Boot without the Parent POM
|
||||
[[using.import]]
|
||||
== Using Spring Boot without the Parent POM
|
||||
There may be reasons for you not to inherit from the `spring-boot-starter-parent` POM.
|
||||
You may have your own corporate standard parent that you need to use or you may prefer to explicitly declare all your Maven configuration.
|
||||
|
||||
@ -69,8 +69,8 @@ include::../maven/using/no-starter-parent-override-dependencies-pom.xml[tags=no-
|
||||
|
||||
|
||||
|
||||
[[using-overriding-command-line]]
|
||||
=== Overriding settings on the command-line
|
||||
[[using.overriding-command-line]]
|
||||
== Overriding settings on the command-line
|
||||
The plugin offers a number of user properties, starting with `spring-boot`, to let you customize the configuration from the command-line.
|
||||
|
||||
For instance, you could tune the profiles to enable when running the application as follows:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user