diff --git a/apache-maven/src/site/apt/index.apt.vm b/apache-maven/src/site/apt/index.apt.vm deleted file mode 100644 index ae7ff8fd49ed..000000000000 --- a/apache-maven/src/site/apt/index.apt.vm +++ /dev/null @@ -1,43 +0,0 @@ -~~ 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 - ----- - 2021-07-11 - ----- - -${project.name} - - ${project.description} - -* References - - * <<>> invocation can be customized through pre-invocation script calls, that can be disabled by setting <<>> environment variable: - -*----------+--------------------------------------------+-----------------------+ -|| || 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) -*----------+--------------------------------------------+-----------------------+ diff --git a/apache-maven/src/site/markdown/index.md.vm b/apache-maven/src/site/markdown/index.md.vm new file mode 100644 index 000000000000..8ec3d8ef6009 --- /dev/null +++ b/apache-maven/src/site/markdown/index.md.vm @@ -0,0 +1,39 @@ +--- +title: ${project.name} +author: + - Hervé Boutemy +date: 2021-07-11 +--- + + + +# ${project.name} + +${project.description} + +References +---------- + +- `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/apt/index.apt b/api/maven-api-cli/src/site/apt/index.apt deleted file mode 100644 index 8d901b352531..000000000000 --- a/api/maven-api-cli/src/site/apt/index.apt +++ /dev/null @@ -1,41 +0,0 @@ -~~ 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 - ----- - 2025-11-16 - ----- - -Maven 4 API - CLI - - This is the {{{./apidocs/org/apache/maven/api/cli/package-summary.html}API}} for Maven's command-line interface and - tools: - - * <<<{{{./apidocs/org/apache/maven/api/cli/mvn/package-summary.html}mvn}}>>>, the Maven build tool, - - * <<<{{{./apidocs/org/apache/maven/api/cli/mvnenc/package-summary.html}mvnenc}}>>>, the Maven Password Encryption tool, - - * <<<{{{./apidocs/org/apache/maven/api/cli/mvnsh/package-summary.html}mvnsh}}>>>, the Maven Shell tool, - - * <<<{{{./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 diff --git a/api/maven-api-cli/src/site/markdown/index.md b/api/maven-api-cli/src/site/markdown/index.md new file mode 100644 index 000000000000..9d7c15b4e0f3 --- /dev/null +++ b/api/maven-api-cli/src/site/markdown/index.md @@ -0,0 +1,38 @@ +--- +title: Introduction +author: + - Hervé Boutemy +date: 2025-11-16 +--- + + + +# Maven 4 API - CLI + +This is the [API](./apidocs/org/apache/maven/api/cli/package-summary.html) for Maven's command-line interface and tools: + +- [`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. + +This API also defines [Core Extensions model](./core-extensions.html) for `.mvn/extensions.xml`. + +See also associated [implementation](../../impl/maven-cli/index.html). diff --git a/api/maven-api-metadata/src/site/apt/index.apt b/api/maven-api-metadata/src/site/apt/index.apt deleted file mode 100644 index a3f76ef0a6e5..000000000000 --- a/api/maven-api-metadata/src/site/apt/index.apt +++ /dev/null @@ -1,33 +0,0 @@ -~~ 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 - ----- - Guillaume Nodet - ----- - 2024-04-04 - ----- - -Maven 4 API - Repository Metadata Model - - This is the immutable model for Repository Metadata in <<>> package. - - The following are generated from this model: - - * {{{./apidocs/index.html}Java sources}} with <<>> inner classes for immutable instances creation. - diff --git a/api/maven-api-metadata/src/site/markdown/index.md b/api/maven-api-metadata/src/site/markdown/index.md new file mode 100644 index 000000000000..6b2992906a9d --- /dev/null +++ b/api/maven-api-metadata/src/site/markdown/index.md @@ -0,0 +1,33 @@ +--- +title: Introduction +author: + - Guillaume Nodet +date: 2024-04-04 +--- + + + +# Maven 4 API - Repository Metadata Model + +This is the immutable model for Repository Metadata in `org.apache.maven.api.metadata` package. + +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/apt/index.apt b/api/maven-api-model/src/site/apt/index.apt deleted file mode 100644 index 5720df24da9f..000000000000 --- a/api/maven-api-model/src/site/apt/index.apt +++ /dev/null @@ -1,36 +0,0 @@ -~~ 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 - ----- - Jason van Zyl - Vincent Siveton - Hervé Boutemy - ----- - 2011-06-12 - ----- - -Maven 4 API - Immutable Maven Model - - This is strictly the immutable model for Maven POM (Project Object Model), so really just plain objects in <<>> package. - - The following are generated from this model: - - * {{{./apidocs/index.html}Java sources}} with <<>> inner classes for immutable instances creation. - - See also corresponding {{{../../compat/maven-model/index.html}Maven classical POM model documentation}}. diff --git a/api/maven-api-model/src/site/markdown/index.md b/api/maven-api-model/src/site/markdown/index.md new file mode 100644 index 000000000000..aae112b117fe --- /dev/null +++ b/api/maven-api-model/src/site/markdown/index.md @@ -0,0 +1,37 @@ +--- +title: Introduction +author: + - Jason van Zyl + - Vincent Siveton + - Hervé Boutemy +date: 2011-06-12 +--- + + + +# Maven 4 API - Immutable Maven 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. + +The following are generated from this model: + +- [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/apt/index.apt b/api/maven-api-plugin/src/site/apt/index.apt deleted file mode 100644 index f229c29d8a8e..000000000000 --- a/api/maven-api-plugin/src/site/apt/index.apt +++ /dev/null @@ -1,33 +0,0 @@ -~~ 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 - ----- - Guillaume Nodet - ----- - 2023-11-15 - ----- - -Maven 4 API - Plugin Descriptor Model - - This is the immutable model for Maven Plugin Descriptor in <<>> package. - - The following are generated from this model: - - * {{{./apidocs/index.html}Java sources}} with <<>> inner classes for immutable instances creation. - diff --git a/api/maven-api-plugin/src/site/markdown/index.md b/api/maven-api-plugin/src/site/markdown/index.md new file mode 100644 index 000000000000..bcbdadc0b4c1 --- /dev/null +++ b/api/maven-api-plugin/src/site/markdown/index.md @@ -0,0 +1,33 @@ +--- +title: Introduction +author: + - Guillaume Nodet +date: 2023-11-15 +--- + + + +# Maven 4 API - Plugin Descriptor Model + +This is the immutable model for Maven Plugin Descriptor in `org.apache.maven.api.plugin.descriptor` package. + +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/apt/index.apt b/api/maven-api-settings/src/site/apt/index.apt deleted file mode 100644 index b650c8e1c9ce..000000000000 --- a/api/maven-api-settings/src/site/apt/index.apt +++ /dev/null @@ -1,35 +0,0 @@ -~~ 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 4 API - Immutable Settings Model - - This is strictly the immutable model for Maven settings in <<>> package. - - The following are generated from this model: - - * {{{./apidocs/index.html}Java sources}} with <<>> inner classes for immutable instances creation. - - See also corresponding {{{../../compat/maven-settings/index.html}Maven classical settings model documentation}}. - \ No newline at end of file diff --git a/api/maven-api-settings/src/site/markdown/index.md b/api/maven-api-settings/src/site/markdown/index.md new file mode 100644 index 000000000000..af02398abbac --- /dev/null +++ b/api/maven-api-settings/src/site/markdown/index.md @@ -0,0 +1,35 @@ +--- +title: Introduction +author: + - Vincent Siveton +date: 2006-11-04 +--- + + + +# Maven 4 API - Immutable Settings Model + +This is strictly the immutable model for Maven settings in `org.apache.maven.api.settings` package. + +The following are generated from this model: + +- [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/apt/index.apt b/api/maven-api-toolchain/src/site/apt/index.apt deleted file mode 100644 index f1a76e9c98bd..000000000000 --- a/api/maven-api-toolchain/src/site/apt/index.apt +++ /dev/null @@ -1,35 +0,0 @@ -~~ 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 4 API - Immutable Toolchains Model - - This is strictly the immutable model for Maven toolchains in <<>> package. - - The following are generated from this model: - - * {{{./apidocs/index.html}Java sources}} with <<>> inner classes for immutable instances creation. - - See also corresponding {{{../../compat/maven-toolchain-model/index.html}Maven classical toolchains model documentation}}. - \ No newline at end of file diff --git a/api/maven-api-toolchain/src/site/markdown/index.md b/api/maven-api-toolchain/src/site/markdown/index.md new file mode 100644 index 000000000000..a4ec02138363 --- /dev/null +++ b/api/maven-api-toolchain/src/site/markdown/index.md @@ -0,0 +1,35 @@ +--- +title: Introduction +author: + - Vincent Siveton +date: 2006-11-04 +--- + + + +# Maven 4 API - Immutable Toolchains Model + +This is strictly the immutable model for Maven toolchains in `org.apache.maven.api.toolchain` package. + +The following are generated from this model: + +- [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/apt/index.apt b/compat/maven-artifact/src/site/apt/index.apt deleted file mode 100644 index f796c1184435..000000000000 --- a/compat/maven-artifact/src/site/apt/index.apt +++ /dev/null @@ -1,47 +0,0 @@ -~~ 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: - -+----+ -$ 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 - 3.2.4-alpha-1 < 3.2.4-SNAPSHOT -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}}, - - * {{{./apidocs/org/apache/maven/artifact/versioning/VersionRange.html}version range}}. diff --git a/compat/maven-artifact/src/site/markdown/index.md b/compat/maven-artifact/src/site/markdown/index.md new file mode 100644 index 000000000000..2fdd1948ceb6 --- /dev/null +++ b/compat/maven-artifact/src/site/markdown/index.md @@ -0,0 +1,46 @@ +--- +title: Introduction +author: + - Hervé Boutemy +date: 2014-11-30 +--- + + + +# 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 + 3.2.4-alpha-1 < 3.2.4-SNAPSHOT +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 [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/apt/index.apt b/compat/maven-compat/src/site/apt/index.apt deleted file mode 100644 index a288cdcc3d2e..000000000000 --- a/compat/maven-compat/src/site/apt/index.apt +++ /dev/null @@ -1,32 +0,0 @@ -~~ 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 - ----- - 2016-05-29 - ----- - -Maven Compat - - 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 - {{{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. diff --git a/compat/maven-compat/src/site/markdown/index.md b/compat/maven-compat/src/site/markdown/index.md new file mode 100644 index 000000000000..27cf9fe5c245 --- /dev/null +++ b/compat/maven-compat/src/site/markdown/index.md @@ -0,0 +1,31 @@ +--- +title: Introduction +author: + - Hervé Boutemy +date: 2016-05-29 +--- + + + +# Maven Compat + +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/apt/cli.apt.vm b/compat/maven-embedder/src/site/apt/cli.apt.vm deleted file mode 100644 index b5dcae7122bf..000000000000 --- a/compat/maven-embedder/src/site/apt/cli.apt.vm +++ /dev/null @@ -1,28 +0,0 @@ -~~ 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 CLI Options Reference - ----- - Hervé Boutemy - ----- - 2012-04-29 - ----- - -Maven CLI Options Reference - -%{snippet|file=${project.basedir}/target/test-classes/options.html|verbatim=false} diff --git a/compat/maven-embedder/src/site/apt/index.apt.vm b/compat/maven-embedder/src/site/apt/index.apt.vm deleted file mode 100644 index e25d04925d58..000000000000 --- a/compat/maven-embedder/src/site/apt/index.apt.vm +++ /dev/null @@ -1,52 +0,0 @@ -~~ 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. - diff --git a/compat/maven-embedder/src/site/apt/logging.apt b/compat/maven-embedder/src/site/apt/logging.apt deleted file mode 100644 index 3793ba762312..000000000000 --- a/compat/maven-embedder/src/site/apt/logging.apt +++ /dev/null @@ -1,87 +0,0 @@ -~~ 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. - -+-----+ -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; - -public class MyClass -{ - final Logger logger = LoggerFactory.getLogger( MyClass.class ); -} -+-----+ - -* 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}}). - - 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-embedder/src/site/markdown/cli.md.vm b/compat/maven-embedder/src/site/markdown/cli.md.vm new file mode 100644 index 000000000000..04cb684f0c1d --- /dev/null +++ b/compat/maven-embedder/src/site/markdown/cli.md.vm @@ -0,0 +1,29 @@ +--- +title: Maven CLI Options Reference +author: + - Hervé Boutemy +date: 2012-04-29 +--- + + + +# 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 new file mode 100644 index 000000000000..b1ab6dc183a8 --- /dev/null +++ b/compat/maven-embedder/src/site/markdown/index.md.vm @@ -0,0 +1,45 @@ +--- +title: ${project.name} +author: + - Hervé Boutemy +date: 2016-11-14 +--- + + + +# ${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 new file mode 100644 index 000000000000..6d9f93c089e2 --- /dev/null +++ b/compat/maven-embedder/src/site/markdown/logging.md @@ -0,0 +1,68 @@ +--- +title: Maven Logging +author: + - Hervé Boutemy +date: 2013-08-02 +--- + + + +# 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; + +public class MyClass +{ + final Logger logger = LoggerFactory.getLogger( MyClass.class ); +} +``` + +## Logger Name + +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. diff --git a/compat/maven-model-builder/src/site/apt/index.apt b/compat/maven-model-builder/src/site/apt/index.apt deleted file mode 100644 index ca1ff8c6cb9b..000000000000 --- a/compat/maven-model-builder/src/site/apt/index.apt +++ /dev/null @@ -1,240 +0,0 @@ -~~ 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 <<>>) - - [] - - [] diff --git a/compat/maven-model-builder/src/site/apt/super-pom.apt.vm b/compat/maven-model-builder/src/site/apt/super-pom.apt.vm deleted file mode 100644 index df86d70efeba..000000000000 --- a/compat/maven-model-builder/src/site/apt/super-pom.apt.vm +++ /dev/null @@ -1,30 +0,0 @@ -~~ 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. - - ----- - Super POM - ----- - Hervé Boutemy - ----- - 2011-09-12 - ----- - -Super POM - - All models implicitly inherit from a super-POM: - -%{snippet|id=superpom|file=${project.build.sourceDirectory}/../resources/org/apache/maven/model/pom-4.0.0.xml} diff --git a/compat/maven-model-builder/src/site/markdown/index.md b/compat/maven-model-builder/src/site/markdown/index.md new file mode 100644 index 000000000000..d364507aeedc --- /dev/null +++ b/compat/maven-model-builder/src/site/markdown/index.md @@ -0,0 +1,104 @@ +--- +title: Introduction +author: + - Hervé Boutemy +date: 2013-03-19 +--- + + + +# 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 new file mode 100644 index 000000000000..ae28c2bd02f0 --- /dev/null +++ b/compat/maven-model-builder/src/site/markdown/super-pom.md.vm @@ -0,0 +1,31 @@ +--- +title: Super POM +author: + - Hervé Boutemy +date: 2011-09-12 +--- + + + +# Super POM + +All models implicitly inherit from a super-POM: + + diff --git a/compat/maven-model/src/site/apt/index.apt b/compat/maven-model/src/site/apt/index.apt deleted file mode 100644 index 0d33ae519441..000000000000 --- a/compat/maven-model/src/site/apt/index.apt +++ /dev/null @@ -1,41 +0,0 @@ -~~ 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 - ----- - Jason van Zyl - Vincent Siveton - Hervé Boutemy - ----- - 2011-06-12 - ----- - -Maven Model - - 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}}. - - 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-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}}. diff --git a/compat/maven-model/src/site/markdown/index.md b/compat/maven-model/src/site/markdown/index.md new file mode 100644 index 000000000000..9d95e43dad3f --- /dev/null +++ b/compat/maven-model/src/site/markdown/index.md @@ -0,0 +1,37 @@ +--- +title: Introduction +author: + - Jason van Zyl + - Vincent Siveton + - Hervé Boutemy +date: 2011-06-12 +--- + + + +# Maven 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/). + +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-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/apt/index.apt b/compat/maven-plugin-api/src/site/apt/index.apt deleted file mode 100644 index aebf9ea28aa5..000000000000 --- a/compat/maven-plugin-api/src/site/apt/index.apt +++ /dev/null @@ -1,45 +0,0 @@ -~~ 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 - ----- - 2012-06-02 - ----- - -Maven 3 Plugin API - - The API for Maven 3 plugins - composed of goals implemented by Mojos - development: - - * goal code extends {{{./apidocs/org/apache/maven/plugin/AbstractMojo.html}<<>> base class}} that implements {{{./apidocs/org/apache/maven/plugin/Mojo.html}<<>> interface}}, - - * {{{./apidocs/org/apache/maven/plugin/logging/Log.html}<<>> interface}} provides easy logging for the goal. - - [] - - 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 - - * {{{/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 diff --git a/compat/maven-plugin-api/src/site/markdown/index.md b/compat/maven-plugin-api/src/site/markdown/index.md new file mode 100644 index 000000000000..71fcd96da4f7 --- /dev/null +++ b/compat/maven-plugin-api/src/site/markdown/index.md @@ -0,0 +1,40 @@ +--- +title: Introduction +author: + - Hervé Boutemy +date: 2012-06-02 +--- + + + +# Maven 3 Plugin API + +The API for Maven 3 plugins - composed of goals implemented by Mojos - development: + +- 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/). + +## See Also + +- [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/apt/index.apt b/compat/maven-repository-metadata/src/site/apt/index.apt deleted file mode 100644 index fb6f37f97c65..000000000000 --- a/compat/maven-repository-metadata/src/site/apt/index.apt +++ /dev/null @@ -1,59 +0,0 @@ -~~ 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 - ----- - 2009-04-26 - ----- - -Maven Repository Metadata Model - - This is strictly the model for Maven Repository Metadata, so really just plain objects. - - The metadata file name is: - - * <<>> in a remote repository, - - * <<.xml>>> in a local repository, for metadata from a repository with <<>> 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: - - [[1]] in a "groupId" directory: a "groupId" directory may contain Maven plugins artifacts, which are described in metadata's <<>> element, - - [[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}}. - diff --git a/compat/maven-repository-metadata/src/site/markdown/index.md b/compat/maven-repository-metadata/src/site/markdown/index.md new file mode 100644 index 000000000000..dad7ccd08e3d --- /dev/null +++ b/compat/maven-repository-metadata/src/site/markdown/index.md @@ -0,0 +1,47 @@ +--- +title: Introduction +author: + - Hervé Boutemy +date: 2009-04-26 +--- + + + +# Maven Repository Metadata Model + +This is strictly the model for Maven Repository Metadata, so really just plain objects. + +The metadata file name is: + +- `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: + +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. + +The following are generated from this model: + +- [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/apt/dependency-types.apt b/compat/maven-resolver-provider/src/site/apt/dependency-types.apt deleted file mode 100644 index 42ae1b7b6cde..000000000000 --- a/compat/maven-resolver-provider/src/site/apt/dependency-types.apt +++ /dev/null @@ -1,82 +0,0 @@ -~~ 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. - - --- - Default Dependency Types - --- - Hervé Boutemy - --- - 2024-04-02 - --- - -Default Dependency Types Reference - - Defined in <<>> - ({{{./apidocs/org/apache/maven/repository/internal/type/DefaultTypeProvider.html}javadoc}}, - {{{./xref/org/apache/maven/repository/internal/type/DefaultTypeProvider.html}source}}): - -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -|| 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 | | <<>> | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ - - * = new in Maven 4 \ No newline at end of file diff --git a/compat/maven-resolver-provider/src/site/apt/index.apt b/compat/maven-resolver-provider/src/site/apt/index.apt deleted file mode 100644 index 3008d093f315..000000000000 --- a/compat/maven-resolver-provider/src/site/apt/index.apt +++ /dev/null @@ -1,35 +0,0 @@ -~~ 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 - ----- - 2012-09-29 - ----- - -Maven Artifact Resolver Provider - - Maven Artifact Resolver Provider is a {{{/resolver/}Maven Artifact Resolver}} extension to support - Maven POMs and local+remote repositories. - - Main component is <<>> - ({{{./apidocs/org/apache/maven/repository/internal/MavenRepositorySystemUtils.html}javadoc}}, - {{{./xref/org/apache/maven/repository/internal/MavenRepositorySystemUtils.html}source}}). - - See also {{{./dependency-types.html}dependency types}}. \ No newline at end of file diff --git a/compat/maven-resolver-provider/src/site/markdown/dependency-types.md b/compat/maven-resolver-provider/src/site/markdown/dependency-types.md new file mode 100644 index 000000000000..c3056c761908 --- /dev/null +++ b/compat/maven-resolver-provider/src/site/markdown/dependency-types.md @@ -0,0 +1,57 @@ +--- +title: Default Dependency Types +author: + - Hervé Boutemy +date: 2024-04-02 +--- + + + +# Default Dependency Types Reference + +Defined in `DefaultTypeProvider` ([javadoc](./apidocs/org/apache/maven/repository/internal/type/DefaultTypeProvider.html), [source](./xref/org/apache/maven/repository/internal/type/DefaultTypeProvider.html)): + +|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 new file mode 100644 index 000000000000..d631a764e8e7 --- /dev/null +++ b/compat/maven-resolver-provider/src/site/markdown/index.md @@ -0,0 +1,33 @@ +--- +title: Introduction +author: + - Hervé Boutemy +date: 2012-09-29 +--- + + + +# Maven Artifact Resolver Provider + +Maven Artifact Resolver Provider is a [Maven Artifact Resolver](/resolver/) extension to support Maven POMs and local+remote repositories. + +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/apt/index.apt b/compat/maven-settings/src/site/apt/index.apt deleted file mode 100644 index bd84dd8036e1..000000000000 --- a/compat/maven-settings/src/site/apt/index.apt +++ /dev/null @@ -1,51 +0,0 @@ -~~ 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}}. diff --git a/compat/maven-settings/src/site/markdown/index.md b/compat/maven-settings/src/site/markdown/index.md new file mode 100644 index 000000000000..97c504f0bf93 --- /dev/null +++ b/compat/maven-settings/src/site/markdown/index.md @@ -0,0 +1,43 @@ +--- +title: Introduction +author: + - Vincent Siveton +date: 2006-11-04 +--- + + + +# 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/apt/index.apt b/compat/maven-toolchain-model/src/site/apt/index.apt deleted file mode 100644 index b3f74172aff4..000000000000 --- a/compat/maven-toolchain-model/src/site/apt/index.apt +++ /dev/null @@ -1,39 +0,0 @@ -~~ 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 - ----- - 2006-11-04 - ----- - -Maven Toolchain Model - - 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}}. - - 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-toolchain/toolchains.html}Descriptor Reference}} - - * An {{{https://maven.apache.org/xsd/toolchains-1.2.0.xsd}XSD}} diff --git a/compat/maven-toolchain-model/src/site/markdown/index.md b/compat/maven-toolchain-model/src/site/markdown/index.md new file mode 100644 index 000000000000..bf7a38e1c122 --- /dev/null +++ b/compat/maven-toolchain-model/src/site/markdown/index.md @@ -0,0 +1,35 @@ +--- +title: Introduction +author: + - Hervé Boutemy +date: 2006-11-04 +--- + + + +# Maven Toolchain 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/). + +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-toolchain/toolchains.html) +- An [XSD](https://maven.apache.org/xsd/toolchains-1.2.0.xsd) diff --git a/impl/maven-core/src/site/apt/artifact-handlers.apt b/impl/maven-core/src/site/apt/artifact-handlers.apt deleted file mode 100644 index 3323c1dc1ffc..000000000000 --- a/impl/maven-core/src/site/apt/artifact-handlers.apt +++ /dev/null @@ -1,61 +0,0 @@ -~~ 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. - - --- - Legacy Artifact Handlers Reference - --- - Hervé Boutemy - --- - 2013-08-02 - --- - -Legacy Artifact Handlers Reference - - 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). - - 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}}. - - For compatibility, legacy Maven 3 artifact handlers are still provided: - -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ -|| 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 | <<>> | | -*--------------------+---------------+------------+------------+-----------+---------------------+-----------------------+ diff --git a/impl/maven-core/src/site/apt/configuration-management.apt b/impl/maven-core/src/site/apt/configuration-management.apt deleted file mode 100644 index 5954ed1dce13..000000000000 --- a/impl/maven-core/src/site/apt/configuration-management.apt +++ /dev/null @@ -1,139 +0,0 @@ -~~ 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 - -+-----+ -${maven.home} - | - +--- maven.properties -+-----+ - -* 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. - -* 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. - - 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. - - 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. - - - elements that are critical for pom dissemination - - those that are used locally by the user like - -* User configuration - - 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. - -Plugin configuration - - The configuration of plugins is of the same form as the maven {{{plugin-descriptors}plugin descriptors}} - themselves: - -+-----+ - - - xdoc - 1.0 - - - theme - classic - - - - -+-----+ - -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 diff --git a/impl/maven-core/src/site/apt/core-extensions.apt.vm b/impl/maven-core/src/site/apt/core-extensions.apt.vm deleted file mode 100644 index 164ec13e6f00..000000000000 --- a/impl/maven-core/src/site/apt/core-extensions.apt.vm +++ /dev/null @@ -1,30 +0,0 @@ -~~ 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 Extensions Reference - --- - Hervé Boutemy - --- - 2016-06-25 - --- - -Maven Core Extensions Reference - - Maven core provides default {{{./extension.html}extensions}} as defined in <<>>: - -%{snippet|id=core-extension|file=${project.basedir}/src/main/resources/META-INF/maven/extension.xml} diff --git a/impl/maven-core/src/site/apt/default-bindings.apt.vm b/impl/maven-core/src/site/apt/default-bindings.apt.vm deleted file mode 100644 index c917d0c2718f..000000000000 --- a/impl/maven-core/src/site/apt/default-bindings.apt.vm +++ /dev/null @@ -1,64 +0,0 @@ -~~ 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. - - --- - Plugins Bindings for Default Lifecycle Reference - --- - Hervé Boutemy - --- - 2013-08-02 - --- - -Plugins Bindings for <<>> Lifecycle Reference - - 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: - -%{toc|fromDepth=2} - - 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} - -* Plugin bindings for <<>> packaging - -%{snippet|id=pom|file=${project.basedir}/src/main/java/org/apache/maven/lifecycle/providers/packaging/PomLifecycleMappingProvider.java} - -* Plugin bindings for <<>> packaging - -%{snippet|id=jar|file=${project.basedir}/src/main/java/org/apache/maven/lifecycle/providers/packaging/JarLifecycleMappingProvider.java} - -* Plugin bindings for <<>> packaging - -%{snippet|id=ejb|file=${project.basedir}/src/main/java/org/apache/maven/lifecycle/providers/packaging/EjbLifecycleMappingProvider.java} - -* 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 <<>> packaging - -%{snippet|id=war|file=${project.basedir}/src/main/java/org/apache/maven/lifecycle/providers/packaging/WarLifecycleMappingProvider.java} - -* Plugin bindings for <<>> packaging - -%{snippet|id=ear|file=${project.basedir}/src/main/java/org/apache/maven/lifecycle/providers/packaging/EarLifecycleMappingProvider.java} - -* Plugin bindings for <<>> packaging - -%{snippet|id=rar|file=${project.basedir}/src/main/java/org/apache/maven/lifecycle/providers/packaging/RarLifecycleMappingProvider.java} diff --git a/impl/maven-core/src/site/apt/getting-to-container-configured-mojos.apt b/impl/maven-core/src/site/apt/getting-to-container-configured-mojos.apt deleted file mode 100644 index 8b8a975f5760..000000000000 --- a/impl/maven-core/src/site/apt/getting-to-container-configured-mojos.apt +++ /dev/null @@ -1,102 +0,0 @@ -~~ 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. - - --- - Getting to Plexus-configured Mojos - --- - John Casey - --- - 2005-04-29 - -Abstract - - 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. - - 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. - - 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. - -Container Enhancements - -* ExpressionEvaluator - - 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. - - We need a replacement for DefaultExpressionEvaluator that is capable of - traversing an object graph and extracting Object values, not just Strings. - -* ComponentConfigurator - - 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. - -* Other - - 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. - -Maven Modifications - -* DefaultPluginManager - - s/getMojoConfiguration()/getConfiguration()/g - - 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. - -* PluginDescriptorBuilder - - s/getMojoConfiguration()/getConfiguration()/g - - That should be all there is to it. - -* MojoDescriptor - - Remove set/getMojoConfiguration(..), as it will become obsolete. - -* 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/apt/index.apt b/impl/maven-core/src/site/apt/index.apt deleted file mode 100644 index cb5e3570385a..000000000000 --- a/impl/maven-core/src/site/apt/index.apt +++ /dev/null @@ -1,97 +0,0 @@ -~~ 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-07-27 - ----- - -Maven Core - - Maven Core classes managing the whole build process. - -* Reference Documentation - - * {{{./lifecycles.html}lifecycles}} and {{{./default-bindings.html}plugin bindings to <<>> lifecycle}}, - - * {{{./artifact-handlers.html}default artifact handlers}}, to manage {{{../../api/maven-api-model/maven.html#class_dependency}dependency types}}, - - * {{{./extension.html}extension descriptor}} and {{{./core-extensions.html}core extensions}}, - - * {{{/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}}, - -* Useful entry points - - * <<>> 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 - - * <<>> 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, - - * <<>> 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: - - * <>: - 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}}). diff --git a/impl/maven-core/src/site/apt/inheritance.apt b/impl/maven-core/src/site/apt/inheritance.apt deleted file mode 100644 index 46e240f0f2ec..000000000000 --- a/impl/maven-core/src/site/apt/inheritance.apt +++ /dev/null @@ -1,100 +0,0 @@ -~~ 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. - - ----- - Inheritance in Maven - ----- - The Maven Team - ----- - -Inheritance in Maven - - In order the understand how inheritance works in Maven there are a few notions that you must be familiar with: - - * 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 - - -Maven super model - - 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 - -+-----+ - super model <- m0 <- m1 <- m2 -+-----+ - -+-----+ - - 4.0.0 - - - - - - -+-----+ - -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, ...). - -Minimum Element-Set for a Project POM - - 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. - - - [modelVersion] tells maven which version of the object model this project - is compliant with (to support future legacy concerns) - - - [artifactId] tells maven what the artifact name is for this particular - project. Each project should have a distinct artifactId. - - - [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/apt/lifecycles.apt.vm b/impl/maven-core/src/site/apt/lifecycles.apt.vm deleted file mode 100644 index 18d990922006..000000000000 --- a/impl/maven-core/src/site/apt/lifecycles.apt.vm +++ /dev/null @@ -1,49 +0,0 @@ -~~ 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. - - ----- - Lifecycles Reference - ----- - Hervé Boutemy - ----- - 2013-08-02 - ----- - -Lifecycles Reference - - Maven defines 3 lifecycles, which are registered in {{{./apidocs/org/apache/maven/api/services/LifecycleRegistry.html}<<>>}}: - -%{toc|fromDepth=2} - -* <<>> 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}}: - -%{snippet|id=default|file=${project.basedir}/src/main/java/org/apache/maven/internal/impl/DefaultLifecycleRegistry.java} - -* <<>> Lifecycle - - <<>> lifecycle phases are defined with their plugins bindings: - -%{snippet|id=clean|file=${project.basedir}/src/main/java/org/apache/maven/internal/impl/DefaultLifecycleRegistry.java} - -* <<>> Lifecycle - - <<>> lifecycle phases are defined with their plugins bindings: - -%{snippet|id=site|file=${project.basedir}/src/main/java/org/apache/maven/internal/impl/DefaultLifecycleRegistry.java} diff --git a/impl/maven-core/src/site/apt/offline-mode.apt b/impl/maven-core/src/site/apt/offline-mode.apt deleted file mode 100644 index 0311bc8ce0fa..000000000000 --- a/impl/maven-core/src/site/apt/offline-mode.apt +++ /dev/null @@ -1,269 +0,0 @@ -~~ 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. - - [[3]] "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. - - So, offline mode has several implications, some of which may not be - altogether obvious: - - * 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. - - 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. - -* Why is Offline Mode Important? - - 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. - - 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. - - 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. - -* Implications for Resolution - -** Dependency Resolution - - This one is obvious...we only have access to the repositories using - the file:// protocol and living on a truly local filesystem when - offline. - -** Plugin Resolution - - This is similar to dependency resolution. Plugin repositories not - using file:// or not residing on a local (not shared) filesystem will - be unavailable. - - -* Implications for Mojo Execution - -** Deployment mojos - - 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. - -** Testing mojos - - 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. - - 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. - -** SCM mojos - - 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 Subsystems - -** Maven-Wagon - - Parts of Wagon will continue to function normally. These include: - - * The file wagon, provided the referenced location is on a local - filesystem. - - 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. - - * If not otherwise specified, all other wagons are assumed to be - remote-only, and are therefore sensitive to offline mode. - -** Maven-Artifact - - This is wholly dependent on Maven-Wagon, above. - - 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... - - OTOH, all offline-mode checks can probably be run from Wagon-based APIs. - -** Maven-SCM - - 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. - -** Maven-Core - - We'll examine the different parts of maven-core on a case-by-case - basis, below: - -*** DefaultLifecycleExecutor - - 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: - - [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. - - 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. - - -* Implementation Notes - -** Accessibility of offline status - - Offline status should be indicated in the MavenSettings instance, since it - can conceivably be set from either the settings.xml or the command-line. - - 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. - -** 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 <<>>: - - * 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: - - Retrieve the file or base-url file to be "downloaded". - - * 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. - -** Control over mojos in the lifecycle - - When binding a mojo to the project's lifecycle instance, check the mojo - descriptor's requiredConnectivity field. - - * If <<<(offline == true) && (requiresOnline != true)>>>, bind - the mojo to the lifecycle. - - In this case, the client is <>, and the mojo does not require - online status. - - * If <<<(offline == false) && (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. - - * 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. - - <> 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/apt/plugin-execution-isolation.apt b/impl/maven-core/src/site/apt/plugin-execution-isolation.apt deleted file mode 100644 index b2983120e8c2..000000000000 --- a/impl/maven-core/src/site/apt/plugin-execution-isolation.apt +++ /dev/null @@ -1,57 +0,0 @@ -~~ 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 plugins - ----- - The Maven Team - ----- - -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] - ^ - | - [plexus.core.maven] - ^ ^ - | | -[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. - diff --git a/impl/maven-core/src/site/markdown/artifact-handlers.md b/impl/maven-core/src/site/markdown/artifact-handlers.md new file mode 100644 index 000000000000..229693cd5743 --- /dev/null +++ b/impl/maven-core/src/site/markdown/artifact-handlers.md @@ -0,0 +1,47 @@ +--- +title: Legacy Artifact Handlers Reference +author: + - Hervé Boutemy +date: 2013-08-02 +--- + + + +# Legacy Artifact Handlers Reference + +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). + +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). + +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 new file mode 100644 index 000000000000..f72f2f84b762 --- /dev/null +++ b/impl/maven-core/src/site/markdown/configuration-management.md @@ -0,0 +1,102 @@ +--- +title: Maven configuration management +author: + - 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 + +``` +${maven.home} + | + +--- maven.properties +``` + +## 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. + +## 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. + +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. + +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. + +\- elements that are critical for pom dissemination - those that are used locally by the user like `` + +## User configuration + +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. + +# Plugin configuration + +The configuration of plugins is of the same form as the maven [plugin descriptors](#plugin-descriptors) themselves: + +```xml + + + xdoc + 1.0 + + + theme + classic + + + + +``` + +# 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 new file mode 100644 index 000000000000..3f1afa3520f2 --- /dev/null +++ b/impl/maven-core/src/site/markdown/core-extensions.md.vm @@ -0,0 +1,31 @@ +--- +title: Maven Core Extensions Reference +author: + - Hervé Boutemy +date: 2016-06-25 +--- + + + +# Maven Core Extensions Reference + +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 new file mode 100644 index 000000000000..b8eba9789d0d --- /dev/null +++ b/impl/maven-core/src/site/markdown/default-bindings.md.vm @@ -0,0 +1,70 @@ +--- +title: Plugins Bindings for Default Lifecycle Reference +author: + - Hervé Boutemy +date: 2013-08-02 +--- + + + +# Plugins Bindings for `default` Lifecycle Reference + +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: + + + +Plugin bindings for `pom` packaging +----------------------------------- + + + +Plugin bindings for `jar` packaging +----------------------------------- + + + +Plugin bindings for `ejb` packaging +----------------------------------- + + + +Plugin bindings for `maven-plugin` packaging +-------------------------------------------- + + + +Plugin bindings for `war` packaging +----------------------------------- + + + +Plugin bindings for `ear` packaging +----------------------------------- + + + +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 new file mode 100644 index 000000000000..397013b238f0 --- /dev/null +++ b/impl/maven-core/src/site/markdown/getting-to-container-configured-mojos.md @@ -0,0 +1,71 @@ +--- +title: Getting to Plexus-configured Mojos +author: + - John Casey +date: 2005-04-29 +--- + + + +# Abstract + +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. + +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. + +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. + +# Container Enhancements + +## ExpressionEvaluator + +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. + +We need a replacement for DefaultExpressionEvaluator that is capable of traversing an object graph and extracting Object values, not just Strings. + +## ComponentConfigurator + +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. + +## Other + +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. + +# Maven Modifications + +## DefaultPluginManager + +s/getMojoConfiguration()/getConfiguration()/g + +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. + +## PluginDescriptorBuilder + +s/getMojoConfiguration()/getConfiguration()/g + +That should be all there is to it. + +## MojoDescriptor + +Remove set/getMojoConfiguration(..), as it will become obsolete. + +## 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 new file mode 100644 index 000000000000..59fda4ea202c --- /dev/null +++ b/impl/maven-core/src/site/markdown/index.md @@ -0,0 +1,61 @@ +--- +title: Introduction +author: + - Hervé Boutemy +date: 2013-07-27 +--- + + + +# Maven Core + +Maven Core classes managing the whole build process. + +## Reference Documentation + +- [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/), + +## Useful entry points + +- `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: + + 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 [`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. + +## Toolchains + +- [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 new file mode 100644 index 000000000000..44e254cc3edc --- /dev/null +++ b/impl/maven-core/src/site/markdown/inheritance.md @@ -0,0 +1,78 @@ +--- +title: Inheritance in Maven +author: + - The Maven Team +--- + + + +# Inheritance in Maven + +In order the understand how inheritance works in Maven there are a few notions that you must be familiar with: + +- 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 + +# Maven super model + +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 + +``` + super model <- m0 <- m1 <- m2 +``` + +```xml + + 4.0.0 + + + + + + +``` + +# 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, ...). + +# Minimum Element-Set for a Project POM + +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. + +\- \[modelVersion\] tells maven which version of the object model this project is compliant with (to support future legacy concerns) + +\- \[artifactId\] tells maven what the artifact name is for this particular project. Each project should have a distinct artifactId. + +\- \[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 new file mode 100644 index 000000000000..7b1ec38d8ef6 --- /dev/null +++ b/impl/maven-core/src/site/markdown/lifecycles.md.vm @@ -0,0 +1,52 @@ +--- +title: Lifecycles Reference +author: + - Hervé Boutemy +date: 2013-08-02 +--- + + + +# Lifecycles Reference + +Maven defines 3 lifecycles, which are registered in [`LifecycleRegistry`](./apidocs/org/apache/maven/api/services/LifecycleRegistry.html): + + + +`default` Lifecycle +------------------- + +`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): + + + +`clean` Lifecycle +----------------- + +`clean` lifecycle phases are defined with their plugins bindings: + + + +`site` Lifecycle +---------------- + +`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 new file mode 100644 index 000000000000..67411b92ac88 --- /dev/null +++ b/impl/maven-core/src/site/markdown/offline-mode.md @@ -0,0 +1,165 @@ +--- +title: Offline Mode Design +author: + - John Casey +date: 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. +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. + + So, offline mode has several implications, some of which may not be altogether obvious: + + - 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. + + 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. + +## Why is Offline Mode Important? + +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. + +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. + +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. + +## Implications for Resolution + +### Dependency Resolution + +This one is obvious...we only have access to the repositories using the file\:// protocol and living on a truly local filesystem when offline. + +### Plugin Resolution + +This is similar to dependency resolution. Plugin repositories not using file\:// or not residing on a local (not shared) filesystem will be unavailable. + +## Implications for Mojo Execution + +### Deployment mojos + +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. + +### Testing mojos + +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. + +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. + +### SCM mojos + +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 Subsystems + +### Maven-Wagon + +Parts of Wagon will continue to function normally. These include: + +- The file wagon, provided the referenced location is on a local filesystem. + + 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. + +- If not otherwise specified, all other wagons are assumed to be remote-only, and are therefore sensitive to offline mode. + +### Maven-Artifact + +This is wholly dependent on Maven-Wagon, above. + +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... + +OTOH, all offline-mode checks can probably be run from Wagon-based APIs. + +### Maven-SCM + +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. + +### Maven-Core + +We'll examine the different parts of maven-core on a case-by-case basis, below: + +#### DefaultLifecycleExecutor + +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: + +
+
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. + +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. + +
+
+ +## Implementation Notes + +### Accessibility of offline status + +Offline status should be indicated in the MavenSettings instance, since it can conceivably be set from either the settings.xml or the command-line. + +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. + +### 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 `offline == true`: + +- 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: + + Retrieve the file or base-url file to be "downloaded". + + - 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. + +### Control over mojos in the lifecycle + +When binding a mojo to the project's lifecycle instance, check the mojo descriptor's requiredConnectivity field. + +- If `(offline == true) && (requiresOnline != true)`, bind the mojo to the lifecycle. + + In this case, the client is **offline**, and the mojo does not require online status. + +- If `(offline == false) && (requiresOnline == true)`, bind the mojo to the lifecycle. + + 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 new file mode 100644 index 000000000000..05f8cdeb481d --- /dev/null +++ b/impl/maven-core/src/site/markdown/plugin-execution-isolation.md @@ -0,0 +1,42 @@ +--- +title: Maven plugins +author: + - The Maven Team +--- + + + +# 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] + ^ + | + [plexus.core.maven] + ^ ^ + | | +[plugin0] [plugin1] +``` + +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/apt/dependency-types.apt b/impl/maven-impl/src/site/apt/dependency-types.apt deleted file mode 100644 index 1d119112b67d..000000000000 --- a/impl/maven-impl/src/site/apt/dependency-types.apt +++ /dev/null @@ -1,82 +0,0 @@ -~~ 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. - - --- - Default Dependency Types - --- - Hervé Boutemy - --- - 2024-12-27 - --- - -Default Dependency Types Reference - - Defined in <<>> - ({{{./apidocs/org/apache/maven/internal/impl/resolver/type/DefaultTypeProvider.html}javadoc}}, - {{{./xref/org/apache/maven/internal/impl/resolver/type/DefaultTypeProvider.html}source}}): - -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ -|| 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 | | <<>> | -*-----------------------+---------------+------------+-----------+-----------------------+-----------------------+ - - * = new in Maven 4 \ No newline at end of file diff --git a/impl/maven-impl/src/site/markdown/dependency-types.md b/impl/maven-impl/src/site/markdown/dependency-types.md new file mode 100644 index 000000000000..d0e0c2fe9ccc --- /dev/null +++ b/impl/maven-impl/src/site/markdown/dependency-types.md @@ -0,0 +1,57 @@ +--- +title: Default Dependency Types +author: + - Hervé Boutemy +date: 2024-12-27 +--- + + + +# Default Dependency Types Reference + +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)): + +|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/apt/index.apt b/impl/maven-logging/src/site/apt/index.apt deleted file mode 100644 index 01a29ee1bba5..000000000000 --- a/impl/maven-logging/src/site/apt/index.apt +++ /dev/null @@ -1,35 +0,0 @@ -~~ 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. - - ----- - About - ----- - Hervé Boutemy - ----- - 2023-06-19 - ----- - -Maven SLF4J Provider - - An extension to {{{https://www.slf4j.org/api/org/slf4j/simple/SimpleLogger.html}SLF4J Simple}} to add enhanced color support. - - 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}} - -* See Also - - * {{{../../compat/maven-embedder/logging.html}Maven Logging}} diff --git a/impl/maven-logging/src/site/markdown/index.md b/impl/maven-logging/src/site/markdown/index.md new file mode 100644 index 000000000000..6dde3221d616 --- /dev/null +++ b/impl/maven-logging/src/site/markdown/index.md @@ -0,0 +1,35 @@ +--- +title: About +author: + - Hervé Boutemy +date: 2023-06-19 +--- + + + +# Maven SLF4J Provider + +An extension to [SLF4J Simple](https://www.slf4j.org/api/org/slf4j/simple/SimpleLogger.html) to add enhanced color support. + +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) + +## See Also + +- [Maven Logging](../../compat/maven-embedder/logging.html) diff --git a/its/core-it-suite/src/site/apt/bootstrap.apt.vm b/its/core-it-suite/src/site/apt/bootstrap.apt.vm deleted file mode 100644 index 252fb56bd0a4..000000000000 --- a/its/core-it-suite/src/site/apt/bootstrap.apt.vm +++ /dev/null @@ -1,96 +0,0 @@ - ----- - Maven Core Integration Tests Bootstrap - ----- - Hervé Boutemy - ----- - 2017-04-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 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}}: - -%{toc|section=1|fromDepth=2} - -* Base Plugins And Their Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/target/resolve-plugins.txt} - -* Group 1 Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-1/target/resolve.txt} - -* Group 2 Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-2/target/resolve.txt} - -* Group 3 Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-3/target/resolve.txt} - -* Group 4 Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-4/target/resolve.txt} - -* Group 5 Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-5/target/resolve.txt} - -* Group 6 Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-6/target/resolve.txt} - -* Group 7 Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-7/target/resolve.txt} - -* Group 8 Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-8/target/resolve.txt} - -* Group 9 Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-9/target/resolve.txt} - -* Group 10 Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-10/target/resolve.txt} - -* Group 11 Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-11/target/resolve.txt} - -* Group 12 Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-12/target/resolve.txt} - -* Group 13 Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-13/target/resolve.txt} - -* Group 14 Dependencies - -%{snippet|file=${project.build.directory}/test-classes/bootstrap/group-14/target/resolve.txt} diff --git a/its/core-it-suite/src/site/apt/index.apt.vm b/its/core-it-suite/src/site/apt/index.apt.vm deleted file mode 100644 index e7285dcc52c2..000000000000 --- a/its/core-it-suite/src/site/apt/index.apt.vm +++ /dev/null @@ -1,79 +0,0 @@ - ----- - 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 -+---- - - Currently deployed {{{./surefire-report.html}Surefire Report}} was generated with following environment: - -%{snippet|file=${project.build.directory}/info.txt} - - -* 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. - - 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. - - 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: - -------- -[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 - - 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. - - 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-suite/src/site/markdown/bootstrap.md.vm b/its/core-it-suite/src/site/markdown/bootstrap.md.vm new file mode 100644 index 000000000000..06a8167ca6bf --- /dev/null +++ b/its/core-it-suite/src/site/markdown/bootstrap.md.vm @@ -0,0 +1,108 @@ +--- +title: Maven Core Integration Tests Bootstrap +author: + - Hervé Boutemy +date: 2017-04-04 +--- + + + +# 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 [Core ITs Suite and dependencies](./index.html#Core_ITs_Suite_and_Dependencies_.28incl._Plugins.29) rationale). + +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 +----------------------------------- + + + +Group 1 Dependencies +-------------------- + + + +Group 2 Dependencies +-------------------- + + + +Group 3 Dependencies +-------------------- + + + +Group 4 Dependencies +-------------------- + + + +Group 5 Dependencies +-------------------- + + + +Group 6 Dependencies +-------------------- + + + +Group 7 Dependencies +-------------------- + + + +Group 8 Dependencies +-------------------- + + + +Group 9 Dependencies +-------------------- + + + +Group 10 Dependencies +--------------------- + + + +Group 11 Dependencies +--------------------- + + + +Group 12 Dependencies +--------------------- + + + +Group 13 Dependencies +--------------------- + + + +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 new file mode 100644 index 000000000000..eb69b366f55d --- /dev/null +++ b/its/core-it-suite/src/site/markdown/index.md.vm @@ -0,0 +1,68 @@ +--- +title: Maven Core Integration Tests Suite +author: + - Hervé Boutemy +date: 2011-09-04 +--- + + + +# 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). + +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 +``` + +Currently deployed [Surefire Report](./surefire-report.html) was generated with following environment: + + + +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 [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 [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 [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]]# + +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. 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/apt/index.apt.vm deleted file mode 100644 index 3800a597390a..000000000000 --- a/its/core-it-support/core-it-plugins/maven-it-plugin-core-stubs/src/site/apt/index.apt.vm +++ /dev/null @@ -1,13 +0,0 @@ - ----- - About - ----- - Hervé Boutemy - ----- - 2012-10-13 - ----- - -${project.name} - - About ${project.description} - - See {{{./modules.html}Project Modules}} report for a complete list with description. 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 new file mode 100644 index 000000000000..71a33174a2c2 --- /dev/null +++ b/its/core-it-support/core-it-plugins/maven-it-plugin-core-stubs/src/site/markdown/index.md.vm @@ -0,0 +1,12 @@ +--- +title: About +author: + - Hervé Boutemy +date: 2012-10-13 +--- + +# ${project.name} + +About ${project.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/apt/index.apt.vm b/its/core-it-support/core-it-plugins/src/site/apt/index.apt.vm deleted file mode 100644 index 3800a597390a..000000000000 --- a/its/core-it-support/core-it-plugins/src/site/apt/index.apt.vm +++ /dev/null @@ -1,13 +0,0 @@ - ----- - About - ----- - Hervé Boutemy - ----- - 2012-10-13 - ----- - -${project.name} - - About ${project.description} - - See {{{./modules.html}Project Modules}} 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 new file mode 100644 index 000000000000..71a33174a2c2 --- /dev/null +++ b/its/core-it-support/core-it-plugins/src/site/markdown/index.md.vm @@ -0,0 +1,12 @@ +--- +title: About +author: + - Hervé Boutemy +date: 2012-10-13 +--- + +# ${project.name} + +About ${project.description} + +See [Project Modules](./modules.html) report for a complete list with description. diff --git a/its/src/site/apt/index.apt b/its/src/site/apt/index.apt deleted file mode 100644 index 239eab0f2601..000000000000 --- a/its/src/site/apt/index.apt +++ /dev/null @@ -1,74 +0,0 @@ - ----- - Introduction - ----- - 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 ITs - - Maven Core Integration Tests provide tooling to test every aspect of Maven functionalities with any Maven version. - - This project is split in 2 modules: - - * {{{./core-it-support/}Maven Core IT Support}}: Maven Integration Tests support tools, to completely decouple ITs from production plugins, - - * {{{./core-it-suite/}Maven Core ITs suite}}: The effective Maven Integration Tests suite, providing the interesting {{{./core-it-suite/surefire-report.html}tests results}}. - - -* Running the Core ITs - - 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: - -+---- -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: - -+---- -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 diff --git a/its/src/site/markdown/index.md b/its/src/site/markdown/index.md new file mode 100644 index 000000000000..a4f5c9358625 --- /dev/null +++ b/its/src/site/markdown/index.md @@ -0,0 +1,62 @@ +--- +title: Introduction +author: + - Hervé Boutemy +date: 2011-09-04 +--- + + + +# Maven Core ITs + +Maven Core Integration Tests provide tooling to test every aspect of Maven functionalities with any Maven version. + +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). + +## Running the Core ITs + +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 +``` + +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 `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: + +```shell +mvn clean test -Prun-its -DmavenVersion=2.2.1 +``` + +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.