From 3328a30b7b7d2e84b19c69973e3de2696778156f Mon Sep 17 00:00:00 2001 From: Andy Wilkinson Date: Thu, 3 Apr 2014 14:22:44 +0100 Subject: [PATCH] Include details of dependency versions in the docs Closes #637 --- spring-boot-docs/pom.xml | 101 +++++++++++++----- .../appendix-dependency-versions.adoc | 8 ++ .../appendix-executable-jar-format.adoc | 2 + .../src/main/asciidoc/appendix.adoc | 1 + .../src/main/asciidoc/build-tool-plugins.adoc | 25 +++-- .../src/main/asciidoc/spring-boot-cli.adoc | 3 +- .../src/main/xslt/dependencyVersions.xsl | 25 +++++ 7 files changed, 125 insertions(+), 40 deletions(-) create mode 100644 spring-boot-docs/src/main/asciidoc/appendix-dependency-versions.adoc create mode 100644 spring-boot-docs/src/main/xslt/dependencyVersions.xsl diff --git a/spring-boot-docs/pom.xml b/spring-boot-docs/pom.xml index 03efe0b0f70..3f8ae1dce42 100644 --- a/spring-boot-docs/pom.xml +++ b/spring-boot-docs/pom.xml @@ -70,6 +70,79 @@ + + org.apache.maven.plugins + maven-dependency-plugin + + + unpack-maven-plugin + generate-resources + + unpack + + + + + org.springframework.boot + spring-boot-maven-plugin + ${project.version} + site + jar + + ${project.build.directory}/contents/maven-plugin + + META-INF/** + + + + + + unpack-dependency-tools-effective-pom + generate-resources + + unpack + + + + + org.springframework.boot + spring-boot-dependency-tools + ${project.version} + jar + + + **/effective-pom.xml + ${project.build.directory}/external-resources + + + + + + org.codehaus.mojo + xml-maven-plugin + 1.0 + + + + transform + + + + + + + ${project.build.directory}/external-resources + src/main/xslt/dependencyVersions.xsl + + + .adoc + + + ${project.build.directory}/generated-resources + + + + org.asciidoctor asciidoctor-maven-plugin @@ -219,34 +292,6 @@ - - org.apache.maven.plugins - maven-dependency-plugin - - - unpack-maven-plugin - generate-resources - - unpack - - - - - org.springframework.boot - spring-boot-maven-plugin - ${project.version} - site - jar - - ${project.build.directory}/contents/maven-plugin - - META-INF/** - - - - - - org.apache.maven.plugins maven-antrun-plugin diff --git a/spring-boot-docs/src/main/asciidoc/appendix-dependency-versions.adoc b/spring-boot-docs/src/main/asciidoc/appendix-dependency-versions.adoc new file mode 100644 index 00000000000..969697c4b23 --- /dev/null +++ b/spring-boot-docs/src/main/asciidoc/appendix-dependency-versions.adoc @@ -0,0 +1,8 @@ +[appendix] +[[appendix-dependency-versions]] +== Dependency versions +The table below provides details of all of the dependency versions that are provided by Spring Boot +in its CLI, Maven dependency management and Gradle plugin. When you declare a dependency on one of +these artifacts without declaring a version the version that is listed in the table will be used. + +include::../../../target/generated-resources/org/springframework/boot/dependency/tools/effective-pom.adoc[] \ No newline at end of file diff --git a/spring-boot-docs/src/main/asciidoc/appendix-executable-jar-format.adoc b/spring-boot-docs/src/main/asciidoc/appendix-executable-jar-format.adoc index 20b299a41af..1e84be46b18 100644 --- a/spring-boot-docs/src/main/asciidoc/appendix-executable-jar-format.adoc +++ b/spring-boot-docs/src/main/asciidoc/appendix-executable-jar-format.adoc @@ -275,3 +275,5 @@ alternatives could be considered: * http://maven.apache.org/plugins/maven-shade-plugin/[Maven Shade Plugin] * http://www.jdotsoft.com/JarClassLoader.php[JarClassLoader] * http://one-jar.sourceforge.net[OneJar] + + diff --git a/spring-boot-docs/src/main/asciidoc/appendix.adoc b/spring-boot-docs/src/main/asciidoc/appendix.adoc index 6acfbf84d7b..9767f8a6c69 100644 --- a/spring-boot-docs/src/main/asciidoc/appendix.adoc +++ b/spring-boot-docs/src/main/asciidoc/appendix.adoc @@ -4,4 +4,5 @@ include::appendix-application-properties.adoc[] include::appendix-auto-configuration-classes.adoc[] include::appendix-executable-jar-format.adoc[] +include::appendix-dependency-versions.adoc[] diff --git a/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc b/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc index 7aad4a0d581..d830ca8dc66 100644 --- a/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc +++ b/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc @@ -202,12 +202,8 @@ If you are using a milestone or snapshot release you will also need to add appro === Declaring dependencies without versions The `spring-boot` plugin will register a custom Gradle `ResolutionStrategy` with your build that allows you to omit version numbers when declaring dependencies to ``blessed'' -artifacts. All artifacts with a `org.springframework.boot` group ID, and any of the -artifacts declared in the `managementDependencies` section of the -{github-code}/spring-boot-dependencies/pom.xml[`spring-dependencies`] -POM can have their version number resolved automatically. - -Simply declare dependencies in the usual way, but leave the version number empty: +artifacts. To make use of this functionality, simply declare dependencies in the usual way, +but leave the version number empty: [source,groovy,indent=0,subs="verbatim,attributes"] ---- @@ -221,9 +217,20 @@ Simply declare dependencies in the usual way, but leave the version number empty NOTE: The version of the `spring-boot` gradle plugin that you declare determines the actual versions of the ``blessed'' dependencies (this ensures that builds are always repeatable). You should always set the version of the `spring-boot` gradle plugin to the -actual Spring Boot version that you wish to use. +actual Spring Boot version that you wish to use. Details of the versions that are +provided can be found in the <>. +The `spring-boot` plugin will only supply a version where one is not specified. To +use a version of an artifact that differs from the one that the plugin would provide, +simply specify the version when you declare the dependency as you usually would. For +example: +[source,groovy,indent=0,subs="verbatim,attributes"] +---- + dependencies { + compile("org.thymeleaf:thymeleaf-spring4:2.1.1.RELEASE") + } +---- [[build-tool-plugins-gradle-custom-version-management]] ==== Custom version management @@ -250,8 +257,6 @@ the above example `mycorp-versions.properties` file might contain the following: The properties file takes precedence over Spring Boot's defaults, and can be used to override version numbers if necessary. - - [[build-tool-plugins-gradle-packaging]] === Packaging executable jar and war files Once the `spring-boot` plugin has been applied to your project it will automatically @@ -520,8 +525,6 @@ Here is a typical example repackage: }); ---- - - [[build-tool-plugins-whats-next]] == What to read next If you're interested in how the build tool plugins work you can diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc index 644bfe63380..e28f808c0c6 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc @@ -160,7 +160,8 @@ without a group or version, for example `@Grab('freemarker')`. This will consult default dependency metadata to deduce the artifact's group and version. Note that the default metadata is tied to the version of the CLI that you're using – it will only change when you move to a new version of the CLI, putting you in control of when the versions of your dependencies -may change. +may change. A table showing the dependencies and their versions that are included in the default +metadata can be found in the <>. diff --git a/spring-boot-docs/src/main/xslt/dependencyVersions.xsl b/spring-boot-docs/src/main/xslt/dependencyVersions.xsl new file mode 100644 index 00000000000..aeb88245cae --- /dev/null +++ b/spring-boot-docs/src/main/xslt/dependencyVersions.xsl @@ -0,0 +1,25 @@ + + + + + + + |================================== + | Group ID | Artifact ID | Version + + + + | + + | + + | + + + + |================================== + + + \ No newline at end of file