diff --git a/buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java b/buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java index 71191f38da5..5930bc64002 100644 --- a/buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java +++ b/buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java @@ -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 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\"]"); diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/anchor-rewrite.properties b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/anchor-rewrite.properties new file mode 100644 index 00000000000..af45d43d683 --- /dev/null +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/anchor-rewrite.properties @@ -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 diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/build-info.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/build-info.adoc index e5f9612c84a..57eb95a810e 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/build-info.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/build-info.adoc @@ -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: diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/getting-started.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/getting-started.adoc index b170907e5a8..f43ef23c0ef 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/getting-started.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/getting-started.adoc @@ -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] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/goals.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/goals.adoc index 97429a58c51..2ce66a85ddb 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/goals.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/goals.adoc @@ -1,5 +1,5 @@ [[goals]] -== Goals += Goals The Spring Boot Plugin has the following goals: include::goals/overview.adoc[] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/help.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/help.adoc index 7a71091ce8e..a3ec8df55c5 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/help.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/help.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] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc index 38f15446f4f..af470f8eecf 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc @@ -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] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/integration-tests.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/integration-tests.adoc index 6d320ee59da..8dd219a1aec 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/integration-tests.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/integration-tests.adoc @@ -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 <>. +If you need to configure the JMX port, see <>. -You could also configure a more advanced setup to skip the integration tests when a specific property has been set, see <>. +You could also configure a more advanced setup to skip the integration tests when a specific property has been set, see <>. -[[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 `` 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: diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/introduction.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/introduction.adoc new file mode 100644 index 00000000000..db6c0234a3e --- /dev/null +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/introduction.adoc @@ -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. diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc index fc0f6c538c2..e4a0cf7e984 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc @@ -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 <>, 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 <>, 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 <>. +For more details, see also <>. -[[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 <>. +For more details, see also <>. -[[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 `` 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 <> examples. +You can override this behaviour as shown in the <> examples. -For more details, see also <>. +For more details, see also <>. 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] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging.adoc index 4a2b89cfc36..c2987c3bd1a 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging.adoc @@ -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 <> for more details. +If some of these dependencies need to be excluded, you can use one of the `exclude` options; see the <> 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 <> for more details. +Application arguments can be specified using the `arguments` parameter, see <> 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 <> for more details. -There is also explicit support for <> and <>. +If you need to specify some JVM arguments (i.e. for debugging purposes), you can use the `jvmArguments` parameter, see <> for more details. +There is also explicit support for <> and <>. -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 <>. +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 <>. 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 <>. +For more details, see <>. 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: diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/using.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/using.adoc index 0ad9ba34ca7..8faf51970e5 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/using.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/using.adoc @@ -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: