diff --git a/buildSrc/src/main/java/org/springframework/boot/build/constraints/DocumentVersionProperties.java b/buildSrc/src/main/java/org/springframework/boot/build/constraints/DocumentVersionProperties.java new file mode 100644 index 0000000000..b8b2435ab6 --- /dev/null +++ b/buildSrc/src/main/java/org/springframework/boot/build/constraints/DocumentVersionProperties.java @@ -0,0 +1,80 @@ +/* + * Copyright 2019-2020 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.boot.build.constraints; + +import java.io.File; +import java.io.FileWriter; +import java.io.IOException; +import java.io.PrintWriter; + +import javax.inject.Inject; + +import org.gradle.api.DefaultTask; +import org.gradle.api.model.ObjectFactory; +import org.gradle.api.provider.SetProperty; +import org.gradle.api.tasks.Input; +import org.gradle.api.tasks.OutputFile; +import org.gradle.api.tasks.TaskAction; + +import org.springframework.boot.build.constraints.ExtractVersionConstraints.VersionProperty; + +/** + * Task for documenting available version properties. + * + * @author Christoph Dreis + */ +public class DocumentVersionProperties extends DefaultTask { + + private final SetProperty versionProperties; + + private File outputFile; + + @Inject + public DocumentVersionProperties(ObjectFactory objectFactory) { + this.versionProperties = objectFactory.setProperty(VersionProperty.class); + } + + @Input + public SetProperty getVersionProperties() { + return this.versionProperties; + } + + @OutputFile + public File getOutputFile() { + return this.outputFile; + } + + public void setOutputFile(File outputFile) { + this.outputFile = outputFile; + } + + @TaskAction + public void documentVersionProperties() throws IOException { + this.outputFile.getParentFile().mkdirs(); + try (PrintWriter writer = new PrintWriter(new FileWriter(this.outputFile))) { + writer.println("|==="); + writer.println("| Library | Version Property"); + for (VersionProperty versionProperty : this.versionProperties.get()) { + writer.println(); + writer.printf("| `%s`%n", versionProperty.getLibraryName()); + writer.printf("| `%s`%n", versionProperty.getVersionProperty()); + } + writer.println("|==="); + } + } + +} diff --git a/buildSrc/src/main/java/org/springframework/boot/build/constraints/ExtractVersionConstraints.java b/buildSrc/src/main/java/org/springframework/boot/build/constraints/ExtractVersionConstraints.java index d32cecfc92..23f368b3da 100644 --- a/buildSrc/src/main/java/org/springframework/boot/build/constraints/ExtractVersionConstraints.java +++ b/buildSrc/src/main/java/org/springframework/boot/build/constraints/ExtractVersionConstraints.java @@ -36,6 +36,9 @@ import org.gradle.api.tasks.Internal; import org.gradle.api.tasks.TaskAction; import org.gradle.platform.base.Platform; +import org.springframework.boot.build.bom.BomExtension; +import org.springframework.boot.build.bom.Library; + /** * {@link Task} to extract constraints from a {@link Platform}. The platform's own * constraints and those in any boms upon which it depends are extracted. @@ -50,6 +53,8 @@ public class ExtractVersionConstraints extends AbstractTask { private final Set constrainedVersions = new TreeSet<>(); + private final Set versionProperties = new TreeSet<>(); + private final List projectPaths = new ArrayList(); public ExtractVersionConstraints() { @@ -74,10 +79,16 @@ public class ExtractVersionConstraints extends AbstractTask { return this.constrainedVersions; } + @Internal + public Set getVersionProperties() { + return this.versionProperties; + } + @TaskAction void extractVersionConstraints() { this.configuration.resolve(); for (String projectPath : this.projectPaths) { + extractVersionProperties(projectPath); for (DependencyConstraint constraint : getProject().project(projectPath).getConfigurations() .getByName("apiElements").getAllDependencyConstraints()) { this.versionConstraints.put(constraint.getGroup() + ":" + constraint.getName(), @@ -88,6 +99,14 @@ public class ExtractVersionConstraints extends AbstractTask { } } + private void extractVersionProperties(String projectPath) { + Object bom = getProject().project(projectPath).getExtensions().getByName("bom"); + BomExtension bomExtension = (BomExtension) bom; + for (Library lib : bomExtension.getLibraries()) { + this.versionProperties.add(new VersionProperty(lib.getName(), lib.getVersionProperty())); + } + } + private void processMetadataDetails(ComponentMetadataDetails details) { details.allVariants((variantMetadata) -> variantMetadata.withDependencyConstraints((dependencyConstraints) -> { for (DependencyConstraintMetadata constraint : dependencyConstraints) { @@ -136,4 +155,34 @@ public class ExtractVersionConstraints extends AbstractTask { } + public static final class VersionProperty implements Comparable, Serializable { + + private final String libraryName; + + private final String versionProperty; + + public VersionProperty(String libraryName, String versionProperty) { + this.libraryName = libraryName; + this.versionProperty = versionProperty; + } + + public String getLibraryName() { + return this.libraryName; + } + + public String getVersionProperty() { + return this.versionProperty; + } + + @Override + public int compareTo(VersionProperty other) { + int groupComparison = this.libraryName.compareToIgnoreCase(other.libraryName); + if (groupComparison != 0) { + return groupComparison; + } + return this.versionProperty.compareTo(other.versionProperty); + } + + } + } diff --git a/spring-boot-project/spring-boot-docs/build.gradle b/spring-boot-project/spring-boot-docs/build.gradle index 2a8d934ee7..5d45f324fc 100644 --- a/spring-boot-project/spring-boot-docs/build.gradle +++ b/spring-boot-project/spring-boot-docs/build.gradle @@ -98,6 +98,12 @@ task documentDependencyVersions(type: org.springframework.boot.build.constraints outputFile = file("${buildDir}/docs/generated/dependency-versions.adoc") } +task documentVersionProperties(type: org.springframework.boot.build.constraints.DocumentVersionProperties) { + dependsOn dependencyVersions + versionProperties.set(providers.provider { dependencyVersions.versionProperties}) + outputFile = file("${buildDir}/docs/generated/version-properties.adoc") +} + task documentConfigurationProperties(type: org.springframework.boot.build.context.properties.DocumentConfigurationProperties) { configurationPropertyMetadata = configurations.configurationProperties outputDir = file("${buildDir}/docs/generated/config-docs/") @@ -152,6 +158,7 @@ syncDocumentationSourceForAsciidoctor { dependsOn documentStarters dependsOn documentAutoConfigurationClasses dependsOn documentDependencyVersions + dependsOn documentVersionProperties dependsOn documentConfigurationProperties from("${buildDir}/docs/generated") { into "asciidoc" @@ -169,6 +176,7 @@ syncDocumentationSourceForAsciidoctorMultipage { dependsOn documentStarters dependsOn documentAutoConfigurationClasses dependsOn documentDependencyVersions + dependsOn documentVersionProperties dependsOn documentConfigurationProperties from("${buildDir}/docs/generated") { into "asciidoc" @@ -186,6 +194,7 @@ syncDocumentationSourceForAsciidoctorPdf { dependsOn documentStarters dependsOn documentAutoConfigurationClasses dependsOn documentDependencyVersions + dependsOn documentVersionProperties dependsOn documentConfigurationProperties from("${buildDir}/docs/generated") { into "asciidoc" diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-dependency-versions.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-dependency-versions.adoc index e5049c86dc..9a4a996722 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-dependency-versions.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/appendix-dependency-versions.adoc @@ -12,3 +12,11 @@ The following table provides details of all of the dependency versions that are When you declare a dependency on one of these artifacts without declaring a version, the version listed in the table is used. include::dependency-versions.adoc[] + +[[version-properties]] +== Version Properties + +The following table provides all version properties that can be used to override the versions managed by Spring-Boot. +Browse the {spring-boot-code}/spring-boot-project/spring-boot-dependencies/build.gradle[`spring-boot-dependencies` build.gradle] for a complete list of dependencies. + +include::version-properties.adoc[] diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc index 7bacd31290..75bc7dbeb5 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto.adoc @@ -2421,7 +2421,7 @@ Using this format lets the time be parsed into a `Date` and its format, when ser [[howto-customize-dependency-versions]] === Customize Dependency Versions If you use a Maven build that inherits directly or indirectly from `spring-boot-dependencies` (for instance, `spring-boot-starter-parent`) but you want to override a specific third-party dependency, you can add appropriate `` elements. -Browse the {spring-boot-code}/spring-boot-project/spring-boot-dependencies/pom.xml[`spring-boot-dependencies`] POM for a complete list of properties. +Browse the <> for a complete list of version properties. For example, to pick a different `slf4j` version, you would add the following property: [source,xml,indent=0,subs="verbatim,quotes,attributes"] diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc index 46acc66513..025c3e7d9e 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using-spring-boot.adoc @@ -81,7 +81,7 @@ For instance, to upgrade to another Spring Data release train, you would add the ---- -TIP: Check the {spring-boot-code}/spring-boot-project/spring-boot-dependencies/pom.xml[`spring-boot-dependencies` pom] for a list of supported properties. +TIP: Check out the <> for more information. diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc index f479f070f8..11fb35a8fc 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc @@ -25,6 +25,7 @@ Andy Wilkinson :spring-boot-docs: https://docs.spring.io/spring-boot/docs/{gradle-project-version} :api-documentation: {spring-boot-docs}/gradle-plugin/api :spring-boot-reference: {spring-boot-docs}/reference/htmlsingle +:version-properties-appendix: {spring-boot-reference}/#version-properties :build-info-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/buildinfo/BuildInfo.html :boot-build-image-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/bundling/BootBuildImage.html :boot-jar-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/bundling/BootJar.html diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/managing-dependencies.adoc b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/managing-dependencies.adoc index 9dd99322e6..6369621eb8 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/managing-dependencies.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/managing-dependencies.adoc @@ -23,7 +23,7 @@ include::../gradle/managing-dependencies/dependencies.gradle.kts[tags=dependenci === Customizing managed versions The `spring-boot-dependencies` bom that is automatically imported when the dependency management plugin is applied uses properties to control the versions of the dependencies that it manages. -Please refer to the {github-code}/spring-boot-project/spring-boot-dependencies/pom.xml[bom] for a complete list of these properties. +Browse the {version-properties-appendix}[`Version Properties Appendix`] in the Spring Boot reference for a complete list of version properties. To customize a managed version you set its corresponding property. For example, to customize the version of SLF4J which is controlled by the `slf4j.version` property: