You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sj...@apache.org on 2024/12/23 15:08:31 UTC
(maven-site) branch master updated: Align TOCs and render headings no longer as links (#601)
This is an automated email from the ASF dual-hosted git repository.
sjaranowski pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new 04e1e14b Align TOCs and render headings no longer as links (#601)
04e1e14b is described below
commit 04e1e14b5b805eca0d45a462b2ea5c716caeb15c
Author: Matthias Bünger <Bu...@users.noreply.github.com>
AuthorDate: Mon Dec 23 16:08:26 2024 +0100
Align TOCs and render headings no longer as links (#601)
* Align TOCs and render headings no longer as links
* Align TOCs and render headings no longer as links
* Remove Link to Maven 2 article
* Remove Link to Maven 2 article
* Fix link
---
content/apt/developers/conventions/code.apt | 22 ++--
content/apt/developers/conventions/git.apt | 2 +-
.../release/maven-project-release-procedure.apt | 2 +-
.../guides/development/guide-maven-development.apt | 6 +-
.../apt/guides/mini/guide-maven-classloading.apt | 16 +--
.../plugin/guide-java-plugin-development.apt.vm | 30 +++---
content/apt/plugin-developers/common-bugs.apt | 36 ++-----
content/apt/pom.apt.vm | 114 ++++++++++-----------
8 files changed, 107 insertions(+), 121 deletions(-)
diff --git a/content/apt/developers/conventions/code.apt b/content/apt/developers/conventions/code.apt
index aca633f8..ef2a72dc 100644
--- a/content/apt/developers/conventions/code.apt
+++ b/content/apt/developers/conventions/code.apt
@@ -60,14 +60,14 @@ Maven Code Style And Code Conventions
<<Note>>: The specific styles and conventions, listed in the next sections, can override these generic rules.
-* {Java}
+* Java
-** {Java Code Style}
+** Java Code Style
Maven adopts the {{{https://github.com/palantir/palantir-java-format}palantir Java format}}.
-** {Java Code Convention}
+** Java Code Convention
For consistency reasons, our Java code convention is mainly:
@@ -89,7 +89,7 @@ Maven Code Style And Code Conventions
[]
-** {Java Code Convention - import layouts}
+** Java Code Convention - import layouts
For consistency reasons, Java imports should be organized as:
@@ -110,13 +110,13 @@ Maven Code Style And Code Conventions
navigate to <Java \> Code Style \> Organize Imports>. Click on <Import...> and select the downloaded
file to change the import order.
-** {JavaDoc Convention}
+** JavaDoc Convention
TO BE DISCUSSED
-* {XML}
+* XML
-** {XML Code Style}
+** XML Code Style
The Maven style for XML files is mainly:
@@ -152,11 +152,11 @@ Maven Code Style And Code Conventions
[]
-** {Generic XML Code Convention}
+** Generic XML Code Convention
No generic code convention exists yet for XML files.
-** {POM Code Convention}
+** POM Code Convention
The team has {{{https://lists.apache.org/thread/h8px5t6f3q59cnkzpj1t02wsoynr3ygk}voted}}
during the end of June 2008 to follow a specific POM convention to ordering POM elements.
@@ -225,7 +225,7 @@ Maven Code Style And Code Conventions
[]
-** {XDOC Code Convention}
+** XDOC Code Convention
For consistency and readability reasons, XDOC files should respect:
@@ -235,7 +235,7 @@ Maven Code Style And Code Conventions
[]
-** {FML Code Convention}
+** FML Code Convention
For readability reasons, FML files should respect:
diff --git a/content/apt/developers/conventions/git.apt b/content/apt/developers/conventions/git.apt
index b08a99e3..fdf800d3 100644
--- a/content/apt/developers/conventions/git.apt
+++ b/content/apt/developers/conventions/git.apt
@@ -67,7 +67,7 @@ Maven Git Convention
For complex changes, you may find it valuable to make a pull request
at github to make it easier to collaborate with others.
-*** {Commit Message Template}
+*** Commit Message Template
Commits should be focused on one issue at a time, because that makes it easier
for others to review the commit.
diff --git a/content/apt/developers/release/maven-project-release-procedure.apt b/content/apt/developers/release/maven-project-release-procedure.apt
index 92f0f1ab..dc33bef6 100644
--- a/content/apt/developers/release/maven-project-release-procedure.apt
+++ b/content/apt/developers/release/maven-project-release-procedure.apt
@@ -28,7 +28,7 @@ Performing a Maven Project Release
This document covers the common release procedures used by the Maven team to perform releases.
-* {Prerequisites}
+* Prerequisites
Be sure that:
diff --git a/content/apt/guides/development/guide-maven-development.apt b/content/apt/guides/development/guide-maven-development.apt
index 16bdb04a..41cd1256 100644
--- a/content/apt/guides/development/guide-maven-development.apt
+++ b/content/apt/guides/development/guide-maven-development.apt
@@ -34,6 +34,8 @@ Developing Maven
This document describes how to get started developing Maven itself. There is a separate page describing how
to {{{./guide-building-maven.html}build Maven}}.
+%{toc|section=0|fromDepth=2|toDepth=5}
+
* Finding some work to do
First of all you need something to work on! Issues can be found in
@@ -70,7 +72,7 @@ Developing Maven
case, you should run all of the integration tests. The tests require an empty local repository.
See {{{/core-its/core-it-suite/}Core IT Suite documentation}} for more details.
-* {Creating and submitting a patch}
+* Creating and submitting a patch
The most convenient way is to create a GitHub fork from the Git repository you are working with.
When you have either completed an issue or just want some feedback on the work you have done, create a pull request.
@@ -188,7 +190,7 @@ Developing Maven
You can {{{/wagon/}read more about Wagon}}.
-* {Further Links}
+* Further Links
* {{{../../developers/conventions/code.html}Maven Code Style And Code Convention}}
diff --git a/content/apt/guides/mini/guide-maven-classloading.apt b/content/apt/guides/mini/guide-maven-classloading.apt
index 9a5cf871..6572f26e 100644
--- a/content/apt/guides/mini/guide-maven-classloading.apt
+++ b/content/apt/guides/mini/guide-maven-classloading.apt
@@ -53,15 +53,15 @@ Guide to Maven Classloading
The search order is always as given above.
-* {Platform Classloader}
+* Platform Classloader
This is the classloader exposing all JRE classes.
-* {System Classloader}
+* System Classloader
It contains only Plexus Classworlds and imports the platform classloader.
-* {Core Classloader}
+* Core Classloader
The second classloader down the graph contains the core requirements of Maven. <<It is used by Maven internally but not by plugins>>.
The core classloader has the libraries in <<<$\{maven.home\}/lib>>>. In general these are just Maven libraries. For example instances of
@@ -73,14 +73,14 @@ Guide to Maven Classloading
to the Maven core and all plugins for the current project (through the API Classloader, see next paragraph).
More information is available in {{{./guide-using-extensions.html}Core Extension}}.
-* {API Classloader}
+* API Classloader
The API classloader is a filtered view of the Core Classloader, done by exposing only the exported packages from all Core Extensions.
The main API is listed in {{{/ref/current/maven-core/core-extensions.html}Maven Core Extensions Reference}}.
This has been introduced with Maven 3.3.1 ({{{https://issues.apache.org/jira/browse/MNG-5771}MNG-5771}}).
-* {Build Extension Classloaders}
+* Build Extension Classloaders
[../../buildExtensionClassRealm.svg] Build Extension Class Realm
@@ -92,14 +92,14 @@ Guide to Maven Classloading
In addition all component references in the plugin descriptor are properly wired from the underlying Plexus container.
Build extensions have limited effect as they are loaded late.
-* {Project Classloaders}
+* Project Classloaders
There is one project classloader per Maven project (identified through its coordinates).
This one imports the API Classloader. In addition it exposes all classes from all Build Extension Classloaders which are bound to the current project.
This is only released with the container.
During the build outside Mojo executions, the thread's context classloader is set to the project classloader.
-* {Plugin Classloaders}
+* Plugin Classloaders
[../../pluginClassRealm.svg] Plugin Class Realm
@@ -145,7 +145,7 @@ Guide to Maven Classloading
When a build plugin is executed, the thread's context classloader is set to the plugin classloader.
-* {Custom Classloaders}
+* Custom Classloaders
Plugins are free to create further classloaders. For example, a plugin might want to create a
classloader that combines the plugin class path and the project class path.
diff --git a/content/apt/guides/plugin/guide-java-plugin-development.apt.vm b/content/apt/guides/plugin/guide-java-plugin-development.apt.vm
index 6b88498a..3799b9dd 100644
--- a/content/apt/guides/plugin/guide-java-plugin-development.apt.vm
+++ b/content/apt/guides/plugin/guide-java-plugin-development.apt.vm
@@ -35,7 +35,7 @@ Guide to Developing Java Plugins
%{toc|fromDepth=2}
-* {Important Notice}
+* Important Notice
{{{../mini/guide-naming-conventions.html}<<Plugin Naming Convention and Apache Maven Trademark>>}}
@@ -48,14 +48,14 @@ Guide to Developing Java Plugins
Using this naming pattern is an infringement of the Apache Maven Trademark.
-* {Your First Plugin}
+* Your First Plugin
In this section we will build a simple plugin with one goal which takes no parameters
and simply displays a message on the screen when run. Along the way, we
will cover the basics of setting up a project to create a plugin, the
minimal contents of a Java mojo which will define goal code, and a couple ways to execute the mojo.
-** {Your First Mojo}
+** Your First Mojo
At its simplest, a Java mojo consists simply of a single class representing one plugin's goal. There is
no requirement for multiple classes like EJBs, although a plugin which
@@ -66,7 +66,7 @@ Guide to Developing Java Plugins
looks for classes with <<<...@Mojo>>> Java 5 annotation.
Any class with this annotation are included in the plugin configuration file.
-*** {A Simple Mojo}
+*** A Simple Mojo
Listed below is a simple mojo class which has no parameters. This is
about as simple as a mojo can be. After the listing is a description
@@ -114,7 +114,7 @@ public class GreetingMojo extends AbstractMojo
All Mojo annotations are described by the {{{../../developers/mojo-api-specification.html#The_Descriptor_and_Annotations}Mojo API Specification}}.
-** {Project Definition}
+** Project Definition
Once the mojos have been written for the plugin, it is time to
build the plugin. To do this properly, the project's descriptor
@@ -191,7 +191,7 @@ public class GreetingMojo extends AbstractMojo
</project>
+----+
-** {Building a Plugin}
+** Building a Plugin
There are few plugins goals bound to the standard build lifecycle
defined with the <<<maven-plugin>>> packaging:
@@ -213,7 +213,7 @@ public class GreetingMojo extends AbstractMojo
For more details, you can look at
{{{/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_maven-plugin_packaging} detailed bindings for <<<maven-plugin>>> packaging}}.
-** {Executing Your First Mojo}
+** Executing Your First Mojo
The most direct means of executing your new plugin is to specify the
plugin goal directly on the command line. To do this, you need to
@@ -249,7 +249,7 @@ mvn groupId:artifactId:version:goal
<<Tips>>: <<<version>>> is not required to run a standalone goal.
-*** {Shortening the Command Line}
+*** Shortening the Command Line
There are several ways to reduce the amount of required typing:
@@ -279,7 +279,7 @@ mvn groupId:artifactId:version:goal
At this point, you can run the mojo with "<<<mvn hello:sayhi>>>".
-*** {Attaching the Mojo to the Build Lifecycle}
+*** Attaching the Mojo to the Build Lifecycle
You can also configure your plugin to attach specific goals to a particular
phase of the build lifecycle. Here is an example:
@@ -316,7 +316,7 @@ mvn groupId:artifactId:version:goal
For more information on binding a mojo to phases in the lifecycle, please
refer to the {{{../introduction/introduction-to-the-lifecycle.html}Build Lifecycle}} document.
-* {Mojo archetype}
+* Mojo archetype
To create a new plugin project, you could using the Mojo
{{{../introduction/introduction-to-archetypes.html}archetype}} with the following command line:
@@ -329,7 +329,7 @@ mvn archetype:generate \
-DarchetypeArtifactId=maven-archetype-plugin
-----
-* {Parameters}
+* Parameters
It is unlikely that a mojo will be very useful without parameters.
Parameters provide a few very important functions:
@@ -342,7 +342,7 @@ mvn archetype:generate \
[]
-** {Defining Parameters Within a Mojo}
+** Defining Parameters Within a Mojo
Defining a parameter is as simple as creating an instance variable
in the mojo and adding the proper annotations. Listed below is an
@@ -367,7 +367,7 @@ mvn archetype:generate \
of the mojo parameter from the command line by referencing a system property that the user sets
via the <<<-D>>> option.
-** {Configuring Parameters in a Project}
+** Configuring Parameters in a Project
Configuring the parameter values for a plugin is done in a Maven
project within the <<<pom.xml>>> file as part of defining the
@@ -392,7 +392,7 @@ mvn archetype:generate \
<<Note>>: More details can be found in the
{{{../mini/guide-configuring-plugins.html}Guide to Configuring Plugins}}.
-* {Using Setters}
+* Using Setters
You are not restricted to using private field mapping which is good if you are trying to make you Mojos resuable
outside the context of Maven.
@@ -441,7 +441,7 @@ public class MyQueryMojo extends AbstractMojo {
Note the specification of the property name for each parameter which tells Maven what setter and getter to use when
the field's name does not match the intended name of the parameter in the plugin configuration.
-* {Resources}
+* Resources
[[1]] {{{../../developers/mojo-api-specification.html}Mojo Documentation}}: Mojo API, Mojo annotations
diff --git a/content/apt/plugin-developers/common-bugs.apt b/content/apt/plugin-developers/common-bugs.apt
index 98330483..aab45998 100644
--- a/content/apt/plugin-developers/common-bugs.apt
+++ b/content/apt/plugin-developers/common-bugs.apt
@@ -34,25 +34,9 @@ Common Bugs and Pitfalls
bugs. Note that the primary focus is on pointing out problems that are subtle in their nature rather than giving a
comprehensive guide for Java or Maven development.
- * {{{Reading_and_Writing_Text_Files}Reading and Writing Text Files}}
+%{toc|section=0|fromDepth=2|toDepth=5}
- * {{{Converting_between_URLs_and_Filesystem_Paths}Converting between URLs and Filesystem Paths}}
-
- * {{{Handling_Strings_Case-insensitively}Handling Strings Case-insensitively}}
-
- * {{{Creating_Resource_Bundle_Families}Creating Resource Bundle Families}}
-
- * {{{Using_System_Properties}Using System Properties}}
-
- * {{{Using_Shutdown_Hooks}Using Shutdown Hooks}}
-
- * {{{Resolving_Relative_Paths}Resolving Relative Paths}}
-
- * {{{Determining_the_Output_Directory_for_a_Site_Report}Determining the Output Directory for a Site Report}}
-
- * {{{Retrieving_the_Mojo_Logger}Retrieving the Mojo Logger}}
-
-* {Reading and Writing Text Files}
+* Reading and Writing Text Files
Textual content is composed of characters while file systems merely store byte streams. A file encoding (aka charset)
is used to convert between bytes and characters. The challenge is using the right file encoding.
@@ -106,7 +90,7 @@ writer.write( xmlContent );
<<<{{{https://codehaus-plexus.github.io/plexus-utils/apidocs/org/codehaus/plexus/util/WriterFactory.html#newXmlWriter(java.io.File)}WriterFactory.newXmlWriter()}}>>>
from the Plexus Utilities.
-* {Converting between URLs and Filesystem Paths}
+* Converting between URLs and Filesystem Paths
URLs and filesystem paths are really two different things and converting between them is not trivial. The main source
of problems is that different encoding rules apply for the strings that make up a URL or filesystem path. For example,
@@ -187,7 +171,7 @@ File path = new File( new URI( url.toExternalForm() ) );
<<<{{{https://codehaus-plexus.github.io/plexus-utils/apidocs/org/codehaus/plexus/util/FileUtils.html#toFile(java.net.URL)}FileUtils.toFile()}}>>>
from a recent Plexus Utilities.
-* {Handling Strings Case-insensitively}
+* Handling Strings Case-insensitively
When developers need to compare strings without regard to case or want to realize a map with case-insensitive string
keys, they often employ
@@ -223,7 +207,7 @@ if ( "info".equals( debugLevel.toLowerCase() ) )
will still run on Non-English systems, the parameter only locks down the casing rules used for the string comparison
such that the code delivers the same results on all platforms.
-* {Creating Resource Bundle Families}
+* Creating Resource Bundle Families
Especially reporting plugins employ resource bundles to support internationalization. One language (usually English)
is provided as the fallback/default language in the base resource bundle. Due to the lookup strategy performed by
@@ -251,7 +235,7 @@ src/
will have the Maven Site Plugin change the JVM's default locale to <<<xy>>> which in turn causes the lookup for
<<<en>>> to fail as outlined above unless the plugin has a dedicated resource bundle for English.
-* {Using System Properties}
+* Using System Properties
Maven's command line supports the definition of system properties via arguments of the form <<<-D key=value>>>.
While these properties are called system properties, plugins should never use
@@ -277,7 +261,7 @@ public MyMojo extends AbstractMojo
execution properties. These can be obtained from
<<<{{{https://maven.apache.org/ref/current/maven-core/apidocs/org/apache/maven/execution/MavenSession.html#getExecutionProperties()}MavenSession.getExecutionProperties()}}>>>.
-* {Using Shutdown Hooks}
+* Using Shutdown Hooks
People occasionally employ shutdown hooks to perform cleanup tasks, e.g. to delete temporary files as shown in the
example below:
@@ -305,7 +289,7 @@ public MyMojo extends AbstractMojo
For this reason, plugin developers should avoid usage of shutdown hooks and rather use <<<try>>>/<<<finally>>> blocks
to perform cleanup as soon as the resources are no longer needed.
-* {Resolving Relative Paths}
+* Resolving Relative Paths
It is common practice for users of Maven to specify relative paths in the POM, not to mention that the Super POM does
so, too. The intention is to resolve such relative paths against the base directory of the current project. In other
@@ -375,7 +359,7 @@ if ( !file.isAbsolute() )
feature known as <path translation>, i.e. the Maven core will automatically resolve relative paths when it pumps the
XML configuration into a mojo.
-* {Determining the Output Directory for a Site Report}
+* Determining the Output Directory for a Site Report
Most reporting plugins inherit from <<<AbstractMavenReport>>>. In doing so, they need to implement the inherited but
abstract method <<<getOutputDirectory()>>>. To implement this method, plugins usually declare a field named
@@ -424,7 +408,7 @@ public MyReportMojo extends AbstractMavenReport
effective output directory for the report. The implementation of <<<AbstractMavenReport.getOutputDirectory()>>>
is only intended as a fallback in case the mojo is not run as part of the site generation.
-* {Retrieving the Mojo Logger}
+* Retrieving the Mojo Logger
Maven employs an IoC container named Plexus to setup a plugin's mojos before their execution. In other words,
components required by a mojo will be provided by means of dependency injection, more precisely field injection. The
diff --git a/content/apt/pom.apt.vm b/content/apt/pom.apt.vm
index 0379c1f4..872dd308 100644
--- a/content/apt/pom.apt.vm
+++ b/content/apt/pom.apt.vm
@@ -26,14 +26,14 @@
POM Reference
-%{toc|section=0|fromDepth=1|toDepth=3}
+%{toc|section=0|fromDepth=2|toDepth=5}
-{Introduction}
+* Introduction
- * {{{/xsd/maven-4.0.0.xsd}The POM 4.0.0 XSD}} and
+ {{{/xsd/maven-4.0.0.xsd}The POM 4.0.0 XSD}} and
{{{/ref/current/maven-model/maven.html}descriptor reference documentation}}
-* {What is the POM?}
+** What is the POM?
POM stands for "Project Object Model". It is an XML representation of a Maven project held in a file
named <<<pom.xml>>>. When in the presence of Maven folks, speaking of a project is speaking in the philosophical
@@ -43,7 +43,7 @@ POM Reference
pieces that come into play to give code life. It is a one-stop-shop for all things concerning the project.
In fact, in the Maven world, a project does not need to contain any code at all, merely a <<<pom.xml>>>.
-* {Quick Overview}
+** Quick Overview
This is a listing of the elements directly under the POM's project element. Notice that <<<modelVersion>>>
contains 4.0.0. That is currently the only supported POM version, and is always required.
@@ -91,7 +91,7 @@ POM Reference
</project>
+--------------------------+
-{The Basics}
+* The Basics
The POM contains all necessary information about a project, as well as configurations of plugins to be
used during the build process. It is the declarative manifestation of the "who", "what",
@@ -114,7 +114,7 @@ POM Reference
</project>
+--------------------------+
-* {Maven Coordinates}
+** Maven Coordinates
The POM defined above is the bare minimum that Maven allows. <<<groupId:artifactId:version>>> are all
required fields (although, groupId and version do not need to be explicitly defined if they are inherited
@@ -154,7 +154,7 @@ POM Reference
The three elements given above point to a specific version of a project, letting Maven know <who> we
are dealing with, and <when> in its software lifecycle we want them.
-* {Packaging}
+** Packaging
Now that we have our address structure of <<<groupId:artifactId:version>>>, there is one more standard
label to give us a really complete <what>: that is the project's packaging. In our
@@ -178,7 +178,7 @@ POM Reference
a particular package structure:
see {{{/ref/current/maven-core/default-bindings.html}Plugin Bindings for default Lifecycle Reference}} for details.
-* {POM Relationships}
+** POM Relationships
One powerful aspect of Maven is its handling of project relationships: this includes
dependencies (and transitive dependencies), inheritance, and aggregation (multi-module projects).
@@ -192,7 +192,7 @@ POM Reference
Maven solves both problems through a common local repository
from which to link projects correctly, versions and all.
-** {Dependencies}
+*** Dependencies
The cornerstone of the POM is its {{{/ref/current/maven-model/maven.html#class_dependency}dependency}} list.
Most projects depend on others to build
@@ -318,13 +318,13 @@ mvn install:install-file -Dfile=non-maven-proj.jar -DgroupId=some.group -Dartifa
In the shortest terms, <<<optional>>> lets other projects know that, when you use this project, you
do not require this dependency in order to work correctly.
-*** {Dependency Management}
+**** Dependency Management
Dependencies can be managed in the <<<dependencyManagement>>> section to affect the resolution of dependencies
which are not fully qualified or to enforce the usage of a specific transitive dependency version. Further information
in {{{./guides/introduction/introduction-to-dependency-mechanism.html}Introduction to the Dependency Mechanism}}.
-*** {Dependency Version Requirement Specification}
+**** Dependency Version Requirement Specification
Dependencies' <<<version>>> elements define version requirements, which are used to compute dependency versions. Soft requirements can be replaced by
different versions of the same artifact found elsewhere in the dependency
@@ -355,7 +355,7 @@ mvn install:install-file -Dfile=non-maven-proj.jar -DgroupId=some.group -Dartifa
hard requirements of the dependencies on that project. If no version
satisfies all the hard requirements, the build fails.
-*** {Version Order Specification}:
+**** Version Order Specification
If version strings are syntactically correct {{{https://semver.org/spec/v1.0.0.html}Semantic Versioning 1.0.0}}
version numbers, then in almost all cases version comparison follows the precedence rules outlined in that specification.
@@ -465,7 +465,7 @@ mvn install:install-file -Dfile=non-maven-proj.jar -DgroupId=some.group -Dartifa
what most people expect. In addition, Gradle interprets it differently, resulting in different dependency trees for the same POM.
If the intention is to restrict it to <1.*> versions, the better version requirement is <<<[1,1.999999)>>>.
-*** {Version Order Testing}:
+**** Version Order Testing
The maven distribution includes a tool to check version order. It was used to produce the examples in the previous paragraphs. Feel free to run it yourself when in doubt. You can run it like this:
@@ -485,7 +485,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
3. 1.1 -> 1.1; tokens: [1, 1]
----------------------------------------
-*** {Exclusions}
+**** Exclusions
It is sometimes useful to limit a dependency's transitive dependencies. A dependency may have incorrectly
specified scopes, or dependencies that conflict with other dependencies in your project. Exclusions tell Maven not to include a
@@ -551,7 +551,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
<<<artifactId>>> denoting a dependency to exclude. Unlike <<<optional>>>, which may or may not
be installed and used, <<<exclusions>>> actively remove artifacts from the dependency tree.
-** {Inheritance}
+*** Inheritance
One powerful addition that Maven brings to build management is the concept of project inheritance.
Although in build systems such as Ant inheritance can be simulated, Maven
@@ -663,7 +663,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
All URLs are transformed when being inherited by default. The other ones are just inherited as is.
For plugin configuration you can overwrite the inheritance behaviour with the attributes <<<combine.children>>> or <<<combine.self>>> outlined in {{Plugins}}.
-*** {The Super POM}
+**** The Super POM
Similar to the inheritance of objects in object oriented programming, POMs that extend
a parent POM inherit certain values from that parent. Moreover, just as Java objects
@@ -675,7 +675,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
You can take a look at how the Super POM affects your Project Object Model by creating a
minimal <<<pom.xml>>> and executing on the command line: <<<mvn help:effective-pom>>>
-*** {Dependency Management}
+**** Dependency Management
Besides inheriting certain top-level elements, parents have elements to configure values for
child POMs and transitive dependencies. One of those elements is
@@ -699,7 +699,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
<<<mvn dependency:tree>>> is helpful.
-** {Aggregation} (or Multi-Module)
+*** Aggregation (or Multi-Module)
A project with modules is known as a multi-module, or aggregator project. Modules are projects
that this POM lists, and are executed as a group. A <<<pom>>> packaged project may
@@ -731,7 +731,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
To see aggregation in action, have a look at the
{{{https://github.com/apache/maven/blob/master/pom.xml}Maven}} base POM.
-*** A final note on {Inheritance v. Aggregation}
+**** A final note on {Inheritance v. Aggregation}
Inheritance and aggregation create a nice dynamic to control builds through a single,
high-level POM. You often see projects that are both parents and aggregators.
@@ -743,7 +743,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
not necessarily have - any modules that it aggregates. Conversely, a POM project may aggregate
projects that do not inherit from it.
-* {Properties}
+** Properties
Properties are the last required piece to understand POM basics. Maven properties
are value placeholders, like properties in Ant. Their values are accessible anywhere
@@ -791,14 +791,14 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
[]
-{Build Settings}
+* Build Settings
Beyond the basics of the POM given above, there are two more elements that must be understood before
claiming basic competency of the POM. They are the <<<build>>> element, that handles things like
declaring your project's directory structure and managing plugins; and the <<<reporting>>> element,
that largely mirrors the build element for reporting purposes.
-* {Build}
+** Build
According to the POM 4.0.0 XSD, the <<<build>>> element is conceptually divided into two parts:
there is a <<<BaseBuild>>> type which contains the set of elements common to both <<<build>>> elements
@@ -825,7 +825,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
</project>
+-----------------------+
-** The {BaseBuild Element} Set
+*** The BaseBuild Element Set
<<<BaseBuild>>> is exactly as it sounds: the base set of elements between the two <<<build>>> elements in the POM.
@@ -867,7 +867,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
For a more comprehensive look at what filters are and what they can do, take a look at the
{{{./guides/getting-started}quick start guide}}.
-*** {Resources}
+**** Resources
Another feature of <<<build>>> elements is specifying where resources exist within your project.
Resources are not (usually) code. They are not compiled, but are items meant to be
@@ -937,7 +937,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
phases. The one difference is that the default (Super POM defined) test resource directory for a project is
<<<$\{project.basedir\}/src/test/resources>>>. Test resources are not deployed.
-*** {Plugins}
+**** Plugins
+------------------------------------------+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -1167,7 +1167,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
Same as above, but confines the configuration to this specific list of goals, rather than all goals
under the plugin.
-*** {Plugin Management}
+**** Plugin Management
* <<pluginManagement>>:
is an element that is seen along side plugins. Plugin Management contains plugin elements in much
@@ -1233,13 +1233,13 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
+------------------------------------------+
-** {The Build Element Set}
+*** The Build Element Set
The <<<Build>>> type in the XSD denotes those elements that are available only for the "project build". Despite
the number of extra elements (six), there are really only two groups of elements that project build contains
that are missing from the profile build: directories and extensions.
-*** {Directories}
+**** Directories
The set of directory elements live in the parent build element, which set various directory structures
for the POM as a whole. Since they do not exist in profile builds, these cannot be altered by profiles.
@@ -1264,7 +1264,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
base build directory: <<<$\{project.basedir\}>>>. <<Please note that the>> <<<scriptSourceDirectory>>> <<is nowhere
used in Maven and is obsolete>>.
-*** {Extensions}
+**** Extensions
Extensions are a list of artifacts that are to be used in this build. They will be included
in the running build's classpath. They can enable extensions to the build process (such as add an
@@ -1291,7 +1291,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
</project>
+------------------------------------------+
-* {Reporting}
+** Reporting
Reporting contains the elements that correspond specifically for the <<<site>>> generation phase.
Certain Maven plugins can generate reports defined and configured under the reporting element,
@@ -1333,7 +1333,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
The other difference is the <<<outputDirectory>>> element under <<<plugin>>>. In the case of reporting,
the output directory is <<<$\{project.basedir\}/target/site>>> by default.
-** {Report Sets}
+*** Report Sets
It is important to keep in mind that an individual plugin may have multiple goals. Each goal may have a
separate configuration. Report sets configure execution of a report plugin's goals. Does this sound familiar
@@ -1379,7 +1379,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
configure plugins, but must also configure the goals of those plugins. That is where these
elements come in, giving the POM ultimate granularity in control of its build destiny.
-{More Project Information}
+* More Project Information
Several elements do not affect the build, but rather document the project for
the convenience of developers. Many of these elements are used to fill in project
@@ -1400,7 +1400,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
* <<inceptionYear>>:
The year the project was first created.
-* {Licenses}
+** Licenses
+-------------------------+
<licenses>
@@ -1426,7 +1426,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
This describes how the project may be legally distributed. The two stated methods are repo (they may be
downloaded from a Maven repository) or manual (they must be manually installed).
-* {Organization}
+** Organization
Most projects are run by some sort of organization (business, private group, etc.). Here is
where the most basic information is set.
@@ -1442,7 +1442,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
</project>
+-------------------------+
-* {Developers}
+** Developers
All projects consist of files that were created, at some time, by a person. Like the other systems
that surround a project, so to do the people involved with a project have a stake in the project.
@@ -1501,7 +1501,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
image or an instant messenger handle. Different plugins may use these properties, or they may simply
be for other developers who read the POM.
-* {Contributors}
+** Contributors
Contributors are like developers
yet play an ancillary role in a project's lifecycle. Perhaps the contributor sent in a bug fix,
@@ -1534,9 +1534,9 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
Contributors contain the same set of elements than developers sans the <<<id>>> element.
-{Environment Settings}
+* Environment Settings
-* {Issue Management}
+** Issue Management
This defines the defect tracking system (<Bugzilla>, <TestTrack>, <ClearQuest>, etc)
used. Although there is nothing stopping a plugin from using this information for
@@ -1554,7 +1554,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
</project>
+-------------------------+
-* {Continuous Integration Management}
+** Continuous Integration Management
Continuous integration build systems based upon triggers or timings (such as, hourly or daily)
have grown in favor over manual builds in the past few years. As build systems have become more
@@ -1588,7 +1588,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
</project>
+-------------------------+
-* {Mailing Lists}
+** Mailing Lists
Mailing lists are a great tool for keeping in touch with people about a project.
Most mailing lists are for developers and users.
@@ -1625,7 +1625,7 @@ Display parameters as parsed by Maven (in canonical form and as a list of tokens
The email address which one would use in order to post to the mailing list. Note that not all
mailing lists have the ability to post to (such as a build failure list).
-* {SCM}
+** SCM
SCM (Software Configuration Management, also called Source Code/Control Management or, succinctly,
version control) is an integral part of any healthy project. If your Maven project uses an SCM system
@@ -1671,7 +1671,7 @@ scm:cvs:pserver:127.0.0.1:/cvs/root:my-project
* <<url>>:
A publicly browsable repository. For example, via ViewCVS.
-* {Prerequisites}
+** Prerequisites
The POM may have certain prerequisites in order to execute correctly.
The only element that exists as a prerequisite in
@@ -1693,7 +1693,7 @@ scm:cvs:pserver:127.0.0.1:/cvs/root:my-project
</project>
+-------------------------+
-* {Repositories}
+** Repositories
Repositories are collections of artifacts which adhere to the Maven repository directory
layout. In order to be a Maven repository artifact, a POM file must live within the structure
@@ -1770,7 +1770,7 @@ scm:cvs:pserver:127.0.0.1:/cvs/root:my-project
Its default value is <<<default>>>.
-* {Plugin Repositories}
+** Plugin Repositories
Repositories are home to two major types of artifacts. The first are artifacts that are used as
dependencies of other artifacts. These are the majority of artifacts that reside within central.
@@ -1781,7 +1781,7 @@ scm:cvs:pserver:127.0.0.1:/cvs/root:my-project
remote location of where Maven can find new plugins.
-* {Distribution Management}
+** Distribution Management
Distribution management acts precisely as it sounds: it manages the distribution of the artifact
and supporting files generated throughout the build process.
@@ -1802,7 +1802,7 @@ scm:cvs:pserver:127.0.0.1:/cvs/root:my-project
</project>
+-------------------------+
-** {Repository}
+*** Repository
Whereas the repositories element specifies in the POM the location and manner in which Maven may
download remote artifacts for use by the current project, distributionManagement specifies where
@@ -1850,7 +1850,7 @@ scm:cvs:pserver:127.0.0.1:/cvs/root:my-project
These are the same types and purpose as the layout element defined in the repository element.
They are <<<default>>> and <<<legacy>>>.
-** {Site Distribution}
+*** Site Distribution
More than distribution to the repositories, <<<distributionManagement>>> is responsible for defining
how to deploy the project's site and documentation.
@@ -1876,7 +1876,7 @@ scm:cvs:pserver:127.0.0.1:/cvs/root:my-project
These elements are similar to their counterparts above in the <<<distributionManagement>>>
<<<repository>>> element.
-** {Relocation}
+*** Relocation
+-------------------------+
<project xmlns="http://maven.apache.org/POM/4.0.0"1 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -1903,7 +1903,7 @@ scm:cvs:pserver:127.0.0.1:/cvs/root:my-project
being renamed to <<<org.apache:my-project:1.0>>>. Besides specifying the new address, it
is also good form to provide a message explaining why.
-** {downloadUrl}
+*** downloadUrl
+-------------------------+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/001/XMLSchema-instance"
@@ -1921,7 +1921,7 @@ scm:cvs:pserver:127.0.0.1:/cvs/root:my-project
This is given to assist in locating artifacts that are not in the repository due to licensing restrictions.
See for example {{{https://issues.apache.org/jira/browse/MNG-2083}MNG-2083}} for a typical workflow.
-** {status}
+*** status
+-------------------------+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/001/XMLSchema-instance"
@@ -1956,7 +1956,7 @@ scm:cvs:pserver:127.0.0.1:/cvs/root:my-project
* <<verified>>:
This project has been verified, and should be considered finalized.
-* {Profiles}
+* Profiles
A new feature of the POM 4.0 is the ability of a project to change settings depending
on the environment where it is being built. A <<<profile>>> element contains both an optional
@@ -1987,7 +1987,7 @@ scm:cvs:pserver:127.0.0.1:/cvs/root:my-project
</project>
+-------------------------+
-** {Activation}
+** Activation
Activations are the key of a profile. The power of a profile comes from its ability to modify the
basic POM only under certain circumstances. Those circumstances are specified via an <<<activation>>> element.
@@ -2082,7 +2082,7 @@ mvn help:active-profiles
Further information about profiles is available in {{{./guides/introduction/introduction-to-profiles.html}Introduction to Build Profiles}}.
-** {The BaseBuild Element Set} <(revisited)>
+* The BaseBuild Element Set (revisited)
As mentioned above, the reason for the two types of build elements reside in the fact that it does
not make sense for a profile to configure build directories or
@@ -2091,7 +2091,7 @@ mvn help:active-profiles
<If you find your project needing to keep two sets of code for different environments, it may be
prudent to investigate refactoring the project into two or more separate projects.>
-{Final}
+* Final
The Maven POM is big. However, its size is also a testament to its versatility. The ability
to abstract all of the aspects of a project into a single artifact is powerful, to say the least.
@@ -2103,5 +2103,5 @@ mvn help:active-profiles
======================
- Aspects of this guide were originally published in the
- {{{http://www.javaworld.com/javaworld/jw-05-2006/jw-0529-maven.html}Maven 2 Pom Demystified}}.
+ Aspects of this guide were originally published in the article "Maven 2 Pom Demystified The evolution of a project
+ model" by Eric Redmond (JavaWorld.com, 2006-05-29).