mirror of
https://github.com/spring-projects/spring-boot.git
synced 2024-07-05 00:56:58 +08:00
Introduce appendix section with version properties
With the introduction of Gradle we lost the list of version properties that were previously in the spring-boot-dependencies POM and were also linked inside the documentation. This commit introduces an appendix section in the docs and links the appropriate places to the new section to restore discoverability. See gh-19898
This commit is contained in:
parent
e325b8813b
commit
65394582f6
@ -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<VersionProperty> versionProperties;
|
||||
|
||||
private File outputFile;
|
||||
|
||||
@Inject
|
||||
public DocumentVersionProperties(ObjectFactory objectFactory) {
|
||||
this.versionProperties = objectFactory.setProperty(VersionProperty.class);
|
||||
}
|
||||
|
||||
@Input
|
||||
public SetProperty<VersionProperty> 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("|===");
|
||||
}
|
||||
}
|
||||
|
||||
}
|
@ -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<ConstrainedVersion> constrainedVersions = new TreeSet<>();
|
||||
|
||||
private final Set<VersionProperty> versionProperties = new TreeSet<>();
|
||||
|
||||
private final List<String> projectPaths = new ArrayList<String>();
|
||||
|
||||
public ExtractVersionConstraints() {
|
||||
@ -74,10 +79,16 @@ public class ExtractVersionConstraints extends AbstractTask {
|
||||
return this.constrainedVersions;
|
||||
}
|
||||
|
||||
@Internal
|
||||
public Set<VersionProperty> 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<VersionProperty>, 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);
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
}
|
||||
|
@ -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"
|
||||
|
@ -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[]
|
||||
|
@ -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 `<properties>` 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 <<appendix-dependency-versions.adoc#version-properties, `Version properties`>> 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"]
|
||||
|
@ -81,7 +81,7 @@ For instance, to upgrade to another Spring Data release train, you would add the
|
||||
</properties>
|
||||
----
|
||||
|
||||
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 <<howto.adoc#howto-customize-dependency-versions, Customize Dependency Versions "`How-to`">> for more information.
|
||||
|
||||
|
||||
|
||||
|
@ -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
|
||||
|
@ -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:
|
||||
|
Loading…
Reference in New Issue
Block a user