From 63be659df23fde8eaf0942361a219060ad855287 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Thu, 6 Aug 2026 13:53:09 +0200 Subject: [PATCH 1/3] Rename the site documents ahead of converting them A pure rename, so that git records it and `git log --follow` and `git blame` still reach the history of each page after the conversion that follows. The content is still APT at this point and the site does not build between the two commits. --- apache-maven/src/site/{apt/index.apt.vm => markdown/index.md.vm} | 0 api/maven-api-cli/src/site/{apt/index.apt => markdown/index.md} | 0 .../src/site/{apt/index.apt => markdown/index.md} | 0 api/maven-api-model/src/site/{apt/index.apt => markdown/index.md} | 0 .../src/site/{apt/index.apt => markdown/index.md} | 0 .../src/site/{apt/index.apt => markdown/index.md} | 0 .../src/site/{apt/index.apt => markdown/index.md} | 0 .../maven-artifact/src/site/{apt/index.apt => markdown/index.md} | 0 compat/maven-compat/src/site/{apt/index.apt => markdown/index.md} | 0 .../src/site/{apt/cli.apt.vm => markdown/cli.md.vm} | 0 .../src/site/{apt/index.apt.vm => markdown/index.md.vm} | 0 .../src/site/{apt/logging.apt => markdown/logging.md} | 0 .../src/site/{apt/index.apt => markdown/index.md} | 0 .../src/site/{apt/super-pom.apt.vm => markdown/super-pom.md.vm} | 0 compat/maven-model/src/site/{apt/index.apt => markdown/index.md} | 0 .../src/site/{apt/index.apt => markdown/index.md} | 0 .../src/site/{apt/index.apt => markdown/index.md} | 0 .../{apt/dependency-types.apt => markdown/dependency-types.md} | 0 .../src/site/{apt/index.apt => markdown/index.md} | 0 .../maven-settings/src/site/{apt/index.apt => markdown/index.md} | 0 .../src/site/{apt/index.apt => markdown/index.md} | 0 .../{apt/artifact-handlers.apt => markdown/artifact-handlers.md} | 0 .../configuration-management.md} | 0 .../core-extensions.apt.vm => markdown/core-extensions.md.vm} | 0 .../default-bindings.apt.vm => markdown/default-bindings.md.vm} | 0 .../getting-to-container-configured-mojos.md} | 0 impl/maven-core/src/site/{apt/index.apt => markdown/index.md} | 0 .../src/site/{apt/inheritance.apt => markdown/inheritance.md} | 0 .../src/site/{apt/lifecycles.apt.vm => markdown/lifecycles.md.vm} | 0 .../src/site/{apt/offline-mode.apt => markdown/offline-mode.md} | 0 .../plugin-execution-isolation.md} | 0 .../{apt/dependency-types.apt => markdown/dependency-types.md} | 0 impl/maven-logging/src/site/{apt/index.apt => markdown/index.md} | 0 .../src/site/{apt/bootstrap.apt.vm => markdown/bootstrap.md.vm} | 0 .../src/site/{apt/index.apt.vm => markdown/index.md.vm} | 0 .../src/site/{apt/index.apt.vm => markdown/index.md.vm} | 0 .../src/site/{apt/index.apt.vm => markdown/index.md.vm} | 0 its/src/site/{apt/index.apt => markdown/index.md} | 0 38 files changed, 0 insertions(+), 0 deletions(-) rename apache-maven/src/site/{apt/index.apt.vm => markdown/index.md.vm} (100%) rename api/maven-api-cli/src/site/{apt/index.apt => markdown/index.md} (100%) rename api/maven-api-metadata/src/site/{apt/index.apt => markdown/index.md} (100%) rename api/maven-api-model/src/site/{apt/index.apt => markdown/index.md} (100%) rename api/maven-api-plugin/src/site/{apt/index.apt => markdown/index.md} (100%) rename api/maven-api-settings/src/site/{apt/index.apt => markdown/index.md} (100%) rename api/maven-api-toolchain/src/site/{apt/index.apt => markdown/index.md} (100%) rename compat/maven-artifact/src/site/{apt/index.apt => markdown/index.md} (100%) rename compat/maven-compat/src/site/{apt/index.apt => markdown/index.md} (100%) rename compat/maven-embedder/src/site/{apt/cli.apt.vm => markdown/cli.md.vm} (100%) rename compat/maven-embedder/src/site/{apt/index.apt.vm => markdown/index.md.vm} (100%) rename compat/maven-embedder/src/site/{apt/logging.apt => markdown/logging.md} (100%) rename compat/maven-model-builder/src/site/{apt/index.apt => markdown/index.md} (100%) rename compat/maven-model-builder/src/site/{apt/super-pom.apt.vm => markdown/super-pom.md.vm} (100%) rename compat/maven-model/src/site/{apt/index.apt => markdown/index.md} (100%) rename compat/maven-plugin-api/src/site/{apt/index.apt => markdown/index.md} (100%) rename compat/maven-repository-metadata/src/site/{apt/index.apt => markdown/index.md} (100%) rename compat/maven-resolver-provider/src/site/{apt/dependency-types.apt => markdown/dependency-types.md} (100%) rename compat/maven-resolver-provider/src/site/{apt/index.apt => markdown/index.md} (100%) rename compat/maven-settings/src/site/{apt/index.apt => markdown/index.md} (100%) rename compat/maven-toolchain-model/src/site/{apt/index.apt => markdown/index.md} (100%) rename impl/maven-core/src/site/{apt/artifact-handlers.apt => markdown/artifact-handlers.md} (100%) rename impl/maven-core/src/site/{apt/configuration-management.apt => markdown/configuration-management.md} (100%) rename impl/maven-core/src/site/{apt/core-extensions.apt.vm => markdown/core-extensions.md.vm} (100%) rename impl/maven-core/src/site/{apt/default-bindings.apt.vm => markdown/default-bindings.md.vm} (100%) rename impl/maven-core/src/site/{apt/getting-to-container-configured-mojos.apt => markdown/getting-to-container-configured-mojos.md} (100%) rename impl/maven-core/src/site/{apt/index.apt => markdown/index.md} (100%) rename impl/maven-core/src/site/{apt/inheritance.apt => markdown/inheritance.md} (100%) rename impl/maven-core/src/site/{apt/lifecycles.apt.vm => markdown/lifecycles.md.vm} (100%) rename impl/maven-core/src/site/{apt/offline-mode.apt => markdown/offline-mode.md} (100%) rename impl/maven-core/src/site/{apt/plugin-execution-isolation.apt => markdown/plugin-execution-isolation.md} (100%) rename impl/maven-impl/src/site/{apt/dependency-types.apt => markdown/dependency-types.md} (100%) rename impl/maven-logging/src/site/{apt/index.apt => markdown/index.md} (100%) rename its/core-it-suite/src/site/{apt/bootstrap.apt.vm => markdown/bootstrap.md.vm} (100%) rename its/core-it-suite/src/site/{apt/index.apt.vm => markdown/index.md.vm} (100%) rename its/core-it-support/core-it-plugins/maven-it-plugin-core-stubs/src/site/{apt/index.apt.vm => markdown/index.md.vm} (100%) rename its/core-it-support/core-it-plugins/src/site/{apt/index.apt.vm => markdown/index.md.vm} (100%) rename its/src/site/{apt/index.apt => markdown/index.md} (100%) diff --git a/apache-maven/src/site/apt/index.apt.vm b/apache-maven/src/site/markdown/index.md.vm similarity index 100% rename from apache-maven/src/site/apt/index.apt.vm rename to apache-maven/src/site/markdown/index.md.vm diff --git a/api/maven-api-cli/src/site/apt/index.apt b/api/maven-api-cli/src/site/markdown/index.md similarity index 100% rename from api/maven-api-cli/src/site/apt/index.apt rename to api/maven-api-cli/src/site/markdown/index.md diff --git a/api/maven-api-metadata/src/site/apt/index.apt b/api/maven-api-metadata/src/site/markdown/index.md similarity index 100% rename from api/maven-api-metadata/src/site/apt/index.apt rename to api/maven-api-metadata/src/site/markdown/index.md diff --git a/api/maven-api-model/src/site/apt/index.apt b/api/maven-api-model/src/site/markdown/index.md similarity index 100% rename from api/maven-api-model/src/site/apt/index.apt rename to api/maven-api-model/src/site/markdown/index.md diff --git a/api/maven-api-plugin/src/site/apt/index.apt b/api/maven-api-plugin/src/site/markdown/index.md similarity index 100% rename from api/maven-api-plugin/src/site/apt/index.apt rename to api/maven-api-plugin/src/site/markdown/index.md diff --git a/api/maven-api-settings/src/site/apt/index.apt b/api/maven-api-settings/src/site/markdown/index.md similarity index 100% rename from api/maven-api-settings/src/site/apt/index.apt rename to api/maven-api-settings/src/site/markdown/index.md diff --git a/api/maven-api-toolchain/src/site/apt/index.apt b/api/maven-api-toolchain/src/site/markdown/index.md similarity index 100% rename from api/maven-api-toolchain/src/site/apt/index.apt rename to api/maven-api-toolchain/src/site/markdown/index.md diff --git a/compat/maven-artifact/src/site/apt/index.apt b/compat/maven-artifact/src/site/markdown/index.md similarity index 100% rename from compat/maven-artifact/src/site/apt/index.apt rename to compat/maven-artifact/src/site/markdown/index.md diff --git a/compat/maven-compat/src/site/apt/index.apt b/compat/maven-compat/src/site/markdown/index.md similarity index 100% rename from compat/maven-compat/src/site/apt/index.apt rename to compat/maven-compat/src/site/markdown/index.md diff --git a/compat/maven-embedder/src/site/apt/cli.apt.vm b/compat/maven-embedder/src/site/markdown/cli.md.vm similarity index 100% rename from compat/maven-embedder/src/site/apt/cli.apt.vm rename to compat/maven-embedder/src/site/markdown/cli.md.vm diff --git a/compat/maven-embedder/src/site/apt/index.apt.vm b/compat/maven-embedder/src/site/markdown/index.md.vm similarity index 100% rename from compat/maven-embedder/src/site/apt/index.apt.vm rename to compat/maven-embedder/src/site/markdown/index.md.vm diff --git a/compat/maven-embedder/src/site/apt/logging.apt b/compat/maven-embedder/src/site/markdown/logging.md similarity index 100% rename from compat/maven-embedder/src/site/apt/logging.apt rename to compat/maven-embedder/src/site/markdown/logging.md diff --git a/compat/maven-model-builder/src/site/apt/index.apt b/compat/maven-model-builder/src/site/markdown/index.md similarity index 100% rename from compat/maven-model-builder/src/site/apt/index.apt rename to compat/maven-model-builder/src/site/markdown/index.md diff --git a/compat/maven-model-builder/src/site/apt/super-pom.apt.vm b/compat/maven-model-builder/src/site/markdown/super-pom.md.vm similarity index 100% rename from compat/maven-model-builder/src/site/apt/super-pom.apt.vm rename to compat/maven-model-builder/src/site/markdown/super-pom.md.vm diff --git a/compat/maven-model/src/site/apt/index.apt b/compat/maven-model/src/site/markdown/index.md similarity index 100% rename from compat/maven-model/src/site/apt/index.apt rename to compat/maven-model/src/site/markdown/index.md diff --git a/compat/maven-plugin-api/src/site/apt/index.apt b/compat/maven-plugin-api/src/site/markdown/index.md similarity index 100% rename from compat/maven-plugin-api/src/site/apt/index.apt rename to compat/maven-plugin-api/src/site/markdown/index.md diff --git a/compat/maven-repository-metadata/src/site/apt/index.apt b/compat/maven-repository-metadata/src/site/markdown/index.md similarity index 100% rename from compat/maven-repository-metadata/src/site/apt/index.apt rename to compat/maven-repository-metadata/src/site/markdown/index.md diff --git a/compat/maven-resolver-provider/src/site/apt/dependency-types.apt b/compat/maven-resolver-provider/src/site/markdown/dependency-types.md similarity index 100% rename from compat/maven-resolver-provider/src/site/apt/dependency-types.apt rename to compat/maven-resolver-provider/src/site/markdown/dependency-types.md diff --git a/compat/maven-resolver-provider/src/site/apt/index.apt b/compat/maven-resolver-provider/src/site/markdown/index.md similarity index 100% rename from compat/maven-resolver-provider/src/site/apt/index.apt rename to compat/maven-resolver-provider/src/site/markdown/index.md diff --git a/compat/maven-settings/src/site/apt/index.apt b/compat/maven-settings/src/site/markdown/index.md similarity index 100% rename from compat/maven-settings/src/site/apt/index.apt rename to compat/maven-settings/src/site/markdown/index.md diff --git a/compat/maven-toolchain-model/src/site/apt/index.apt b/compat/maven-toolchain-model/src/site/markdown/index.md similarity index 100% rename from compat/maven-toolchain-model/src/site/apt/index.apt rename to compat/maven-toolchain-model/src/site/markdown/index.md diff --git a/impl/maven-core/src/site/apt/artifact-handlers.apt b/impl/maven-core/src/site/markdown/artifact-handlers.md similarity index 100% rename from impl/maven-core/src/site/apt/artifact-handlers.apt rename to impl/maven-core/src/site/markdown/artifact-handlers.md diff --git a/impl/maven-core/src/site/apt/configuration-management.apt b/impl/maven-core/src/site/markdown/configuration-management.md similarity index 100% rename from impl/maven-core/src/site/apt/configuration-management.apt rename to impl/maven-core/src/site/markdown/configuration-management.md diff --git a/impl/maven-core/src/site/apt/core-extensions.apt.vm b/impl/maven-core/src/site/markdown/core-extensions.md.vm similarity index 100% rename from impl/maven-core/src/site/apt/core-extensions.apt.vm rename to impl/maven-core/src/site/markdown/core-extensions.md.vm diff --git a/impl/maven-core/src/site/apt/default-bindings.apt.vm b/impl/maven-core/src/site/markdown/default-bindings.md.vm similarity index 100% rename from impl/maven-core/src/site/apt/default-bindings.apt.vm rename to impl/maven-core/src/site/markdown/default-bindings.md.vm diff --git a/impl/maven-core/src/site/apt/getting-to-container-configured-mojos.apt b/impl/maven-core/src/site/markdown/getting-to-container-configured-mojos.md similarity index 100% rename from impl/maven-core/src/site/apt/getting-to-container-configured-mojos.apt rename to impl/maven-core/src/site/markdown/getting-to-container-configured-mojos.md diff --git a/impl/maven-core/src/site/apt/index.apt b/impl/maven-core/src/site/markdown/index.md similarity index 100% rename from impl/maven-core/src/site/apt/index.apt rename to impl/maven-core/src/site/markdown/index.md diff --git a/impl/maven-core/src/site/apt/inheritance.apt b/impl/maven-core/src/site/markdown/inheritance.md similarity index 100% rename from impl/maven-core/src/site/apt/inheritance.apt rename to impl/maven-core/src/site/markdown/inheritance.md diff --git a/impl/maven-core/src/site/apt/lifecycles.apt.vm b/impl/maven-core/src/site/markdown/lifecycles.md.vm similarity index 100% rename from impl/maven-core/src/site/apt/lifecycles.apt.vm rename to impl/maven-core/src/site/markdown/lifecycles.md.vm diff --git a/impl/maven-core/src/site/apt/offline-mode.apt b/impl/maven-core/src/site/markdown/offline-mode.md similarity index 100% rename from impl/maven-core/src/site/apt/offline-mode.apt rename to impl/maven-core/src/site/markdown/offline-mode.md diff --git a/impl/maven-core/src/site/apt/plugin-execution-isolation.apt b/impl/maven-core/src/site/markdown/plugin-execution-isolation.md similarity index 100% rename from impl/maven-core/src/site/apt/plugin-execution-isolation.apt rename to impl/maven-core/src/site/markdown/plugin-execution-isolation.md diff --git a/impl/maven-impl/src/site/apt/dependency-types.apt b/impl/maven-impl/src/site/markdown/dependency-types.md similarity index 100% rename from impl/maven-impl/src/site/apt/dependency-types.apt rename to impl/maven-impl/src/site/markdown/dependency-types.md diff --git a/impl/maven-logging/src/site/apt/index.apt b/impl/maven-logging/src/site/markdown/index.md similarity index 100% rename from impl/maven-logging/src/site/apt/index.apt rename to impl/maven-logging/src/site/markdown/index.md diff --git a/its/core-it-suite/src/site/apt/bootstrap.apt.vm b/its/core-it-suite/src/site/markdown/bootstrap.md.vm similarity index 100% rename from its/core-it-suite/src/site/apt/bootstrap.apt.vm rename to its/core-it-suite/src/site/markdown/bootstrap.md.vm diff --git a/its/core-it-suite/src/site/apt/index.apt.vm b/its/core-it-suite/src/site/markdown/index.md.vm similarity index 100% rename from its/core-it-suite/src/site/apt/index.apt.vm rename to its/core-it-suite/src/site/markdown/index.md.vm diff --git a/its/core-it-support/core-it-plugins/maven-it-plugin-core-stubs/src/site/apt/index.apt.vm b/its/core-it-support/core-it-plugins/maven-it-plugin-core-stubs/src/site/markdown/index.md.vm similarity index 100% rename from its/core-it-support/core-it-plugins/maven-it-plugin-core-stubs/src/site/apt/index.apt.vm rename to its/core-it-support/core-it-plugins/maven-it-plugin-core-stubs/src/site/markdown/index.md.vm diff --git a/its/core-it-support/core-it-plugins/src/site/apt/index.apt.vm b/its/core-it-support/core-it-plugins/src/site/markdown/index.md.vm similarity index 100% rename from its/core-it-support/core-it-plugins/src/site/apt/index.apt.vm rename to its/core-it-support/core-it-plugins/src/site/markdown/index.md.vm diff --git a/its/src/site/apt/index.apt b/its/src/site/markdown/index.md similarity index 100% rename from its/src/site/apt/index.apt rename to its/src/site/markdown/index.md From a1d64730d7df41b9f6cc254790ff81bbcb17ea0b Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Thu, 6 Aug 2026 13:53:09 +0200 Subject: [PATCH 2/3] Port the site documentation from APT to Markdown 38 page(s) converted with doxia-converter and then cleaned up by hand: - <<>> becomes backticks, <> becomes **bold**, {{{url}text}} becomes [text](url) - the ASF license header becomes a single block HTML comment - a page whose only Velocity reference was ${project.name} is now a plain .md with the title spelled out - a page that keeps a reference stays a .vm. Velocity reads ## as a line comment and would silently swallow every ATX heading below level one, so subsections use setext underlines and anything deeper is wrapped in #[[ ... ]]# - a reference APT rendered literally is escaped with ${esc.d} Two tests read the dependency types table straight out of the site documentation to check it against DefaultTypeProvider, so they follow the page to Markdown. APT let a table carry a second header row part way down to group the rows beneath it; a Markdown table has one header row only, so those group labels are now ordinary rows carrying bold text, and the tests skip a row whose only filled column is the first. Verified by building the site before and after and comparing every generated page: the visible text and the link targets are unchanged apart from / becoming / and quotes and ellipses in prose picking up the Markdown module's typographic substitution. The four modules under its/ could not be built here, so their five pages are converted but unverified. --- apache-maven/src/site/markdown/index.md.vm | 63 ++-- api/maven-api-cli/src/site/markdown/index.md | 58 ++- .../src/site/markdown/index.md | 47 ++- .../src/site/markdown/index.md | 52 ++- .../src/site/markdown/index.md | 47 ++- .../src/site/markdown/index.md | 51 ++- .../src/site/markdown/index.md | 51 ++- .../maven-artifact/src/site/markdown/index.md | 68 ++-- .../maven-compat/src/site/markdown/index.md | 48 ++- .../src/site/markdown/cli.md.vm | 44 +-- .../src/site/markdown/index.md.vm | 90 ++--- .../src/site/markdown/logging.md | 128 +++---- .../src/site/markdown/index.md | 337 +++++------------- .../src/site/markdown/super-pom.md.vm | 46 ++- compat/maven-model/src/site/markdown/index.md | 57 ++- .../src/site/markdown/index.md | 62 ++-- .../src/site/markdown/index.md | 77 ++-- .../src/site/markdown/dependency-types.md | 122 +++---- .../src/site/markdown/index.md | 51 ++- .../type/DefaultTypeProviderTest.java | 26 +- .../maven-settings/src/site/markdown/index.md | 87 ++--- .../src/site/markdown/index.md | 55 ++- .../src/site/markdown/artifact-handlers.md | 89 ++--- .../site/markdown/configuration-management.md | 175 ++++----- .../src/site/markdown/core-extensions.md.vm | 46 ++- .../src/site/markdown/default-bindings.md.vm | 87 +++-- .../getting-to-container-configured-mojos.md | 116 ++---- impl/maven-core/src/site/markdown/index.md | 125 +++---- .../src/site/markdown/inheritance.md | 110 +++--- .../src/site/markdown/lifecycles.md.vm | 68 ++-- .../src/site/markdown/offline-mode.md | 295 +++++---------- .../markdown/plugin-execution-isolation.md | 67 ++-- .../artifact/handler/ArtifactHandlerTest.java | 21 +- .../src/site/markdown/dependency-types.md | 122 +++---- .../type/DefaultTypeProviderTest.java | 26 +- impl/maven-logging/src/site/markdown/index.md | 51 ++- .../src/site/markdown/bootstrap.md.vm | 127 +++---- .../src/site/markdown/index.md.vm | 112 +++--- .../src/site/markdown/index.md.vm | 14 +- .../src/site/markdown/index.md.vm | 14 +- its/src/site/markdown/index.md | 103 +++--- 41 files changed, 1341 insertions(+), 2094 deletions(-) diff --git a/apache-maven/src/site/markdown/index.md.vm b/apache-maven/src/site/markdown/index.md.vm index ae7ff8fd49ed..318bc03df87a 100644 --- a/apache-maven/src/site/markdown/index.md.vm +++ b/apache-maven/src/site/markdown/index.md.vm @@ -1,43 +1,32 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - ${project.description} +# ${project.name} -* References +${project.description} - * <<>> invocation can be customized through pre-invocation script calls, that can be disabled by setting <<>> environment variable: +References +---------- -*----------+--------------------------------------------+-----------------------+ -|| || system level || user level -*----------+--------------------------------------------+-----------------------+ -|| POSIX | <<>>\ -|| | <<>> (since 3.8.2) | <<<$HOME/.mavenrc>>> -*----------+--------------------------------------------+-----------------------+ -|| Windows | <<<%PROGRAMDATA%\\mavenrc.cmd>>> (since 4) | <<<%USERPROFILE%\\mavenrc_pre.bat>>>\ -|| | | <<<%USERPROFILE%\\mavenrc_pre.cmd>>> (since 3.3.1)\ -|| | | <<<%USERPROFILE%\\mavenrc.cmd>>> (since 4) -*----------+--------------------------------------------+-----------------------+ +- `mvn` invocation can be customized through pre-invocation script calls, that can be disabled by setting `MAVEN_SKIP_RC` environment variable: + + ||system level|user level| +|:---|:---|:---| +|POSIX|`/etc/mavenrc` 
`/usr/local/etc/mavenrc` (since 3.8.2)|`$HOME/.mavenrc`| +|Windows|`%PROGRAMDATA%\mavenrc.cmd` (since 4)|`%USERPROFILE%\mavenrc_pre.bat` 
`%USERPROFILE%\mavenrc_pre.cmd` (since 3.3.1) 
`%USERPROFILE%\mavenrc.cmd` (since 4)| diff --git a/api/maven-api-cli/src/site/markdown/index.md b/api/maven-api-cli/src/site/markdown/index.md index 8d901b352531..a34155f1d4c5 100644 --- a/api/maven-api-cli/src/site/markdown/index.md +++ b/api/maven-api-cli/src/site/markdown/index.md @@ -1,41 +1,31 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - This is the {{{./apidocs/org/apache/maven/api/cli/package-summary.html}API}} for Maven's command-line interface and - tools: +# Maven 4 API - CLI - * <<<{{{./apidocs/org/apache/maven/api/cli/mvn/package-summary.html}mvn}}>>>, the Maven build tool, +This is the [API](./apidocs/org/apache/maven/api/cli/package-summary.html) for Maven's command-line interface and tools: - * <<<{{{./apidocs/org/apache/maven/api/cli/mvnenc/package-summary.html}mvnenc}}>>>, the Maven Password Encryption tool, +- [`mvn`](./apidocs/org/apache/maven/api/cli/mvn/package-summary.html), the Maven build tool, +- [`mvnenc`](./apidocs/org/apache/maven/api/cli/mvnenc/package-summary.html), the Maven Password Encryption tool, +- [`mvnsh`](./apidocs/org/apache/maven/api/cli/mvnsh/package-summary.html), the Maven Shell tool, +- [`mvnup`](./apidocs/org/apache/maven/api/cli/mvnup/package-summary.html), the Maven Upgrade tool. - * <<<{{{./apidocs/org/apache/maven/api/cli/mvnsh/package-summary.html}mvnsh}}>>>, the Maven Shell tool, +This API also defines [Core Extensions model](./core-extensions.html) for `.mvn/extensions.xml`. - * <<<{{{./apidocs/org/apache/maven/api/cli/mvnup/package-summary.html}mvnup}}>>>, the Maven Upgrade tool. - - This API also defines {{{./core-extensions.html}Core Extensions model}} for <<<.mvn/extensions.xml>>>. - - See also associated {{{../../impl/maven-cli/index.html}implementation}}. \ No newline at end of file +See also associated [implementation](../../impl/maven-cli/index.html). diff --git a/api/maven-api-metadata/src/site/markdown/index.md b/api/maven-api-metadata/src/site/markdown/index.md index a3f76ef0a6e5..d57d2d69ba4c 100644 --- a/api/maven-api-metadata/src/site/markdown/index.md +++ b/api/maven-api-metadata/src/site/markdown/index.md @@ -1,33 +1,26 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - This is the immutable model for Repository Metadata in <<>> package. +# Maven 4 API - Repository Metadata Model - The following are generated from this model: +This is the immutable model for Repository Metadata in `org.apache.maven.api.metadata` package. - * {{{./apidocs/index.html}Java sources}} with <<>> inner classes for immutable instances creation. +The following are generated from this model: +- [Java sources](./apidocs/index.html) with `Builder` inner classes for immutable instances creation. diff --git a/api/maven-api-model/src/site/markdown/index.md b/api/maven-api-model/src/site/markdown/index.md index 5720df24da9f..ce6f082dbf5d 100644 --- a/api/maven-api-model/src/site/markdown/index.md +++ b/api/maven-api-model/src/site/markdown/index.md @@ -1,36 +1,28 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - This is strictly the immutable model for Maven POM (Project Object Model), so really just plain objects in <<>> package. +# Maven 4 API - Immutable Maven Model - The following are generated from this model: +This is strictly the immutable model for Maven POM (Project Object Model), so really just plain objects in `org.apache.maven.api.model` package. - * {{{./apidocs/index.html}Java sources}} with <<>> inner classes for immutable instances creation. +The following are generated from this model: - See also corresponding {{{../../compat/maven-model/index.html}Maven classical POM model documentation}}. +- [Java sources](./apidocs/index.html) with `Builder` inner classes for immutable instances creation. + +See also corresponding [Maven classical POM model documentation](../../compat/maven-model/index.html). diff --git a/api/maven-api-plugin/src/site/markdown/index.md b/api/maven-api-plugin/src/site/markdown/index.md index f229c29d8a8e..80594703890f 100644 --- a/api/maven-api-plugin/src/site/markdown/index.md +++ b/api/maven-api-plugin/src/site/markdown/index.md @@ -1,33 +1,26 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - This is the immutable model for Maven Plugin Descriptor in <<>> package. +# Maven 4 API - Plugin Descriptor Model - The following are generated from this model: +This is the immutable model for Maven Plugin Descriptor in `org.apache.maven.api.plugin.descriptor` package. - * {{{./apidocs/index.html}Java sources}} with <<>> inner classes for immutable instances creation. +The following are generated from this model: +- [Java sources](./apidocs/index.html) with `Builder` inner classes for immutable instances creation. diff --git a/api/maven-api-settings/src/site/markdown/index.md b/api/maven-api-settings/src/site/markdown/index.md index b650c8e1c9ce..634fc2f4ddd1 100644 --- a/api/maven-api-settings/src/site/markdown/index.md +++ b/api/maven-api-settings/src/site/markdown/index.md @@ -1,35 +1,28 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - This is strictly the immutable model for Maven settings in <<>> package. +# Maven 4 API - Immutable Settings Model - The following are generated from this model: +This is strictly the immutable model for Maven settings in `org.apache.maven.api.settings` package. - * {{{./apidocs/index.html}Java sources}} with <<>> inner classes for immutable instances creation. +The following are generated from this model: - See also corresponding {{{../../compat/maven-settings/index.html}Maven classical settings model documentation}}. - \ No newline at end of file +- [Java sources](./apidocs/index.html) with `Builder` inner classes for immutable instances creation. + +See also corresponding [Maven classical settings model documentation](../../compat/maven-settings/index.html). diff --git a/api/maven-api-toolchain/src/site/markdown/index.md b/api/maven-api-toolchain/src/site/markdown/index.md index f1a76e9c98bd..1f98b89e261a 100644 --- a/api/maven-api-toolchain/src/site/markdown/index.md +++ b/api/maven-api-toolchain/src/site/markdown/index.md @@ -1,35 +1,28 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - This is strictly the immutable model for Maven toolchains in <<>> package. +# Maven 4 API - Immutable Toolchains Model - The following are generated from this model: +This is strictly the immutable model for Maven toolchains in `org.apache.maven.api.toolchain` package. - * {{{./apidocs/index.html}Java sources}} with <<>> inner classes for immutable instances creation. +The following are generated from this model: - See also corresponding {{{../../compat/maven-toolchain-model/index.html}Maven classical toolchains model documentation}}. - \ No newline at end of file +- [Java sources](./apidocs/index.html) with `Builder` inner classes for immutable instances creation. + +See also corresponding [Maven classical toolchains model documentation](../../compat/maven-toolchain-model/index.html). diff --git a/compat/maven-artifact/src/site/markdown/index.md b/compat/maven-artifact/src/site/markdown/index.md index f796c1184435..650c17748e52 100644 --- a/compat/maven-artifact/src/site/markdown/index.md +++ b/compat/maven-artifact/src/site/markdown/index.md @@ -1,36 +1,29 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. - - ----- - Introduction - ----- - Hervé Boutemy - ----- - 2014-11-30 - ----- - -Maven Artifact - - Maven Artifact classes, providing <<>> interface ({{{./apidocs/org/apache/maven/artifact/Artifact.html}javadoc}}), - with its <<>> implementation ({{{./xref/org/apache/maven/artifact/DefaultArtifact.html}source}}). - - The jar file is executable and provides a little tool to display how Maven parses and compares versions: - -+----+ + + +# Maven Artifact + +Maven Artifact classes, providing `Artifact` interface ([javadoc](./apidocs/org/apache/maven/artifact/Artifact.html)), with its `DefaultArtifact` implementation ([source](./xref/org/apache/maven/artifact/DefaultArtifact.html)). + +The jar file is executable and provides a little tool to display how Maven parses and compares versions: + +```shell $ java -jar maven-artifact-*.jar 3.2.4-alpha-1 3.2.4-SNAPSHOT 3.2.4.0 Display parameters as parsed by Maven (in canonical form) and comparison result: 1. 3.2.4-alpha-1 == 3.2.4.alpha.1 @@ -38,10 +31,9 @@ Display parameters as parsed by Maven (in canonical form) and comparison result: 2. 3.2.4-SNAPSHOT == 3.2.4.snapshot 3.2.4-SNAPSHOT < 3.2.4.0 3. 3.2.4.0 == 3.2.4 -+----+ - -* Useful entry points +``` - * artifact version comparison {{{./apidocs/org/apache/maven/artifact/versioning/ComparableVersion.html}javadoc}}, +## Useful entry points - * {{{./apidocs/org/apache/maven/artifact/versioning/VersionRange.html}version range}}. +- artifact version comparison [javadoc](./apidocs/org/apache/maven/artifact/versioning/ComparableVersion.html), +- [version range](./apidocs/org/apache/maven/artifact/versioning/VersionRange.html). diff --git a/compat/maven-compat/src/site/markdown/index.md b/compat/maven-compat/src/site/markdown/index.md index a288cdcc3d2e..047fbf805eab 100644 --- a/compat/maven-compat/src/site/markdown/index.md +++ b/compat/maven-compat/src/site/markdown/index.md @@ -1,32 +1,24 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - Maven2 classes maintained as compatibility layer for plugins that need to keep Maven2 compatibility. +# Maven Compat - Plugins should avoid these classes and be updated to use only Maven3 dependencies (and require Maven3): see - {{{https://cwiki.apache.org/confluence/display/MAVEN/Plugin+migration+to+Maven3+dependencies} Plugin migration to Maven3 dependencies}} - documentation to get hints on how to make the update. +Maven2 classes maintained as compatibility layer for plugins that need to keep Maven2 compatibility. + +Plugins should avoid these classes and be updated to use only Maven3 dependencies (and require Maven3): see [Plugin migration to Maven3 dependencies](https://cwiki.apache.org/confluence/display/MAVEN/Plugin+migration+to+Maven3+dependencies) documentation to get hints on how to make the update. diff --git a/compat/maven-embedder/src/site/markdown/cli.md.vm b/compat/maven-embedder/src/site/markdown/cli.md.vm index b5dcae7122bf..131e0e156bca 100644 --- a/compat/maven-embedder/src/site/markdown/cli.md.vm +++ b/compat/maven-embedder/src/site/markdown/cli.md.vm @@ -1,28 +1,22 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + -%{snippet|file=${project.basedir}/target/test-classes/options.html|verbatim=false} +# Maven CLI Options Reference + + diff --git a/compat/maven-embedder/src/site/markdown/index.md.vm b/compat/maven-embedder/src/site/markdown/index.md.vm index e25d04925d58..ea69c077656c 100644 --- a/compat/maven-embedder/src/site/markdown/index.md.vm +++ b/compat/maven-embedder/src/site/markdown/index.md.vm @@ -1,52 +1,38 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. - - ----- - ${project.name} - ----- - Hervé Boutemy - ----- - 2016-11-14 - ----- - -${project.name} - - ${project.description} - -* Useful entry points - - * {{{./apidocs/org/apache/maven/cli/MavenCli.html}MavenCli.doMain(CliRequest)}} is the main method preparing runtime environment before running {{{../maven-core/}Maven.execute()}} - -* References - - * {{{./cli.html}CLI options}}, - - * {{{./logging.html}logging API}}. - - * since 3.3.1 (see {{{/docs/3.3.1/release-notes.html#Core_Extensions}3.3.1 release notes}} for more details), - per project settings can be defined by files in <<<.mvn/>>> directory: - - * <<<.mvn/jvm.config>>> containing jvm options, - - * <<<.mvn/maven.config>>> containing Maven command-line parameter, - - * <<<.mvn/extensions.xml>>> containing {{{./core-extensions.html}a list of extensions}}, - - * since 3.5.0, output is colorized by default, with color disabled in batch mode: see - {{{/shared/maven-shared-utils/apidocs/org/apache/maven/shared/utils/logging/package-summary.html}styled message API}} - for more details on adding color to a plugin output or customizing colors. - + + +# ${project.name} + +${project.description} + +Useful entry points +------------------- + +- [MavenCli.doMain(CliRequest)](./apidocs/org/apache/maven/cli/MavenCli.html) is the main method preparing runtime environment before running [Maven.execute()](../maven-core/) + +References +---------- + +- [CLI options](./cli.html), +- [logging API](./logging.html). +- since 3.3.1 (see [3.3.1 release notes](/docs/3.3.1/release-notes.html#Core_Extensions) for more details), per project settings can be defined by files in `.mvn/` directory: + - `.mvn/jvm.config` containing jvm options, + - `.mvn/maven.config` containing Maven command-line parameter, + - `.mvn/extensions.xml` containing [a list of extensions](./core-extensions.html), +- since 3.5.0, output is colorized by default, with color disabled in batch mode: see [styled message API](/shared/maven-shared-utils/apidocs/org/apache/maven/shared/utils/logging/package-summary.html) for more details on adding color to a plugin output or customizing colors. diff --git a/compat/maven-embedder/src/site/markdown/logging.md b/compat/maven-embedder/src/site/markdown/logging.md index 3793ba762312..6c5b646b5122 100644 --- a/compat/maven-embedder/src/site/markdown/logging.md +++ b/compat/maven-embedder/src/site/markdown/logging.md @@ -1,75 +1,50 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. - - ----- - Maven Logging - ----- - Hervé Boutemy - ----- - 2013-08-02 - ----- - -Maven Logging - - {{{/maven-logging.html}End-user logging documentation}} is available {{{/maven-logging.html}in Maven site}}. - This documentation is focused on internal implementation details. - -* Logging API - - Maven uses - {{{https://codehaus-plexus.github.io/plexus-containers/plexus-container-default/apidocs/org/codehaus/plexus/logging/package-summary.html}Plexus - Container logging API}}, like any other Plexus components, ie - {{{https://codehaus-plexus.github.io/plexus-containers/plexus-container-default/apidocs/org/codehaus/plexus/logging/LoggerManager.html}LoggerManager}} - / {{{https://codehaus-plexus.github.io/plexus-containers/plexus-container-default/apidocs/org/codehaus/plexus/logging/Logger.html}Logger}}. - - Starting with Maven 3.1.0: - - * Maven supports SLF4J API logging API too, ie {{{http://slf4j.org/apidocs/org/slf4j/LoggerFactory.html}LoggerFactory}} / - {{{http://slf4j.org/apidocs/org/slf4j/Logger.html}Logger}}, - - * instead of implementing Plexus logging API itself with basic output to console, Maven implements it using SLF4J API in - {{{./apidocs/org/apache/maven/cli/logging/Slf4jLoggerManager.html}Slf4jLoggerManager}} - / {{{./apidocs/org/apache/maven/cli/logging/Slf4jLogger.html}Slf4jLogger}}. - - -* Logging Implementation - - Maven 3.1.0 ships bundled with {{{https://www.slf4j.org/api/org/slf4j/simple/SimpleLogger.html}SLF4J simple logger}} and since 3.5.0 {{{../maven-slf4j-provider/}Maven-customized <<>>}}, - but is ready to use other logging implementations: SLF4J is responsible for loading the implementation, referred to as - {{{http://www.slf4j.org/manual.html#swapping}"SLF4J bindings"}}. - - Logging configuration loading is actually done by logging implementation, without any Maven extensions to support merging - Maven installation configuration with per-user configuration for example: - <<<$\{maven.conf}/logging>>> directory was added to core's classpath (see <<<$\{maven.home}/bin/m2.conf>>>). See your implementation - documentation for details on file names, formats, and so on. - - During Maven initialization, Maven tweaks default root logging level to match CLI verbosity choice. Since such feature isn't available - in SLF4J API, logging implementation specific extensions need to be added into Maven to support these CLI options: see - {{{./apidocs/org/apache/maven/cli/logging/Slf4jConfigurationFactory.html}Slf4jConfigurationFactory}} / - {{{./apidocs/org/apache/maven/cli/logging/Slf4jConfiguration.html}Slf4jConfiguration}}. - -~~ TODO document META-INF/maven/slf4j-configuration.properties - -* Getting Logger Instance - - Starting with Maven 3.1.0, SLF4J Logger can be used directly. This technique can be used safely in Maven core - components or in plugins/component not requiring compatibility with previous Maven versions. - -+-----+ + + +# Maven Logging + +[End-user logging documentation](/maven-logging.html) is available [in Maven site](/maven-logging.html). This documentation is focused on internal implementation details. + +## Logging API + +Maven uses [Plexus Container logging API](https://codehaus-plexus.github.io/plexus-containers/plexus-container-default/apidocs/org/codehaus/plexus/logging/package-summary.html), like any other Plexus components, ie [LoggerManager](https://codehaus-plexus.github.io/plexus-containers/plexus-container-default/apidocs/org/codehaus/plexus/logging/LoggerManager.html) / [Logger](https://codehaus-plexus.github.io/plexus-containers/plexus-container-default/apidocs/org/codehaus/plexus/logging/Logger.html). + +Starting with Maven 3.1.0: + +- Maven supports SLF4J API logging API too, ie [LoggerFactory](http://slf4j.org/apidocs/org/slf4j/LoggerFactory.html) / [Logger](http://slf4j.org/apidocs/org/slf4j/Logger.html), +- instead of implementing Plexus logging API itself with basic output to console, Maven implements it using SLF4J API in [Slf4jLoggerManager](./apidocs/org/apache/maven/cli/logging/Slf4jLoggerManager.html) / [Slf4jLogger](./apidocs/org/apache/maven/cli/logging/Slf4jLogger.html). + +## Logging Implementation + +Maven 3.1.0 ships bundled with [SLF4J simple logger](https://www.slf4j.org/api/org/slf4j/simple/SimpleLogger.html) and since 3.5.0 [Maven-customized `maven-slf4j-provider`](../maven-slf4j-provider/), but is ready to use other logging implementations: SLF4J is responsible for loading the implementation, referred to as ["SLF4J bindings"](http://www.slf4j.org/manual.html#swapping). + +Logging configuration loading is actually done by logging implementation, without any Maven extensions to support merging Maven installation configuration with per-user configuration for example: `${maven.conf}/logging` directory was added to core's classpath (see `${maven.home}/bin/m2.conf`). See your implementation documentation for details on file names, formats, and so on. + +During Maven initialization, Maven tweaks default root logging level to match CLI verbosity choice. Since such feature isn't available in SLF4J API, logging implementation specific extensions need to be added into Maven to support these CLI options: see [Slf4jConfigurationFactory](./apidocs/org/apache/maven/cli/logging/Slf4jConfigurationFactory.html) / [Slf4jConfiguration](./apidocs/org/apache/maven/cli/logging/Slf4jConfiguration.html). + + + +## Getting Logger Instance + +Starting with Maven 3.1.0, SLF4J Logger can be used directly. This technique can be used safely in Maven core components or in plugins/component not requiring compatibility with previous Maven versions. + +```java import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -77,11 +52,10 @@ public class MyClass { final Logger logger = LoggerFactory.getLogger( MyClass.class ); } -+-----+ +``` -* Logger Name +## Logger Name - Logger name is basically the classical fully qualified class name: it's not visible by default, but can be activated (see {{{/maven-logging.html}user documentation}}). +Logger name is basically the classical fully qualified class name: it's not visible by default, but can be activated (see [user documentation](/maven-logging.html)). - Notice that before Maven 3.1.0, with logger created by Maven, some code used to pass logger from class to class because it could not create a new logger: - discrepencies between logger name and actual class may happen. +Notice that before Maven 3.1.0, with logger created by Maven, some code used to pass logger from class to class because it could not create a new logger: discrepencies between logger name and actual class may happen. diff --git a/compat/maven-model-builder/src/site/markdown/index.md b/compat/maven-model-builder/src/site/markdown/index.md index ca1ff8c6cb9b..33549cf3b09b 100644 --- a/compat/maven-model-builder/src/site/markdown/index.md +++ b/compat/maven-model-builder/src/site/markdown/index.md @@ -1,240 +1,97 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. - - ----- - Introduction - ----- - Hervé Boutemy - ----- - 2013-03-19 - ----- - -Maven Model Builder - - The effective model builder, with profile activation, inheritance, interpolation, ... - - The main component is <<>> - ({{{./apidocs/org/apache/maven/model/building/ModelBuilder.html}javadoc}}, - {{{./xref/org/apache/maven/model/building/ModelBuilder.html}source}}), - with its <<>> implementation - ({{{./apidocs/org/apache/maven/model/building/DefaultModelBuilder.html}javadoc}}, - {{{./xref/org/apache/maven/model/building/DefaultModelBuilder.html}source}}) - that manages the steps sequence. - - The sequence is divided into 2 phases: - - * phase 1 - - ** profile activation: see {{{./apidocs/org/apache/maven/model/profile/activation/package-summary.html}available activators}}. - Notice that model interpolation hasn't happened yet, then interpolation for file-based activation is limited to - <<<$\{basedir}>>> (since Maven 3), <<<$\{rootDirectory}>>> (since Maven 4), system properties and user properties - - ** file model validation: <<>> ({{{./apidocs/org/apache/maven/model/validation/ModelValidator.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/model/validation/DefaultModelValidator.html}source}}) - - [] - - * phase 2, with optional plugin processing - - ** Build up a raw model by re-reading the file and enriching it based on information available in the reactor. Some features: - - *** Resolve version of versionless parents based on relativePath (including ci-friendly versions) - - *** Resolve version of versionless dependencies that are part of the reactor - - [] - - ** raw model validation: <<>> ({{{./apidocs/org/apache/maven/model/validation/ModelValidator.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/model/validation/DefaultModelValidator.html}source}}) - - ** model normalization - merge duplicates: <<>> ({{{./apidocs/org/apache/maven/model/normalization/ModelNormalizer.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/model/normalization/DefaultModelNormalizer.html}source}}) - - ** profile injection: <<>> ({{{./apidocs/org/apache/maven/model/profile/ProfileInjector.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/model/profile/DefaultProfileInjector.html}source}}) - - ** parent resolution until {{{./super-pom.html}super-pom}} - - ** inheritance assembly (see {{{./index.html#Inheritance_Assembly}below}}) - - ** model interpolation (see {{{./index.html#Model_Interpolation}below}}) - - ** url normalization: <<>> ({{{./apidocs/org/apache/maven/model/path/UrlNormalizer.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/model/path/DefaultUrlNormalizer.html}source}}) - - ** model path translation: <<>> ({{{./apidocs/org/apache/maven/model/path/ModelPathTranslator.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/model/path/DefaultModelPathTranslator.html}source}}) - - ** plugin management injection: <<>> ({{{./apidocs/org/apache/maven/model/management/PluginManagementInjector.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/model/management/DefaultPluginManagementInjector.html}source}}) - - ** <(optional)> lifecycle bindings injection: <<>> ({{{./apidocs/org/apache/maven/model/plugin/LifecycleBindingsInjector.html}javadoc}}), - with its <<>> implementation in maven-core - ({{{./maven-core/xref/org/apache/maven/model/plugin/DefaultLifecycleBindingsInjector.html}source}}) - - ** dependency management import (for dependencies of type <<>> and scope <<>> in the <<<\>>> section) - - ** dependency management injection: <<>> ({{{./apidocs/org/apache/maven/model/management/DependencyManagementInjector.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/model/management/DefaultDependencyManagementInjector.html}source}}) - - ** model normalization - inject default values: <<>> ({{{./apidocs/org/apache/maven/model/normalization/ModelNormalizer.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/model/normalization/DefaultModelNormalizer.html}source}}) - - ** <(optional)> reports configuration: <<>> ({{{./apidocs/org/apache/maven/model/plugin/ReportConfigurationExpander.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/model/plugin/DefaultReportConfigurationExpander.html}source}}) - - ** <(optional)> reports conversion to decoupled site plugin: <<>> ({{{./apidocs/org/apache/maven/model/plugin/ReportingConverter.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/model/plugin/DefaultReportingConverter.html}source}}) - - ** <(optional)> plugins configuration: <<>> ({{{./apidocs/org/apache/maven/model/plugin/PluginConfigurationExpander.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/model/plugin/DefaultPluginConfigurationExpander.html}source}}) - - ** effective model validation: <<>> ({{{./apidocs/org/apache/maven/model/validation/ModelValidator.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/model/validation/DefaultModelValidator.html}source}}) - - [] - - [] - - -* Inheritance Assembly - - Inheritance Assembly consists in filling current model empty fields with values taken from parent model. - It is done in <<>> ({{{./apidocs/org/apache/maven/model/inheritance/InheritanceAssembler.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/model/inheritance/DefaultInheritanceAssembler.html}source}}). - - By default, every model field is inherited as-is from parent, with a few exceptions that are intentionally not inherited: - <<>>, <<>>, <<>>, <<>> (injected in phase 1) and <<>>. - - Notice that the 5 URLs from the model (<<>>, <<>>, <<>>, - <<>> and <<>>) have a special inheritance handling: - - ** if not configured in current model, the inherited value is the parent's one with current artifact id appended, - - ** since Maven 3.5.0, if <<>> POM property value is defined, it is used instead of artifact id: - this permits default inheritance calculations when module directory name is not equal to artifact id. Notice that this - property is not inherited from a POM to its child: child's POM will use child artifact id if property is not - set. - - ** since Maven 3.6.1, inheritance can avoid appending any path to parent value by setting model attribute value to - <<>> for each url: - <<>>, - <<>>, - <<>>, - <<>> and - <<>>. - - [] - -* Model Interpolation - - Model Interpolation consists in replacing <<<$\{...\}>>> with calculated value. It is done in <<>> - ({{{./apidocs/org/apache/maven/model/interpolation/StringVisitorModelInterpolator.html}javadoc}}, - {{{./xref/org/apache/maven/model/interpolation/StringVisitorModelInterpolator.html}source}}). - - Notice that model interpolation happens profile activation, and that profile activation doesn't benefit from every values: - interpolation for file-based activation is limited to <<<$\{basedir}>>> (which was introduced in Maven 3 and is not deprecated - in this context) and <<<$\{rootDirectory}>>> (introduced in Maven 4), system properties and user properties. - - Values are evaluated in sequence from different syntaxes: - -*----+------+------+ -|| value || evaluation result || common examples || -*----+------+------+ -| <<>>\ -<<>> ()\ -<<<*>>> () | POM content (see {{{../maven-model/maven.html}POM reference}}) | <<<$\{project.version\}>>>\ - | | <<<$\{project.build.finalName\}>>>\ - | | <<<$\{project.artifactId\}>>>\ - | | <<<$\{project.build.directory\}>>> | -*----+------+------+ -| <<>>\ -<<>> ()\ -<<>> () | the directory containing the <<>> file | <<<$\{project.basedir\}>>> | -*----+------+------+ -| <<>>\ -<<>> () | the directory containing the <<>> file as URI | <<<$\{project.baseUri\}>>> | -*----+------+------+ -| <<>> | the project's root directory (containing a <<<.mvn>>> directory or with the <<>> xml attribute) | <<<$\{project.rootDirectory\}>>> | -*----+------+------+ -| <<>>\ -<<>> | the UTC timestamp of build start, in <<>> default format, which can be overridden with <<>> POM property | <<<$\{maven.build.timestamp\}>>> | -*----+------+------+ -| <<<*>>> | user properties, set from CLI with <<<-Dproperty=value>>> | <<<$\{skipTests\}>>> | -*----+------+------+ -| <<<*>>> | model properties, such as project properties set in the pom | <<<$\{any.key\}>>> | -*----+------+------+ -| <<>> | The path to the current Maven home. | <<<$\{maven.home\}>>> | -*----+------+------+ -| <<>> | The version number of the current Maven execution <(since 3.0.4)>. For example, "<<<3.0.5>>>". | <<<$\{maven.version\}>>> | -*----+------+------+ -| <<>> | The full build version of the current Maven execution <(since 3.0.4)>. For example, "<<>>". | <<<$\{maven.build.version\}>>> | -*----+------+------+ -| <<>> | The repository on the local machine Maven shall use to store installed and downloaded artifacts (POMs, JARs, etc). | <<<$\{user.home\}/.m2/repository>>> | -*----+------+------+ -| <<<*>>> | Java system properties (see {{{https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#getProperties()}JDK reference}}) | <<<$\{user.home\}>>>\ - | | <<<$\{java.home\}>>> | -*----+------+------+ -| <<<*>>> | User properties | <<<$\{foo\}>>> | -*----+------+------+ -| <<>>\ -<<<*>>> | environment variables | <<<$\{env.PATH\}>>> | -*----+------+------+ -| <<>> | Local user settings (see {{{../maven-settings/settings.html}settings reference}}) | <<<$\{settings.localRepository\}>>> | -*----+------+------+ -| <<>> \ -<<>> \ -<<>> | CI friendly placeholders for the project version (see {{{/maven-ci-friendly.html}Maven CI Friendly Versions}}) | <<<1.0.0-$\{changelist\}-SNAPSHOT>>> | -*----+------+------+ - - -** Notice - - * after model interpolation, <<<$\{...\}>>> content can remain in the model that will be evaluated later - when setting plugin parameters. This happens in particular with <<>> values for - {{{../maven-settings/settings.html}Settings Model}}, - - * encoding configuration have been defined as POM properties looking like POM content but not added to POM model to maintain - compatibility with previous Maven versions: - - * <<<$\{project.build.sourceEncoding\}>>> for - {{{https://cwiki.apache.org/confluence/display/MAVEN/POM+Element+for+Source+File+Encoding}source files encoding}} - (defaults to <<>> since Maven 4.0.0, no default value was provided in Maven 3.x, meaning that the platform - encoding was used by plugins) - - * <<<$\{project.reporting.outputEncoding\}>>> for - {{{https://cwiki.apache.org/confluence/display/MAVENOLD/Reporting+Encoding+Configuration}reporting output files encoding}} - (defaults to <<>> since Maven 4.0.0, no default value was provided in Maven 3.x, plugins usually defaulting - to <<>>) - - [] - - [] + + +# Maven Model Builder + +The effective model builder, with profile activation, inheritance, interpolation, ... + +The main component is `ModelBuilder` ([javadoc](./apidocs/org/apache/maven/model/building/ModelBuilder.html), [source](./xref/org/apache/maven/model/building/ModelBuilder.html)), with its `DefaultModelBuilder` implementation ([javadoc](./apidocs/org/apache/maven/model/building/DefaultModelBuilder.html), [source](./xref/org/apache/maven/model/building/DefaultModelBuilder.html)) that manages the steps sequence. + +The sequence is divided into 2 phases: + +- phase 1 + - profile activation: see [available activators](./apidocs/org/apache/maven/model/profile/activation/package-summary.html). Notice that model interpolation hasn't happened yet, then interpolation for file-based activation is limited to `${basedir}` (since Maven 3), `${rootDirectory}` (since Maven 4), system properties and user properties + - file model validation: `ModelValidator` ([javadoc](./apidocs/org/apache/maven/model/validation/ModelValidator.html)), with its `DefaultModelValidator` implementation ([source](./xref/org/apache/maven/model/validation/DefaultModelValidator.html)) +- phase 2, with optional plugin processing + - Build up a raw model by re-reading the file and enriching it based on information available in the reactor. Some features: + - Resolve version of versionless parents based on relativePath (including ci-friendly versions) + - Resolve version of versionless dependencies that are part of the reactor + - raw model validation: `ModelValidator` ([javadoc](./apidocs/org/apache/maven/model/validation/ModelValidator.html)), with its `DefaultModelValidator` implementation ([source](./xref/org/apache/maven/model/validation/DefaultModelValidator.html)) + - model normalization - merge duplicates: `ModelNormalizer` ([javadoc](./apidocs/org/apache/maven/model/normalization/ModelNormalizer.html)), with its `DefaultModelNormalizer` implementation ([source](./xref/org/apache/maven/model/normalization/DefaultModelNormalizer.html)) + - profile injection: `ProfileInjector` ([javadoc](./apidocs/org/apache/maven/model/profile/ProfileInjector.html)), with its `DefaultProfileInjector` implementation ([source](./xref/org/apache/maven/model/profile/DefaultProfileInjector.html)) + - parent resolution until [super-pom](./super-pom.html) + - inheritance assembly (see [below](./index.html#Inheritance_Assembly)) + - model interpolation (see [below](./index.html#Model_Interpolation)) + - url normalization: `UrlNormalizer` ([javadoc](./apidocs/org/apache/maven/model/path/UrlNormalizer.html)), with its `DefaultUrlNormalizer` implementation ([source](./xref/org/apache/maven/model/path/DefaultUrlNormalizer.html)) + - model path translation: `ModelPathTranslator` ([javadoc](./apidocs/org/apache/maven/model/path/ModelPathTranslator.html)), with its `DefaultModelPathTranslator` implementation ([source](./xref/org/apache/maven/model/path/DefaultModelPathTranslator.html)) + - plugin management injection: `PluginManagementInjector` ([javadoc](./apidocs/org/apache/maven/model/management/PluginManagementInjector.html)), with its `DefaultPluginManagementInjector` implementation ([source](./xref/org/apache/maven/model/management/DefaultPluginManagementInjector.html)) + - _(optional)_ lifecycle bindings injection: `LifecycleBindingsInjector` ([javadoc](./apidocs/org/apache/maven/model/plugin/LifecycleBindingsInjector.html)), with its `DefaultLifecycleBindingsInjector` implementation in maven-core ([source](./maven-core/xref/org/apache/maven/model/plugin/DefaultLifecycleBindingsInjector.html)) + - dependency management import (for dependencies of type `pom` and scope `import` in the `` section) + - dependency management injection: `DependencyManagementInjector` ([javadoc](./apidocs/org/apache/maven/model/management/DependencyManagementInjector.html)), with its `DefaultDependencyManagementInjector` implementation ([source](./xref/org/apache/maven/model/management/DefaultDependencyManagementInjector.html)) + - model normalization - inject default values: `ModelNormalizer` ([javadoc](./apidocs/org/apache/maven/model/normalization/ModelNormalizer.html)), with its `DefaultModelNormalizer` implementation ([source](./xref/org/apache/maven/model/normalization/DefaultModelNormalizer.html)) + - _(optional)_ reports configuration: `ReportConfigurationExpander` ([javadoc](./apidocs/org/apache/maven/model/plugin/ReportConfigurationExpander.html)), with its `DefaultReportConfigurationExpander` implementation ([source](./xref/org/apache/maven/model/plugin/DefaultReportConfigurationExpander.html)) + - _(optional)_ reports conversion to decoupled site plugin: `ReportingConverter` ([javadoc](./apidocs/org/apache/maven/model/plugin/ReportingConverter.html)), with its `DefaultReportingConverter` implementation ([source](./xref/org/apache/maven/model/plugin/DefaultReportingConverter.html)) + - _(optional)_ plugins configuration: `PluginConfigurationExpander` ([javadoc](./apidocs/org/apache/maven/model/plugin/PluginConfigurationExpander.html)), with its `DefaultPluginConfigurationExpander` implementation ([source](./xref/org/apache/maven/model/plugin/DefaultPluginConfigurationExpander.html)) + - effective model validation: `ModelValidator` ([javadoc](./apidocs/org/apache/maven/model/validation/ModelValidator.html)), with its `DefaultModelValidator` implementation ([source](./xref/org/apache/maven/model/validation/DefaultModelValidator.html)) + +## Inheritance Assembly + +Inheritance Assembly consists in filling current model empty fields with values taken from parent model. It is done in `InheritanceAssembler` ([javadoc](./apidocs/org/apache/maven/model/inheritance/InheritanceAssembler.html)), with its `DefaultInheritanceAssembler` implementation ([source](./xref/org/apache/maven/model/inheritance/DefaultInheritanceAssembler.html)). + +By default, every model field is inherited as-is from parent, with a few exceptions that are intentionally not inherited: `modelVersion`, `artifactId`, `packaging`, `profiles` (injected in phase 1) and `prerequisites`. + +Notice that the 5 URLs from the model (`project.url`, `project.scm.connection`, `project.scm.developerConnection`, `project.scm.url` and `project.distributionManagement.site.url`) have a special inheritance handling: + +- if not configured in current model, the inherited value is the parent's one with current artifact id appended, +- since Maven 3.5.0, if `project.directory` POM property value is defined, it is used instead of artifact id: this permits default inheritance calculations when module directory name is not equal to artifact id. Notice that this property is not inherited from a POM to its child: child's POM will use child artifact id if property is not set. +- since Maven 3.6.1, inheritance can avoid appending any path to parent value by setting model attribute value to `false` for each url: `project/@child.project.url.inherit.append.path`, `project/distributionManagement/site/@child.site.url.inherit.append.path`, `project/scm/@child.scm.connection.inherit.append.path`, `project/scm/@child.scm.developerConnection.inherit.append.path` and `project/scm/@child.scm.url.inherit.append.path`. + +## Model Interpolation + +Model Interpolation consists in replacing `${...}` with calculated value. It is done in `StringVisitorModelInterpolator` ([javadoc](./apidocs/org/apache/maven/model/interpolation/StringVisitorModelInterpolator.html), [source](./xref/org/apache/maven/model/interpolation/StringVisitorModelInterpolator.html)). + +Notice that model interpolation happens _after_ profile activation, and that profile activation doesn't benefit from every values: interpolation for file-based activation is limited to `${basedir}` (which was introduced in Maven 3 and is not deprecated in this context) and `${rootDirectory}` (introduced in Maven 4), system properties and user properties. + +Values are evaluated in sequence from different syntaxes: + +|value|evaluation result|common examples| +|:---|:---|:---| +|`project.*` 
`pom.*` (_deprecated_) 
`*` (_deprecated_)|POM content (see [POM reference](../maven-model/maven.html))|`${project.version}` 
`${project.build.finalName}` 
`${project.artifactId}` 
`${project.build.directory}`| +|`project.basedir` 
`pom.basedir` (_deprecated_) 
`basedir` (_deprecated_)|the directory containing the `pom.xml` file|`${project.basedir}`| +|`project.baseUri` 
`pom.baseUri` (_deprecated_)|the directory containing the `pom.xml` file as URI|`${project.baseUri}`| +|`project.rootDirectory`|the project's root directory (containing a `.mvn` directory or with the `root="true"` xml attribute)|`${project.rootDirectory}`| +|`build.timestamp` 
`maven.build.timestamp`|the UTC timestamp of build start, in `yyyy-MM-dd'T'HH:mm:ss'Z'` default format, which can be overridden with `maven.build.timestamp.format` POM property|`${maven.build.timestamp}`| +|`*`|user properties, set from CLI with `-Dproperty=value`|`${skipTests}`| +|`*`|model properties, such as project properties set in the pom|`${any.key}`| +|`maven.home`|The path to the current Maven home.|`${maven.home}`| +|`maven.version`|The version number of the current Maven execution _(since 3.0.4)_. For example, "`3.0.5`".|`${maven.version}`| +|`maven.build.version`|The full build version of the current Maven execution _(since 3.0.4)_. For example, "`Apache Maven 3.2.2 (r01de14724cdef164cd33c7c8c2fe155faf9602da; 2013-02-19T14:51:28+01:00)`".|`${maven.build.version}`| +|`maven.repo.local`|The repository on the local machine Maven shall use to store installed and downloaded artifacts (POMs, JARs, etc).|`${user.home}/.m2/repository`| +|`*`|Java system properties (see [JDK reference](https://docs.oracle.com/javase/8/docs/api/java/lang/System.html#getProperties()))|`${user.home}` 
`${java.home}`| +|`*`|User properties|`${foo}`| +|`env.*` 
`*`|environment variables|`${env.PATH}`| +|`settings.*`|Local user settings (see [settings reference](../maven-settings/settings.html))|`${settings.localRepository}`| +|`changelist`  
`revision`  
`sha1`|CI friendly placeholders for the project version (see [Maven CI Friendly Versions](/maven-ci-friendly.html))|`1.0.0-${changelist}-SNAPSHOT`| + +### Notice + +- after model interpolation, `${...}` content can remain in the model that will be evaluated later when setting plugin parameters. This happens in particular with `settings.*` values for [Settings Model](../maven-settings/settings.html), +- encoding configuration have been defined as POM properties looking like POM content but not added to POM model to maintain compatibility with previous Maven versions: + - `${project.build.sourceEncoding}` for [source files encoding](https://cwiki.apache.org/confluence/display/MAVEN/POM+Element+for+Source+File+Encoding) (defaults to `UTF-8` since Maven 4.0.0, no default value was provided in Maven 3.x, meaning that the platform encoding was used by plugins) + - `${project.reporting.outputEncoding}` for [reporting output files encoding](https://cwiki.apache.org/confluence/display/MAVENOLD/Reporting+Encoding+Configuration) (defaults to `UTF-8` since Maven 4.0.0, no default value was provided in Maven 3.x, plugins usually defaulting to `UTF-8`) diff --git a/compat/maven-model-builder/src/site/markdown/super-pom.md.vm b/compat/maven-model-builder/src/site/markdown/super-pom.md.vm index df86d70efeba..94a6fb4e8ed4 100644 --- a/compat/maven-model-builder/src/site/markdown/super-pom.md.vm +++ b/compat/maven-model-builder/src/site/markdown/super-pom.md.vm @@ -1,30 +1,24 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - All models implicitly inherit from a super-POM: +# Super POM -%{snippet|id=superpom|file=${project.build.sourceDirectory}/../resources/org/apache/maven/model/pom-4.0.0.xml} +All models implicitly inherit from a super-POM: + + diff --git a/compat/maven-model/src/site/markdown/index.md b/compat/maven-model/src/site/markdown/index.md index 0d33ae519441..47f6a4f17a2b 100644 --- a/compat/maven-model/src/site/markdown/index.md +++ b/compat/maven-model/src/site/markdown/index.md @@ -1,41 +1,28 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - This is strictly the model for Maven POM (Project Object Model) in <<>> package, - delegating content to {{{../../api/maven-api-model/index.html}Maven 4 API immutable model}}. All the effective model - building logic from multiple POMs and building context is done in {{{../maven-model-builder/}Maven Model Builder}}. +# Maven Model - The following are generated from this model: +This is strictly the model for Maven POM (Project Object Model) in `org.apache.maven.model` package, delegating content to [Maven 4 API immutable model](../../api/maven-api-model/index.html). All the effective model building logic from multiple POMs and building context is done in [Maven Model Builder](../maven-model-builder/). - * {{{./apidocs/index.html}Java sources}} with Reader and Writers for the Xpp3 XML parser, <<>> and <<>> transformers, and <<>> package - for Merger and v4 Reader and Writers for the Xpp3 XML parser, +The following are generated from this model: - * A {{{../../api/maven-api-model/maven.html}Descriptor Reference}} - - * An XSD {{{https://maven.apache.org/xsd/maven-v3_0_0.xsd}for Maven 1.1}} and {{{https://maven.apache.org/xsd/maven-4.0.0.xsd}for Maven 2 and 3}}. +- [Java sources](./apidocs/index.html) with Reader and Writers for the Xpp3 XML parser, `ToAPiV3()` and `ToApiV4()` transformers, and `v4` package for Merger and v4 Reader and Writers for the Xpp3 XML parser, +- A [Descriptor Reference](../../api/maven-api-model/maven.html) +- An XSD [for Maven 1.1](https://maven.apache.org/xsd/maven-v3_0_0.xsd) and [for Maven 2 and 3](https://maven.apache.org/xsd/maven-4.0.0.xsd). diff --git a/compat/maven-plugin-api/src/site/markdown/index.md b/compat/maven-plugin-api/src/site/markdown/index.md index aebf9ea28aa5..b12af6e063e0 100644 --- a/compat/maven-plugin-api/src/site/markdown/index.md +++ b/compat/maven-plugin-api/src/site/markdown/index.md @@ -1,45 +1,33 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - The API for Maven 3 plugins - composed of goals implemented by Mojos - development: +# Maven 3 Plugin API - * goal code extends {{{./apidocs/org/apache/maven/plugin/AbstractMojo.html}<<>> base class}} that implements {{{./apidocs/org/apache/maven/plugin/Mojo.html}<<>> interface}}, +The API for Maven 3 plugins - composed of goals implemented by Mojos - development: - * {{{./apidocs/org/apache/maven/plugin/logging/Log.html}<<>> interface}} provides easy logging for the goal. +- goal code extends [`AbstractMojo` base class](./apidocs/org/apache/maven/plugin/AbstractMojo.html) that implements [`Mojo` interface](./apidocs/org/apache/maven/plugin/Mojo.html), +- [`Log` interface](./apidocs/org/apache/maven/plugin/logging/Log.html) provides easy logging for the goal. - [] +A plugin is described in a [`META-INF/maven/plugin.xml` plugin descriptor](../../api/maven-api-plugin/plugin.html), generally generated from plugin sources using [maven-plugin-plugin](/plugin-tools/maven-plugin-plugin/). - A plugin is described in a {{{../../api/maven-api-plugin/plugin.html}<<>> plugin descriptor}}, - generally generated from plugin sources using {{{/plugin-tools/maven-plugin-plugin/}maven-plugin-plugin}}. +## See Also -* See Also - - * {{{/developers/mojo-api-specification.html}Mojo API Specification}} - - * {{{/plugin-tools/}Plugin Tools}} that provide {{{/plugin-tools/maven-plugin-plugin/}maven-plugin-plugin}} to generate the {{{./plugin.html}<<>> plugin descriptor}} - - * {{{/plugin-testing/}Plugin Testing}} frameworks +- [Mojo API Specification](/developers/mojo-api-specification.html) +- [Plugin Tools](/plugin-tools/) that provide [maven-plugin-plugin](/plugin-tools/maven-plugin-plugin/) to generate the [`META-INF/maven/plugin.xml` plugin descriptor](./plugin.html) +- [Plugin Testing](/plugin-testing/) frameworks diff --git a/compat/maven-repository-metadata/src/site/markdown/index.md b/compat/maven-repository-metadata/src/site/markdown/index.md index fb6f37f97c65..ac0616c3475f 100644 --- a/compat/maven-repository-metadata/src/site/markdown/index.md +++ b/compat/maven-repository-metadata/src/site/markdown/index.md @@ -1,59 +1,40 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - This is strictly the model for Maven Repository Metadata, so really just plain objects. +# Maven Repository Metadata Model - The metadata file name is: +This is strictly the model for Maven Repository Metadata, so really just plain objects. - * <<>> in a remote repository, +The metadata file name is: - * <<.xml>>> in a local repository, for metadata from a repository with <<>> identifier. +- `maven-metadata.xml` in a remote repository, +- `maven-metadata-.xml` in a local repository, for metadata from a repository with `repo-id` identifier. - [] +Depending on what the directory represents ("groupId", "groupId/artifactId" or "groupId/artifactId/version"), the Maven Repository Metadata file contains 3 different sets of metadata: - Depending on what the directory represents ("groupId", "groupId/artifactId" or "groupId/artifactId/version"), - the Maven Repository Metadata file contains 3 different sets of metadata: +1. in a "groupId" directory: a "groupId" directory may contain Maven plugins artifacts, which are described in metadata's `plugins` element, +1. in a "groupId/artifactId" directory: metadata describes `groupId`, `artifactId` and `versioning` element that gives data about available versions (`latest`, `release`, `versions` list and `lastUpdated`), +1. in a "groupId/artifactId/version" snapshot artifact directory: metadata describes `groupId`, `artifactId`, `version` (base version, i.e. ending in `-SNAPSHOT`) and `versioning` element that gives data about snapshot (`snapshot`, `lastUpdated` and `snapshotVersions` list). Notice that a release artifact directory is not expected to provide metadata. - [[1]] in a "groupId" directory: a "groupId" directory may contain Maven plugins artifacts, which are described in metadata's <<>> element, +The following are generated from this model: - [[2]] in a "groupId/artifactId" directory: metadata describes <<>>, <<>> and <<>> element that - gives data about available versions (<<>>, <<>>, <<>> list and <<>>), - - [[3]] in a "groupId/artifactId/version" snapshot artifact directory: metadata describes <<>>, <<>>, <<>> (base version, i.e. ending in <<<-SNAPSHOT>>>) and - <<>> element that gives data about snapshot (<<>>, <<>> and <<>> list). Notice that a - release artifact directory is not expected to provide metadata. - - [] - - The following are generated from this model: - - * {{{./apidocs/index.html}Java sources}} with Reader and Writers for the Xpp3 XML parser, to read and write <<>> files, - - * a {{{../../api/maven-api-metadata/repository-metadata.html}Descriptor Reference}}. - - For more information see this page: {{{https://maven.apache.org/repositories/metadata.html}Maven Metadata}}. +- [Java sources](./apidocs/index.html) with Reader and Writers for the Xpp3 XML parser, to read and write `maven-metadata(-*).xml` files, +- a [Descriptor Reference](../../api/maven-api-metadata/repository-metadata.html). +For more information see this page: [Maven Metadata](https://maven.apache.org/repositories/metadata.html). diff --git a/compat/maven-resolver-provider/src/site/markdown/dependency-types.md b/compat/maven-resolver-provider/src/site/markdown/dependency-types.md index 42ae1b7b6cde..f57c7a11170a 100644 --- a/compat/maven-resolver-provider/src/site/markdown/dependency-types.md +++ b/compat/maven-resolver-provider/src/site/markdown/dependency-types.md @@ -1,82 +1,50 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - Defined in <<>> - ({{{./apidocs/org/apache/maven/repository/internal/type/DefaultTypeProvider.html}javadoc}}, - {{{./xref/org/apache/maven/repository/internal/type/DefaultTypeProvider.html}source}}): +# Default Dependency Types Reference -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -|| type || classifier || extension || language || path types || includesDependencies || -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -|| Maven || || || || || || -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | | <= type> | none | | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <<>> | none | | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | | <<>> | java | classes | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -|| Java || || || || || || -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | | <= type> | java | classes, modules | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | <<>> | <<>> | java | | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | <<>> | <<>> | java | classes | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | <<>> | <<>> | java | classes, patch module | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | <<>> | <<>> | java | | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <<>> | java | modules | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <<>> | java | classes | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <<>> | java | classes | <<>> | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <<>> | java | processor classes, processor modules | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <<>> | java | processor classes | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <<>> | java | processor modules | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -|| Java/Jakarta EE || || || || || || -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | | <<>> | java | classes | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | <<>> | <<>> | java | classes | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | | <= type> | java | | <<>> | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | | <= type> | java | | <<>> | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | | <= type> | java | | <<>> | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <= type> | java | | <<>> | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ +Defined in `DefaultTypeProvider` ([javadoc](./apidocs/org/apache/maven/repository/internal/type/DefaultTypeProvider.html), [source](./xref/org/apache/maven/repository/internal/type/DefaultTypeProvider.html)): - * = new in Maven 4 \ No newline at end of file +|type|classifier|extension|language|path types|includesDependencies| +|:---|:---|:---|:---|:---|:---| +|**Maven**| | | | | | +|`pom`| |_= type_|none| | | +|`bom` *| |`pom`|none| | | +|`maven-plugin`| |`jar`|java|classes| | +|**Java**| | | | | | +|`jar`| |_= type_|java|classes, modules| | +|`java-source`|`sources`|`jar`|java| | | +|`javadoc`|`javadoc`|`jar`|java|classes| | +|`test-jar`|`tests`|`jar`|java|classes, patch module| | +|`test-java-source` *|`test-sources`|`jar`|java| | | +|`modular-jar` *| |`jar`|java|modules| | +|`classpath-jar` *| |`jar`|java|classes| | +|`fatjar` *| |`jar`|java|classes|`true`| +|`processor` *| |`jar`|java|processor classes, processor modules| | +|`classpath-processor` *| |`jar`|java|processor classes| | +|`modular-processor` *| |`jar`|java|processor modules| | +|**Java/Jakarta EE**| | | | | | +|`ejb`| |`jar`|java|classes| | +|`ejb-client`|`client`|`jar`|java|classes| | +|`war`| |_= type_|java| |`true`| +|`ear`| |_= type_|java| |`true`| +|`rar`| |_= type_|java| |`true`| +|`par` *| |_= type_|java| |`true`| + +- = new in Maven 4 diff --git a/compat/maven-resolver-provider/src/site/markdown/index.md b/compat/maven-resolver-provider/src/site/markdown/index.md index 3008d093f315..90a868043363 100644 --- a/compat/maven-resolver-provider/src/site/markdown/index.md +++ b/compat/maven-resolver-provider/src/site/markdown/index.md @@ -1,35 +1,26 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - Maven Artifact Resolver Provider is a {{{/resolver/}Maven Artifact Resolver}} extension to support - Maven POMs and local+remote repositories. +# Maven Artifact Resolver Provider - Main component is <<>> - ({{{./apidocs/org/apache/maven/repository/internal/MavenRepositorySystemUtils.html}javadoc}}, - {{{./xref/org/apache/maven/repository/internal/MavenRepositorySystemUtils.html}source}}). +Maven Artifact Resolver Provider is a [Maven Artifact Resolver](/resolver/) extension to support Maven POMs and local+remote repositories. - See also {{{./dependency-types.html}dependency types}}. \ No newline at end of file +Main component is `MavenRepositorySystemUtils` ([javadoc](./apidocs/org/apache/maven/repository/internal/MavenRepositorySystemUtils.html), [source](./xref/org/apache/maven/repository/internal/MavenRepositorySystemUtils.html)). + +See also [dependency types](./dependency-types.html). diff --git a/compat/maven-resolver-provider/src/test/java/org/apache/maven/repository/internal/type/DefaultTypeProviderTest.java b/compat/maven-resolver-provider/src/test/java/org/apache/maven/repository/internal/type/DefaultTypeProviderTest.java index 83fd669e432b..66e2f56e2da0 100644 --- a/compat/maven-resolver-provider/src/test/java/org/apache/maven/repository/internal/type/DefaultTypeProviderTest.java +++ b/compat/maven-resolver-provider/src/test/java/org/apache/maven/repository/internal/type/DefaultTypeProviderTest.java @@ -20,6 +20,7 @@ import java.nio.file.Files; import java.nio.file.Path; +import java.util.Arrays; import java.util.LinkedHashSet; import java.util.List; import java.util.Map; @@ -45,18 +46,18 @@ class DefaultTypeProviderTest { "processor modules", JavaPathType.PROCESSOR_MODULES); @Test - void testAptConsistency() throws Exception { + void testDocumentationConsistency() throws Exception { Map types = new DefaultTypeProvider().types().stream().collect(Collectors.toMap(DefaultType::id, t -> t)); - Path apt = Path.of(System.getProperty("basedir", ""), "src/site/apt/dependency-types.apt"); - List lines = Files.readAllLines(apt); + Path doc = Path.of(System.getProperty("basedir", ""), "src/site/markdown/dependency-types.md"); + List lines = Files.readAllLines(doc); Set documentedTypes = new LinkedHashSet<>(); for (String line : lines) { - if (line.startsWith("||") || !line.startsWith("|")) { - continue; + if (!line.startsWith("|") || line.startsWith("|type|") || line.startsWith("|:-")) { + continue; // not a row, or the header row, or the alignment row beneath it } String[] cols = line.split("\\|"); @@ -64,6 +65,11 @@ void testAptConsistency() throws Exception { if (typeId == null) { continue; } + // a row carrying only a label groups the rows beneath it; APT wrote those as a + // second header row, which a Markdown table cannot express + if (Arrays.stream(cols).skip(2).allMatch(c -> trimApt(c) == null)) { + continue; + } documentedTypes.add(typeId); @@ -90,7 +96,7 @@ void testAptConsistency() throws Exception { Set undocumented = new LinkedHashSet<>(types.keySet()); undocumented.removeAll(documentedTypes); - assertTrue(undocumented.isEmpty(), "Types in provider but not in APT doc: " + undocumented); + assertTrue(undocumented.isEmpty(), "Types in provider but not documented: " + undocumented); } private Set parsePathTypes(String pathTypesStr) { @@ -107,8 +113,14 @@ private Set parsePathTypes(String pathTypesStr) { return result; } + /** Strips the Markdown emphasis and code markers the table uses around a cell value. */ private String trimApt(String content) { - content = content.replace('<', ' ').replace('>', ' ').replace('*', ' ').trim(); + content = content.replace('`', ' ') + .replace('_', ' ') + .replace('<', ' ') + .replace('>', ' ') + .replace('*', ' ') + .trim(); return content.isEmpty() ? null : content; } } diff --git a/compat/maven-settings/src/site/markdown/index.md b/compat/maven-settings/src/site/markdown/index.md index bd84dd8036e1..a96abd14c221 100644 --- a/compat/maven-settings/src/site/markdown/index.md +++ b/compat/maven-settings/src/site/markdown/index.md @@ -1,51 +1,36 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. - - ----- - Introduction - ----- - Vincent Siveton - ----- - 2006-11-04 - ----- - -Maven Settings Model - - This is the model for Maven settings in <<>> package, - delegating content to {{{../../api/maven-api-settings/index.html}Maven 4 API immutable settings}}. All the effective model - building logic from multiple settings files is done in {{{../maven-settings-builder/}Maven Settings Builder}}. - - The following are generated from this model: - - * {{{./apidocs/index.html}Java sources}} with Reader and Writers for the Xpp3 XML parser, <<>> and <<>> transformers, and <<>> package - for Merger and v4 Reader and Writers for the Xpp3 XML parser, - - * A {{{../../api/maven-api-settings/settings.html}Descriptor Reference}} - - * An {{{https://maven.apache.org/xsd/settings-2.0.0.xsd}XSD}} - -* See Also User Documentation - - * {{{https://maven.apache.org/settings.html} Settings Reference}}, - - * {{{https://maven.apache.org/guides/mini/guide-mirror-settings.html} Mirror Settings}}, - - * {{{https://maven.apache.org/guides/mini/guide-deployment-security-settings.html} Security and Deployment Settings}}, - - * {{{https://maven.apache.org/guides/mini/guide-encryption-4.html} Password Encryption}}, - - * {{{https://maven.apache.org/guides/mini/guide-proxies.html} Configuring a proxy}}. + + +# Maven Settings Model + +This is the model for Maven settings in `org.apache.maven.settings` package, delegating content to [Maven 4 API immutable settings](../../api/maven-api-settings/index.html). All the effective model building logic from multiple settings files is done in [Maven Settings Builder](../maven-settings-builder/). + +The following are generated from this model: + +- [Java sources](./apidocs/index.html) with Reader and Writers for the Xpp3 XML parser, `ToAPiV3()` and `ToApiV4()` transformers, and `v4` package for Merger and v4 Reader and Writers for the Xpp3 XML parser, +- A [Descriptor Reference](../../api/maven-api-settings/settings.html) +- An [XSD](https://maven.apache.org/xsd/settings-2.0.0.xsd) + +## See Also User Documentation + +- [Settings Reference](https://maven.apache.org/settings.html), +- [Mirror Settings](https://maven.apache.org/guides/mini/guide-mirror-settings.html), +- [Security and Deployment Settings](https://maven.apache.org/guides/mini/guide-deployment-security-settings.html), +- [Password Encryption](https://maven.apache.org/guides/mini/guide-encryption-4.html), +- [Configuring a proxy](https://maven.apache.org/guides/mini/guide-proxies.html). diff --git a/compat/maven-toolchain-model/src/site/markdown/index.md b/compat/maven-toolchain-model/src/site/markdown/index.md index b3f74172aff4..48633e0d819c 100644 --- a/compat/maven-toolchain-model/src/site/markdown/index.md +++ b/compat/maven-toolchain-model/src/site/markdown/index.md @@ -1,39 +1,28 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - This is the model for Maven toolchain in <<>> package, - delegating content to {{{../../api/maven-api-toolchain/index.html}Maven 4 API immutable toolchain}}. All the effective model - building logic from multiple toolchains files is done in {{{../maven-toolchain-builder/}Maven Toolchain Builder}}. +# Maven Toolchain Model - The following are generated from this model: +This is the model for Maven toolchain in `org.apache.maven.toolchain` package, delegating content to [Maven 4 API immutable toolchain](../../api/maven-api-toolchain/index.html). All the effective model building logic from multiple toolchains files is done in [Maven Toolchain Builder](../maven-toolchain-builder/). - * {{{./apidocs/index.html}Java sources}} with Reader and Writers for the Xpp3 XML parser, <<>> and <<>> transformers, and <<>> package - for Merger and v4 Reader and Writers for the Xpp3 XML parser, +The following are generated from this model: - * A {{{../../api/maven-api-toolchain/toolchains.html}Descriptor Reference}} - - * An {{{https://maven.apache.org/xsd/toolchains-1.2.0.xsd}XSD}} +- [Java sources](./apidocs/index.html) with Reader and Writers for the Xpp3 XML parser, `ToAPiV3()` and `ToApiV4()` transformers, and `v4` package for Merger and v4 Reader and Writers for the Xpp3 XML parser, +- A [Descriptor Reference](../../api/maven-api-toolchain/toolchains.html) +- An [XSD](https://maven.apache.org/xsd/toolchains-1.2.0.xsd) diff --git a/impl/maven-core/src/site/markdown/artifact-handlers.md b/impl/maven-core/src/site/markdown/artifact-handlers.md index 3323c1dc1ffc..cf236cac2631 100644 --- a/impl/maven-core/src/site/markdown/artifact-handlers.md +++ b/impl/maven-core/src/site/markdown/artifact-handlers.md @@ -1,61 +1,40 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - Maven 3 artifact handlers (see {{{../../compat/maven-artifact/apidocs/org/apache/maven/artifact/handler/ArtifactHandler.html} API}}) - define for each {{{../../api/maven-api-model/maven.html#class_dependency}dependency type}} information on the artifact - (classifier, extension, language) and how to manage it as dependency (add to classpath, include dependencies). +# Legacy Artifact Handlers Reference - They are replaced in Maven 4 with Maven 4 API Core's {{{../../api/maven-api-core/apidocs/org/apache/maven/api/Type.html}Dependency Types}}, - with default values defined in {{{../../compat/maven-resolver-provider/apidocs/org/apache/maven/repository/internal/type/DefaultTypeProvider.html}DefaultTypeProvider}}. +Maven 3 artifact handlers (see [API](../../compat/maven-artifact/apidocs/org/apache/maven/artifact/handler/ArtifactHandler.html)) define for each [dependency type](../../api/maven-api-model/maven.html#class_dependency) information on the artifact (classifier, extension, language) and how to manage it as dependency (add to classpath, include dependencies). - For compatibility, legacy Maven 3 artifact handlers are still provided: +They are replaced in Maven 4 with Maven 4 API Core's [Dependency Types](../../api/maven-api-core/apidocs/org/apache/maven/api/Type.html), with default values defined in [DefaultTypeProvider](../../compat/maven-resolver-provider/apidocs/org/apache/maven/repository/internal/type/DefaultTypeProvider.html). -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ -|| type || classifier || extension || packaging || language || added to classpath || includesDependencies || -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ -| <<>> | | <= type> | <= type> | none | | | -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ -| <<>> | | <= type> | <= type> | java | <<>> | | -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ -| <<>> | <<>> | <<>> | <<>> | java | <<>> | | -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ -| <<>> | | <<>> | <= type> | java | <<>> | | -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ -| <<>> | | <<>> | <= type> | java | <<>> | | -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ -| <<>> | <<>> | <<>> | <<>> | java | <<>> | | -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ -| <<>> | | <= type> | <= type> | java | | <<>> | -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ -| <<>> | | <= type> | <= type> | java | | <<>> | -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ -| <<>> | | <= type> | <= type> | java | | <<>> | -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ -| <<>> | <<>> | <<>> | <= type> | java | | | -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ -| <<>> | <<>> | <<>> | <= type> | java | <<>> | | -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ +For compatibility, legacy Maven 3 artifact handlers are still provided: + +|type|classifier|extension|packaging|language|added to classpath|includesDependencies| +|:---|:---|:---|:---|:---|:---|:---| +|`pom`| |_= type_|_= type_|none| | | +|`jar`| |_= type_|_= type_|java|`true`| | +|`test-jar`|`tests`|`jar`|`jar`|java|`true`| | +|`maven-plugin`| |`jar`|_= type_|java|`true`| | +|`ejb`| |`jar`|_= type_|java|`true`| | +|`ejb-client`|`client`|`jar`|`ejb`|java|`true`| | +|`war`| |_= type_|_= type_|java| |`true`| +|`ear`| |_= type_|_= type_|java| |`true`| +|`rar`| |_= type_|_= type_|java| |`true`| +|`java-source`|`sources`|`jar`|_= type_|java| | | +|`javadoc`|`javadoc`|`jar`|_= type_|java|`true`| | diff --git a/impl/maven-core/src/site/markdown/configuration-management.md b/impl/maven-core/src/site/markdown/configuration-management.md index 5954ed1dce13..d3ef8986acab 100644 --- a/impl/maven-core/src/site/markdown/configuration-management.md +++ b/impl/maven-core/src/site/markdown/configuration-management.md @@ -1,95 +1,65 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. - - ----- - Maven configuration management - ----- - The Maven Team - ----- - -Configuration levels in maven - - In maven configuration control happens on four differ levels: the site level, the group level, - the project level, and the user level. On the site level you can configure maven for all users - utilizing the local installation, the group level allows configuration management for all the projects - that belong to the same group, the project level allows configuration management at - the project level, and the user level allows users to override settings on - the site level, group level and project level. - -* Site configuration - - At the site level all configuration is achieved by tweaking the various files that - are available in the ${maven.home}/site-configuration directory - -+-----+ + + +# Configuration levels in maven + +In maven configuration control happens on four differ levels: the site level, the group level, the project level, and the user level. On the site level you can configure maven for all users utilizing the local installation, the group level allows configuration management for all the projects that belong to the same group, the project level allows configuration management at the project level, and the user level allows users to override settings on the site level, group level and project level. + +## Site configuration + +At the site level all configuration is achieved by tweaking the various files that are available in the `${maven.home}`/site-configuration directory + +``` ${maven.home} | +--- maven.properties -+-----+ +``` -* Group configuration +## Group configuration - As far as properties go for an entire build the maven.properties could be placed at - the top of the group but I'm not really sure how this might work. There could probably - also be a directory for plugins.xml and maven.properties. +As far as properties go for an entire build the maven.properties could be placed at the top of the group but I'm not really sure how this might work. There could probably also be a directory for plugins.xml and maven.properties. -* Project configuration +## Project configuration - At the project level all configuration is achieved by tweaking the POM. One of the differences between - maven 1.x and 2.x is that all project parameterization occurs in the POM and not from properties - files. +At the project level all configuration is achieved by tweaking the POM. One of the differences between maven 1.x and 2.x is that all project parameterization occurs in the POM and not from properties files. - For many of the more advanced features in Maven2 it is critical that POMs be available in the local repository. - Features like transitive dependencies and the new parent specification mechanism. The problem we run into is - that currently we have information about a project scattered across the project.xml and the - various properties files. What needs to be done is to encapsulate all of this in the POM. +For many of the more advanced features in Maven2 it is critical that POMs be available in the local repository. Features like transitive dependencies and the new parent specification mechanism. The problem we run into is that currently we have information about a project scattered across the project.xml and the various properties files. What needs to be done is to encapsulate all of this in the POM. - Typically users parameterize the use of plugins, or have custom values like ${user.name} - for use in elements like the . It would be idea if we - could encapsulate everything we need about the project in the POM including - plugin parameters and anything else. +Typically users parameterize the use of plugins, or have custom values like `${user.name}` for use in elements like the ``. It would be idea if we could encapsulate everything we need about the project in the POM including plugin parameters and anything else. - We once had a document that Vincent and I agreed upon and I was about to - implement it and then I disappeared for 8 months so it never came to pass. +We once had a document that Vincent and I agreed upon and I was about to implement it and then I disappeared for 8 months so it never came to pass. - So I guess it's important to figure out what people are using properties - files for and see if we can't incorporate it all into the POM. Or if we do - have properties file (something I would like to avoid) say they don't - contribute in any meaningful way to information in the POM. For example a - properties file could be used the specify $ so it can be interpolated in - but you couldn't use a properties file to specify the - version of your project say. Anyway, food for thought to begin with. +So I guess it's important to figure out what people are using properties files for and see if we can't incorporate it all into the POM. Or if we do have properties file (something I would like to avoid) say they don't contribute in any meaningful way to information in the POM. For example a properties file could be used the specify $ so it can be interpolated in `` but you couldn't use a properties file to specify the version of your project say. Anyway, food for thought to begin with. - - elements that are critical for pom dissemination - - those that are used locally by the user like +\- elements that are critical for pom dissemination - those that are used locally by the user like `` -* User configuration +## User configuration - User configuration which is utilized site wide are controlled with the ${user.home}/.m2/maven.properties. +User configuration which is utilized site wide are controlled with the `${user.home}`/.m2/maven.properties. - User configuration which is utilized at the project level are controlled with the - ${project.home}/maven.properties file. +User configuration which is utilized at the project level are controlled with the `${project.home}`/maven.properties file. -Plugin configuration +# Plugin configuration - The configuration of plugins is of the same form as the maven {{{plugin-descriptors}plugin descriptors}} - themselves: +The configuration of plugins is of the same form as the maven [plugin descriptors](#plugin-descriptors) themselves: -+-----+ +```xml xdoc @@ -102,38 +72,25 @@ Plugin configuration -+-----+ - -Unified source directory - - Unified source directory structure that is analogous to the repository - itself. This way locations of intermediary artifacts of a build would be - in a known location. This would also help with developer setup i.e. getting - new developers up and running. They could run a maven command and have all - their source trees set up in the same way as their colleagues. - - here's what I do currently in the netbeans part of the mavenide project to - find the relevant subprojects/sibling projects. I check if the user has - defined the maven.multiproject.includes property in any of his properties - files for the current project. if yes. then I'm able to find projects that - can be offered to be opened together with the current project. - problems with the current solution are: - 1. information is duplicate. once in POM's dependencies and once in the - maven.multiproject.includes property. - 2. it works without problems only for projects with relative paths, e.g., from - one CVS repository.. for projects from multiple SCM repositories it's harder - to maintain the same relative links on all developer computers. - not sure the unified source directory structure addresses this issue. - - Properties - - maven.user.config.dir (system,default=${user.home}/.m2) - maven.home (system,user,default=${user.home}/m2) - maven.repo.local (system,user,default=${maven.user.config.dir}/repository) - - We need to define what happens in the when things are not setup correctly - - o ~/.m2 directory does not exist - o ~/.m2/maven.properties does not exist - o if they once existed but now to do not exist - o what the installer will take care of of what we can recover from +``` + +# Unified source directory + +Unified source directory structure that is analogous to the repository itself. This way locations of intermediary artifacts of a build would be in a known location. This would also help with developer setup i.e. getting new developers up and running. They could run a maven command and have all their source trees set up in the same way as their colleagues. + +here's what I do currently in the netbeans part of the mavenide project to find the relevant subprojects/sibling projects. I check if the user has defined the maven.multiproject.includes property in any of his properties files for the current project. if yes. then I'm able to find projects that can be offered to be opened together with the current project. problems with the current solution are: 1. information is duplicate. once in POM's dependencies and once in the maven.multiproject.includes property. 2. it works without problems only for projects with relative paths, e.g., from one CVS repository.. for projects from multiple SCM repositories it's harder to maintain the same relative links on all developer computers. not sure the unified source directory structure addresses this issue. + +### Properties + +``` +maven.user.config.dir (system,default=${user.home}/.m2) +maven.home (system,user,default=${user.home}/m2) +maven.repo.local (system,user,default=${maven.user.config.dir}/repository) +``` + +We need to define what happens in the when things are not setup correctly + +- `~/.m2` directory does not exist +- `~/.m2/maven.properties` does not exist +- if they once existed but now to do not exist +- what the installer will take care of of what we can recover from diff --git a/impl/maven-core/src/site/markdown/core-extensions.md.vm b/impl/maven-core/src/site/markdown/core-extensions.md.vm index 164ec13e6f00..d8c0eaaefb51 100644 --- a/impl/maven-core/src/site/markdown/core-extensions.md.vm +++ b/impl/maven-core/src/site/markdown/core-extensions.md.vm @@ -1,30 +1,24 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - Maven core provides default {{{./extension.html}extensions}} as defined in <<>>: +# Maven Core Extensions Reference -%{snippet|id=core-extension|file=${project.basedir}/src/main/resources/META-INF/maven/extension.xml} +Maven core provides default [extensions](./extension.html) as defined in `/META-INF/maven/extension.xml`: + + diff --git a/impl/maven-core/src/site/markdown/default-bindings.md.vm b/impl/maven-core/src/site/markdown/default-bindings.md.vm index c917d0c2718f..4e08468028a9 100644 --- a/impl/maven-core/src/site/markdown/default-bindings.md.vm +++ b/impl/maven-core/src/site/markdown/default-bindings.md.vm @@ -1,64 +1,63 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - The {{{./lifecycles.html}<<>> lifecycle}} is defined without any plugin binding; plugins bindings are defined separately - in {{{./apidocs/org/apache/maven/lifecycle/providers/packaging/package-summary.html}<<>>}} package - because they are specific for each packaging: +# Plugins Bindings for `default` Lifecycle Reference -%{toc|fromDepth=2} +The [`default` lifecycle](./lifecycles.html) is defined without any plugin binding; plugins bindings are defined separately in [`org.apache.maven.lifecycle.providers.packaging`](./apidocs/org/apache/maven/lifecycle/providers/packaging/package-summary.html) package because they are specific for each packaging: - Versions of the plugins are shared in a few constants: + -%{snippet|id=versions|file=${project.basedir}/src/main/java/org/apache/maven/lifecycle/providers/packaging/AbstractLifecycleMappingProvider.java} +Versions of the plugins are shared in a few constants: -* Plugin bindings for <<>> packaging + -%{snippet|id=pom|file=${project.basedir}/src/main/java/org/apache/maven/lifecycle/providers/packaging/PomLifecycleMappingProvider.java} +Plugin bindings for `pom` packaging +----------------------------------- -* Plugin bindings for <<>> packaging + -%{snippet|id=jar|file=${project.basedir}/src/main/java/org/apache/maven/lifecycle/providers/packaging/JarLifecycleMappingProvider.java} +Plugin bindings for `jar` packaging +----------------------------------- -* Plugin bindings for <<>> packaging + -%{snippet|id=ejb|file=${project.basedir}/src/main/java/org/apache/maven/lifecycle/providers/packaging/EjbLifecycleMappingProvider.java} +Plugin bindings for `ejb` packaging +----------------------------------- -* Plugin bindings for <<>> packaging + -%{snippet|id=maven-plugin|file=${project.basedir}/src/main/java/org/apache/maven/lifecycle/providers/packaging/MavenPluginLifecycleMappingProvider.java} +Plugin bindings for `maven-plugin` packaging +-------------------------------------------- -* Plugin bindings for <<>> packaging + -%{snippet|id=war|file=${project.basedir}/src/main/java/org/apache/maven/lifecycle/providers/packaging/WarLifecycleMappingProvider.java} +Plugin bindings for `war` packaging +----------------------------------- -* Plugin bindings for <<>> packaging + -%{snippet|id=ear|file=${project.basedir}/src/main/java/org/apache/maven/lifecycle/providers/packaging/EarLifecycleMappingProvider.java} +Plugin bindings for `ear` packaging +----------------------------------- -* Plugin bindings for <<>> packaging + -%{snippet|id=rar|file=${project.basedir}/src/main/java/org/apache/maven/lifecycle/providers/packaging/RarLifecycleMappingProvider.java} +Plugin bindings for `rar` packaging +----------------------------------- + + diff --git a/impl/maven-core/src/site/markdown/getting-to-container-configured-mojos.md b/impl/maven-core/src/site/markdown/getting-to-container-configured-mojos.md index 8b8a975f5760..d0563cbd2873 100644 --- a/impl/maven-core/src/site/markdown/getting-to-container-configured-mojos.md +++ b/impl/maven-core/src/site/markdown/getting-to-container-configured-mojos.md @@ -1,102 +1,64 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - We're moving toward integrating mojos as first-class plexus components, while - at the same time avoiding introducing required plexus dependencies into the - mojo development model. +# Abstract - In order to really achieve this, we need mojo configurations (which are - provided both in terms of static expressions that are just looked up, and - in terms of user-provided configuration from properties or the POM). - If these mojos are to be first-class components, the configuration from these - various sources must be consolidated and injected using the container. +We're moving toward integrating mojos as first-class plexus components, while at the same time avoiding introducing required plexus dependencies into the mojo development model. - Currently, mojo configuration is done externally to the container, in the - DefaultPluginManager in the maven-core API. In order to get from here to - there, we need to do several things to add capability to the default - configuration of plexus. This document will detail those changes. +In order to really achieve this, we need mojo configurations (which are provided both in terms of static expressions that are just looked up, and in terms of user-provided configuration from properties or the POM). If these mojos are to be first-class components, the configuration from these various sources must be consolidated and injected using the container. -Container Enhancements +Currently, mojo configuration is done externally to the container, in the DefaultPluginManager in the maven-core API. In order to get from here to there, we need to do several things to add capability to the default configuration of plexus. This document will detail those changes. -* ExpressionEvaluator +# Container Enhancements - Currently, the expression evaluator used to resolve configuration values - is the DefaultExpressionEvaluator, which is a local variable within the - implementation of the BasicComponentConfigurator. This ExpressionEvaluator - simply returns the expression itself as the resolved value, which adds - very little value to the container. Things like ${project.build.resources} - are not resolved, and result in a type mismatch for the member injection. +## ExpressionEvaluator - We need a replacement for DefaultExpressionEvaluator that is capable of - traversing an object graph and extracting Object values, not just Strings. +Currently, the expression evaluator used to resolve configuration values is the DefaultExpressionEvaluator, which is a local variable within the implementation of the BasicComponentConfigurator. This ExpressionEvaluator simply returns the expression itself as the resolved value, which adds very little value to the container. Things like `${project.build.resources}` are not resolved, and result in a type mismatch for the member injection. -* ComponentConfigurator +We need a replacement for DefaultExpressionEvaluator that is capable of traversing an object graph and extracting Object values, not just Strings. - Currently, the container uses BasicComponentConfigurator, to configure - components. This wouldn't be a problem, except for the local instance of - DefaultExpressionEvaluator used within. See the above discussion for more - on why this evaluator is bad. We need to provide either an alternative - implementation under a different roleHint, or else replace the - BasicComponentConfigurator. +## ComponentConfigurator -* Other +Currently, the container uses BasicComponentConfigurator, to configure components. This wouldn't be a problem, except for the local instance of DefaultExpressionEvaluator used within. See the above discussion for more on why this evaluator is bad. We need to provide either an alternative implementation under a different roleHint, or else replace the BasicComponentConfigurator. - We may need to define a new lifecycle/phase to contextualize a mojo right - before it's used, and reset it's state afterward. Up to now, the approach - of most plexus components has been to avoid instance state like the plague. - With the current parameter passing model of mojos, this will not be possible, - particularly when we move mojos to a singleton instantiation model, and then - run a reactorized project...the successive calls may leave behind configuration - artifacts from invocation to invocation. +## Other -Maven Modifications +We may need to define a new lifecycle/phase to contextualize a mojo right before it's used, and reset it's state afterward. Up to now, the approach of most plexus components has been to avoid instance state like the plague. With the current parameter passing model of mojos, this will not be possible, particularly when we move mojos to a singleton instantiation model, and then run a reactorized project...the successive calls may leave behind configuration artifacts from invocation to invocation. -* DefaultPluginManager +# Maven Modifications - s/getMojoConfiguration()/getConfiguration()/g +## DefaultPluginManager - That should re-enable usage of mojo configuration. Ideally, we won't need any - of the code that references this method, since the container should provide - some way of recontextualizing the mojo, and all we would need to do is inject - POM configuration via the lookup method or something. +s/getMojoConfiguration()/getConfiguration()/g -* PluginDescriptorBuilder +That should re-enable usage of mojo configuration. Ideally, we won't need any of the code that references this method, since the container should provide some way of recontextualizing the mojo, and all we would need to do is inject POM configuration via the lookup method or something. - s/getMojoConfiguration()/getConfiguration()/g +## PluginDescriptorBuilder - That should be all there is to it. +s/getMojoConfiguration()/getConfiguration()/g -* MojoDescriptor +That should be all there is to it. - Remove set/getMojoConfiguration(..), as it will become obsolete. +## MojoDescriptor -* MavenSession +Remove set/getMojoConfiguration(..), as it will become obsolete. - We may need to enable the context injection here, since this will be - instantiated per-project. If we always inject the same context parameters, - and are careful to inject nulls where things are missing, we should be - able to minimize reconfiguration artifacts injected from basic parameters. +## MavenSession +We may need to enable the context injection here, since this will be instantiated per-project. If we always inject the same context parameters, and are careful to inject nulls where things are missing, we should be able to minimize reconfiguration artifacts injected from basic parameters. diff --git a/impl/maven-core/src/site/markdown/index.md b/impl/maven-core/src/site/markdown/index.md index cb5e3570385a..7f8da6e843ca 100644 --- a/impl/maven-core/src/site/markdown/index.md +++ b/impl/maven-core/src/site/markdown/index.md @@ -1,97 +1,54 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - Maven Core classes managing the whole build process. +# Maven Core -* Reference Documentation +Maven Core classes managing the whole build process. - * {{{./lifecycles.html}lifecycles}} and {{{./default-bindings.html}plugin bindings to <<>> lifecycle}}, +## Reference Documentation - * {{{./artifact-handlers.html}default artifact handlers}}, to manage {{{../../api/maven-api-model/maven.html#class_dependency}dependency types}}, +- [lifecycles](./lifecycles.html) and [plugin bindings to `default` lifecycle](./default-bindings.html), +- [default artifact handlers](./artifact-handlers.html), to manage [dependency types](../../api/maven-api-model/maven.html#class_dependency), +- [extension descriptor](./extension.html) and [core extensions](./core-extensions.html), +- [classloader hierarchy](/guides/mini/guide-maven-classloading.html) done by `ClassRealmManager` component ([javadoc](./apidocs/org/apache/maven/classrealm/ClassRealmManager.html)), with its `DefaultClassRealmManager` implementation ([source](./xref/org/apache/maven/classrealm/DefaultClassRealmManager.html)), using [Plexus Classworlds](https://codehaus-plexus.github.io/plexus-classworlds/), - * {{{./extension.html}extension descriptor}} and {{{./core-extensions.html}core extensions}}, +## Useful entry points - * {{{/guides/mini/guide-maven-classloading.html}classloader hierarchy}} done by <<>> component - ({{{./apidocs/org/apache/maven/classrealm/ClassRealmManager.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/classrealm/DefaultClassRealmManager.html}source}}), using - {{{https://codehaus-plexus.github.io/plexus-classworlds/}Plexus Classworlds}}, +- `Maven` component ([javadoc](./apidocs/org/apache/maven/Maven.html)), with its `DefaultMaven` implementation ([source](./xref/org/apache/maven/DefaultMaven.html)), to drive a full Maven execution session +- `ProjectBuilder` component ([javadoc](./apidocs/org/apache/maven/project/ProjectBuilder.html)), with its `DefaultProjectBuilder` implementation ([source](./xref/org/apache/maven/project/DefaultProjectBuilder.html)), to prepare [`MavenProject` descriptor](./apidocs/org/apache/maven/project/MavenProject.html) from POM files, +- `LifecycleExecutor` component ([javadoc](./apidocs/org/apache/maven/lifecycle/LifecycleExecutor.html)), with its `DefaultLifecycleExecutor` implementation([source](/xref/org/apache/maven/lifecycle/DefaultLifecycleExecutor.html)), to plan or execute tasks. + on plugin goals execution order: + - **in a given phase, goals order is not expected to be guaranteed nor finely tuned**: it is just a consequence of the order obtained during [effective model building](../maven-model-builder/), which combines profile activation+injection and inheritance assembly from parents, + - known limitations are notably that: -* Useful entry points + 1\. plugin goal execution in a child is usually simply appended (at end): you can't try to insert in the middle of pre-existing inherited executions, - * <<>> component ({{{./apidocs/org/apache/maven/Maven.html}javadoc}}), - with its <<>> implementation ({{{./xref/org/apache/maven/DefaultMaven.html}source}}), to drive - a full Maven execution session + 2\. append happens at plugin level first, then goal level, independently from phases. This means for example that adding pluginA:goal2 to pre-existing (pluginA:goal1, pluginB:goal) will lead to (pluginA:goal1, pluginA:goal2, pluginB:goal) - * <<>> component ({{{./apidocs/org/apache/maven/project/ProjectBuilder.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/project/DefaultProjectBuilder.html}source}}), to prepare {{{./apidocs/org/apache/maven/project/MavenProject.html}<<>> descriptor}} from POM files, + - see effective POM as shown by [`help:effective-pom`](/plugins/maven-help-plugin/effective-pom-mojo.html) to see the effective plugins then goals order. +- `MavenPluginManager` component ([javadoc](./apidocs/org/apache/maven/plugin/MavenPluginManager.html)), with its `DefaultMavenPluginManager` implementation ([source](./xref/org/apache/maven/plugin/internal/DefaultMavenPluginManager.html)), +- [PluginParameterExpressionEvaluator](./apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html), used to evaluate plugin parameters values during Mojo configuration, +- `ExceptionHandler` component ([javadoc](./apidocs/org/apache/maven/exception/ExceptionHandler.html)), with its `DefaultExceptionHandler` implementation ([source](./xref/org/apache/maven/exception/DefaultExceptionHandler.html)), use to transform exception into useful end-user messages. - * <<>> component ({{{./apidocs/org/apache/maven/lifecycle/LifecycleExecutor.html}javadoc}}), - with its <<>> implementation({{{/xref/org/apache/maven/lifecycle/DefaultLifecycleExecutor.html}source}}), to plan or execute tasks.\ - on plugin goals execution order: +## Toolchains - * <>: - it is just a consequence of the order obtained during {{{../maven-model-builder/}effective model building}}, - which combines profile activation+injection and inheritance assembly from parents, - - * known limitations are notably that: - - 1. plugin goal execution in a child is usually simply appended (at end): you can't try to insert in the middle of pre-existing inherited executions, - - 2. append happens at plugin level first, then goal level, independently from phases. - This means for example that adding pluginA:goal2 to pre-existing (pluginA:goal1, pluginB:goal) will lead to (pluginA:goal1, pluginA:goal2, pluginB:goal) - - * see effective POM as shown by {{{/plugins/maven-help-plugin/effective-pom-mojo.html}<<>>}} to see the effective plugins then goals order. - - * <<>> component ({{{./apidocs/org/apache/maven/plugin/MavenPluginManager.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/plugin/internal/DefaultMavenPluginManager.html}source}}), - - * {{{./apidocs/org/apache/maven/plugin/PluginParameterExpressionEvaluator.html}PluginParameterExpressionEvaluator}}, used to - evaluate plugin parameters values during Mojo configuration, - - * <<>> component ({{{./apidocs/org/apache/maven/exception/ExceptionHandler.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/exception/DefaultExceptionHandler.html}source}}), use to transform exception into useful end-user messages. - -* Toolchains - - * {{{../../api/maven-api-toolchain/toolchains.html}Toolchains descriptor reference}}, - - * public API for toolchains-aware plugins: <<>> component ({{{./apidocs/org/apache/maven/toolchain/ToolchainManager.html}javadoc}}) - with its <<>> implementation ({{{./xref/org/apache/maven/toolchain/DefaultToolchainManager.html}source}}), - to get selected <<>> ({{{./apidocs/org/apache/maven/toolchain/Toolchain.html}javadoc}}) instance, - - * internal <<>> component ({{{./apidocs/org/apache/maven/toolchain/ToolchainManagerPrivate.html}javadoc}}) - with its <<>> implementation ({{{./xref/org/apache/maven/toolchain/DefaultToolchainManagerPrivate.html}source}}), - to manage toolchain selection, - - * internal JDK toolchain implementation: <<>> interface ({{{./apidocs/org/apache/maven/toolchain/java/JavaToolchain.html}javadoc}}), - with its <<>> implementation - ({{{./xref/org/apache/maven/toolchain/java/JavaToolchainImpl.html}source}}) and <<>> - factory ({{{./xref/org/apache/maven/toolchain/java/JavaToolchainFactory.html}source}}). +- [Toolchains descriptor reference](../../api/maven-api-toolchain/toolchains.html), +- public API for toolchains-aware plugins: `ToolchainManager` component ([javadoc](./apidocs/org/apache/maven/toolchain/ToolchainManager.html)) with its `DefaultToolchainManager` implementation ([source](./xref/org/apache/maven/toolchain/DefaultToolchainManager.html)), to get selected `Toolchain` ([javadoc](./apidocs/org/apache/maven/toolchain/Toolchain.html)) instance, +- internal `ToolchainManagerPrivate` component ([javadoc](./apidocs/org/apache/maven/toolchain/ToolchainManagerPrivate.html)) with its `DefaultToolchainManagerPrivate` implementation ([source](./xref/org/apache/maven/toolchain/DefaultToolchainManagerPrivate.html)), to manage toolchain selection, +- internal JDK toolchain implementation: `JavaToolchain` interface ([javadoc](./apidocs/org/apache/maven/toolchain/java/JavaToolchain.html)), with its `JavaToolchainImpl` implementation ([source](./xref/org/apache/maven/toolchain/java/JavaToolchainImpl.html)) and `JavaToolchainFactory` factory ([source](./xref/org/apache/maven/toolchain/java/JavaToolchainFactory.html)). diff --git a/impl/maven-core/src/site/markdown/inheritance.md b/impl/maven-core/src/site/markdown/inheritance.md index 46e240f0f2ec..04b9927b522d 100644 --- a/impl/maven-core/src/site/markdown/inheritance.md +++ b/impl/maven-core/src/site/markdown/inheritance.md @@ -1,61 +1,50 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - In order the understand how inheritance works in Maven there are a few notions that you must be familiar with: +# Inheritance in Maven - * The maven super model +In order the understand how inheritance works in Maven there are a few notions that you must be familiar with: - * how parent poms are processed +- The maven super model +- how parent poms are processed +- the order in which elements in the POM are overridden +- minimum element-set for a valid project pom - * the order in which elements in the POM are overridden +# Maven super model - * minimum element-set for a valid project pom +Inheritance is recursive in Maven but there is a special model which is the implicit super parent in the lineage of models you may specify: +all of the models that you specify are collected to produce a lineage and then the super model is place at the top of that lineage to provide default values. -Maven super model +The super model is where we place all the values which we believe to be standard, values that can be shared and utilized across all your Maven projects. - Inheritance is recursive in Maven but there is a special model which is the implicit super parent in the lineage - of models you may specify: - - all of the models that you specify are collected to produce a lineage and then the super model is place at - the top of that lineage to provide default values. - - The super model is where we place all the values which we believe to be standard, values that can be shared and - utilized across all your Maven projects. - -+-----+ +``` m0 <- m1 <- m2 -+-----+ +``` - which is transformed into +which is transformed into -+-----+ +``` super model <- m0 <- m1 <- m2 -+-----+ +``` -+-----+ +```xml 4.0.0 @@ -64,37 +53,20 @@ Maven super model -+-----+ - -Extending the POM in the future +``` - In order to anticipate changes in the structure of the POM as new releases of - maven occur, the maven inheritance model must be pinned against a particular - modelVersion. This is required so that a change from modelVersion 4.0.0 to - 4.1.0 doesn't cause compatibility problems with users who have not upgraded - their projects. It also allows for a certain amount of legacy support into the - future. Therefore, we should rename this file from pom.xml in the maven-core - jarfile to pom-4.0.0.xml (and successive revisions to the base pom made to - accommodate changes in the model will be named accordingly - 4.0.1, 4.0.2, ...). +# Extending the POM in the future -Minimum Element-Set for a Project POM +In order to anticipate changes in the structure of the POM as new releases of maven occur, the maven inheritance model must be pinned against a particular modelVersion. This is required so that a change from modelVersion 4.0.0 to 4.1.0 doesn't cause compatibility problems with users who have not upgraded their projects. It also allows for a certain amount of legacy support into the future. Therefore, we should rename this file from pom.xml in the maven-core jarfile to pom-4.0.0.xml (and successive revisions to the base pom made to accommodate changes in the model will be named accordingly - 4.0.1, 4.0.2, ...). - In order to furnish a basic set of information which we need to distinguish one - project from another, maven requires a minimum set of elements to be specified - in each project's pom.xml. +# Minimum Element-Set for a Project POM - - [modelVersion] tells maven which version of the object model this project - is compliant with (to support future legacy concerns) +In order to furnish a basic set of information which we need to distinguish one project from another, maven requires a minimum set of elements to be specified in each project's pom.xml. - - [artifactId] tells maven what the artifact name is for this particular - project. Each project should have a distinct artifactId. +\- \[modelVersion\] tells maven which version of the object model this project is compliant with (to support future legacy concerns) - - [version] tells maven what release of this artifact we're trying to produce. - The fact that a project has a distinct pom.xml should indicate a separate - release cycle that is also distinct to that project, so a concrete version - declaration is required. +\- \[artifactId\] tells maven what the artifact name is for this particular project. Each project should have a distinct artifactId. - - [name] tells maven what the user-friendly name of this project is. The name - element is similar to artifactId in that it is a unique descriptor for - this and only this project, and therefore should be concretely defined. +\- \[version\] tells maven what release of this artifact we're trying to produce. The fact that a project has a distinct pom.xml should indicate a separate release cycle that is also distinct to that project, so a concrete version declaration is required. +\- \[name\] tells maven what the user-friendly name of this project is. The name element is similar to artifactId in that it is a unique descriptor for this and only this project, and therefore should be concretely defined. diff --git a/impl/maven-core/src/site/markdown/lifecycles.md.vm b/impl/maven-core/src/site/markdown/lifecycles.md.vm index 18d990922006..90afe7d9390a 100644 --- a/impl/maven-core/src/site/markdown/lifecycles.md.vm +++ b/impl/maven-core/src/site/markdown/lifecycles.md.vm @@ -1,49 +1,45 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - Maven defines 3 lifecycles, which are registered in {{{./apidocs/org/apache/maven/api/services/LifecycleRegistry.html}<<>>}}: +# Lifecycles Reference -%{toc|fromDepth=2} +Maven defines 3 lifecycles, which are registered in [`LifecycleRegistry`](./apidocs/org/apache/maven/api/services/LifecycleRegistry.html): -* <<>> Lifecycle + - <<>> lifecycle is defined only with phases, <> any associated plugin binding: - plugins bindings for this lifecycle are {{{./default-bindings.html}defined separately for each packaging}}: +`default` Lifecycle +------------------- -%{snippet|id=default|file=${project.basedir}/src/main/java/org/apache/maven/internal/impl/DefaultLifecycleRegistry.java} +`default` lifecycle is defined only with phases, **without** any associated plugin binding: plugins bindings for this lifecycle are [defined separately for each packaging](./default-bindings.html): -* <<>> Lifecycle + - <<>> lifecycle phases are defined with their plugins bindings: +`clean` Lifecycle +----------------- -%{snippet|id=clean|file=${project.basedir}/src/main/java/org/apache/maven/internal/impl/DefaultLifecycleRegistry.java} +`clean` lifecycle phases are defined with their plugins bindings: -* <<>> Lifecycle + - <<>> lifecycle phases are defined with their plugins bindings: +`site` Lifecycle +---------------- -%{snippet|id=site|file=${project.basedir}/src/main/java/org/apache/maven/internal/impl/DefaultLifecycleRegistry.java} +`site` lifecycle phases are defined with their plugins bindings: + + diff --git a/impl/maven-core/src/site/markdown/offline-mode.md b/impl/maven-core/src/site/markdown/offline-mode.md index 0311bc8ce0fa..19a4e1d51aca 100644 --- a/impl/maven-core/src/site/markdown/offline-mode.md +++ b/impl/maven-core/src/site/markdown/offline-mode.md @@ -1,269 +1,158 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. - - --- - Offline Mode Design - --- - John Casey - --- - 2005-04-08 - --- - -Offline Mode Design - -* UPDATE: 18-April-2005 - - We cannot take the approach outlined below of detecting which remote - repositories are "really" offline, since offline mode is more of a behavior, - and this will lead to counter-intuitive results. A different feature may exist - unimplemented, which is to detect when the network is down and provide better - feedback for that case. However, when offline mode is declared, nothing - earmarked as remote should be accessed, regardless of whether it is actually - a physically local resource. - - NOTE: One side effect of this design change is that all offline-mode code can - be isolated to maven-core, maven-plugin-descriptor, and [possibly] - maven-artifact. Usage of maven-wagon will be determined by an offline-aware - manager. - -* Assumptions: What is Offline? - - For the purposes of determining the areas sensitive to offline status, - it is definitely useful to define what the offline state really means. - - [[1]] This is obvious, but the network/internet is unavailable. - - [[2]] Localhost (127.0.0.1) may also be unavailable if the whole - network stack is offline. + - * Not all "remote" repositories will fail. Specifically, if the remote - repo uses the file:// protocol, and it doesn't refer to a shared - filesystem, it will continue to be available. +# Offline Mode Design - The question remaining is: Which level of offline mode will we support? It - seems reasonable to assume that users will be able to tell when localhost is - not active (in most cases, localhost should be available, even if the rest of - the network is not). Therefore, let's concentrate on the state where no - network exists, and leave the more extreme state to users - to diagnose and correct as necessary. +## UPDATE: 18-April-2005 -* Why is Offline Mode Important? +We cannot take the approach outlined below of detecting which remote repositories are "really" offline, since offline mode is more of a behavior, and this will lead to counter-intuitive results. A different feature may exist unimplemented, which is to detect when the network is down and provide better feedback for that case. However, when offline mode is declared, nothing earmarked as remote should be accessed, regardless of whether it is actually a physically local resource. - Offline mode is essential for breaking the requirement that m2 operate in a - network-connected environment. It means legitimizing a development environment - in which there is no network connection, and providing a robust m2 service - offering in such circumstances. Introduction of offline mode allows m2 to - anticipate the inevitable network failures that accompany being physically - disconnected from the network, and adjust it's behavior accordingly. +NOTE: One side effect of this design change is that all offline-mode code can be isolated to maven-core, maven-plugin-descriptor, and \[possibly\] maven-artifact. Usage of maven-wagon will be determined by an offline-aware manager. - It is more than simply understanding that m2 cannot go and check for the - latest version of some snapshot artifact. If m2 is offline, SCM operations - cannot succeed; no artifact downloads can take place, regardless of whether - they are snapshot versions; artifact deployment cannot take place; certain - types of tests cannot be setup, since the container used to run them cannot be - reached or started. +## Assumptions: What is Offline? - All of these operations will produce their own unique errors in the absence of - a coordinated offline strategy. In addition, efforts to unite these failing - behaviors behind a consistent user interface is much, much more difficult if - the system can't tell whether it has access to the network required by these - operations. +For the purposes of determining the areas sensitive to offline status, it is definitely useful to define what the offline state really means. - Offline mode really means anticipating a lack of network connectivity, and as - a result turning off certain services provided by m2 and providing a coherent - way of predicting and reporting when network-related failures will take place. - It means warning users that since the network is missing, certain features and - operations will be unavailable, rather than simply waiting for those - operations to fail, then trying to help users decipher the error messages they - get as a result. +1. This is obvious, but the network/internet is unavailable. +1. Localhost (127.0.0.1) may also be unavailable if the whole network stack is offline. +1. "Remote" repositories referenced using the file\:// protocol may be available. However, if that file\:// url references a file-share, as in the case of an NFS or SMB mount, that will be unavailable. -* Implications for Resolution + So, offline mode has several implications, some of which may not be altogether obvious: -** Dependency Resolution + - Localhost may be unavailable. Therefore, even locally installed server processes which work by conversing over a port may fail. + - Not all "remote" repositories will fail. Specifically, if the remote repo uses the file\:// protocol, and it doesn't refer to a shared filesystem, it will continue to be available. - This one is obvious...we only have access to the repositories using - the file:// protocol and living on a truly local filesystem when - offline. + The question remaining is: Which level of offline mode will we support? It seems reasonable to assume that users will be able to tell when localhost is not active (in most cases, localhost should be available, even if the rest of the network is not). Therefore, let's concentrate on the state where no network _beyond localhost_ exists, and leave the more extreme state to users to diagnose and correct as necessary. -** Plugin Resolution +## Why is Offline Mode Important? - This is similar to dependency resolution. Plugin repositories not - using file:// or not residing on a local (not shared) filesystem will - be unavailable. +Offline mode is essential for breaking the requirement that m2 operate in a network-connected environment. It means legitimizing a development environment in which there is no network connection, and providing a robust m2 service offering in such circumstances. Introduction of offline mode allows m2 to anticipate the inevitable network failures that accompany being physically disconnected from the network, and adjust it's behavior accordingly. +It is more than simply understanding that m2 cannot go and check for the latest version of some snapshot artifact. If m2 is offline, SCM operations cannot succeed; no artifact downloads can take place, regardless of whether they are snapshot versions; artifact deployment cannot take place; certain types of tests cannot be setup, since the container used to run them cannot be reached or started. -* Implications for Mojo Execution +All of these operations will produce their own unique errors in the absence of a coordinated offline strategy. In addition, efforts to unite these failing behaviors behind a consistent user interface is much, much more difficult if the system can't tell whether it has access to the network required by these operations. -** Deployment mojos +Offline mode really means anticipating a lack of network connectivity, and as a result turning off certain services provided by m2 and providing a coherent way of predicting and reporting when network-related failures will take place. It means warning users that since the network is missing, certain features and operations will be unavailable, rather than simply waiting for those operations to fail, then trying to help users decipher the error messages they get as a result. - The concept of deployment is dependent on the availability of a some - remote repository. Just as above, if that repository is not using - file:// (which is highly likely to be the case), or the repository is - not on a local filesystem, deployment will fail when offline. +## Implications for Resolution -** Testing mojos +### Dependency Resolution - This can be a problem if the tests are more than simple unit tests; - that is, if they require configuration of a server process, and - subsequent testing in-container. +This one is obvious...we only have access to the repositories using the file\:// protocol and living on a truly local filesystem when offline. - Since we're only going to concern ourselves with states where localhost is - still active, we only need to worry about this case when the server container - is <> installed on localhost. This allows the popular pattern of starting - a server container in-JVM, running tests against it, and shutting it down. +### Plugin Resolution -** SCM mojos +This is similar to dependency resolution. Plugin repositories not using file\:// or not residing on a local (not shared) filesystem will be unavailable. - See below for discussion on SCM-related operations. Any mojo which - carries out some analysis or other interaction with a SCM system - will likely be unavailable when in offline mode. +## Implications for Mojo Execution +### Deployment mojos -* Implications for Subsystems +The concept of deployment is dependent on the availability of a some remote repository. Just as above, if that repository is not using file\:// (which is highly likely to be the case), or the repository is not on a local filesystem, deployment will fail when offline. -** Maven-Wagon +### Testing mojos - Parts of Wagon will continue to function normally. These include: +This can be a problem if the tests are more than simple unit tests; that is, if they require configuration of a server process, and subsequent testing in-container. - * The file wagon, provided the referenced location is on a local - filesystem. +Since we're only going to concern ourselves with states where localhost is still active, we only need to worry about this case when the server container is **not** installed on localhost. This allows the popular pattern of starting a server container in-JVM, running tests against it, and shutting it down. - It is not possible to determine whether a file-based location will - be available except on a case-by-case basis (or a root-url by - root-url basis). We may want to move the offline sensitivity entirely to - Maven-Artifact, below, so we can be smarter about testing filesystem-based - repositories, etc. +### SCM mojos - * If not otherwise specified, all other wagons are assumed to be - remote-only, and are therefore sensitive to offline mode. +See below for discussion on SCM-related operations. Any mojo which carries out some analysis or other interaction with a SCM system will likely be unavailable when in offline mode. -** Maven-Artifact +## Implications for Subsystems - This is wholly dependent on Maven-Wagon, above. +### Maven-Wagon - We could possibly use a flag on a particular Wagon to see whether it supports - offline mode, and then test to see if the file-based basedir for an artifact - repository works...if it doesn't work, we can mark that repository offline... +Parts of Wagon will continue to function normally. These include: - OTOH, all offline-mode checks can probably be run from Wagon-based APIs. +- The file wagon, provided the referenced location is on a local filesystem. -** Maven-SCM + It is not possible to determine whether a file-based location will be available except on a case-by-case basis (or a root-url by root-url basis). We may want to move the offline sensitivity entirely to Maven-Artifact, below, so we can be smarter about testing filesystem-based repositories, etc. - In all but trivial examples, SCM operations cannot complete without - having access to the versioning server. Therefore, it is assumed that - any SCM-related activity will be unavailable when m2 is in offline - mode. +- If not otherwise specified, all other wagons are assumed to be remote-only, and are therefore sensitive to offline mode. -** Maven-Core +### Maven-Artifact - We'll examine the different parts of maven-core on a case-by-case - basis, below: +This is wholly dependent on Maven-Wagon, above. -*** DefaultLifecycleExecutor +We could possibly use a flag on a particular Wagon to see whether it supports offline mode, and then test to see if the file-based basedir for an artifact repository works...if it doesn't work, we can mark that repository offline... - When binding goals to the project's configured lifecycle, each mojo - descriptor should declare whether it requires online/offline status. - This value should be a java.lang.Boolean, so it can implement 3VL - (three value logic: yes, no, don't-care). The requiresOnline - field in the mojo descriptor has the following semantics: +OTOH, all offline-mode checks can probably be run from Wagon-based APIs. - [true] Online status is required for this mojo to function - correctly. +### Maven-SCM - [false] <<(Default)>> Either status is acceptable for the mojo to - execute. It doesn't care. +In all but trivial examples, SCM operations cannot complete without having access to the versioning server. Therefore, it is assumed that any SCM-related activity will be unavailable when m2 is in offline mode. - The majority of mojos will leave the requiresOnline == false, - since online/offline status will be irrelevant, provided they have - access to their required artifacts and other classpath elements. In the case - of required artifacts and other classpath elements, this is assumed by the - mojo API to be in a correct state, and will be handled by the Wagon - modifications. +### Maven-Core +We'll examine the different parts of maven-core on a case-by-case basis, below: -* Implementation Notes +#### DefaultLifecycleExecutor -** Accessibility of offline status +When binding goals to the project's configured lifecycle, each mojo descriptor should declare whether it requires online/offline status. This value should be a java.lang.Boolean, so it can implement 3VL (three value logic: yes, no, don't-care). The requiresOnline field in the mojo descriptor has the following semantics: - Offline status should be indicated in the MavenSettings instance, since it - can conceivably be set from either the settings.xml or the command-line. +
+
true
+
Online status is required for this mojo to function correctly.
+
false
+
(Default) Either status is acceptable for the mojo to execute. It doesn't care. - In the event the '-o' switch is the impetus for setting offline mode, this - should result in modification of the active profile in the MavenSettings - instance, just as definition of the active profile from the command-line - should result in similar modification. This object is not meant to be - static within the build process, but rather to be setup as an aggregation of - all settings-related information passed into the system. +The majority of mojos will leave the requiresOnline == false, since online/offline status will be irrelevant, provided they have access to their required artifacts and other classpath elements. In the case of required artifacts and other classpath elements, this is assumed by the mojo API to be in a correct state, and will be handled by the Wagon modifications. -** Control over downloads +
+
- Find the control point for m2 using maven-wagon. At this point, inject - a offline status parameter which is used when retrieving the specific Wagon. +## Implementation Notes - If <<>>: +### Accessibility of offline status - * If the wagon is not bound to "file://", then ignore the request and print - a debug message. +Offline status should be indicated in the MavenSettings instance, since it can conceivably be set from either the settings.xml or the command-line. - * If the wagon is bound to "file://" then: +In the event the '-o' switch is the impetus for setting offline mode, this should result in modification of the active profile in the MavenSettings instance, just as definition of the active profile from the command-line should result in similar modification. This object is not meant to be static within the build process, but rather to be setup as an aggregation of all settings-related information passed into the system. - Retrieve the file or base-url file to be "downloaded". +### Control over downloads + +Find the control point for m2 using maven-wagon. At this point, inject a offline status parameter which is used when retrieving the specific Wagon. - * If the file (or more usefully, the base-url file) exists, proceed. +If `offline == true`: - * If the file (or base-url file) doesn't exist, assume that this location - is part of a file-share. Ignore the request and print a debug message - as above. +- If the wagon is not bound to "file\://", then ignore the request and print a debug message. +- If the wagon is bound to "file\://" then: -** Control over mojos in the lifecycle + Retrieve the file or base-url file to be "downloaded". - When binding a mojo to the project's lifecycle instance, check the mojo - descriptor's requiredConnectivity field. + - If the file (or more usefully, the base-url file) exists, proceed. + - If the file (or base-url file) doesn't exist, assume that this location is part of a file-share. Ignore the request and print a debug message as above. - * If <<<(offline == true) && (requiresOnline != true)>>>, bind - the mojo to the lifecycle. +### Control over mojos in the lifecycle - In this case, the client is <>, and the mojo does not require - online status. +When binding a mojo to the project's lifecycle instance, check the mojo descriptor's requiredConnectivity field. - * If <<<(offline == false) && (requiresOnline == true)>>>, bind - the mojo to the lifecycle. +- If `(offline == true) && (requiresOnline != true)`, bind the mojo to the lifecycle. - In this case, the client is <>, and the mojo either requires - <> status, or else doesn't care. + In this case, the client is **offline**, and the mojo does not require online status. - * Otherwise, don't bind the mojo. Log a debug message to indicate that it is - sensitive the online state of the application, and that this state is - currently wrong for execution. +- If `(offline == false) && (requiresOnline == true)`, bind the mojo to the lifecycle. - <> Do we want to fail when we cannot bind a mojo to the lifecycle - because of offline/online status? That would probably indicate that the user - was trying to do something they cannot succeed at for now...so we probably - should throw an exception in this case. + In this case, the client is **online**, and the mojo either requires **online** status, or else doesn't care. +- Otherwise, don't bind the mojo. Log a debug message to indicate that it is sensitive the online state of the application, and that this state is currently wrong for execution. + **NOTE:** Do we want to fail when we cannot bind a mojo to the lifecycle because of offline/online status? That would probably indicate that the user was trying to do something they cannot succeed at for now...so we probably should throw an exception in this case. diff --git a/impl/maven-core/src/site/markdown/plugin-execution-isolation.md b/impl/maven-core/src/site/markdown/plugin-execution-isolation.md index b2983120e8c2..79e2a3c1d08c 100644 --- a/impl/maven-core/src/site/markdown/plugin-execution-isolation.md +++ b/impl/maven-core/src/site/markdown/plugin-execution-isolation.md @@ -1,34 +1,27 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - Maven2 takes advantage of Plexus' ability to execute a component using a - ClassWorlds ClassRealm that is populated with the JAR containing the - component in question and all of its dependencies. Using ClassWorlds - notation for realms we have the following: +# Maven plugin execution isolation -+-----+ +Maven2 takes advantage of Plexus' ability to execute a component using a ClassWorlds ClassRealm that is populated with the JAR containing the component in question and all of its dependencies. Using ClassWorlds notation for realms we have the following: + +``` [plexus.core] ^ | @@ -36,22 +29,8 @@ Maven plugin execution isolation ^ ^ | | [plugin0] [plugin1] -+-----+ - - The <<>> realm contains the resources required to run any - plexus application; The <<>> realm contains all of the - resources required to run Maven. Each subsequent plugin realm contains the - JAR plugin as well as its dependencies. The realms noted above are setup - in a hierarchical structure where the resources in the parent realms are - available but the <>. +``` - Plugins are guaranteed to be provided the resources found in - <<>> and <<>> realms at run-time if required. - Plugins can state compile-time dependencies on any of the resources found in - the core realms listed above and these dependencies will be included in the - plugin descriptor that is generated but when running within Maven these - resources will be filtered out. In other words these resources will not - be added the realm created for the plugins execution as they are provided - in the parent realms. +The `plexus.core` realm contains the resources required to run any plexus application; The `plexus.core.maven` realm contains all of the resources required to run Maven. Each subsequent plugin realm contains the JAR plugin as well as its dependencies. The realms noted above are setup in a hierarchical structure where the resources in the parent realms are available but the **realm is searched first before a search is made in the parent realm**. +Plugins are guaranteed to be provided the resources found in `plexus.core` and `plexus.core.maven` realms at run-time if required. Plugins can state compile-time dependencies on any of the resources found in the core realms listed above and these dependencies will be included in the plugin descriptor that is generated but when running within Maven these resources will be filtered out. In other words these resources will not be added the realm created for the plugins execution as they are provided in the parent realms. diff --git a/impl/maven-core/src/test/java/org/apache/maven/artifact/handler/ArtifactHandlerTest.java b/impl/maven-core/src/test/java/org/apache/maven/artifact/handler/ArtifactHandlerTest.java index 122da1e15a3d..1ac3f1b3c6cd 100644 --- a/impl/maven-core/src/test/java/org/apache/maven/artifact/handler/ArtifactHandlerTest.java +++ b/impl/maven-core/src/test/java/org/apache/maven/artifact/handler/ArtifactHandlerTest.java @@ -39,14 +39,14 @@ class ArtifactHandlerTest { @Test @SuppressWarnings("checkstyle:UnusedLocalVariable") - void testAptConsistency() throws Exception { - File apt = getTestFile("src/site/apt/artifact-handlers.apt"); + void testDocumentationConsistency() throws Exception { + File doc = getTestFile("src/site/markdown/artifact-handlers.md"); - List lines = Files.readAllLines(apt.toPath()); + List lines = Files.readAllLines(doc.toPath()); for (String line : lines) { - if (line.startsWith("||")) { - String[] cols = line.split("\\|\\|"); + if (line.startsWith("|type|")) { + String[] cols = line.split("\\|"); String[] expected = new String[] { "", "type", @@ -55,14 +55,15 @@ void testAptConsistency() throws Exception { "packaging", "language", "added to classpath", - "includesDependencies", - "" + "includesDependencies" }; int i = 0; for (String col : cols) { assertEquals(expected[i++], col.trim(), "Wrong column header"); } + } else if (line.startsWith("|:-")) { + continue; // the alignment row beneath the header } else if (line.startsWith("|")) { String[] cols = line.split("\\|"); @@ -97,7 +98,11 @@ private String trimApt(String content, String type) { } private String trimApt(String content) { - content = content.replace('<', ' ').replace('>', ' ').trim(); + content = content.replace('`', ' ') + .replace('_', ' ') + .replace('<', ' ') + .replace('>', ' ') + .trim(); return (content.isEmpty()) ? null : content; } diff --git a/impl/maven-impl/src/site/markdown/dependency-types.md b/impl/maven-impl/src/site/markdown/dependency-types.md index 1d119112b67d..4ecc8d322e32 100644 --- a/impl/maven-impl/src/site/markdown/dependency-types.md +++ b/impl/maven-impl/src/site/markdown/dependency-types.md @@ -1,82 +1,50 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - Defined in <<>> - ({{{./apidocs/org/apache/maven/internal/impl/resolver/type/DefaultTypeProvider.html}javadoc}}, - {{{./xref/org/apache/maven/internal/impl/resolver/type/DefaultTypeProvider.html}source}}): +# Default Dependency Types Reference -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -|| type || classifier || extension || language || path types || includesDependencies || -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -|| Maven || || || || || || -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | | <= type> | none | | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <<>> | none | | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | | <<>> | java | classes | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -|| Java || || || || || || -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | | <= type> | java | classes, modules | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | <<>> | <<>> | java | | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | <<>> | <<>> | java | classes | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | <<>> | <<>> | java | classes, patch module | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | <<>> | <<>> | java | | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <<>> | java | modules | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <<>> | java | classes | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <<>> | java | classes | <<>> | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <<>> | java | processor classes, processor modules | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <<>> | java | processor classes | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <<>> | java | processor modules | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -|| Java/Jakarta EE || || || || || || -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | | <<>> | java | classes | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | <<>> | <<>> | java | classes | | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | | <= type> | java | | <<>> | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | | <= type> | java | | <<>> | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> | | <= type> | java | | <<>> | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -| <<>> * | | <= type> | java | | <<>> | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ +Defined in `DefaultTypeProvider` ([javadoc](./apidocs/org/apache/maven/internal/impl/resolver/type/DefaultTypeProvider.html), [source](./xref/org/apache/maven/internal/impl/resolver/type/DefaultTypeProvider.html)): - * = new in Maven 4 \ No newline at end of file +|type|classifier|extension|language|path types|includesDependencies| +|:---|:---|:---|:---|:---|:---| +|**Maven**| | | | | | +|`pom`| |_= type_|none| | | +|`bom` *| |`pom`|none| | | +|`maven-plugin`| |`jar`|java|classes| | +|**Java**| | | | | | +|`jar`| |_= type_|java|classes, modules| | +|`java-source`|`sources`|`jar`|java| | | +|`javadoc`|`javadoc`|`jar`|java|classes| | +|`test-jar`|`tests`|`jar`|java|classes, patch module| | +|`test-java-source` *|`test-sources`|`jar`|java| | | +|`modular-jar` *| |`jar`|java|modules| | +|`classpath-jar` *| |`jar`|java|classes| | +|`fatjar` *| |`jar`|java|classes|`true`| +|`processor` *| |`jar`|java|processor classes, processor modules| | +|`classpath-processor` *| |`jar`|java|processor classes| | +|`modular-processor` *| |`jar`|java|processor modules| | +|**Java/Jakarta EE**| | | | | | +|`ejb`| |`jar`|java|classes| | +|`ejb-client`|`client`|`jar`|java|classes| | +|`war`| |_= type_|java| |`true`| +|`ear`| |_= type_|java| |`true`| +|`rar`| |_= type_|java| |`true`| +|`par` *| |_= type_|java| |`true`| + +- = new in Maven 4 diff --git a/impl/maven-impl/src/test/java/org/apache/maven/impl/resolver/type/DefaultTypeProviderTest.java b/impl/maven-impl/src/test/java/org/apache/maven/impl/resolver/type/DefaultTypeProviderTest.java index d0bf22edca20..6bef7dac09c5 100644 --- a/impl/maven-impl/src/test/java/org/apache/maven/impl/resolver/type/DefaultTypeProviderTest.java +++ b/impl/maven-impl/src/test/java/org/apache/maven/impl/resolver/type/DefaultTypeProviderTest.java @@ -20,6 +20,7 @@ import java.nio.file.Files; import java.nio.file.Path; +import java.util.Arrays; import java.util.LinkedHashSet; import java.util.List; import java.util.Map; @@ -44,18 +45,18 @@ class DefaultTypeProviderTest { "processor modules", JavaPathType.PROCESSOR_MODULES); @Test - void testAptConsistency() throws Exception { + void testDocumentationConsistency() throws Exception { Map types = new DefaultTypeProvider().types().stream().collect(Collectors.toMap(DefaultType::id, t -> t)); - Path apt = Path.of(System.getProperty("basedir", ""), "src/site/apt/dependency-types.apt"); - List lines = Files.readAllLines(apt); + Path doc = Path.of(System.getProperty("basedir", ""), "src/site/markdown/dependency-types.md"); + List lines = Files.readAllLines(doc); Set documentedTypes = new LinkedHashSet<>(); for (String line : lines) { - if (line.startsWith("||") || !line.startsWith("|")) { - continue; + if (!line.startsWith("|") || line.startsWith("|type|") || line.startsWith("|:-")) { + continue; // not a row, or the header row, or the alignment row beneath it } String[] cols = line.split("\\|"); @@ -63,6 +64,11 @@ void testAptConsistency() throws Exception { if (typeId == null) { continue; } + // a row carrying only a label groups the rows beneath it; APT wrote those as a + // second header row, which a Markdown table cannot express + if (Arrays.stream(cols).skip(2).allMatch(c -> trimApt(c) == null)) { + continue; + } documentedTypes.add(typeId); @@ -89,7 +95,7 @@ void testAptConsistency() throws Exception { Set undocumented = new LinkedHashSet<>(types.keySet()); undocumented.removeAll(documentedTypes); - assertTrue(undocumented.isEmpty(), "Types in provider but not in APT doc: " + undocumented); + assertTrue(undocumented.isEmpty(), "Types in provider but not documented: " + undocumented); } private Set parsePathTypes(String pathTypesStr) { @@ -106,8 +112,14 @@ private Set parsePathTypes(String pathTypesStr) { return result; } + /** Strips the Markdown emphasis and code markers the table uses around a cell value. */ private String trimApt(String content) { - content = content.replace('<', ' ').replace('>', ' ').replace('*', ' ').trim(); + content = content.replace('`', ' ') + .replace('_', ' ') + .replace('<', ' ') + .replace('>', ' ') + .replace('*', ' ') + .trim(); return content.isEmpty() ? null : content; } } diff --git a/impl/maven-logging/src/site/markdown/index.md b/impl/maven-logging/src/site/markdown/index.md index 01a29ee1bba5..d0d2abc5569f 100644 --- a/impl/maven-logging/src/site/markdown/index.md +++ b/impl/maven-logging/src/site/markdown/index.md @@ -1,35 +1,28 @@ -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. + - An extension to {{{https://www.slf4j.org/api/org/slf4j/simple/SimpleLogger.html}SLF4J Simple}} to add enhanced color support. +# Maven SLF4J Provider - Color is managed by <<>>, created by <<>>, and injected by <<>>: everything else is - copied at build time from {{{https://www.slf4j.org/api/org/slf4j/simple/SimpleLogger.html}SLF4J Simple}} +An extension to [SLF4J Simple](https://www.slf4j.org/api/org/slf4j/simple/SimpleLogger.html) to add enhanced color support. -* See Also +Color is managed by `MavenSimpleLogger`, created by `MavenSimpleLoggerFactory`, and injected by `StaticLoggerBinder`: everything else is copied at build time from [SLF4J Simple](https://www.slf4j.org/api/org/slf4j/simple/SimpleLogger.html) - * {{{../../compat/maven-embedder/logging.html}Maven Logging}} +## See Also + +- [Maven Logging](../../compat/maven-embedder/logging.html) diff --git a/its/core-it-suite/src/site/markdown/bootstrap.md.vm b/its/core-it-suite/src/site/markdown/bootstrap.md.vm index 252fb56bd0a4..06ea160c508b 100644 --- a/its/core-it-suite/src/site/markdown/bootstrap.md.vm +++ b/its/core-it-suite/src/site/markdown/bootstrap.md.vm @@ -1,96 +1,101 @@ - ----- - Maven Core Integration Tests Bootstrap - ----- - Hervé Boutemy - ----- - 2017-04-04 - ----- + -Maven Core Integration Tests Bootstrap +# Maven Core Integration Tests Bootstrap - Core IT Bootstrapping downloads from Central repository every dependency (artifacts, plugins) required to let - Core ITs Suite run without downloading anything later (see {{{./index.html#Core_ITs_Suite_and_Dependencies_.28incl._Plugins.29}Core ITs Suite and dependencies}} rationale). - - Content to download is defined in {{{https://github.com/apache/maven-integration-testing/tree/master/core-it-suite/src/test/resources/bootstrap}a series of bootstrap projects}}: +Core IT Bootstrapping downloads from Central repository every dependency (artifacts, plugins) required to let Core ITs Suite run without downloading anything later (see [Core ITs Suite and dependencies](./index.html#Core_ITs_Suite_and_Dependencies_.28incl._Plugins.29) rationale). -%{toc|section=1|fromDepth=2} +Content to download is defined in [a series of bootstrap projects](https://github.com/apache/maven-integration-testing/tree/master/core-it-suite/src/test/resources/bootstrap): -* Base Plugins And Their Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/target/resolve-plugins.txt} +Base Plugins And Their Dependencies +----------------------------------- -* Group 1 Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-1/target/resolve.txt} +Group 1 Dependencies +-------------------- -* Group 2 Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-2/target/resolve.txt} +Group 2 Dependencies +-------------------- -* Group 3 Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-3/target/resolve.txt} +Group 3 Dependencies +-------------------- -* Group 4 Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-4/target/resolve.txt} +Group 4 Dependencies +-------------------- -* Group 5 Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-5/target/resolve.txt} +Group 5 Dependencies +-------------------- -* Group 6 Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-6/target/resolve.txt} +Group 6 Dependencies +-------------------- -* Group 7 Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-7/target/resolve.txt} +Group 7 Dependencies +-------------------- -* Group 8 Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-8/target/resolve.txt} +Group 8 Dependencies +-------------------- -* Group 9 Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-9/target/resolve.txt} +Group 9 Dependencies +-------------------- -* Group 10 Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-10/target/resolve.txt} +Group 10 Dependencies +--------------------- -* Group 11 Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-11/target/resolve.txt} +Group 11 Dependencies +--------------------- -* Group 12 Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-12/target/resolve.txt} +Group 12 Dependencies +--------------------- -* Group 13 Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-13/target/resolve.txt} +Group 13 Dependencies +--------------------- -* Group 14 Dependencies + -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-14/target/resolve.txt} +Group 14 Dependencies +--------------------- + + diff --git a/its/core-it-suite/src/site/markdown/index.md.vm b/its/core-it-suite/src/site/markdown/index.md.vm index e7285dcc52c2..76412f030360 100644 --- a/its/core-it-suite/src/site/markdown/index.md.vm +++ b/its/core-it-suite/src/site/markdown/index.md.vm @@ -1,79 +1,61 @@ - ----- - Maven Core Integration Tests Suite - ----- - Hervé Boutemy - ----- - 2011-09-04 - ----- - -~~ Licensed to the Apache Software Foundation (ASF) under one -~~ or more contributor license agreements. See the NOTICE file -~~ distributed with this work for additional information -~~ regarding copyright ownership. The ASF licenses this file -~~ to you 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 -~~ -~~ http://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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Maven Core Integration Tests Suite - - This module provides the {{{./testapidocs/org/apache/maven/it/package-summary.html}effective Core Integration Tests suite}}, - starting with {{{./bootstrap.html}bootstrap}}. - -* Running Core ITs Suite - - Follow the steps that are described in the {{{https://github.com/apache/maven-integration-testing/blob/master/README.md}README.md}} - of the official {{{https://github.com/apache/maven-integration-testing}Core ITs Suite}} repository. - -* Core ITs Suite Results - - ITs results are displayed on the console and can be published in the site through Surefire Report. - -+---- -mvn -Preporting site -+---- + + +# Maven Core Integration Tests Suite + +This module provides the [effective Core Integration Tests suite](./testapidocs/org/apache/maven/it/package-summary.html), starting with [bootstrap](./bootstrap.html). - Currently deployed {{{./surefire-report.html}Surefire Report}} was generated with following environment: +Running Core ITs Suite +---------------------- + +Follow the steps that are described in the [README.md](https://github.com/apache/maven-integration-testing/blob/master/README.md) of the official [Core ITs Suite](https://github.com/apache/maven-integration-testing) repository. + +Core ITs Suite Results +---------------------- + +ITs results are displayed on the console and can be published in the site through Surefire Report. + +```shell +mvn -Preporting site +``` -%{snippet|file=${project.build.directory}/info.txt} +Currently deployed [Surefire Report](./surefire-report.html) was generated with following environment: + -* Core ITs Suite and Dependencies (incl. Plugins) +Core ITs Suite and Dependencies (incl. Plugins) +----------------------------------------------- - A good IT does not depend on external repos like Central, it uses dedicated test plugins and test repositories. - The {{{https://github.com/apache/maven-integration-testing/blob/master/core-it-suite/src/test/resources-filtered/settings.xml}default <<>>}} - used by ITs helps to enforce this by pointing <<>> at <<>>, - which obviously can't resolve anything. This setup using a file-based dummy repo also helps execution time, - because this repo produces (expected) <<<404>>>s much faster than a HTTP-based repo. +A good IT does not depend on external repos like Central, it uses dedicated test plugins and test repositories. The [default `settings.xml`](https://github.com/apache/maven-integration-testing/blob/master/core-it-suite/src/test/resources-filtered/settings.xml) used by ITs helps to enforce this by pointing `central` at `file:target/null`, which obviously can't resolve anything. This setup using a file-based dummy repo also helps execution time, because this repo produces (expected) `404`s much faster than a HTTP-based repo. - The one place where access to Central is desired is by adding artifacts to the - {{{https://github.com/apache/maven-integration-testing/blob/master/core-it-suite/src/test/resources/bootstrap.txt}bootstrap.txt}} file, - which is used to prime the local repo with any artifacts the ITs will need. This file should be kept sorted alphabetically for ease of use. +The one place where access to Central is desired is by adding artifacts to the [bootstrap.txt](https://github.com/apache/maven-integration-testing/blob/master/core-it-suite/src/test/resources/bootstrap.txt) file, which is used to prime the local repo with any artifacts the ITs will need. This file should be kept sorted alphabetically for ease of use. - So some care needs to be taken when introducing new dependencies into the ITs themselves or {{{../core-it-support/}the support plugins}}. - Many times the failures that we encounter are discrepancies between actual artifact consumption required and - what is populated during bootstrapping. When forgetting, typical failures (as seen in ASF CI) will give following traces in log: +So some care needs to be taken when introducing new dependencies into the ITs themselves or [the support plugins](../core-it-support/). Many times the failures that we encounter are discrepancies between actual artifact consumption required and what is populated during bootstrapping. When forgetting, typical failures (as seen in ASF CI) will give following traces in log: -------- +``` [ERROR] testit(org.apache.maven.it.MavenITmng...) Time elapsed: 0.145 s <<< ERROR! ... [ERROR] Failed to execute goal ... (...) on project ...: ... Could not find artifact ... in central (file:target/null) -> [Help 1] -------- +``` -** Using Local Repository Manager +#[[### Using Local Repository Manager]]# - If you are using a local repository manager, configured in your <<<~/.m2/settings.xml>>> as a mirror of <<>>, it will invalidate previous setup: - working Core ITs Suite can work on your laptop but fail on ASF CI because of missing artifact. +If you are using a local repository manager, configured in your `~/.m2/settings.xml` as a mirror of `central`, it will invalidate previous setup: working Core ITs Suite can work on your laptop but fail on ASF CI because of missing artifact. - Comment out your mirror configuration to enable the expected local failure, then be able to debug and fix the issue. +Comment out your mirror configuration to enable the expected local failure, then be able to debug and fix the issue. diff --git a/its/core-it-support/core-it-plugins/maven-it-plugin-core-stubs/src/site/markdown/index.md.vm b/its/core-it-support/core-it-plugins/maven-it-plugin-core-stubs/src/site/markdown/index.md.vm index 3800a597390a..53266450ef24 100644 --- a/its/core-it-support/core-it-plugins/maven-it-plugin-core-stubs/src/site/markdown/index.md.vm +++ b/its/core-it-support/core-it-plugins/maven-it-plugin-core-stubs/src/site/markdown/index.md.vm @@ -1,13 +1,5 @@ - ----- - About - ----- - Hervé Boutemy - ----- - 2012-10-13 - ----- +# ${project.name} -${project.name} +About ${project.description} - About ${project.description} - - See {{{./modules.html}Project Modules}} report for a complete list with description. +See [Project Modules](./modules.html) report for a complete list with description. diff --git a/its/core-it-support/core-it-plugins/src/site/markdown/index.md.vm b/its/core-it-support/core-it-plugins/src/site/markdown/index.md.vm index 3800a597390a..53266450ef24 100644 --- a/its/core-it-support/core-it-plugins/src/site/markdown/index.md.vm +++ b/its/core-it-support/core-it-plugins/src/site/markdown/index.md.vm @@ -1,13 +1,5 @@ - ----- - About - ----- - Hervé Boutemy - ----- - 2012-10-13 - ----- +# ${project.name} -${project.name} +About ${project.description} - About ${project.description} - - See {{{./modules.html}Project Modules}} report for a complete list with description. +See [Project Modules](./modules.html) report for a complete list with description. diff --git a/its/src/site/markdown/index.md b/its/src/site/markdown/index.md index 239eab0f2601..96ac18d30ef7 100644 --- a/its/src/site/markdown/index.md +++ b/its/src/site/markdown/index.md @@ -1,74 +1,55 @@ - ----- - Introduction - ----- - Hervé Boutemy - ----- - 2011-09-04 - ----- + +# Maven Core ITs -Maven Core ITs +Maven Core Integration Tests provide tooling to test every aspect of Maven functionalities with any Maven version. - Maven Core Integration Tests provide tooling to test every aspect of Maven functionalities with any Maven version. +This project is split in 2 modules: - This project is split in 2 modules: +- [Maven Core IT Support](./core-it-support/): Maven Integration Tests support tools, to completely decouple ITs from production plugins, +- [Maven Core ITs suite](./core-it-suite/): The effective Maven Integration Tests suite, providing the interesting [tests results](./core-it-suite/surefire-report.html). - * {{{./core-it-support/}Maven Core IT Support}}: Maven Integration Tests support tools, to completely decouple ITs from production plugins, +## Running the Core ITs - * {{{./core-it-suite/}Maven Core ITs suite}}: The effective Maven Integration Tests suite, providing the interesting {{{./core-it-suite/surefire-report.html}tests results}}. +By default, the project just packages the tests in an artifact. To actually run them, activate the `run-its` profile: +```shell +mvn clean test -Prun-its +``` -* Running the Core ITs +This will subject the Maven version running the build to the integration tests. - By default, the project just packages the tests in an artifact. To actually run them, activate the <<>> profile: - -+---- -mvn clean test -Prun-its -+---- - - This will subject the Maven version running the build to the integration tests. - - If you would like to test a different Maven distribution, you can use the <<>> system property to specify the - path of the Maven distribution to test: - -+---- +If you would like to test a different Maven distribution, you can use the `mavenHome` system property to specify the path of the Maven distribution to test: + +```shell mvn clean test -Prun-its -DmavenHome= -+---- - - Alternatively, you can just specify the version of a previously installed/deployed Maven distribution which will be - downloaded, unpacked and tested: - -+---- +``` + +Alternatively, you can just specify the version of a previously installed/deployed Maven distribution which will be downloaded, unpacked and tested: + +```shell mvn clean test -Prun-its -DmavenVersion=2.2.1 -+---- - - To run the ITs using embedded Maven 3.x, additionally activate the <<>> profile. - - ITs that don't require to fork Maven can also be run from the IDE using the Maven projects from the workspace if the - Maven dependencies are added to the test class path. - - If you're behind a proxy, use the system properties <<>>, <<>>, <<>>, <<>> - and <<>> to specify the required proxy setup for the ITs. Alternatively, set the system property - <<>> to a URL of a local repository manager (anonymous authentication only) that proxies the required - artifacts. - \ No newline at end of file +``` + +To run the ITs using embedded Maven 3.x, additionally activate the `embedded` profile. + +ITs that don't require to fork Maven can also be run from the IDE using the Maven projects from the workspace if the Maven dependencies are added to the test class path. + +If you're behind a proxy, use the system properties `proxy.host`, `proxy.port`, `proxy.user`, `proxy.pass` and `proxy.nonProxyHosts` to specify the required proxy setup for the ITs. Alternatively, set the system property `maven.it.central` to a URL of a local repository manager (anonymous authentication only) that proxies the required artifacts. From 19b6223c078ae3417b54ddaf6e381e11c4d3b221 Mon Sep 17 00:00:00 2001 From: Sylwester Lachiewicz Date: Fri, 7 Aug 2026 12:08:12 +0200 Subject: [PATCH 3/3] Restore the document metadata dropped when the pages were ported An APT document opens with a header block giving its title, authors and date, and doxia-converter turns that into YAML front matter. The port removed the front matter along with the converter's per-line licence comments, so the generated pages lost their author and date meta tags, and took their title from the first heading rather than from the document title. The front matter has to come first in the file: the Markdown parser only looks for it when the source begins with "---". --- apache-maven/src/site/markdown/index.md.vm | 7 +++++++ api/maven-api-cli/src/site/markdown/index.md | 7 +++++++ api/maven-api-metadata/src/site/markdown/index.md | 7 +++++++ api/maven-api-model/src/site/markdown/index.md | 9 +++++++++ api/maven-api-plugin/src/site/markdown/index.md | 7 +++++++ api/maven-api-settings/src/site/markdown/index.md | 7 +++++++ api/maven-api-toolchain/src/site/markdown/index.md | 7 +++++++ compat/maven-artifact/src/site/markdown/index.md | 7 +++++++ compat/maven-compat/src/site/markdown/index.md | 7 +++++++ compat/maven-embedder/src/site/markdown/cli.md.vm | 7 +++++++ compat/maven-embedder/src/site/markdown/index.md.vm | 7 +++++++ compat/maven-embedder/src/site/markdown/logging.md | 7 +++++++ compat/maven-model-builder/src/site/markdown/index.md | 7 +++++++ .../src/site/markdown/super-pom.md.vm | 7 +++++++ compat/maven-model/src/site/markdown/index.md | 9 +++++++++ compat/maven-plugin-api/src/site/markdown/index.md | 7 +++++++ .../maven-repository-metadata/src/site/markdown/index.md | 7 +++++++ .../src/site/markdown/dependency-types.md | 7 +++++++ .../maven-resolver-provider/src/site/markdown/index.md | 7 +++++++ compat/maven-settings/src/site/markdown/index.md | 7 +++++++ compat/maven-toolchain-model/src/site/markdown/index.md | 7 +++++++ impl/maven-core/src/site/markdown/artifact-handlers.md | 7 +++++++ .../src/site/markdown/configuration-management.md | 6 ++++++ impl/maven-core/src/site/markdown/core-extensions.md.vm | 7 +++++++ impl/maven-core/src/site/markdown/default-bindings.md.vm | 7 +++++++ .../markdown/getting-to-container-configured-mojos.md | 7 +++++++ impl/maven-core/src/site/markdown/index.md | 7 +++++++ impl/maven-core/src/site/markdown/inheritance.md | 6 ++++++ impl/maven-core/src/site/markdown/lifecycles.md.vm | 7 +++++++ impl/maven-core/src/site/markdown/offline-mode.md | 7 +++++++ .../src/site/markdown/plugin-execution-isolation.md | 6 ++++++ impl/maven-impl/src/site/markdown/dependency-types.md | 7 +++++++ impl/maven-logging/src/site/markdown/index.md | 7 +++++++ its/core-it-suite/src/site/markdown/bootstrap.md.vm | 7 +++++++ its/core-it-suite/src/site/markdown/index.md.vm | 7 +++++++ .../src/site/markdown/index.md.vm | 7 +++++++ .../core-it-plugins/src/site/markdown/index.md.vm | 7 +++++++ its/src/site/markdown/index.md | 7 +++++++ 38 files changed, 267 insertions(+) diff --git a/apache-maven/src/site/markdown/index.md.vm b/apache-maven/src/site/markdown/index.md.vm index 318bc03df87a..8ec3d8ef6009 100644 --- a/apache-maven/src/site/markdown/index.md.vm +++ b/apache-maven/src/site/markdown/index.md.vm @@ -1,3 +1,10 @@ +--- +title: ${project.name} +author: + - Hervé Boutemy +date: 2021-07-11 +--- +