You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sp...@apache.org on 2025/08/05 09:18:34 UTC
(maven-site) branch master updated: Convert gettingStarted/introduction from APT to Markdown (#1359)
This is an automated email from the ASF dual-hosted git repository.
sparsick 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 75d00cc1 Convert gettingStarted/introduction from APT to Markdown (#1359)
75d00cc1 is described below
commit 75d00cc1d026de63b8cd738b082c0651982debd6
Author: Matthias Bünger <Bu...@users.noreply.github.com>
AuthorDate: Tue Aug 5 11:18:30 2025 +0200
Convert gettingStarted/introduction from APT to Markdown (#1359)
---
content/apt/guides/getting-started/index.apt | 1225 --------------------
.../getting-started/maven-in-five-minutes.apt | 321 -----
.../getting-started/windows-prerequisites.apt | 66 --
.../introduction/introduction-to-archetypes.apt | 100 --
.../introduction-to-dependency-mechanism.apt | 909 ---------------
...ction-to-optional-and-excludes-dependencies.apt | 320 -----
.../introduction/introduction-to-plugins.apt | 87 --
.../introduction/introduction-to-profiles.apt | 859 --------------
.../introduction/introduction-to-repositories.apt | 163 ---
.../introduction/introduction-to-the-lifecycle.apt | 470 --------
.../introduction/introduction-to-the-pom.apt | 543 ---------
...troduction-to-the-standard-directory-layout.apt | 86 --
.../guides/development/guide-testing-releases.md | 2 +-
content/markdown/guides/getting-started/index.md | 1029 ++++++++++++++++
.../getting-started/maven-in-five-minutes.md | 254 ++++
.../getting-started/windows-prerequisites.md | 47 +
.../introduction/introduction-to-archetypes.md | 62 +
.../introduction-to-dependency-mechanism.md | 760 ++++++++++++
...uction-to-optional-and-excludes-dependencies.md | 235 ++++
.../guides/introduction/introduction-to-plugins.md | 46 +
.../introduction/introduction-to-profiles.md | 635 ++++++++++
.../introduction/introduction-to-repositories.md | 113 ++
.../introduction/introduction-to-the-lifecycle.md | 312 +++++
.../guides/introduction/introduction-to-the-pom.md | 465 ++++++++
...ntroduction-to-the-standard-directory-layout.md | 53 +
25 files changed, 4012 insertions(+), 5150 deletions(-)
diff --git a/content/apt/guides/getting-started/index.apt b/content/apt/guides/getting-started/index.apt
deleted file mode 100644
index 90a9959a..00000000
--- a/content/apt/guides/getting-started/index.apt
+++ /dev/null
@@ -1,1225 +0,0 @@
- ----
- Maven Getting Started Guide
- -----
- Jason van Zyl
- Vincent Siveton
- -----
- 2006-11-01
- -----
-
-Maven Getting Started Guide
-
- This guide is intended as a reference for those working with Maven for the first time, but is also intended to serve as
- a cookbook with self-contained references and solutions for common use cases. For first time users, it is recommended
- that you step through the material in a sequential fashion. For users more familiar with Maven, this guide endeavours
- to provide a quick solution for the need at hand. It is assumed at this point that you have downloaded Maven and
- installed Maven on your local machine. If you have not done so please refer to the
- {{{../../download.html}Download and Installation}} instructions.
-
- Ok, so you now have Maven installed and we're ready to go. Before we jump into our examples we'll very briefly go over
- what Maven is and how it can help you with your daily work and collaborative efforts with team members. Maven will, of
- course, work for small projects, but Maven shines in helping teams operate more effectively by allowing team members
- to focus on what the stakeholders of a project require. You can leave the build infrastructure to Maven!
-
-Sections
-
-%{toc|section=0|fromDepth=2|toDepth=3}
-
-* What is Maven?
-
- At first glance Maven can appear to be many things, but in a nutshell Maven is an attempt <to apply patterns to
- a project's build infrastructure in order to promote comprehension and productivity by providing a clear path in the
- use of best practices>. Maven is essentially a project management and comprehension tool and as such provides a way to
- help with managing:
-
-
- * Builds
-
- * Documentation
-
- * Reporting
-
- * Dependencies
-
- * SCMs
-
- * Releases
-
- * Distribution
-
- []
-
- If you want more background information on Maven you can check out {{{../../background/philosophy-of-maven.html}The Philosophy of Maven}} and
- {{{../../background/history-of-maven.html}The History of Maven}}. Now let's move on to how you, the user, can benefit from
- using Maven.
-
-* How can Maven benefit my development process?
-
- Maven can provide benefits for your build process by employing standard conventions and practices to accelerate your development
- cycle while at the same time helping you achieve a higher rate of success.
-
- Now that we have covered a little bit of the history and purpose of Maven let's get into some real examples to
- get you up and running with Maven!
-
-* How do I setup Maven?
-
- The defaults for Maven are often sufficient, but if you need to change the cache location or are behind a HTTP proxy,
- you will need to create configuration. See the {{{../mini/guide-configuring-maven.html} Guide to Configuring Maven}} for
- more information.
-
-* How do I make my first Maven project?
-
- We are going to jump headlong into creating your first Maven project!
- To create our first Maven project we are going to use Maven's archetype mechanism. An archetype is defined as
- <an original pattern or model from which all other things of the same kind are made>. In Maven, an archetype is a template
- of a project which is combined with some user input to produce a working Maven project that has been tailored to the
- user's requirements. We are going to show you how the archetype mechanism works now, but if you would like to know more
- about archetypes please refer to our {{{../introduction/introduction-to-archetypes.html}Introduction to Archetypes}}.
-
- On to creating your first project! In order to create the simplest of Maven projects, execute the following from
- the command line:
-
------
-mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.5 -DinteractiveMode=false
------
-
- Once you have executed this command, you will notice a few things have happened. First, you will notice that
- a directory named <<<my-app>>> has been created for the new project, and this directory contains a file named
- <<<pom.xml>>> that should look like this:
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1.0-SNAPSHOT</version>
-
- <name>my-app</name>
- <!-- FIXME change it to the project's website -->
- <url>http://www.example.com</url>
-
- <properties>
- <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
- <maven.compiler.release>17</maven.compiler.release>
- </properties>
-
- <dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>org.junit</groupId>
- <artifactId>junit-bom</artifactId>
- <version>5.11.0</version>
- <type>pom</type>
- <scope>import</scope>
- </dependency>
- </dependencies>
- </dependencyManagement>
-
- <dependencies>
- <dependency>
- <groupId>org.junit.jupiter</groupId>
- <artifactId>junit-jupiter-api</artifactId>
- <scope>test</scope>
- </dependency>
- <!-- Optionally: parameterized tests support -->
- <dependency>
- <groupId>org.junit.jupiter</groupId>
- <artifactId>junit-jupiter-params</artifactId>
- <scope>test</scope>
- </dependency>
- </dependencies>
-
- <build>
- <pluginManagement><!-- lock down plugins versions to avoid using Maven defaults (may be moved to parent pom) -->
- ... lots of helpful plugins
- </pluginManagement>
- </build>
-</project>
-+-----+
-
- <<<pom.xml>>> contains the Project Object Model (POM) for this project. The POM is the basic unit
- of work in Maven. This is important to remember because Maven is inherently project-centric in that everything revolves
- around the notion of a project. In short, the POM contains every important piece of information about your project and
- is essentially one-stop-shopping for finding anything related to your project. Understanding the POM is important and
- new users are encouraged to refer to the {{{../introduction/introduction-to-the-pom.html}Introduction to the POM}}.
-
- This is a very simple POM but still displays the key elements every POM contains, so let's walk through each of them
- to familiarize you with the POM essentials:
-
- * <<project>> This is the top-level element in all Maven <<<pom.xml>>> files.
-
- * <<modelVersion>> This element indicates what version of the object model this POM is using. The version of the
- model itself changes very infrequently but it is mandatory in order to ensure stability of use if and when
- the Maven developers deem it necessary to change the model.
-
- * <<groupId>> This element indicates the unique identifier of the organization or group that created the project.
- The groupId is one of the key identifiers of a project and is typically based on the fully qualified
- domain name of your organization. For example <<<org.apache.maven.plugins>>> is the designated groupId for
- all Maven plugins.
-
- * <<artifactId>> This element indicates the unique base name of the primary artifact being generated by this project.
- The primary artifact for a project is typically a JAR file. Secondary artifacts like source bundles also use
- the artifactId as part of their final name. A typical artifact produced by Maven would have the form
- \<artifactId\>-\<version\>.\<extension\> (for example, <<<myapp-1.0.jar>>>).
-
- * <<version>> This element indicates the version of the artifact generated by the project. Maven goes a long way
- to help you with version management and you will often see the <<<SNAPSHOT>>> designator in a version, which
- indicates that a project is in a state of development. We will discuss the use of
- {{{./index.html#what-is-a-snapshot-version}snapshots}} and how they work further on in this guide.
-
- * <<name>> This element indicates the display name used for the project. This is often used in Maven's
- generated documentation.
-
- * <<url>> This element indicates where the project's site can be found. This is often used in Maven's
- generated documentation.
-
- * <<properties>> This element contains value placeholders accessible anywhere within a POM.
-
- * <<dependencies>> This element's children list {{{/pom.html#dependencies}dependencies}}. The cornerstone of the POM.
-
- * <<build>> This element handles things like declaring your project's directory structure and managing plugins.
-
- []
-
- For a complete reference of what elements are available for use in the POM please refer to our {{{/ref/current/maven-model/maven.html}POM Reference}}.
- Now let's get back to the project at hand.
-
- After the archetype generation of your first project you will also notice that the following directory structure
- has been created:
-
------
-my-app
-|-- pom.xml
-`-- src
- |-- main
- | `-- java
- | `-- com
- | `-- mycompany
- | `-- app
- | `-- App.java
- `-- test
- `-- java
- `-- com
- `-- mycompany
- `-- app
- `-- AppTest.java
------
-
- As you can see, the project created from the archetype has a POM, a source tree for your application's sources and
- a source tree for your test sources. This is the standard layout for Maven projects (the application sources
- reside in <<<$\{project.basedir\}/src/main/java>>> and test sources reside in <<<$\{project.basedir\}/src/test/java>>>, where <<<$\{project.basedir\}>>>
- represents the directory containing <<<pom.xml>>>).
-
- If you were to create a Maven project by hand this is the directory structure that we recommend using. This is a
- Maven convention and to learn more about it you can read our
- {{{../introduction/introduction-to-the-standard-directory-layout.html}Introduction to the Standard Directory Layout}}.
-
- Now that we have a POM, some application sources, and some test sources you are probably asking...
-
-* How do I compile my application sources?
-
- Change to the directory where <<<pom.xml>>> is created by archetype:generate and execute the following command to compile
- your application sources:
-
--------
-mvn compile
--------
-
- Upon executing this command you should see output like the following:
-
------
-[INFO] Scanning for projects...
-[INFO]
-[INFO] ----------------------< com.mycompany.app:my-app >----------------------
-[INFO] Building my-app 1.0-SNAPSHOT
-[INFO] --------------------------------[ jar ]---------------------------------
-[INFO]
-[INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ my-app ---
-[INFO] Using 'UTF-8' encoding to copy filtered resources.
-[INFO] skip non existing resourceDirectory <dir>/my-app/src/main/resources
-[INFO]
-[INFO] --- maven-compiler-plugin:3.8.0:compile (default-compile) @ my-app ---
-[INFO] Changes detected - recompiling the module!
-[INFO] Compiling 1 source file to <dir>/my-app/target/classes
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD SUCCESS
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 0.899 s
-[INFO] Finished at: 2020-07-12T11:31:54+01:00
-[INFO] ------------------------------------------------------------------------
------
-
- The first time you execute this (or any other) command, Maven will need to download all the plugins and related
- dependencies it needs to fulfill the command. From a clean installation of Maven, this can take quite a while (in
- the output above, it took almost 4 minutes). If you execute the command again, Maven will now have what it needs,
- so it won't need to download anything new and will be able to execute the command much more quickly.
-
- As you can see from the output, the compiled classes were placed in <<<$\{project.basedir\}/target/classes>>>, which is
- another standard convention employed by Maven. So, if you're a keen observer, you'll notice that by using the
- standard conventions, the POM above is very small and you haven't had to tell Maven explicitly where any of
- your sources are or where the output should go. By following the standard Maven conventions, you can get
- a lot done with very little effort! Just as a casual comparison, let's take a look at what you might have had to do
- in {{{http://ant.apache.org}Ant}} to accomplish the same {{{../../ant/build-a1.xml}thing}}.
-
- Now, this is simply to compile a single tree of application sources and the Ant script shown is pretty much the same
- size as the POM shown above. But we'll see how much more we can do with just that simple POM!
-
-* How do I compile my test sources and run my unit tests?
-
- Now you're successfully compiling your application's sources and now you've got some unit tests that you want to compile
- and execute (because every programmer always writes and executes their unit tests *nudge nudge wink wink*).
-
- Execute the following command:
-
-------
-mvn test
-------
-
- Upon executing this command you should see output like the following:
-
-----
-[INFO] Scanning for projects...
-[INFO]
-[INFO] ----------------------< com.mycompany.app:my-app >----------------------
-[INFO] Building my-app 1.0-SNAPSHOT
-[INFO] --------------------------------[ jar ]---------------------------------
-[INFO]
-[INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ my-app ---
-[INFO] Using 'UTF-8' encoding to copy filtered resources.
-[INFO] skip non existing resourceDirectory <dir>/my-app/src/main/resources
-[INFO]
-[INFO] --- maven-compiler-plugin:3.8.0:compile (default-compile) @ my-app ---
-[INFO] Nothing to compile - all classes are up to date
-[INFO]
-[INFO] --- maven-resources-plugin:3.0.2:testResources (default-testResources) @ my-app ---
-[INFO] Using 'UTF-8' encoding to copy filtered resources.
-[INFO] skip non existing resourceDirectory <dir>/my-app/src/test/resources
-[INFO]
-[INFO] --- maven-compiler-plugin:3.8.0:testCompile (default-testCompile) @ my-app ---
-[INFO] Changes detected - recompiling the module!
-[INFO] Compiling 1 source file to <dir>/my-app/target/test-classes
-[INFO]
-[INFO] --- maven-surefire-plugin:2.22.1:test (default-test) @ my-app ---
-[INFO]
-[INFO] -------------------------------------------------------
-[INFO] T E S T S
-[INFO] -------------------------------------------------------
-[INFO] Running com.mycompany.app.AppTest
-[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.025 s - in com.mycompany.app.AppTest
-[INFO]
-[INFO] Results:
-[INFO]
-[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
-[INFO]
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD SUCCESS
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 1.881 s
-[INFO] Finished at: 2020-07-12T12:00:33+01:00
-[INFO] ------------------------------------------------------------------------
-----
-
- Some things to notice about the output:
-
- * Maven downloads more dependencies this time. These are the dependencies and plugins necessary for executing the tests
- (it already has the dependencies it needs for compiling and won't download them again).
-
- * Before compiling and executing the tests Maven compiles the main code (all these classes are up to date because
- we haven't changed anything since we compiled last).
-
- If you simply want to compile your test sources (but not execute the tests), you can execute the following:
-
-------
- mvn test-compile
-------
-
- Now that you can compile your application sources, compile your tests, and execute the tests, you'll want to move
- on to the next logical step so you'll be asking ...
-
-* How do I create a JAR and install it in my local repository?
-
- Making a JAR file is straight forward enough and can be accomplished by executing the following command:
-
-~~ How to skip tests ... jvz
-
-------
-mvn package
-------
-
- You can now take a look in the <<<$\{project.basedir\}/target>>> directory and you will see the generated JAR file.
-
- Now you'll want to install the artifact you've generated (the JAR file) in your local repository
- (<<<$\{user.home\}/.m2/repository>>> is the default location). For more information on repositories you can refer to our
- {{{../introduction/introduction-to-repositories.html}Introduction to Repositories}} but let's move on to installing our artifact!
- To do so execute the following command:
-
-------
-mvn install
-------
-
- Upon executing this command you should see the following output:
-
-----
-[INFO] Scanning for projects...
-[INFO]
-[INFO] ----------------------< com.mycompany.app:my-app >----------------------
-[INFO] Building my-app 1.0-SNAPSHOT
-[INFO] --------------------------------[ jar ]---------------------------------
-[INFO]
-[INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ my-app ---
-...
-[INFO] --- maven-compiler-plugin:3.8.0:compile (default-compile) @ my-app ---
-[INFO] Nothing to compile - all classes are up to date
-[INFO]
-[INFO] --- maven-resources-plugin:3.0.2:testResources (default-testResources) @ my-app ---
-...
-[INFO] --- maven-compiler-plugin:3.8.0:testCompile (default-testCompile) @ my-app ---
-[INFO] Nothing to compile - all classes are up to date
-[INFO]
-[INFO] --- maven-surefire-plugin:2.22.1:test (default-test) @ my-app ---
-[INFO]
-[INFO] -------------------------------------------------------
-[INFO] T E S T S
-[INFO] -------------------------------------------------------
-[INFO] Running com.mycompany.app.AppTest
-[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.025 s - in com.mycompany.app.AppTest
-[INFO]
-[INFO] Results:
-[INFO]
-[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
-[INFO]
-[INFO]
-[INFO] --- maven-jar-plugin:3.0.2:jar (default-jar) @ my-app ---
-[INFO] Building jar: <dir>/my-app/target/my-app-1.0-SNAPSHOT.jar
-[INFO]
-[INFO] --- maven-install-plugin:2.5.2:install (default-install) @ my-app ---
-[INFO] Installing <dir>/my-app/target/my-app-1.0-SNAPSHOT.jar to <local-repository>/com/mycompany/app/my-app/1.0-SNAPSHOT/my-app-1.0-SNAPSHOT.jar
-[INFO] Installing <dir>/my-app/pom.xml to <local-repository>/com/mycompany/app/my-app/1.0-SNAPSHOT/my-app-1.0-SNAPSHOT.pom
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD SUCCESS
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 1.678 s
-[INFO] Finished at: 2020-07-12T12:04:45+01:00
-[INFO] ------------------------------------------------------------------------
-----
-
- Note that the surefire plugin (which executes the test) looks for tests contained in files with a particular naming convention. By default
- the tests included are:
-
- * <<<\*\*/\*Test.java>>>
-
- * <<<\*\*/Test\*.java>>>
-
- * <<<\*\*/\*TestCase.java>>>
-
- []
-
- And the default excludes are:
-
- * <<<\*\*/Abstract\*Test.java>>>
-
- * <<<\*\*/Abstract\*TestCase.java>>>
-
- []
-
- You have walked through the process for setting up, building, testing, packaging, and installing a typical Maven project.
- This is likely the vast majority of what projects will be doing with Maven and if you've noticed, everything you've been
- able to do up to this point has been driven by an 18-line file, namely the project's model or POM. If you look at
- a typical Ant {{{../../ant/build-a1.xml}build file}} that provides the same functionality that we've achieved thus
- far you'll notice it's already twice the size of the POM and we're just getting started! There is far more
- functionality available to you from Maven without requiring any additions to our POM as it currently stands. To
- get any more functionality out of our example Ant build file you must keep making error-prone additions.
-
- So what else can you get for free? There are a great number of Maven plugins that work out of the box with
- even a simple POM like we have above. We'll mention one here specifically as it is one of the highly
- prized features of Maven: without any work on your part this POM has enough information to generate
- a web site for your project! You will most likely want to customize your Maven site but if you're pressed for
- time all you need to do to provide basic information about your project is execute the following command:
-
-------
-mvn site
-------
-
- There are plenty of other standalone goals that can be executed as well, for example:
-
-------
-mvn clean
-------
-
- This will remove the <<<target>>> directory with all the build data before starting so that it is fresh.
-
-* What is a SNAPSHOT version?
-
- Notice the value of the <<version>> tag in the <<<pom.xml>>> file shown below has the suffix: <<<-SNAPSHOT>>>.
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0"
- ...
- <groupId>...</groupId>
- <artifactId>my-app</artifactId>
- ...
- <version>1.0-SNAPSHOT</version>
- <name>Maven Quick Start Archetype</name>
- ...
-+-----+
-
- The <<<SNAPSHOT>>> value refers to the 'latest' code along a development branch, and provides no guarantee the
- code is stable or unchanging. Conversely, the code in a 'release' version (any version value without the suffix <<<SNAPSHOT>>>)
- is unchanging.
-
- In other words, a SNAPSHOT version is the 'development' version before the final 'release' version.
- The SNAPSHOT is "older" than its release.
-
- During the {{{../../plugins/maven-release-plugin/}release}} process, a version of <<x.y-SNAPSHOT>> changes to
- <<x.y>>. The release process also increments the development version to <<x.(y+1)-SNAPSHOT>>.
- For example, version <<1.0-SNAPSHOT>> is released as version <<1.0>>, and the new development version is
- version <<1.1-SNAPSHOT>>.
-
-* How do I use plugins?
-
- Whenever you want to customise the build for a Maven project, this is done by adding or reconfiguring plugins.
-
- For this example, we will configure the Java compiler to allow JDK 5.0 sources. This is as simple as
- adding this to your POM:
-
-+----+
-...
-<build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-compiler-plugin</artifactId>
- <version>3.3</version>
- <configuration>
- <source>1.5</source>
- <target>1.5</target>
- </configuration>
- </plugin>
- </plugins>
-</build>
-...
-+----+
-
- You'll notice that all plugins in Maven look much like a dependency - and in some ways they are.
- This plugin will be automatically downloaded and used - including a specific version if you request it
- (the default is to use the latest available).
-
- The <<<configuration>>> element applies the given parameters to every goal from the compiler plugin.
- In the above case, the compiler plugin is already used as part of the build process and this just changes the
- configuration. It is also possible to add new goals to the process, and configure specific goals. For information on
- this, see the {{{../introduction/introduction-to-the-lifecycle.html} Introduction to the Build Lifecycle}}.
-
- To find out what configuration is available for a plugin, you can see the {{{../../plugins/} Plugins List}} and navigate
- to the plugin and goal you are using. For general information about how to configure the available parameters of a
- plugin, have a look at the {{{../mini/guide-configuring-plugins.html}Guide to Configuring Plugins}}.
-
-* How do I add resources to my JAR?
-
- Another common use case that can be satisfied which requires no changes to the POM that we have
- above is packaging resources in the JAR file. For this common task, Maven again relies on the
- {{{../introduction/introduction-to-the-standard-directory-layout.html}Standard Directory Layout}}, which means by using
- standard Maven conventions you can package resources within JARs simply by placing those resources in a standard
- directory structure.
-
- You see below in our example we have added the directory <<<$\{project.basedir\}/src/main/resources>>> into which we place
- any resources we wish to package in our JAR. The simple rule employed by Maven is this: any directories or files
- placed within the <<<$\{project.basedir\}/src/main/resources>>> directory are packaged in your JAR with the exact same
- structure starting at the base of the JAR.
-
-----
-my-app
-|-- pom.xml
-`-- src
- |-- main
- | |-- java
- | | `-- com
- | | `-- mycompany
- | | `-- app
- | | `-- App.java
- | `-- resources
- | `-- META-INF
- | `-- application.properties
- `-- test
- `-- java
- `-- com
- `-- mycompany
- `-- app
- `-- AppTest.java
-----
-
- So you can see in our example that we have a <<<META-INF>>> directory with an <<<application.properties>>> file
- within that directory. If you unpacked the JAR that Maven created for you and took a look at it you would
- see the following:
-
-----
-|-- META-INF
-| |-- MANIFEST.MF
-| `-- application.properties
-| `-- maven
-| `-- com.mycompany.app
-| `-- my-app
-| |-- pom.properties
-| `-- pom.xml
-`-- com
- `-- mycompany
- `-- app
- `-- App.class
-----
-
- As you can see, the contents of <<<$\{project.basedir\}/src/main/resources>>> can be found starting at the base of the
- JAR and our <<<application.properties>>> file is there in the <<<META-INF>>> directory. You will also notice some other files there
- like <<<META-INF/MANIFEST.MF>>> as well as a <<<pom.xml>>> and <<<pom.properties>>> file. These come standard with
- generation of a JAR in Maven. You can create your own manifest if you choose, but Maven will generate one by
- default if you don't. (You can also modify the entries in the default manifest. We will touch on this
- later.) The <<<pom.xml>>> and <<<pom.properties>>> files are packaged up in the JAR so that each artifact
- produced by Maven is self-describing and also allows you to utilize the metadata in your own application
- if the need arises. One simple use might be to retrieve the version of your application. Operating on the POM
- file would require you to use some Maven utilities but the properties can be utilized using the standard
- Java API and look like the following:
-
-----
-#Generated by Maven
-#Tue Oct 04 15:43:21 GMT-05:00 2005
-version=1.0-SNAPSHOT
-groupId=com.mycompany.app
-artifactId=my-app
-----
-
- To add resources to the classpath for your unit tests, you follow the same pattern as you do for adding resources to the JAR
- except the directory you place resources in is <<<$\{project.basedir\}/src/test/resources>>>. At this point you would have a
- project directory structure that would look like the following:
-
------
-my-app
-|-- pom.xml
-`-- src
- |-- main
- | |-- java
- | | `-- com
- | | `-- mycompany
- | | `-- app
- | | `-- App.java
- | `-- resources
- | `-- META-INF
- | |-- application.properties
- `-- test
- |-- java
- | `-- com
- | `-- mycompany
- | `-- app
- | `-- AppTest.java
- `-- resources
- `-- test.properties
------
-
- In a unit test you could use a simple snippet of code like the following to access the resource required for
- testing:
-
-+----+
-...
-
-// Retrieve resource
-InputStream is = getClass().getResourceAsStream( "/test.properties" );
-
-// Do something with the resource
-
-...
-+----+
-
-* How do I filter resource files?
-
- Sometimes a resource file will need to contain a value that can only be supplied at build time. To accomplish this in
- Maven, put a reference to the property that will contain the value into your resource file using the syntax <<<$\{<property name>\}>>>.
- The property can be one of the values defined in your <<<pom.xml>>>, a value defined in the user's <<<settings.xml>>>, a property
- defined in an external properties file, or a system property.
-
- To have Maven filter resources when copying, simply set <<<filtering>>> to true for the resource directory in your <<<pom.xml>>>:
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1.0-SNAPSHOT</version>
- <packaging>jar</packaging>
-
- <name>Maven Quick Start Archetype</name>
- <url>http://maven.apache.org</url>
-
- <dependencies>
- <dependency>
- <groupId>junit</groupId>
- <artifactId>junit</artifactId>
- <version>4.11</version>
- <scope>test</scope>
- </dependency>
- </dependencies>
-
- <build>
- <resources>
- <resource>
- <directory>src/main/resources</directory>
- <filtering>true</filtering>
- </resource>
- </resources>
- </build>
-</project>
-+----+
-
- You'll notice that we had to add the <<<build>>>, <<<resources>>>, and <<<resource>>> elements which weren't there before.
- In addition, we had to explicitly state that the resources are located in the <<<src/main/resources>>> directory. All of this
- information was provided as default values previously, but because the default value for <<<filtering>>> is false, we had
- to add this to our <<<pom.xml>>> in order to override that default value and set <<<filtering>>> to true.
-
- To reference a property defined in your <<<pom.xml>>>, the property name uses the names of the XML elements that define the value,
- with "pom" being allowed as an alias for the project (root) element. So <<<$\{project.name\}>>> refers to the name of the project,
- <<<$\{project.version\}>>> refers to the version of the project, <<<$\{project.build.finalName\}>>> refers to the final name of the file created
- when the built project is packaged, etc. Note that some elements of the POM have default values, so don't need to be explicitly
- defined in your <<<pom.xml>>> for the values to be available here. Similarly, values in the user's <<<settings.xml>>> can be referenced
- using property names beginning with "settings" (for example, <<<$\{settings.localRepository\}>>> refers to the path of the user's
- local repository).
-
- To continue our example, let's add a couple of properties to the <<<application.properties>>> file (which we put in the
- <<<src/main/resources>>> directory) whose values will be supplied when the resource is filtered:
-
-------
-# application.properties
-application.name=${project.name}
-application.version=${project.version}
-------
-
- With that in place, you can execute the following command (process-resources is the build lifecycle phase where the resources are
- copied and filtered):
-
-------
-mvn process-resources
-------
-
- and the <<<application.properties>>> file under <<<target/classes>>> (and will eventually go into the jar) looks like this:
-
-------
-# application.properties
-application.name=Maven Quick Start Archetype
-application.version=1.0-SNAPSHOT
-------
-
- To reference a property defined in an external file, all you need to do is add a reference to this external file in your <<<pom.xml>>>.
- First, let's create our external properties file and call it <<<src/main/filters/filter.properties>>>:
-
-------
-# filter.properties
-my.filter.value=hello!
-------
-
- Next, we'll add a reference to this new file in the <<<pom.xml>>>:
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1.0-SNAPSHOT</version>
- <packaging>jar</packaging>
-
- <name>Maven Quick Start Archetype</name>
- <url>http://maven.apache.org</url>
-
- <dependencies>
- <dependency>
- <groupId>junit</groupId>
- <artifactId>junit</artifactId>
- <version>4.11</version>
- <scope>test</scope>
- </dependency>
- </dependencies>
-
- <build>
- <filters>
- <filter>src/main/filters/filter.properties</filter>
- </filters>
- <resources>
- <resource>
- <directory>src/main/resources</directory>
- <filtering>true</filtering>
- </resource>
- </resources>
- </build>
-</project>
-+----+
-
- Then, if we add a reference to this property in the <<<application.properties>>> file:
-
-------
-# application.properties
-application.name=${project.name}
-application.version=${project.version}
-message=${my.filter.value}
-------
-
- the next execution of the <<<mvn process-resources>>> command will put our new property value into <<<application.properties>>>.
- As an alternative to defining the my.filter.value property in an external file, you could also have defined it in the <<<properties>>>
- section of your <<<pom.xml>>> and you'd get the same effect (notice I don't need the references to <<<src/main/filters/filter.properties>>> either):
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1.0-SNAPSHOT</version>
- <packaging>jar</packaging>
-
- <name>Maven Quick Start Archetype</name>
- <url>http://maven.apache.org</url>
-
- <dependencies>
- <dependency>
- <groupId>junit</groupId>
- <artifactId>junit</artifactId>
- <version>4.11</version>
- <scope>test</scope>
- </dependency>
- </dependencies>
-
- <build>
- <resources>
- <resource>
- <directory>src/main/resources</directory>
- <filtering>true</filtering>
- </resource>
- </resources>
- </build>
-
- <properties>
- <my.filter.value>hello</my.filter.value>
- </properties>
-</project>
-+----+
-
- Filtering resources can also get values from system properties; either the system properties built into Java (like <<<java.version>>> or
- <<<user.home>>>) or properties defined on the command line using the standard Java -D parameter. To continue the example, let's change
- our <<<application.properties>>> file to look like this:
-
-------
-# application.properties
-java.version=${java.version}
-command.line.prop=${command.line.prop}
-------
-
- Now, when you execute the following command (note the definition of the command.line.prop property on the command line), the
- <<<application.properties>>> file will contain the values from the system properties.
-
-------
-mvn process-resources "-Dcommand.line.prop=hello again"
-------
-
-
-* How do I use external dependencies?
-
- You've probably already noticed a <<<dependencies>>> element in the POM we've been using as an example.
- You have, in fact, been using an external dependency all this time, but here we'll talk about how this
- works in a bit more detail. For a more thorough introduction, please refer to our
- {{{../introduction/introduction-to-dependency-mechanism.html}Introduction to Dependency Mechanism}}.
-
- The <<<dependencies>>> section of the <<<pom.xml>>> lists all of the external dependencies that our project needs
- in order to build (whether it needs that dependency at compile time, test time, run time, or whatever). Right
- now, our project is depending on JUnit only (I took out all of the resource filtering stuff for clarity):
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1.0-SNAPSHOT</version>
- <packaging>jar</packaging>
-
- <name>Maven Quick Start Archetype</name>
- <url>http://maven.apache.org</url>
-
- <dependencies>
- <dependency>
- <groupId>junit</groupId>
- <artifactId>junit</artifactId>
- <version>4.11</version>
- <scope>test</scope>
- </dependency>
- </dependencies>
-</project>
-+----+
-
- For each external dependency, you'll need to define at least 4 things: groupId, artifactId, version, and scope. The groupId,
- artifactId, and version are the same as those given in the <<<pom.xml>>> for the project that built that dependency. The scope
- element indicates how your project uses that dependency, and can be values like <<<compile>>>, <<<test>>>, and <<<runtime>>>.
- For more information on everything you can specify for a dependency, see the {{{/ref/current/maven-model/maven.html}Project Descriptor Reference}}.
- ~~DJ: Does this link work? I can't find the document.
- For more information about the dependency mechanism as a whole, see
- {{{../introduction/introduction-to-dependency-mechanism.html}Introduction to Dependency Mechanism}}.
-
- With this information about a dependency, Maven will be able to reference the dependency when it builds the project. Where does
- Maven reference the dependency from? Maven looks in your local repository (<<<$\{user.home\}/.m2/repository>>> is the default location) to find
- all dependencies. In a {{{How_do_I_create_a_JAR_and_install_it_in_my_local_repository}previous section}}, we installed the artifact
- from our project (my-app-1.0-SNAPSHOT.jar) into the local repository. Once it's installed there, another project can reference that jar
- as a dependency simply by adding the dependency information to its <<<pom.xml>>>:
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-other-app</artifactId>
- ...
- <dependencies>
- ...
- <dependency>
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1.0-SNAPSHOT</version>
- <scope>compile</scope>
- </dependency>
- </dependencies>
-</project>
-+----+
-
- What about dependencies built somewhere else? How do they get into my local repository? Whenever a project references a dependency
- that isn't available in the local repository, Maven will download the dependency from a remote repository into the local repository. You
- probably noticed Maven downloading a lot of things when you built your very first project (these downloads were dependencies for the
- various plugins used to build the project). By default, the remote repository Maven uses can be found (and browsed) at
- {{https://repo.maven.apache.org/maven2/}}. You can also set up your own remote repository (maybe a central repository for your company) to
- use instead of or in addition to the default remote repository. For more information on repositories you can refer to the
- {{{../introduction/introduction-to-repositories.html}Introduction to Repositories}}.
-
- Let's add another dependency to our project. Let's say we've added some logging to the code and need to add log4j as a dependency.
- First, we need to know what the groupId, artifactId, and version are for log4j. The appropriate directory on Maven Central is called
- {{{https://repo.maven.apache.org/maven2/log4j/log4j/}/maven2/log4j/log4j}}. In that directory is a file called maven-metadata.xml. Here's what the maven-metadata.xml for
- log4j looks like:
-
-+----+
-<metadata>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.1.3</version>
- <versioning>
- <versions>
- <version>1.1.3</version>
- <version>1.2.4</version>
- <version>1.2.5</version>
- <version>1.2.6</version>
- <version>1.2.7</version>
- <version>1.2.8</version>
- <version>1.2.11</version>
- <version>1.2.9</version>
- <version>1.2.12</version>
- </versions>
- </versioning>
-</metadata>
-+----+
-
- From this file, we can see that the groupId we want is "log4j" and the artifactId is "log4j". We see lots of different version values
- to choose from; for now, we'll just use the latest version, 1.2.12 (some maven-metadata.xml files may also specify which version is
- the current release version: see {{{/ref/current/maven-repository-metadata/repository-metadata.html}repository metadata reference}}).
- Alongside the maven-metadata.xml file, we can see a directory corresponding to each version of the
- log4j library. Inside each of these, we'll find the actual jar file (e.g. log4j-1.2.12.jar) as well as a pom file (this is the <<<pom.xml>>>
- for the dependency, indicating any further dependencies it might have and other information) and another maven-metadata.xml file.
- There's also an md5 file corresponding to each of these, which contains an MD5 hash for these files. You can use this to authenticate
- the library or to figure out which version of a particular library you may be using already.
-
- Now that we know the information we need, we can add the dependency to our pom.xml:
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1.0-SNAPSHOT</version>
- <packaging>jar</packaging>
-
- <name>Maven Quick Start Archetype</name>
- <url>http://maven.apache.org</url>
-
- <dependencies>
- <dependency>
- <groupId>junit</groupId>
- <artifactId>junit</artifactId>
- <version>4.11</version>
- <scope>test</scope>
- </dependency>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.12</version>
- <scope>compile</scope>
- </dependency>
- </dependencies>
-</project>
-+----+
-
- Now, when we compile the project (<<<mvn compile>>>), we'll see Maven download the log4j dependency for us.
-
-~~DJ: Current
-
-* How do I deploy my jar in my remote repository?
-
- For deploying jars to an external repository, you have to configure the repository url in the <<<pom.xml>>>
- and the authentication information for connecting to the repository in the <<<settings.xml>>>.
-
- Here is an example using scp and username/password authentication:
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1.0-SNAPSHOT</version>
- <packaging>jar</packaging>
-
- <name>Maven Quick Start Archetype</name>
- <url>http://maven.apache.org</url>
-
- <dependencies>
- <dependency>
- <groupId>junit</groupId>
- <artifactId>junit</artifactId>
- <version>4.11</version>
- <scope>test</scope>
- </dependency>
- <dependency>
- <groupId>org.apache.codehaus.plexus</groupId>
- <artifactId>plexus-utils</artifactId>
- <version>1.0.4</version>
- </dependency>
- </dependencies>
-
- <build>
- <filters>
- <filter>src/main/filters/filters.properties</filter>
- </filters>
- <resources>
- <resource>
- <directory>src/main/resources</directory>
- <filtering>true</filtering>
- </resource>
- </resources>
- </build>
- <!--
- |
- |
- |
- -->
- <distributionManagement>
- <repository>
- <id>mycompany-repository</id>
- <name>MyCompany Repository</name>
- <url>scp://repository.mycompany.com/repository/maven2</url>
- </repository>
- </distributionManagement>
-</project>
-+----+
-
-+----+
-<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
- ...
- <servers>
- <server>
- <id>mycompany-repository</id>
- <username>jvanzyl</username>
- <!-- Default value is ~/.ssh/id_dsa -->
- <privateKey>/path/to/identity</privateKey> (default is ~/.ssh/id_dsa)
- <passphrase>my_key_passphrase</passphrase>
- </server>
- </servers>
- ...
-</settings>
-+----+
-
- Note that if you are connecting to an openssh ssh server which has the parameter "PasswordAuthentication" set to "no"
- in the sshd_config, you will have to type your password each time for username/password authentication
- (although you can log in using another ssh client by typing in the username and password).
- You might want to switch to public key authentication in this case.
-
- Care should be taken if using passwords in <<<settings.xml>>>. For more information, see {{{../mini/guide-encryption.html} Password Encryption}}.
-
-* How do I create documentation?
-
- To get you jump started with Maven's documentation system you can use the archetype mechanism to generate a site
- for your existing project using the following command:
-
-------
-mvn archetype:generate \
- -DarchetypeGroupId=org.apache.maven.archetypes \
- -DarchetypeArtifactId=maven-archetype-site \
- -DgroupId=com.mycompany.app \
- -DartifactId=my-app-site
-------
-
- Now head on over to the {{{../mini/guide-site.html}Guide to creating a site}}
- to learn how to create the documentation for your project.
-
-* How do I build other types of projects?
-
- Note that the lifecycle applies to any project type. For example, back in the base directory we can create a
- simple web application:
-
-------
-mvn archetype:generate \
- -DarchetypeGroupId=org.apache.maven.archetypes \
- -DarchetypeArtifactId=maven-archetype-webapp \
- -DgroupId=com.mycompany.app \
- -DartifactId=my-webapp
-------
-
- Note that these must all be on a single line. This will create a directory called
- <<<my-webapp>>> containing the following project descriptor:
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-webapp</artifactId>
- <version>1.0-SNAPSHOT</version>
- <packaging>war</packaging>
-
- <dependencies>
- <dependency>
- <groupId>junit</groupId>
- <artifactId>junit</artifactId>
- <version>4.11</version>
- <scope>test</scope>
- </dependency>
- </dependencies>
-
- <build>
- <finalName>my-webapp</finalName>
- </build>
-</project>
-+----+
-
- Note the <<<\<packaging\>>>> element - this tells Maven to build as a WAR. Change into the webapp project's directory
- and try:
-
-------
-mvn package
-------
-
- You'll see <<<target/my-webapp.war>>> is built, and that all the normal steps were executed.
-
-* How do I build more than one project at once?
-
- The concept of dealing with multiple modules is built in to Maven.
- In this section, we will show how to build the WAR above, and include the previous JAR as well in one step.
-
- Firstly, we need to add a parent <<<pom.xml>>> file in the directory above the other two, so it should look like this:
-
-----
-+- pom.xml
-+- my-app
-| +- pom.xml
-| +- src
-| +- main
-| +- java
-+- my-webapp
-| +- pom.xml
-| +- src
-| +- main
-| +- webapp
-----
-
- The POM file you'll create should contain the following:
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>app</artifactId>
- <version>1.0-SNAPSHOT</version>
- <packaging>pom</packaging>
-
- <modules>
- <module>my-app</module>
- <module>my-webapp</module>
- </modules>
-</project>
-+----+
-
- We'll need a dependency on the JAR from the webapp, so add this to <<<my-webapp/pom.xml>>>:
-
-+----+
- ...
- <dependencies>
- <dependency>
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1.0-SNAPSHOT</version>
- </dependency>
- ...
- </dependencies>
-+----+
-
- Finally, add the following <<<\<parent\>>>> element to both of the other <<<pom.xml>>> files in the subdirectories:
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
- <parent>
- <groupId>com.mycompany.app</groupId>
- <artifactId>app</artifactId>
- <version>1.0-SNAPSHOT</version>
- </parent>
- ...
-+----+
-
- Now, try it... from the top level directory, run:
-
-------
-mvn verify
-------
-
- The WAR has now been created in <<<my-webapp/target/my-webapp.war>>>, and the JAR is included:
-
-----
-$ jar tvf my-webapp/target/my-webapp-1.0-SNAPSHOT.war
- 0 Fri Jun 24 10:59:56 EST 2005 META-INF/
- 222 Fri Jun 24 10:59:54 EST 2005 META-INF/MANIFEST.MF
- 0 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/
- 0 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/
- 0 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/my-webapp/
-3239 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/my-webapp/pom.xml
- 0 Fri Jun 24 10:59:56 EST 2005 WEB-INF/
- 215 Fri Jun 24 10:59:56 EST 2005 WEB-INF/web.xml
- 123 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/my-webapp/pom.properties
- 52 Fri Jun 24 10:59:56 EST 2005 index.jsp
- 0 Fri Jun 24 10:59:56 EST 2005 WEB-INF/lib/
-2713 Fri Jun 24 10:59:56 EST 2005 WEB-INF/lib/my-app-1.0-SNAPSHOT.jar
-----
-
- How does this work? Firstly, the parent POM created (called <<<app>>>), has a packaging of <<<pom>>>
- and a list of modules defined. This tells Maven to run all operations over the set of projects instead of
- just the current one (to override this behaviour, you can use the <<<--non-recursive>>> command line option).
-
- Next, we tell the WAR that it requires the <<<my-app>>> JAR. This does a few things: it makes it available
- on the classpath to any code in the WAR (none in this case), it makes sure the JAR is always built before the
- WAR, and it indicates to the WAR plugin to include the JAR in its library directory.
-
- You may have noticed that <<<junit-4.11.jar>>> was a dependency, but didn't end up in the WAR. The
- reason for this is the <<<\<scope\>test\</scope\>>>> element - it is only required for testing,
- and so is not included in the web application as the compile time dependency <<<my-app>>> is.
-
- The final step was to include a parent definition.
- This ensures that the POM can always be located even if the project
- is distributed separately from its parent by looking it up in the repository.
diff --git a/content/apt/guides/getting-started/maven-in-five-minutes.apt b/content/apt/guides/getting-started/maven-in-five-minutes.apt
deleted file mode 100644
index 55439c6a..00000000
--- a/content/apt/guides/getting-started/maven-in-five-minutes.apt
+++ /dev/null
@@ -1,321 +0,0 @@
- ----
- Maven in 5 Minutes
- -----
- Eric Redmond
- -----
- 2008-01-01
- -----
-
-~~ 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 in 5 Minutes
-
-* Prerequisites
-
- You must understand how to install software on your computer.
- If you do not know how to do this, please ask someone at your office, school, etc.
- or pay someone to explain this to you. The Maven mailing lists are not the best place to ask for this advice.
-
-* Installation
-
- <Maven is a Java tool, so you must have {{{https://www.oracle.com/technetwork/java/javase/downloads/index.html}Java}}
- installed in order to proceed.>
-
- First, {{{../../download.html}download Maven}} and follow the {{{../../install.html}installation instructions}}.
- After that, type the following in a terminal or in a command prompt:
-
------
-mvn --version
------
-
- It should print out your installed version of Maven, for example:
-
------
-Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f)
-Maven home: D:\apache-maven-3.6.3\apache-maven\bin\..
-Java version: 1.8.0_232, vendor: AdoptOpenJDK, runtime: C:\Program Files\AdoptOpenJDK\jdk-8.0.232.09-hotspot\jre
-Default locale: en_US, platform encoding: Cp1250
-OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"
------
-
- Depending upon your network setup, you may require extra configuration. Check out the
- {{{../mini/guide-configuring-maven.html}Guide to Configuring Maven}} if necessary.
-
- <<If you are using Windows, you should look at>> {{{./windows-prerequisites.html}Windows Prerequisites}}
- <<to ensure that you are prepared to use Maven on Windows.>>
-
-* Creating a Project
-
- You need somewhere for your project to reside. Create a directory somewhere and start a shell in that directory.
- On your command line, execute the following Maven goal:
-
------
-mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.5 -DinteractiveMode=false
------
-
- <If you have just installed Maven, it may take a while on the first run. This is because Maven is downloading
- the most recent artifacts (plugin jars and other files) into your local repository. You may also need to
- execute the command a couple of times before it succeeds. This is because the remote server may time out before
- your downloads are complete. Don't worry, there are ways to fix that.>
-
- You will notice that the <generate> goal created a directory with the same name given as the
- artifactId. Change into that directory.
-
------
-cd my-app
------
-
- Under this directory you will notice the following
- {{{../introduction/introduction-to-the-standard-directory-layout.html}standard project structure}}.
-
------
-my-app
-|-- pom.xml
-`-- src
- |-- main
- | `-- java
- | `-- com
- | `-- mycompany
- | `-- app
- | `-- App.java
- `-- test
- `-- java
- `-- com
- `-- mycompany
- `-- app
- `-- AppTest.java
------
-
- The <<<src/main/java>>> directory contains the project source code, the <<<src/test/java>>> directory contains
- the test source, and the <<<pom.xml>>> file is the project's Project Object Model, or POM.
-
-** The POM
-
- The <<<pom.xml>>> file is the core of a project's configuration in Maven. It is a single configuration
- file that contains the majority of information required to build a project in just the way you want.
- The POM is huge and can be daunting in its complexity, but it is not necessary to understand all
- of the intricacies just yet to use it effectively. This project's POM should look like this:
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1.0-SNAPSHOT</version>
-
- <name>my-app</name>
- <!-- FIXME change it to the project's website -->
- <url>http://www.example.com</url>
-
- <properties>
- <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
- <maven.compiler.release>17</maven.compiler.release>
- </properties>
-
- <dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>org.junit</groupId>
- <artifactId>junit-bom</artifactId>
- <version>5.11.0</version>
- <type>pom</type>
- <scope>import</scope>
- </dependency>
- </dependencies>
- </dependencyManagement>
-
- <dependencies>
- <dependency>
- <groupId>org.junit.jupiter</groupId>
- <artifactId>junit-jupiter-api</artifactId>
- <scope>test</scope>
- </dependency>
- <!-- Optionally: parameterized tests support -->
- <dependency>
- <groupId>org.junit.jupiter</groupId>
- <artifactId>junit-jupiter-params</artifactId>
- <scope>test</scope>
- </dependency>
- </dependencies>
-
- <build>
- <pluginManagement><!-- lock down plugins versions to avoid using Maven defaults (may be moved to parent pom) -->
- ... lots of helpful plugins
- </pluginManagement>
- </build>
-</project>
-+-----+
-
-** What did I just do?
-
- You executed the Maven goal <archetype:generate>, and passed in various parameters to that goal.
- The prefix <archetype> is the {{{../../plugins/index.html}plugin}} that provides the goal. If you are familiar with
- {{{http://ant.apache.org}Ant}}, you
- may conceive of this as similar to a task. This <archetype:generate> goal created a simple project based upon
- a {{{/archetypes/maven-archetype-quickstart/}maven-archetype-quickstart}} archetype.
- Suffice it to say for now that a <plugin> is a collection
- of <goals> with a general common purpose. For example the jboss-maven-plugin, whose purpose is "deal with
- various jboss items".
-
-** Build the Project
-
------
-mvn package
------
-
- The command line will print out various actions, and end with the following:
-
------
- ...
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD SUCCESS
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 2.953 s
-[INFO] Finished at: 2019-11-24T13:05:10+01:00
-[INFO] ------------------------------------------------------------------------
------
-
- Unlike the first command executed (<archetype:generate>), the second is simply
- a single word - <package>. Rather than a <goal>, this is a <phase>. A phase is a step in the
- {{{../introduction/introduction-to-the-lifecycle.html}build lifecycle}}, which is an ordered
- sequence of phases. When a phase is given, Maven executes every phase in the sequence
- up to and including the one defined. For example, if you execute the <compile> phase, the
- phases that actually get executed are:
-
- [[1]] validate
-
- [[2]] generate-sources
-
- [[3]] process-sources
-
- [[4]] generate-resources
-
- [[5]] process-resources
-
- [[6]] compile
-
- []
-
- You may test the newly compiled and packaged JAR with the following command:
-
------
-java -cp target/my-app-1.0-SNAPSHOT.jar com.mycompany.app.App
------
-
- Which will print the quintessential:
-
------
-Hello World!
------
-
-* Java 9 or later
-
- By default your version of Maven might use an old version of the <<<maven-compiler-plugin>>>
- that is not compatible with Java 9 or later versions. To target Java 9 or later,
- you should at least use version 3.6.0 of the <<<maven-compiler-plugin>>> and set the
- <<<maven.compiler.release>>> property to the Java release you are targetting (e.g. 9, 10, 11, 12, etc.).
-
- In the following example, we have configured our Maven project to use version 3.8.1 of <<<maven-compiler-plugin>>>
- and target Java 11:
-
-+-----+
- <properties>
- <maven.compiler.release>11</maven.compiler.release>
- </properties>
-
- <build>
- <pluginManagement>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-compiler-plugin</artifactId>
- <version>3.8.1</version>
- </plugin>
- </plugins>
- </pluginManagement>
- </build>
-+-----+
-
- To learn more about <<<javac>>>'s <<<--release>>> option, see {{{https://openjdk.java.net/jeps/247}JEP 247}}.
-
-* Running Maven Tools
-
-** Maven Phases
-
- Although hardly a comprehensive list, these are the most common <default> lifecycle phases executed.
-
- * <<validate>>: validate the project is correct and all necessary information is available
-
- * <<compile>>: compile the source code of the project
-
- * <<test>>: test the compiled source code using a suitable unit testing framework. These tests should not require the code be packaged or deployed
-
- * <<package>>: take the compiled code and package it in its distributable format, such as a JAR.
-
- * <<integration-test>>: process and deploy the package if necessary into an environment where integration tests can be run
-
- * <<verify>>: run any checks to verify the package is valid and meets quality criteria
-
- * <<install>>: install the package into the local repository, for use as a dependency in other projects locally
-
- * <<deploy>>: done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects.
-
- []
-
- There are two other Maven lifecycles of note beyond the <default> list above. They are
-
- * <<clean>>: cleans up artifacts created by prior builds
-
- []
-
- * <<site>>: generates site documentation for this project
-
- []
-
- Phases are actually mapped to underlying goals. The specific goals executed per phase is dependant upon the
- packaging type of the project. For example, <package> executes <jar:jar> if the project type is a JAR, and
- <war:war> if the project type is - you guessed it - a WAR.
-
- An interesting thing to note is that phases and goals may be executed in sequence.
-
------
-mvn clean dependency:copy-dependencies package
------
-
- This command will clean the project, copy dependencies, and package the project (executing all phases up to
- <package>, of course).
-
-** Generating the Site
-
------
-mvn site
------
-
- This phase generates a site based upon information on the project's pom. You can look at the
- documentation generated under <<<target/site>>>.
-
-* Conclusion
-
- We hope this quick overview has piqued your interest in the versatility of Maven. Note that this is a very
- truncated quick-start guide. Now you are ready for more comprehensive details concerning
- the actions you have just performed. Check out the {{{./index.html}Maven Getting Started Guide}}.
diff --git a/content/apt/guides/getting-started/windows-prerequisites.apt b/content/apt/guides/getting-started/windows-prerequisites.apt
deleted file mode 100644
index 8fd7640b..00000000
--- a/content/apt/guides/getting-started/windows-prerequisites.apt
+++ /dev/null
@@ -1,66 +0,0 @@
- ----
- Maven on Windows
- -----
- Benson Margulies
- -----
- 2012-07-01
- -----
-
-~~ 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 on Windows
-
- Maven is a command-line tool for building Java (and other) programs. The Maven project provides a simple ZIP
- file containing a precompiled version of Maven for your convenience. There is no installer. It's up to you
- to set up your prerequisites and environment to run Maven on Windows.
-
-
-* Prerequisites
-
- Maven is written in Java (and primarily used to build Java programs). Thus, the major prerequisite is the Java SDK.
- You need to install the Java SDK (e.g. from {{{https://www.oracle.com/technetwork/java/javase/downloads/index.html}Oracle's download site}}).
-
- Once Java is installed, you must ensure that the commands from the Java SDK are in your PATH environment variable.
- Running, for example,
-
--------
-java -version
--------
-
- must show the right version number.
-
-* Maven Unpacked
-
- You need to unpack the Maven distribution. Don't unpack it in the middle of your source code; pick some location
- and unpack it there. Let's assume that the path is <<<$\{maven.home\}>>>.
-
-* Maven in PATH
-
- You run Maven by invoking a command-line tool: <<<mvn.cmd>>> from the <<<bin>>> directory of the Maven. To do this conveniently,
- <<<$\{maven.home\}\bin>>> must be in your PATH, just like the Java SDK commands. You can add directories to your <<<PATH>>>
- in the control panel; the details vary by Windows version.
-
-* Firewalls and Anti-virus
-
- Firewall and Anti-virus sometimes prevent Java from running properly, or Windows Firewall (and various other Firewalls) actively
- prevent Java.exe from reaching out to the Internet to "download stuff" which is a key part of Maven.
- You may need to configure the Firewall or Anti-virus to add exceptions to allow such actions.
-
diff --git a/content/apt/guides/introduction/introduction-to-archetypes.apt b/content/apt/guides/introduction/introduction-to-archetypes.apt
deleted file mode 100644
index 394a5540..00000000
--- a/content/apt/guides/introduction/introduction-to-archetypes.apt
+++ /dev/null
@@ -1,100 +0,0 @@
- ------
- Introduction to Archetypes
- ------
- Jason van Zyl
- ------
- 2009-08-26
- ------
-
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
-
-Introduction to Archetypes
-
-What is Archetype?
-
- In short, Archetype is a Maven project templating toolkit. An archetype is defined as <an original pattern or model
- from which all other things of the same kind are made>. The name fits as we are trying to provide a system that
- provides a consistent means of generating Maven projects. Archetype will help authors create
- Maven project templates for users, and provides users with the means to generate parameterized versions
- of those project templates.
-
- Using archetypes provides a great way to enable developers work quickly in a way consistent with best practices employed
- by your project or organization. Within the Maven project, we use archetypes to try and get our users up and running
- as quickly as possible by providing a sample project that demonstrates many of the features of Maven, while introducing
- new users to the best practices employed by Maven. In a matter of seconds, a new user can have a working Maven project
- to use as a jumping board for investigating more of the features in Maven. We have also tried to make the Archetype
- mechanism additive, and by that we mean allowing portions of a project to be captured in an archetype so that pieces
- or aspects of a project can be added to existing projects. A good example of this is the Maven site archetype.
- If, for example, you have used the quick start archetype to generate a working project, you can then quickly
- create a site for that project by using the site archetype within that existing project. You can do anything like
- this with archetypes.
-
- You may want to standardize J2EE development within your organization, so you may want to provide archetypes
- for EJBs, or WARs, or for your web services. Once these archetypes are created and deployed in your organization's
- repository, they are available for use by all developers within your organization.
-
-* Using an Archetype
-
- To create a new project based on an Archetype, you need to call <<<mvn archetype:generate>>> goal, like the following:
-
------
-mvn archetype:generate
------
-
- Please refer to {{{/archetype/maven-archetype-plugin/}Archetype Plugin page}}.
-
-* Provided Archetypes
-
- Maven provides several Archetype artifacts:
-
-*-----------------------------+----------------+
-|| Archetype ArtifactIds || Description ||
-*-----------------------------+----------------+
-| maven-archetype-archetype | An archetype to generate a sample archetype project. |
-*-----------------------------+----------------+
-| maven-archetype-j2ee-simple | An archetype to generate a simplifed sample J2EE application. |
-*-----------------------------+----------------+
-| maven-archetype-plugin | An archetype to generate a sample Maven plugin. |
-*-----------------------------+----------------+
-| maven-archetype-plugin-site | An archetype to generate a sample Maven plugin site. |
-*-----------------------------+----------------+
-| maven-archetype-portlet | An archetype to generate a sample JSR-268 Portlet. |
-*-----------------------------+----------------+
-| maven-archetype-quickstart | An archetype to generate a sample Maven project. |
-*-----------------------------+----------------+
-| maven-archetype-simple | An archetype to generate a simple Maven project. |
-*-----------------------------+----------------+
-| maven-archetype-site | An archetype to generate a sample Maven site which demonstrates some of the supported document types like APT, XDoc, and FML and demonstrates how to i18n your site. |
-*-----------------------------+----------------+
-| maven-archetype-site-simple | An archetype to generate a sample Maven site. |
-*-----------------------------+----------------+
-| maven-archetype-webapp | An archetype to generate a sample Maven Webapp project. |
-*-----------------------------+----------------+
-
- For more information on these archetypes, please refer to the {{{/archetypes/index.html}Maven Archetype Bundles page}}.
-
-* What makes up an Archetype?
-
- Archetypes are packaged up in a JAR and they consist of the archetype metadata which describes the contents of
- archetype, and a set of {{{http://velocity.apache.org/}Velocity}} templates which make up the prototype
- project. If you would like to know how to make your own archetypes, please refer to our
- {{{../mini/guide-creating-archetypes.html}Guide to creating archetypes}}.
-
diff --git a/content/apt/guides/introduction/introduction-to-dependency-mechanism.apt b/content/apt/guides/introduction/introduction-to-dependency-mechanism.apt
deleted file mode 100644
index cc8e263a..00000000
--- a/content/apt/guides/introduction/introduction-to-dependency-mechanism.apt
+++ /dev/null
@@ -1,909 +0,0 @@
- ------
- Introduction to the Dependency Mechanism
- ------
- Brett Porter
- Trygve Laugstol
- Karl Heinz Marbaise
- ------
- 2005-10-12
- 2016-06-17
- ------
-
-~~ 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
-
-Introduction to the Dependency Mechanism
-
- Dependency management is a core feature of Maven. Managing dependencies for a single project is easy.
- Managing dependencies for multi-module projects and applications that consist of hundreds of modules
- is possible. Maven helps a great deal in defining, creating, and maintaining reproducible builds
- with well-defined classpaths and library versions.
-
- Learn more about:
-
-%{toc|section=0|fromDepth=2|toDepth=3}
-
-
-* Transitive Dependencies
-
- Maven avoids the need to discover and
- specify the libraries that your own dependencies require by including transitive dependencies automatically.
-
- This feature is facilitated by reading the project files of your dependencies from the remote repositories
- specified. In general, all dependencies of those projects are used in your project, as are any that the
- project inherits from its parents, or from its dependencies, and so on.
-
- There is no limit to the number of levels that dependencies can be gathered from. A problem arises
- only if a cyclic dependency is discovered.
-
- With transitive dependencies, the graph of included libraries can quickly grow quite large. For this reason,
- there are additional features that limit which dependencies are included:
-
- * <Dependency mediation>
- - this determines what version of an artifact will be chosen when multiple
- versions are encountered as dependencies. Maven picks the "nearest definition". That is,
- it uses the version of the closest dependency to your project in the tree of dependencies.
- You can always guarantee a version by declaring it explicitly in your project's POM.
- Note that if two dependency versions are at the same depth in the dependency tree,
- the first declaration wins.
-
- * "nearest definition" means that the version used will be the closest one to your project in the tree of dependencies. Consider this tree of dependencies:
-
-----
- A
- ├── B
- │ └── C
- │ └── D 2.0
- └── E
- └── D 1.0
-----
-
- In text, dependencies for A, B, and C are defined as A -> B -> C -> D 2.0 and A -> E -> D 1.0,
- then D 1.0 will be used when building A because the path from A to D through E is shorter.
- You could explicitly add a dependency to D 2.0 in A to force the use of D 2.0, as shown here:
-
-----
- A
- ├── B
- │ └── C
- │ └── D 2.0
- ├── E
- │ └── D 1.0
- │
- └── D 2.0
-----
-
- * <Dependency management>
- - this allows project authors to directly specify the versions of artifacts to be used when they are encountered
- in transitive dependencies or in dependencies where no version has been specified. In the example in
- the preceding section a dependency was directly added to A even though it is not directly used by A. Instead,
- A can include D as a dependency in its dependencyManagement section and directly control which version of
- D is used when, or if, it is ever referenced.
-
- * <Dependency scope>
- - this allows you to only include dependencies appropriate for the current stage
- of the build. This is described in more detail below.
-
- * <Excluded dependencies>
- - If project X depends on project Y, and project Y depends on project Z, the owner of project X can explicitly exclude project Z
- as a dependency, using the "exclusion" element.
-
- * <Optional dependencies>
- - If project Y depends on project Z, the owner of project Y can mark project Z
- as an optional dependency, using the "optional" element. When project X depends on project Y, X will
- depend only on Y and not on Y's optional dependency Z. The owner of project X may then
- explicitly add a dependency on Z, at her option. (It may be helpful to think of optional
- dependencies as "excluded by default.")
-
- []
-
- Although transitive dependencies can implicitly include desired dependencies, it is a good practice to explicitly
- specify the dependencies your source code uses directly. This best practice proves its value especially
- when the dependencies of your project change their dependencies.
-
- For example, assume that your project A specifies a
- dependency on another project B, and project B specifies a dependency on project C. If you are directly using components
- in project C, and you don't specify project C in your project A, it may cause build failure when project B suddenly
- updates/removes its dependency on project C.
-
- Another reason to directly specify dependencies is that it provides better
- documentation for your project: one can learn more information by just reading the POM file in your project, or by executing <<mvn dependency:tree>>.
-
- Maven also
- provides {{{/plugins/maven-dependency-plugin/analyze-mojo.html}dependency:analyze}} plugin goal
- for analyzing the dependencies: it helps making this best practice more achievable.
-
-* Dependency Scope
-
- Dependency scope is used to limit the transitivity of a dependency and to determine when a dependency is
- included in a classpath.
-
- There are 6 scopes:
-
- * <<compile>>\
- This is the default scope, used if none is specified. Compile dependencies are available
- in all classpaths of a project. Furthermore, those dependencies are propagated to dependent projects.
-
- * <<provided>>\
- This is much like <<<compile>>>, but indicates you expect the JDK or a container to provide the dependency at runtime.
- For example, when building a web application for the Java Enterprise Edition, you would set the dependency on the
- Servlet API and related Java EE APIs to scope <<<provided>>> because the web container provides those classes.
- A dependency with this scope is added to the classpath used for compilation and test, but not the
- runtime classpath. It is not transitive.
-
- * <<runtime>>\
- This scope indicates that the dependency is not required for compilation, but is for
- execution. Maven includes a dependency with this scope in the runtime and test classpaths,
- but not the compile classpath.
-
- * <<test>>\
- This scope indicates that the dependency is not required for normal use of the application, and
- is only available for the test compilation and execution phases. This scope is not transitive.
- Typically this scope is used for test libraries such as JUnit and Mockito.
- It is also used for non-test libraries such as Apache Commons IO if those libraries are used in
- unit tests (src/test/java) but not in the model code (src/main/java).
-
- * <<system>>\
- This scope indicates that the dependency is required for compilation and execution.
- However, Maven will not download the dependency from the repository system.
- Instead it looks for a jar in the local file system at a specified path.
-
- * <<import>>\
- This scope is only supported on a dependency of type <<<pom>>> in the <<<\<dependencyManagement\>>>> section. It
- indicates the dependency is to be replaced with the effective list of dependencies in the specified POM's
- <<<\<dependencyManagement\>>>> section. Since they are replaced, dependencies with a scope of <<<import>>> do not
- actually participate in limiting the transitivity of a dependency.
-
- []
-
- Each of the scopes (except for <<<import>>>) affects transitive dependencies in different ways, as is demonstrated in the table below.
- If a dependency is set to the scope in the left column, a transitive dependency of that dependency with the
- scope across the top row results in a dependency in the main project with the scope listed at the
- intersection. If no scope is listed, it means the dependency is omitted.
-
-*----------+------------+----------+----------+------+
-| | compile | provided | runtime | test
-*----------+------------+----------+----------+------+
-| compile | compile(*) | - | runtime | -
-*----------+------------+----------+----------+------+
-| provided | provided | - | provided | -
-*----------+------------+----------+----------+------+
-| runtime | runtime | - | runtime | -
-*----------+------------+----------+----------+------+
-| test | test | - | test | -
-*----------+------------+----------+----------+------+
-
- <<(*) Note:>>
- it is intended that this should be runtime scope instead, so that all compile dependencies must
- be explicitly listed. However, if a library you depend on extends a class from another
- library, both must be available at compile time. For this reason, compile time dependencies remain
- as compile scope even when they are transitive.
-
-* Dependency Management
-
- The dependency management section is a mechanism for centralizing dependency information. When you have
- a set of projects that inherit from a common parent, it's possible to put all information about the dependency
- in the common POM and have simpler references to the artifacts in the child POMs. The mechanism is best
- illustrated through some examples. Given these two POMs which extend the same parent:
-
- Project A:
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <dependencies>
- <dependency>
- <groupId>group-a</groupId>
- <artifactId>artifact-a</artifactId>
- <version>1.0</version>
- <exclusions>
- <exclusion>
- <groupId>group-c</groupId>
- <artifactId>excluded-artifact</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- <dependency>
- <groupId>group-a</groupId>
- <artifactId>artifact-b</artifactId>
- <version>1.0</version>
- <type>bar</type>
- <scope>runtime</scope>
- </dependency>
- </dependencies>
-</project>
-
-+----+
-
- Project B:
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <dependencies>
- <dependency>
- <groupId>group-c</groupId>
- <artifactId>artifact-b</artifactId>
- <version>1.0</version>
- <type>war</type>
- <scope>runtime</scope>
- </dependency>
- <dependency>
- <groupId>group-a</groupId>
- <artifactId>artifact-b</artifactId>
- <version>1.0</version>
- <type>bar</type>
- <scope>runtime</scope>
- </dependency>
- </dependencies>
-</project>
-
-+----+
-
- These two example POMs share a common dependency and each has one non-trivial dependency. This information
- can be put in the parent POM like this:
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>group-a</groupId>
- <artifactId>artifact-a</artifactId>
- <version>1.0</version>
-
- <exclusions>
- <exclusion>
- <groupId>group-c</groupId>
- <artifactId>excluded-artifact</artifactId>
- </exclusion>
- </exclusions>
-
- </dependency>
-
- <dependency>
- <groupId>group-c</groupId>
- <artifactId>artifact-b</artifactId>
- <version>1.0</version>
- <type>war</type>
- <scope>runtime</scope>
- </dependency>
-
- <dependency>
- <groupId>group-a</groupId>
- <artifactId>artifact-b</artifactId>
- <version>1.0</version>
- <type>bar</type>
- <scope>runtime</scope>
- </dependency>
- </dependencies>
- </dependencyManagement>
-</project>
-
-+----+
-
- Then the two child POMs become much simpler:
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <dependencies>
- <dependency>
- <groupId>group-a</groupId>
- <artifactId>artifact-a</artifactId>
- </dependency>
-
- <dependency>
- <groupId>group-a</groupId>
- <artifactId>artifact-b</artifactId>
- <!-- This is not a jar dependency, so we must specify type. -->
- <type>bar</type>
- </dependency>
- </dependencies>
-</project>
-
-+----+
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <dependencies>
- <dependency>
- <groupId>group-c</groupId>
- <artifactId>artifact-b</artifactId>
- <!-- This is not a jar dependency, so we must specify type. -->
- <type>war</type>
- </dependency>
-
- <dependency>
- <groupId>group-a</groupId>
- <artifactId>artifact-b</artifactId>
- <!-- This is not a jar dependency, so we must specify type. -->
- <type>bar</type>
- </dependency>
- </dependencies>
-</project>
-
-+----+
-
- <<NOTE:>> In two of these dependency references, we had to specify the \<type/\>
- element. This is because the minimal set of information for matching a dependency
- reference against a dependencyManagement section is actually
- <<\{groupId, artifactId, type, classifier\}>>. In many cases, these dependencies
- will refer to jar artifacts with no classifier. This allows us to shorthand the
- identity set to <<\{groupId, artifactId\}>>, since the default for the type field
- is <<<jar>>>, and the default classifier is null.
-
- A second, and very important use of the dependency management section is to control the versions
- of artifacts used in transitive dependencies. As an example consider these projects:
-
- Project A:
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
- <groupId>maven</groupId>
- <artifactId>A</artifactId>
- <packaging>pom</packaging>
- <name>A</name>
- <version>1.0</version>
- <dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>test</groupId>
- <artifactId>a</artifactId>
- <version>1.2</version>
- </dependency>
- <dependency>
- <groupId>test</groupId>
- <artifactId>b</artifactId>
- <version>1.0</version>
- <scope>compile</scope>
- </dependency>
- <dependency>
- <groupId>test</groupId>
- <artifactId>c</artifactId>
- <version>1.0</version>
- <scope>compile</scope>
- </dependency>
- <dependency>
- <groupId>test</groupId>
- <artifactId>d</artifactId>
- <version>1.2</version>
- </dependency>
- </dependencies>
- </dependencyManagement>
-</project>
-
-+----+
-
- Project B:
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <parent>
- <artifactId>A</artifactId>
- <groupId>maven</groupId>
- <version>1.0</version>
- </parent>
- <modelVersion>4.0.0</modelVersion>
- <groupId>maven</groupId>
- <artifactId>B</artifactId>
- <packaging>pom</packaging>
- <name>B</name>
- <version>1.0</version>
-
- <dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>test</groupId>
- <artifactId>d</artifactId>
- <version>1.0</version>
- </dependency>
- </dependencies>
- </dependencyManagement>
-
- <dependencies>
- <dependency>
- <groupId>test</groupId>
- <artifactId>a</artifactId>
- <version>1.0</version>
- <scope>runtime</scope>
- </dependency>
- <dependency>
- <groupId>test</groupId>
- <artifactId>c</artifactId>
- <scope>runtime</scope>
- </dependency>
- </dependencies>
-</project>
-
-+----+
-
- When maven is run on project B, version 1.0 of artifacts a, b, c, and d will be used regardless of
- the version specified in their POM.
-
- * a and c both are declared as dependencies of the project so version 1.0 is used due to
- dependency mediation. Both also have runtime scope since it is directly specified.
-
- * b is defined in B's parent's dependency management section and since dependency management
- takes precedence over dependency mediation for transitive dependencies, version 1.0 will be
- selected should it be referenced in a or c's POM. b will also have compile scope.
-
- * Finally, since d is specified in B's dependency management section, should d be a dependency
- (or transitive dependency) of a or c, version 1.0 will be chosen - again because dependency
- management takes precedence over dependency mediation and also because the current POM's
- declaration takes precedence over its parent's declaration.
-
- []
-
- <<NOTE:>> The dependency management won't affect the (transitive) dependencies of any <plugins>
- used in the same effective POM but only the (transitive) project dependencies.
-
- The reference information about the dependency management tags is available from the
- {{{../../ref/current/maven-model/maven.html#class_DependencyManagement}project descriptor reference}}.
-
-** Importing Dependencies
-
- The examples in the previous section describe how to specify managed dependencies through inheritance. However,
- in larger projects it may be impossible to accomplish this since a project can only inherit from a single parent.
- To accommodate this, projects can import managed dependencies from other projects. This is accomplished by declaring a
- POM artifact as a dependency with a scope of "import".
-
- Project B:
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
- <groupId>maven</groupId>
- <artifactId>B</artifactId>
- <packaging>pom</packaging>
- <name>B</name>
- <version>1.0</version>
-
- <dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>maven</groupId>
- <artifactId>A</artifactId>
- <version>1.0</version>
- <type>pom</type>
- <scope>import</scope>
- </dependency>
- <dependency>
- <groupId>test</groupId>
- <artifactId>d</artifactId>
- <version>1.0</version>
- </dependency>
- </dependencies>
- </dependencyManagement>
-
- <dependencies>
- <dependency>
- <groupId>test</groupId>
- <artifactId>a</artifactId>
- <version>1.0</version>
- <scope>runtime</scope>
- </dependency>
- <dependency>
- <groupId>test</groupId>
- <artifactId>c</artifactId>
- <scope>runtime</scope>
- </dependency>
- </dependencies>
-</project>
-
-+----+
-
- Assuming A is the POM defined in the preceding example, the end result would be the same. All of A's managed dependencies
- would be incorporated into B except for d since it is defined in this POM.
-
- Project X:
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
- <groupId>maven</groupId>
- <artifactId>X</artifactId>
- <packaging>pom</packaging>
- <name>X</name>
- <version>1.0</version>
-
- <dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>test</groupId>
- <artifactId>a</artifactId>
- <version>1.1</version>
- </dependency>
- <dependency>
- <groupId>test</groupId>
- <artifactId>b</artifactId>
- <version>1.0</version>
- <scope>compile</scope>
- </dependency>
- </dependencies>
- </dependencyManagement>
-</project>
-
-+----+
-
- Project Y:
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
- <groupId>maven</groupId>
- <artifactId>Y</artifactId>
- <packaging>pom</packaging>
- <name>Y</name>
- <version>1.0</version>
-
- <dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>test</groupId>
- <artifactId>a</artifactId>
- <version>1.2</version>
- </dependency>
- <dependency>
- <groupId>test</groupId>
- <artifactId>c</artifactId>
- <version>1.0</version>
- <scope>compile</scope>
- </dependency>
- </dependencies>
- </dependencyManagement>
-</project>
-
-+----+
-
- Project Z:
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
- <groupId>maven</groupId>
- <artifactId>Z</artifactId>
- <packaging>pom</packaging>
- <name>Z</name>
- <version>1.0</version>
-
- <dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>maven</groupId>
- <artifactId>X</artifactId>
- <version>1.0</version>
- <type>pom</type>
- <scope>import</scope>
- </dependency>
- <dependency>
- <groupId>maven</groupId>
- <artifactId>Y</artifactId>
- <version>1.0</version>
- <type>pom</type>
- <scope>import</scope>
- </dependency>
- </dependencies>
- </dependencyManagement>
-</project>
-
-+----+
-
- In the example above Z imports the managed dependencies from both X and Y. However, both X and Y contain dependency a. Here,
- version 1.1 of a would be used since X is declared first and a is not declared in Z's dependencyManagement.
-
- This process is recursive. For example, if X imports another POM, Q, when Z is processed it will simply appear that all
- of Q's managed dependencies are defined in X.
-
-** Bill of Materials (BOM) POMs
-
- Imports are most effective when used for defining a "library" of related artifacts that are generally part of a
- multiproject build. It is fairly common for one project to use one or more artifacts from these libraries.
- However, it has sometimes been difficult to keep the versions in the project using the artifacts in synch
- with the versions distributed in the library. The pattern below illustrates how a "bill of materials" (BOM) can be
- created for use by other projects.
-
- The root of the project is the BOM POM. It defines the versions of all the artifacts that will be created
- in the library. Other projects that wish to use the library should import this POM into the dependencyManagement
- section of their POM.
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
- <groupId>com.test</groupId>
- <artifactId>bom</artifactId>
- <version>1.0.0</version>
- <packaging>pom</packaging>
- <properties>
- <project1Version>1.0.0</project1Version>
- <project2Version>1.0.0</project2Version>
- </properties>
-
- <dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>com.test</groupId>
- <artifactId>project1</artifactId>
- <version>${project1Version}</version>
- </dependency>
- <dependency>
- <groupId>com.test</groupId>
- <artifactId>project2</artifactId>
- <version>${project2Version}</version>
- </dependency>
- </dependencies>
- </dependencyManagement>
-
- <modules>
- <module>parent</module>
- </modules>
-</project>
-
-+----+
-
- The parent subproject has the BOM POM as its parent. It is a normal multiproject pom.
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
- <parent>
- <groupId>com.test</groupId>
- <version>1.0.0</version>
- <artifactId>bom</artifactId>
- </parent>
-
- <groupId>com.test</groupId>
- <artifactId>parent</artifactId>
- <version>1.0.0</version>
- <packaging>pom</packaging>
-
- <dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- <version>1.2.12</version>
- </dependency>
- <dependency>
- <groupId>commons-logging</groupId>
- <artifactId>commons-logging</artifactId>
- <version>1.1.1</version>
- </dependency>
- </dependencies>
- </dependencyManagement>
- <modules>
- <module>project1</module>
- <module>project2</module>
- </modules>
-</project>
-
-+----+
-
- Next are the actual project POMs.
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
- <parent>
- <groupId>com.test</groupId>
- <version>1.0.0</version>
- <artifactId>parent</artifactId>
- </parent>
- <groupId>com.test</groupId>
- <artifactId>project1</artifactId>
- <version>${project1Version}</version>
- <packaging>jar</packaging>
-
- <dependencies>
- <dependency>
- <groupId>log4j</groupId>
- <artifactId>log4j</artifactId>
- </dependency>
- </dependencies>
-</project>
-
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
- <parent>
- <groupId>com.test</groupId>
- <version>1.0.0</version>
- <artifactId>parent</artifactId>
- </parent>
- <groupId>com.test</groupId>
- <artifactId>project2</artifactId>
- <version>${project2Version}</version>
- <packaging>jar</packaging>
-
- <dependencies>
- <dependency>
- <groupId>commons-logging</groupId>
- <artifactId>commons-logging</artifactId>
- </dependency>
- </dependencies>
-</project>
-
-+----+
-
- The project that follows shows how the library can now be used in another project without having to
- specify the dependent project's versions.
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
- <modelVersion>4.0.0</modelVersion>
- <groupId>com.test</groupId>
- <artifactId>use</artifactId>
- <version>1.0.0</version>
- <packaging>jar</packaging>
-
- <dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>com.test</groupId>
- <artifactId>bom</artifactId>
- <version>1.0.0</version>
- <type>pom</type>
- <scope>import</scope>
- </dependency>
- </dependencies>
- </dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>com.test</groupId>
- <artifactId>project1</artifactId>
- </dependency>
- <dependency>
- <groupId>com.test</groupId>
- <artifactId>project2</artifactId>
- </dependency>
- </dependencies>
-</project>
-
-+----+
-
- Finally, when creating projects that import dependencies, beware of the following:
-
- * Do not attempt to import a POM that is defined in a submodule of the current POM.
- Attempting to do that will result in the build failing since it won't be able to locate the POM.
-
- * Never declare the POM importing a POM as the parent (or grandparent, etc) of the target POM.
- There is no way to resolve the circularity and an exception will be thrown.
-
- * When referring to artifacts whose POMs have transitive dependencies, the project needs to specify versions
- of those artifacts as managed dependencies. Not doing so results in a build failure since the
- artifact may not have a version specified. (This should be considered a best practice in any case as it
- keeps the versions of artifacts from changing from one build to the next).
-
- []
-
- Starting from Maven 4.0, a new specific BOM packaging has been introduced.
- It allows defining a BOM which is not used as a parent in a project leveraging
- the newer 4.1.0 model, while still providing full compatibility with Maven 3.X
- clients and projects. This BOM packaging is translated into a more usual POM
- packaging at installation / deployment time, leveraging the build/consumer POM
- feature from Maven 4. This thus provides full compatibility with Maven 3.x.
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.1.0 https://maven.apache.org/xsd/maven-4.1.0.xsd">
- <parent>
- <groupId>com.test</groupId>
- <version>1.0.0</version>
- <artifactId>parent</artifactId>
- </parent>
- <groupId>com.test</groupId>
- <artifactId>bom</artifactId>
- <version>1.0.0</version>
- <packaging>bom</packaging>
- <properties>
- <project1Version>1.0.0</project1Version>
- <project2Version>1.0.0</project2Version>
- </properties>
- <dependencyManagement>
- <dependencies>
- <dependency>
- <groupId>com.test</groupId>
- <artifactId>project1</artifactId>
- <version>${project1Version}</version>
- </dependency>
- <dependency>
- <groupId>com.test</groupId>
- <artifactId>project2</artifactId>
- <version>${project2Version}</version>
- </dependency>
- </dependencies>
- </dependencyManagement>
- </project>
-
-+----+
-
-* System Dependencies
-
- <<<Important note: This is deprecated.>>>
-
- Dependencies with the scope <system> are not looked up in the Maven repository system.
- Instead the <<<dependency>>> element contains a <<<systemPath>>> pointing to a jar on the local
- file system.
-
- The system scope is commonly used to tell Maven about dependencies provided by the JDK or the VM.
- System dependencies are especially useful for resolving dependencies on artifacts which
- are now provided by the JDK, but were available as separate downloads earlier. A typical
- examples is the Java Authentication and Authorization Service (JAAS):
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <dependencies>
- <dependency>
- <groupId>javax.security</groupId>
- <artifactId>jaas</artifactId>
- <version>1.0.01</version>
- <scope>system</scope>
- <systemPath>${java.home}/lib/rt.jar</systemPath>
- </dependency>
- </dependencies>
- ...
-</project>
-
-+----+
-
- If your artifact is provided by the JDK's <<<tools.jar>>>, the system path
- would be defined as follows:
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <dependencies>
- <dependency>
- <groupId>sun.jdk</groupId>
- <artifactId>tools</artifactId>
- <version>1.5.0</version>
- <scope>system</scope>
- <systemPath>${java.home}/../lib/tools.jar</systemPath>
- </dependency>
- </dependencies>
- ...
-</project>
-+----+
-
-
diff --git a/content/apt/guides/introduction/introduction-to-optional-and-excludes-dependencies.apt b/content/apt/guides/introduction/introduction-to-optional-and-excludes-dependencies.apt
deleted file mode 100644
index 01dbcf34..00000000
--- a/content/apt/guides/introduction/introduction-to-optional-and-excludes-dependencies.apt
+++ /dev/null
@@ -1,320 +0,0 @@
- ------
- Optional Dependencies and Dependency Exclusions
- ------
- Allan Ramirez
- ------
- 2006-01-23
- ------
-
-~~ 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
-
-Introduction
-
- This section discusses optional dependencies and
- dependency exclusions. This will help users to understand what they are and
- when and how to use them. It also explains why exclusions are made on a
- per dependency basis instead of at the POM level.
-
-* Optional Dependencies
-
- Optional dependencies are used when it's not possible
- (for whatever reason) to split a project into sub-modules.
- The idea is that some of the dependencies are only used for certain features
- in the project and will not be needed if that feature isn't used. Ideally,
- such a feature would be split into a sub-module that depends on the core
- functionality project. This new subproject would have only non-optional
- dependencies, since you'd need them all if you decided to use the
- subproject's functionality.
-
- However, since the project cannot be split up (again, for whatever reason),
- these dependencies are declared optional. If a user wants to use
- functionality related to an optional dependency, they have to redeclare
- that optional dependency in their own project. This is not the clearest
- way to handle this situation, but both optional dependencies and
- dependency exclusions are stop-gap solutions.
-
-** Why use optional dependencies?
-
- Optional dependencies save space and memory. They prevent problematic jars
- that violate a license agreement or cause classpath issues from being
- bundled into a WAR, EAR, fat jar, or the like.
-
-** How do I use the optional tag?
-
- A dependency is declared optional by setting the <<<\<optional\>>>> element
- to true in its dependency declaration:
-
-+---+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <dependencies>
- <!-- declare the dependency to be set as optional -->
- <dependency>
- <groupId>sample.ProjectA</groupId>
- <artifactId>Project-A</artifactId>
- <version>1.0</version>
- <scope>compile</scope>
- <optional>true</optional> <!-- value will be true or false only -->
- </dependency>
- </dependencies>
-</project>
-
-+---+
-
-** How do optional dependencies work?
-
------
-
-Project-A -> Project-B
-
------
-
- The diagram above says that Project-A depends on Project-B. When A
- declares B as an optional dependency in its POM, this relationship remains
- unchanged. It's just like a normal build where Project-B will be added in
- Project-A's classpath.
-
------
-
-Project-X -> Project-A
-
------
-
- When another project (Project-X) declares Project-A as a dependency in
- its POM, the optional nature of the dependency takes effect.
- Project-B is not included in the classpath of Project-X. You
- need to declare it directly in the POM of Project X for B to be included
- in X's classpath.
-
-** Example
-
- Suppose there is a project named <X2> that has similar functionality
- to <Hibernate>. It supports many databases such as
- MySQL, PostgreSQL, and several versions of Oracle.
- Each supported database requires an additional dependency on a driver jar.
- All of these dependencies are needed at compile time to build X2.
- However your project only uses one specific database
- and doesn't need drivers for the others. X2 can
- declare these dependencies as optional, so that when your project
- declares X2 as a direct dependency in its POM, all the drivers supported
- by the X2 are not automatically included in your project's classpath.
- Your project will have to include an explicit dependency on the specific
- driver for the one database it does use.
-
-* Dependency Exclusions
-
- Since Maven resolves dependencies transitively, it is possible
- for unwanted dependencies to be included in your project's classpath.
- For example, a certain older jar may have security issues or be incompatible with the Java
- version you're using. To address this, Maven allows you to exclude specific dependencies.
- Exclusions are set on a specific dependency in your POM, and are targeted
- at a specific groupId and artifactId. When you build your project, that
- artifact will not be added to your project's classpath <by way of the
- dependency in which the exclusion was declared>.
-
-** How to use dependency exclusions
-
- Add an <<<\<exclusions\>>>> element in the <<<\<dependency\>>>> element by which
- the problematic jar is included.
-
-+---+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <dependencies>
- <dependency>
- <groupId>sample.ProjectA</groupId>
- <artifactId>Project-A</artifactId>
- <version>1.0</version>
- <scope>compile</scope>
- <exclusions>
- <exclusion> <!-- declare the exclusion here -->
- <groupId>sample.ProjectB</groupId>
- <artifactId>Project-B</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- </dependencies>
-</project>
-
-+---+
-
-** How dependency exclusion works and when to use it <<( as a last resort! )>>
-
------
-
-Project-A
- -> Project-B
- -> Project-D <! -- This dependency should be excluded -->
- -> Project-E
- -> Project-F
- -> Project C
-
------
-
- The diagram shows that Project-A depends on both Project-B and C. Project-B
- depends on Project-D. Project-D depends on both Project-E and F. By default,
- Project A's classpath will include:
-
------
-B, C, D, E, F
------
-
- Suppose you don't want project D and its dependencies to be added to
- Project A's classpath because some of Project-D's dependencies
- are missing from the repository, and you
- don't need the functionality in Project-B that depends on Project-D
- anyway. Project-B's developers could have marked the dependency on
- Project-D <<<\<optional\>true\</optional\>>>>:
-
-+---+
-<dependency>
- <groupId>sample.ProjectD</groupId>
- <artifactId>ProjectD</artifactId>
- <version>1.0-SNAPSHOT</version>
- <optional>true</optional>
-</dependency>
-+---+
-
- Unfortunately, they didn't. As a last resort, you can exclude it
- on your own POM for Project-A like this:
-
-+---+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
- <groupId>sample.ProjectA</groupId>
- <artifactId>Project-A</artifactId>
- <version>1.0-SNAPSHOT</version>
- <packaging>jar</packaging>
- ...
- <dependencies>
- <dependency>
- <groupId>sample.ProjectB</groupId>
- <artifactId>Project-B</artifactId>
- <version>1.0-SNAPSHOT</version>
- <exclusions>
- <exclusion>
- <groupId>sample.ProjectD</groupId> <!-- Exclude Project-D from Project-B -->
- <artifactId>Project-D</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- </dependencies>
-</project>
-
-+---+
-
- If you deploy Project-A to a repository, and Project-X declares a
- normal dependency on Project-A, will Project-D still be excluded from the
- classpath?
-
------
-
-Project-X -> Project-A
-
------
-
- The answer is <<Yes>>. Project-A has declared that it doesn't need
- Project-D to run, so it won't be brought in as a transitive dependency
- of Project-A.
-
- Now, consider that Project-X depends on Project-Y, as in the diagram below:
-
------
-
-Project-X -> Project-Y
- -> Project-B
- -> Project-D
- ...
-
------
-
- Project-Y also has a dependency on Project-B, and it does need the features
- supported by Project-D. Therefore, it will NOT place an exclusion on
- Project-D in its dependency list. It may also supply an additional
- repository, from which it can resolve Project-E. In this case, it's important
- that Project-D <<is not>> excluded globally, since it is a legitimate
- dependency of Project-Y.
-
- As another scenario, suppose the dependency you don't want is Project-E
- instead of Project-D. How do you exclude it? See the diagram below:
-
------
-
-Project-A
- -> Project-B
- -> Project-D
- -> Project-E <!-- Exclude this dependency -->
- -> Project-F
- -> Project C
-
------
-
- Exclusions work on the entire dependency graph below the point where they
- are declared. If you want to exclude Project-E instead of Project-D,
- simply change the exclusion to point at Project-E, but you don't
- move the exclusion down to Project-D. You cannot change Project-D's POM.
- If you could, you would use optional dependencies instead of exclusions,
- or split Project-D up into multiple subprojects, each with nothing but
- normal dependencies.
-
-+---+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
- <groupId>sample.ProjectA</groupId>
- <artifactId>Project-A</artifactId>
- <version>1.0-SNAPSHOT</version>
- <packaging>jar</packaging>
- ...
- <dependencies>
- <dependency>
- <groupId>sample.ProjectB</groupId>
- <artifactId>Project-B</artifactId>
- <version>1.0-SNAPSHOT</version>
- <exclusions>
- <exclusion>
- <groupId>sample.ProjectE</groupId> <!-- Exclude Project-E from Project-B -->
- <artifactId>Project-E</artifactId>
- </exclusion>
- </exclusions>
- </dependency>
- </dependencies>
-</project>
-
-+---+
-
-** Why exclusions are made on a per-dependency basis, rather than at the POM level
-
- This is mainly to be sure the dependency graph is predictable, and to
- keep inheritance effects from excluding a dependency that should not be
- excluded. If you get to the method of last resort and have to put in an
- exclusion, you should be absolutely certain which of your dependencies is
- bringing in that unwanted transitive dependency.
-
- If you truly want to ensure that a particular dependency appears nowhere in
- your classpath, regardless of path, the
- {{{/enforcer/enforcer-rules/bannedDependencies.html}banned dependencies rule}}
- can be configured to fail the build if a problematic dependency is found.
- When the build fails, you'll need to add specific exclusions on each path
- the enforcer finds.
diff --git a/content/apt/guides/introduction/introduction-to-plugins.apt b/content/apt/guides/introduction/introduction-to-plugins.apt
deleted file mode 100644
index cde95074..00000000
--- a/content/apt/guides/introduction/introduction-to-plugins.apt
+++ /dev/null
@@ -1,87 +0,0 @@
- ------
- Introduction to Maven Plugin Development
- ------
- John Casey
- ------
- 2005-06-24
- ------
-
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
-
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
-
-Introduction to Maven Plugin Development
-
- Maven consists of a core engine which provides basic project-processing
- capabilities and build-process management, and a host of plugins which are
- used to execute the actual build tasks.
-
-* What is a Plugin?
-
- "Maven" is really just a core framework for a collection of
- Maven Plugins. In other words, plugins are where much of the real action is
- performed, plugins are used to: create jar files, create war files, compile
- code, unit test code, create project documentation, and on and on. Almost
- any action that you can think of performing on a project is implemented as
- a Maven plugin.
-
- Plugins are the central feature of Maven that allow for the reuse of
- common build logic across multiple projects. They do this by executing an
- "action" (i.e. creating a WAR file or compiling unit tests) in the context
- of a project's description - the Project Object Model (POM). Plugin behavior
- can be customized through a set of unique parameters which are exposed by a
- description of each plugin goal (or Mojo).
-
- One of the simplest plugins in Maven is the Clean Plugin. The
- {{{../../plugins/maven-clean-plugin/}Maven
- Clean plugin}} (maven-clean-plugin) is responsible for removing the target
- directory of a Maven project. When you run "mvn clean", Maven executes
- the "clean" goal as defined in the Clean plug-in, and the target directory
- is removed. The Clean plugin
- {{{../../plugins/maven-clean-plugin/clean-mojo.html}defines
- a parameter}} which can be used to customize plugin behavior, this parameter is
- called outputDirectory and it defaults to $\{project.build.directory\}.
-
-* What is a Mojo (<And Why the H--- is it Named 'Mojo'>)?
-
- A Mojo is really just a <<goal>> in Maven, and plug-ins consist of
- any number of goals (Mojos). Mojos can be defined as annotated Java classes or
- Beanshell script. A Mojo specifies
- metadata about a goal: a goal name, which phase of the lifecycle it fits into,
- and the parameters it is expecting.
-
- MOJO is a play on POJO (Plain-old-Java-object), substituting "Maven" for
- "Plain". Mojo is also an interesting word (see {{{http://www.answers.com/mojo&r=67}definition}}).
- From {{{http://www.wikipedia.org}Wikipedia}}, a "mojo" is defined as:
- "...a small bag worn by a person under the clothes (also known as a mojo hand).
- Such bags were thought to have supernatural powers, such as protecting from evil,
- bringing good luck, etc."
-
-* What is the Build Lifecycle? (Overview)
-
- The build lifecycle is a series of common <<stage>>s through which all project
- builds naturally progress. Plugin goals are bound to specific stages in the
- lifecycle.
-
-Resources
-
- [[1]] {{{/plugin-developers/index.html}Plugin Development Center}}
-
- [[2]] {{{../mini/guide-configuring-plugins.html}Configuring plugins}}
-
diff --git a/content/apt/guides/introduction/introduction-to-profiles.apt b/content/apt/guides/introduction/introduction-to-profiles.apt
deleted file mode 100644
index ef0d145e..00000000
--- a/content/apt/guides/introduction/introduction-to-profiles.apt
+++ /dev/null
@@ -1,859 +0,0 @@
- ---
- Introduction to build profiles
- ---
- John Casey/Allan Ramirez
- ---
- 2008-01-01
- ---
-
-~~ 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
-
-Introduction to Build Profiles
-
-%{toc|section=0|fromDepth=2|toDepth=5}
-
- Apache Maven goes to great lengths to ensure that builds are portable. Among
- other things, this means allowing build configuration inside the POM,
- avoiding <<all>> filesystem references (in inheritance, dependencies, and
- other places), and leaning much more heavily on the local repository to
- store the metadata needed to make this possible.
-
- However, sometimes portability is not entirely possible. Under certain
- conditions, plugins may need to be configured with local filesystem paths.
- Under other circumstances, a slightly different dependency set will be
- required, and the project's artifact name may need to be adjusted slightly.
- And at still other times, you may even need to include a whole plugin in the
- build lifecycle depending on the detected build environment.
-
- To address these circumstances, Maven supports build profiles.
- Profiles are specified using a subset of the elements available in
- the POM itself (plus one extra section), and are triggered in any of a
- variety of ways. They modify the POM at build time, and are meant to be used
- in complementary sets to give equivalent-but-different parameters for a set
- of target environments (providing, for example, the path of the appserver root
- in the development, testing, and production environments). As such, profiles
- can easily lead to differing build results from different members of your team.
- However, used properly, profiles can be used while still preserving
- project portability. This will also minimize the use of <<<-f>>> option of
- maven which allows user to create another POM with different parameters or
- configuration to build which makes it more maintainable since it is running
- with one POM only.
-
-* What are the different types of profile? Where is each defined?
-
- * Per Project
-
- - Defined in the POM itself <<<(pom.xml)>>>.
-
- * Per User
-
- - Defined in the {{{/ref/current/maven-settings/settings.html} Maven-settings}}
- <<<(%USER_HOME%/.m2/settings.xml)>>>.
-
- * Global
-
- - Defined in the {{{/ref/current/maven-settings/settings.html} global Maven-settings}}
- <<<($\{maven.home\}/conf/settings.xml)>>>.
-
-* Profile Inheritance
-
- The profiles are not inherited as other POM elements by child POMs. Instead they are resolved very early by the {{{/ref/current/maven-model-builder/}Maven Model Builder}}
- and only the effects of active profiles are inherited (e.g. the plugins defined in the profile).
- That also leads to the fact that implicit profile activation only has an effect on the surrounding profile container but never on any other profile (even if it has the same id).
-
-* How can a profile be triggered? How does this vary according to the type of profile being used?
-
- A profile can be activated in several ways:
-
- * Explicitly
-
- * Implicitly
-
- * Based on OS
-
- * Based on system properties
-
- * Based on presence of files
-
- []
-
- Refer to the sections below for details.
-
-** Details on profile activation
-
-*** Explicit profile activation
-
- Profiles can be explicitly specified using the <<<-P>>> command line flag.
-
- This flag is followed by a comma-delimited list of
- profile IDs to use. The profile(s) specified in the option
- are activated in addition to any profiles which are activated by their activation
- configuration or the <<<\<activeProfiles\>>>> section in <<<settings.xml>>>.
- From Maven 4 onward, Maven will refuse to activate or deactivate a profile that cannot be resolved.
- To prevent this, prefix the profile identifier with an <<<?>>>, marking it as optional:
-
------
-mvn groupId:artifactId:goal -P profile-1,profile-2,?profile-3
------
-
- Profiles can be activated in the Maven settings, via the <<<\<activeProfiles\>>>>
- section. This section takes a list of <<<\<activeProfile\>>>> elements, each
- containing a profile-id inside.
-
-+---+
-<settings>
- ...
- <activeProfiles>
- <activeProfile>profile-1</activeProfile>
- </activeProfiles>
- ...
-</settings>
-+---+
-
- Profiles listed in the <<<\<activeProfiles\>>>> tag would be activated by default
- every time a project use it.
-
- Profiles can also be active by default using a configuration like the following in a POM:
-
-+---+
-<profiles>
- <profile>
- <id>profile-1</id>
- <activation>
- <activeByDefault>true</activeByDefault>
- </activation>
- ...
- </profile>
-</profiles>
-+---+
-
- This profile will automatically be active for all builds unless another profile in the same POM
- is activated using one of the previously described methods. All profiles that are active by
- default are automatically deactivated when a profile in the POM is activated on the command line
- or through its activation config.
-
-*** Implicit profile activation
-
- Profiles can be automatically triggered based on the detected state of
- the build environment. These triggers are specified via an <<<\<activation\>>>>
- section in the profile itself. Currently, this detection is limited to
- JDK version matching, operating system matching or
- the presence/the value of a system property. The implicit profile activation always only refers to the container profile (and not to profiles in other modules with the same id).
- Here are some examples.
-
-**** JDK
-
- The following configuration will trigger the profile when the JDK's
- version <starts with> "1.4" (eg. "1.4.0_08", "1.4.2_07", "1.4"), in particular it <won't be active>
- for <<newer>> versions like "1.8" or "11":
-
-+---+
-<profiles>
- <profile>
- <activation>
- <jdk>1.4</jdk>
- </activation>
- ...
- </profile>
-</profiles>
-+---+
-
- {{{/enforcer/enforcer-rules/versionRanges.html} Ranges}} can also be used.
- Range values must start with either <<<[>>> or <<<(>>>. Otherwise, the value is interpreted as a prefix.
- The following honours versions 1.3, 1.4 and 1.5.
-
-+---+
-<profiles>
- <profile>
- <activation>
- <jdk>[1.3,1.6)</jdk>
- </activation>
- ...
- </profile>
-</profiles>
-+---+
-
- <Note:> an upper bound such as <<<,1.5]>>> is likely not to include most releases of 1.5, since they will have an additional "patch" release such as <<<_05>>> that is not taken into consideration in the above range.
-
-
-**** OS
-
- This next one will activate based on the detected operating system. See the {{{/enforcer/enforcer-rules/requireOS.html}Maven Enforcer Plugin}} for more details about OS values.
-
-+---+
-<profiles>
- <profile>
- <activation>
- <os>
- <name>Windows XP</name>
- <family>Windows</family>
- <arch>x86</arch>
- <version>5.1.2600</version>
- </os>
- </activation>
- ...
- </profile>
-</profiles>
-+---+
-
- The values are interpreted as Strings and are matched against the {{{https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html}Java System properties}}
- <<<os.name>>>, <<<os.arch>>>, <<<os.version>>> and the family being derived from those.
-
- Each value can be prefixed with <<<!>>> to negate the matching.
- The values match if they are (not) equal to the actual String value (<<case insensitive>>).
- All given OS conditions must match for the profile to be considered for activation.
-
- Since {{{https://issues.apache.org/jira/browse/MNG-5726}Maven 3.9.7}} the value for <<<version>>> may be prefixed with <<<regex:>>>.
- In that case {{{https://docs.oracle.com/javase/tutorial/essential/regex/}regular pattern matching}} is applied for the version matching and applied against the <<lower case>> <<<os.version>>> value.
-
- The actual OS values which need to match the given values are emitted when executing <<<mvn --version>>>.
-
-**** Property
-
- The profile below will be activated when the system property "debug" is specified
- with any value:
-
-+---+
-<profiles>
- <profile>
- <activation>
- <property>
- <name>debug</name>
- </property>
- </activation>
- ...
- </profile>
-</profiles>
-+---+
-
- The following profile will be activated when the system property "debug" is not defined
- at all:
-
-+---+
-<profiles>
- <profile>
- <activation>
- <property>
- <name>!debug</name>
- </property>
- </activation>
- ...
- </profile>
-</profiles>
-+---+
-
- The following profile will be activated when the system property "debug" is defined with no value,
- or is defined with the value "true".
-
-+---+
-<profiles>
- <profile>
- <activation>
- <property>
- <name>debug</name>
- <value>true</value>
- </property>
- </activation>
- ...
- </profile>
-</profiles>
-+---+
-
- To activate this you would type one of those on the command line:
-
------
-mvn groupId:artifactId:goal -Ddebug
-mvn groupId:artifactId:goal -Ddebug=true
------
-
- The following profile will be activated when the system property "debug" is not defined,
- or is defined with a value which is not "true".
-
-+---+
-<profiles>
- <profile>
- <activation>
- <property>
- <name>debug</name>
- <value>!true</value>
- </property>
- </activation>
- ...
- </profile>
-</profiles>
-+---+
-
- To activate this you would type one of those on the command line:
-
------
-mvn groupId:artifactId:goal
-mvn groupId:artifactId:goal -Ddebug=false
------
-
- The next example will trigger the profile when the system property
- "environment" is specified with the value "test":
-
-+---+
-<profiles>
- <profile>
- <activation>
- <property>
- <name>environment</name>
- <value>test</value>
- </property>
- </activation>
- ...
- </profile>
-</profiles>
-+---+
-
- To activate this you would type this on the command line:
-
------
-mvn groupId:artifactId:goal -Denvironment=test
------
-
- Profiles in the POM can also be activated based on properties from active profiles from the
- <<<settings.xml>>>.
-
- <<Note>>: Environment variables like <<<FOO>>> are available as properties of the form <<<env.FOO>>>. Further note
- that environment variable names are normalized to all upper-case on Windows.
-
- Since Maven 3.9.0 one can also evaluate the POM's packaging value by referencing property <<<packaging>>>.
- This is only useful where the profile activation is defined in a common parent POM which is reused among multiple Maven projects.
- The next example will trigger the profile when a project with packaging <<<war>>> is built:
-
-+---+
-<profiles>
- <profile>
- <activation>
- <property>
- <name>packaging</name>
- <value>war</value>
- </property>
- </activation>
- ...
- </profile>
-</profiles>
-+---+
-
-**** Files
-
- This example will trigger the profile when the generated file
- <<<target/generated-sources/axistools/wsdl2java/org/apache/maven>>> is missing.
-
-+---+
-<profiles>
- <profile>
- <activation>
- <file>
- <missing>target/generated-sources/axistools/wsdl2java/org/apache/maven</missing>
- </file>
- </activation>
- ...
- </profile>
-</profiles>
-+---+
-
- The tags <<<\<exists\>>>> and <<<\<missing\>>>> can be interpolated. Supported variables are
- system properties like <<<$\{user.home\}>>> and environment variables like <<<$\{env.HOME\}>>>. Please note that
- properties and values defined in the POM itself are not available for interpolation here, e.g. the above example
- activator cannot use <<<$\{project.build.directory\}>>> but needs to hard-code the path <<<target>>>.
-
-*** Multiple conditions
-
- Different implicit activation types can be combined in one profile.
- The profile is then only active if all conditions are met (since Maven 3.2.2, {{{https://issues.apache.org/jira/browse/MNG-4565}MNG-4565}}).
- Using the same type more than once in the same profile is not supported ({{{https://issues.apache.org/jira/browse/MNG-5909}MNG-5909}}, {{{https://issues.apache.org/jira/browse/MNG-3328}MNG-3328}}).
-
-** Deactivating a profile
-
- One or more profiles can be deactivated using the command line by prefixing their
- identifier with either the character '!' or '-' as shown below.
-
- <<Note>> that <<<!>>> needs to be escaped with <<<\\>>> or quoted in Bash, ZSH and other shells as it has {{{https://www.gnu.org/software/bash/manual/html_node/Event-Designators.html}a special meaning}}.
- Also there is a known bug with command line option values starting with <<<->>> ({{{https://issues.apache.org/jira/browse/CLI-309}CLI-309}}), therefore it is recommended to use it with the syntax <<<-P=-profilename>>>.
-
------
-mvn groupId:artifactId:goal -P \!profile-1,\!profile-2,\!?profile-3
------
-
- or
-
------
-mvn groupId:artifactId:goal -P=-profile-1,-profile-2,-?profile-3
------
-
- This can be used to deactivate profiles marked as activeByDefault or profiles that would
- otherwise be activated through their activation config.
-
-* Which areas of a POM can be customized by each type of profile? Why?
-
- Now that we've talked about where to specify profiles, and how to activate them,
- it will be useful to talk about <what> you can specify in a profile. As with
- the other aspects of profile configuration, this answer is not straightforward.
-
- Depending on where you choose to configure your profile, you will have access
- to varying POM configuration options.
-
-** Profiles in external files
-
- Profiles specified in external files
- (i.e in <<<settings.xml>>> or <<<profiles.xml>>>) are not portable in the
- strictest sense. Anything that seems to stand a high chance of changing the result
- of the build is restricted to the inline profiles in the POM. Things like
- repository lists could simply be a proprietary repository of approved
- artifacts, and won't change the outcome of the build. Therefore, you will
- only be able to modify the <<<\<repositories\>>>> and <<<\<pluginRepositories\>>>>
- sections, plus an extra <<<\<properties\>>>> section.
-
- The <<<\<properties\>>>> section allows you to specify free-form key-value pairs
- which will be included in the interpolation process for the POM. This allows
- you to specify a plugin configuration in the form of <<<$\{profile.provided.path\}>>>.
-
-** Profiles in POMs
-
- On the other hand, if your profiles can be reasonably specified <inside> the
- POM, you have many more options. The trade-off, of course, is that you can
- only modify <that> project and its sub-modules. Since these profiles are
- specified inline, and therefore have a better chance of preserving portability,
- it's reasonable to say you can add more information to them without the risk
- of that information being unavailable to other users.
-
- Profiles specified in the POM can modify
- {{{/ref/current/maven-model/maven.html}the following POM elements}}:
-
- * <<<\<repositories\>>>>
-
- * <<<\<pluginRepositories\>>>>
-
- * <<<\<dependencies\>>>>
-
- * <<<\<plugins\>>>>
-
- * <<<\<properties\>>>> (not actually available in the main POM, but used behind the
- scenes)
-
- * <<<\<modules\>>>>
-
- * <<<\<reports\>>>>
-
- * <<<\<reporting\>>>>
-
- * <<<\<dependencyManagement\>>>>
-
- * <<<\<distributionManagement\>>>>
-
- * a subset of the <<<\<build\>>>> element, which consists of:
-
- * <<<\<defaultGoal\>>>>
-
- * <<<\<resources\>>>>
-
- * <<<\<testResources\>>>>
-
- * <<<\<directory\>>>>
-
- * <<<\<finalName\>>>>
-
- * <<<\<filters\>>>>
-
- * <<<\<pluginManagement\>>>>
-
- * <<<\<plugins\>>>>
-
- []
-
-** POM elements outside \<profiles\>
-
- We don't allow modification of some POM elements outside of POM-profiles
- because these runtime modifications will not be distributed when the POM
- is deployed to the repository system, making that person's build of that
- project completely unique from others. While you can do this to some extent
- with the options given for external profiles, the danger is limited.
- Another reason is that this POM info is sometimes being reused from the
- parent POM.
-
- External files such as <<<settings.xml>>> and <<<profiles.xml>>> also do not support elements
- outside the POM-profiles. Let us take this scenario for elaboration. When the
- effective POM is deployed to a remote repository, any person can pickup
- its info out of the repository and use it to build a Maven project directly.
- Now, imagine that if we can set profiles in dependencies, which is very
- important to a build, or in any other elements outside POM-profiles in
- <<<settings.xml>>> then most probably we cannot expect someone else to use that
- POM from the repository and be able to build it. And we have to also think about
- how to share the <<<settings.xml>>> with others. Note that too many files to
- configure are very confusing and very hard to maintain.
- Bottom line is that since this is build data, it should be in the POM.
-
-* Profile Order
-
- All profile elements in a POM from active profiles overwrite the global elements with the same name of the POM or extend those in case of collections.
- In case multiple profiles are active in the same POM or external file, the ones which are defined <<later>> take precedence over the ones defined <<earlier>> (independent of their profile id and activation order).
-
- Example:
-
-+---+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <repositories>
- <repository>
- <id>global-repo</id>
- ...
- </repository>
- </repositories>
- ...
- <profiles>
- <profile>
- <id>profile-1</id>
- <activation>
- <activeByDefault>true</activeByDefault>
- </activation>
- <repositories>
- <repository>
- <id>profile-1-repo</id>
- ...
- </repository>
- </repositories>
- </profile>
- <profile>
- <id>profile-2</id>
- <activation>
- <activeByDefault>true</activeByDefault>
- </activation>
- <repositories>
- <repository>
- <id>profile-2-repo</id>
- ...
- </repository>
- </repositories>
- </profile>
- ...
- </profiles>
- ...
-</project>
-+---+
-
- This leads to the repository list: <<<profile-2-repo, profile-1-repo, global-repo>>>.
-
-* Profile Pitfalls
-
- We've already mentioned the fact that adding profiles to your build has the
- potential to break portability for your project. We've even gone so far as to
- highlight circumstances where profiles are likely to break project portability.
- However, it's worth reiterating those points as part of a more coherent
- discussion about some pitfalls to avoid when using profiles.
-
- There are two main problem areas to keep in mind when using profiles.
- First are external properties, usually used in plugin configurations. These pose
- the risk of breaking portability in your project. The other, more subtle area
- is the incomplete specification of a natural set of profiles.
-
-** External Properties
-
- External property definition concerns any property value defined outside
- the <<<pom.xml>>> but not defined in a corresponding profile inside it.
- The most obvious usage of properties in the POM is in plugin configuration.
- While it is certainly possible to break project portability without properties,
- these critters can have subtle effects that cause builds to fail. For example,
- specifying appserver paths in a profile that is specified in the
- <<<settings.xml>>> may cause your integration test plugin to fail when another
- user on the team attempts to build without a similar <<<settings.xml>>>.
- Consider the following <<<pom.xml>>> snippet for a web application project:
-
-+---+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <build>
- <plugins>
- <plugin>
- <groupId>org.myco.plugins</groupId>
- <artifactId>spiffy-integrationTest-plugin</artifactId>
- <version>1.0</version>
- <configuration>
- <appserverHome>${appserver.home}</appserverHome>
- </configuration>
- </plugin>
- ...
- </plugins>
- </build>
- ...
-</project>
-+---+
-
- Now, in your local <<<$\{user.home\}/.m2/settings.xml>>>, you have:
-
-+---+
-<settings>
- ...
- <profiles>
- <profile>
- <id>appserverConfig</id>
- <properties>
- <appserver.home>/path/to/appserver</appserver.home>
- </properties>
- </profile>
- </profiles>
-
- <activeProfiles>
- <activeProfile>appserverConfig</activeProfile>
- </activeProfiles>
- ...
-</settings>
-+---+
-
- When you build the <<integration-test>> lifecycle phase, your integration
- tests pass, since the path you've provided allows the test plugin to install
- and test this web application.
-
- <However>, when your colleague attempts to build to <<integration-test>>,
- his build fails spectacularly, complaining that it cannot resolve the plugin
- configuration parameter <<<\<appserverHome\>>>>, or worse, that the value of that
- parameter - literally <<<$\{appserver.home\}>>> - is invalid (if it warns you at all).
-
- Congratulations, your project is now non-portable. Inlining this profile in
- your <<<pom.xml>>> can help alleviate this, with the obvious drawback that
- each project hierarchy (allowing for the effects of inheritance) now have to
- specify this information. Since Maven provides good support for project
- inheritance, it's possible to stick this sort of configuration in the
- <<<\<pluginManagement\>>>> section of a team-level POM or similar, and simply
- inherit the paths.
-
- Another, less attractive answer might be standardization of development
- environments. However, this will tend to compromise the productivity
- gain that Maven is capable of providing.
-
-** Incomplete Specification of a Natural Profile Set
-
- In addition to the above portability-breaker, it's easy to fail to cover all
- cases with your profiles. When you do this, you're usually leaving one of
- your target environments high and dry. Let's take the example <<<pom.xml>>>
- snippet from above one more time:
-
-+---+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <build>
- <plugins>
- <plugin>
- <groupId>org.myco.plugins</groupId>
- <artifactId>spiffy-integrationTest-plugin</artifactId>
- <version>1.0</version>
- <configuration>
- <appserverHome>${appserver.home}</appserverHome>
- </configuration>
- </plugin>
- ...
- </plugins>
- </build>
- ...
-</project>
-+---+
-
- Now, consider the following profile, which would be specified inline in the
- <<<pom.xml>>>:
-
-+---+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <profiles>
- <profile>
- <id>appserverConfig-dev</id>
- <activation>
- <property>
- <name>env</name>
- <value>dev</value>
- </property>
- </activation>
- <properties>
- <appserver.home>/path/to/dev/appserver</appserver.home>
- </properties>
- </profile>
-
- <profile>
- <id>appserverConfig-dev-2</id>
- <activation>
- <property>
- <name>env</name>
- <value>dev-2</value>
- </property>
- </activation>
- <properties>
- <appserver.home>/path/to/another/dev/appserver2</appserver.home>
- </properties>
- </profile>
- </profiles>
- ..
-</project>
-+---+
-
- This profile looks quite similar to the one from the last example, with a few
- important exceptions: it's plainly geared toward a development environment,
- a new profile named <<<appserverConfig-dev-2>>> is added and it has an
- activation section that will trigger its inclusion when the system
- properties contain "env=dev" for a profile named <<<appserverConfig-dev>>> and
- "env=dev-2" for a profile named <<<appserverConfig-dev-2>>>. So, executing:
-
------
-mvn -Denv=dev-2 integration-test
------
-
- will result in a successful build, applying the properties given
- by profile named <<<appserverConfig-dev-2>>>. And when we execute
-
------
-mvn -Denv=dev integration-test
------
-
- it will result in a successful build applying the properties given
- by the profile named <<<appserverConfig-dev>>>. However, executing:
-
------
-mvn -Denv=production integration-test
------
-
- will not do a successful build. Why? Because, the resulting non-interpolated
- literal value of <<<$\{appserver.home\}>>> will not be a valid path for deploying
- and testing your web application. We haven't considered the case for the
- production environment when writing our profiles. The "production"
- environment (env=production), along with "test" and possibly even "local"
- constitute a natural set of target environments for which we may want to
- build the integration-test lifecycle phase. The incomplete specification of
- this natural set means we have effectively limited our valid target environments
- to the development environment. Your teammates - and probably your manager -
- will not see the humor in this. When you construct profiles to handle cases
- such as these, be sure to address the entire set of target permutations.
-
- As a quick aside, it's possible for user-specific profiles to act in a similar
- way. This means that profiles for handling different environments which are
- keyed to the user can act up when the team adds a new developer. While I
- suppose this <could> act as useful training for the newbie, it just wouldn't
- be nice to throw them to the wolves in this way. Again, be sure to think of the
- <whole> set of profiles.
-
-* How can I tell which profiles are in effect during a build?
-
- Determining active profiles will help the user to know what particular
- profiles has been executed during a build. We can use the {{{/plugins/maven-help-plugin/}Maven Help Plugin}}
- to tell what profiles are in effect during a build.
-
------
- mvn help:active-profiles
------
-
- Let us have some small samples that will help us to understand more on the
- <active-profiles> goal of that plugin.
-
- From the last example of profiles in the <<<pom.xml>>>, you'll notice that there are
- two profiles named <<<appserverConfig-dev>>> and <<<appserverConfig-dev-2>>>
- which has been given different values for properties. If we go ahead
- and execute:
-
------
- mvn help:active-profiles -Denv=dev
------
-
- The result will be a bulleted list of the id of the profile with an
- activation property of "env=dev" together with the source where it was
- declared. See sample below.
-
----
-The following profiles are active:
-
- - appserverConfig-dev (source: pom)
----
-
- Now if we have a profile declared in <<<settings.xml>>> (refer to the sample of profile
- in <<<settings.xml>>>) and that have been set to be an active profile and execute:
-
------
- mvn help:active-profiles
------
-
- The result should be something like this
-
----
-The following profiles are active:
-
- - appserverConfig (source: settings.xml)
----
-
- Even though we don't have an activation property, a profile has been listed as active.
- Why? Like we mentioned before, a profile that has been set as an active profile
- in the <<<settings.xml>>> is automatically activated.
-
- Now if we have something like a profile in the <<<settings.xml>>> that has been set
- as an active profile and also triggered a profile in the POM. Which profile do
- you think will have an effect on the build?
-
------
- mvn help:active-profiles -P appserverConfig-dev
------
-
- This will list the activated profiles:
-
----
-The following profiles are active:
-
- - appserverConfig-dev (source: pom)
- - appserverConfig (source: settings.xml)
----
-
- Even though it listed the two active profiles, we are not sure which one
- of them has been applied. To see the effect on the build execute:
-
------
- mvn help:effective-pom -P appserverConfig-dev
------
-
- This will print the effective POM for this build configuration out to the
- console. Take note that profiles in the <<<settings.xml>>> takes higher priority
- than profiles in the POM. So the profile that has been applied here is
- <<<appserverConfig>>> not <<<appserverConfig-dev>>>.
-
- If you want to redirect the output from the plugin to a file called <<<effective-pom.xml>>>,
- use the command-line option <<<-Doutput=effective-pom.xml>>>.
-
-* Naming Conventions
-
- By now you've noticed that profiles are a natural way of addressing the problem of
- different build configuration requirements for different target environments. Above,
- we discussed the concept of a "natural set" of profiles to address this situation,
- and the importance of considering the whole set of profiles that will be required.
-
- However, the question of how to organize and manage the evolution of that set is
- non-trivial as well. Just as a good developer strives to write self-documenting
- code, it's important that your profile id's give a hint to their intended use.
- One good way to do this is to use the common system property trigger as part of
- the name for the profile. This might result in names like <<env-dev>>, <<env-test>>,
- and <<env-prod>> for profiles that are triggered by the system property <<env>>.
- Such a system leaves a highly intuitive hint on how to activate a build targeted
- at a particular environment. Thus, to activate a build for the test environment,
- you need to activate <<env-test>> by issuing:
-
------
-mvn -Denv=test <phase>
------
-
- The right command-line option can be had by simply substituting "=" for "-" in
- the profile id.
-
-
diff --git a/content/apt/guides/introduction/introduction-to-repositories.apt b/content/apt/guides/introduction/introduction-to-repositories.apt
deleted file mode 100644
index da2c50eb..00000000
--- a/content/apt/guides/introduction/introduction-to-repositories.apt
+++ /dev/null
@@ -1,163 +0,0 @@
- ------
- Introduction to Repositories
- ------
- Jason van Zyl
- Brian Fox
- ------
- 2008-05-13
- ------
-
-~~ 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
-
-Introduction to Repositories
-
-* Artifact Repositories
-
- A repository in Maven holds build artifacts of varying types.
-
- There are exactly two types of repositories: <<local>> and <<remote>>:
-
- [[1]] the <<local>> repository is a directory
- on the computer where Maven runs. It caches remote downloads and contains temporary
- build artifacts that you have not yet released.
-
- [[2]] <<remote>> repositories refer to any other type of repository, accessed by a variety of protocols such as
- <<<file://>>> and <<<https://>>>. These repositories might be a truly remote repository
- set up by a third party to provide their artifacts for downloading (for example,
- {{{https://repo.maven.apache.org/maven2/}repo.maven.apache.org}}).
- Other "remote" repositories may be internal repositories
- set up on a file or HTTP server within your company, used to share private artifacts between development teams
- and for releases.
-
- []
-
- Local and remote repositories are structured the same way so that scripts can run on either
- side, or they can be synced for offline use. The layout of the repositories is completely
- transparent to the Maven user, however.
-
-* Using Repositories
-
- In general, you should not need to do anything with the local repository on a regular basis, except clean
- it out if you are short on disk space (or erase it completely if you are willing to download everything again).
-
- For the remote repositories, they are used for both downloading and uploading (if you have the permission to
- do so).
-
-** Downloading from a Remote Repository
-
- Downloading in Maven is triggered by a project declaring a dependency that is not present in the local
- repository (or for a <<<SNAPSHOT>>>, when the remote repository contains one that is newer).
- By default, Maven will download from the {{{https://repo.maven.apache.org/maven2/}central}} repository.
-
- To override this, you need to specify a <<<mirror>>> as shown in {{{../mini/guide-mirror-settings.html}Using Mirrors for Repositories}}.
-
- You can set this in your <<<settings.xml>>> file to globally use a certain mirror. However,
- it is common for a project to {{{../mini/guide-multiple-repositories.html}customise the repository in its <<<pom.xml>>>}}
- and that your setting will take precedence. If dependencies are not being found, check that you
- have not overridden the remote repository.
-
- For more information on dependencies, see {{{./introduction-to-dependency-mechanism.html}Dependency Mechanism}}.
-
-** Using Mirrors for the Central Repository
-
- There are {{{/repository/}several official Central repositories}} geographically distributed. You can make
- changes to your <<<settings.xml>>> file to use one or more mirrors. Instructions for this can be
- found in the guide {{{../mini/guide-mirror-settings.html}Using Mirrors for Repositories}}.
-
-* Building Offline
-
- If you are temporarily disconnected from the internet and you need to build your projects offline,
- you can use the offline switch on the CLI:
-
------
- mvn -o package
------
-
- Many plugins honor the offline setting and do not perform any operations that connect to
- the internet. Some examples are resolving Javadoc links and link checking the site.
-
-* Uploading to a Remote Repository
-
- While this is possible for any type of remote repository, you must have the permission to do so.
- To have someone upload to the Central Maven repository, see {{{../../repository/index.html}Repository Center}}.
-
-* Internal Repositories
-
- When using Maven, particularly in a corporate environment, connecting to the internet to download dependencies
- is not acceptable for security, speed or bandwidth reasons. For that reason, it is desirable to set up an
- internal repository to house a copy of artifacts, and to publish private artifacts to.
-
- Such an internal repository can be downloaded using HTTP or the file system (with a <<<file://>>>
- URL), and uploaded to using SCP, FTP, or a file copy.
-
- As far as Maven is concerned, there is nothing special about this repository: it is another
- <<remote repository>> that contains artifacts to download to a user's local cache, and is a publish
- destination for artifact releases.
-
- Additionally, you may want to share the repository server with your generated project sites. For more
- information on creating and deploying sites, see {{{../mini/guide-site.html}Creating a Site}}.
-
-* Setting up the Internal Repository
-
- Setting up an internal repository just requires that you have a place to put it, and then copy
- required artifacts there using the same layout as in a remote repository such as {{{https://repo.maven.apache.org/maven2/}repo.maven.apache.org}}.
-
- Do <not> scrape or <<<rsync://>>> a full copy of central as there is a large amount
- of data there and doing so will get you banned. You can use a program such as those described on the {{{../../repository-management.html}Repository Management}} page to
- run your internal repository's server, download from the internet as required, and then hold
- the artifacts in your internal repository for faster downloading later.
-
- The other options are to manually download and vet releases, then copy them to the internal
- repository; or to have Maven download them for a user, then manually upload the vetted artifacts to the
- internal repository which is used for releases. This step is useful for artifacts whose
- license forbids their automatic distribution, such as several J2EE JARs.
-
-* Using the Internal Repository
-
- Using the internal repository is quite simple. Simply make a change to add a <<<repositories>>> element:
-
-+----+
-
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <repositories>
- <repository>
- <id>my-internal-site</id>
- <url>https://myserver/repo</url>
- </repository>
- </repositories>
- ...
-</project>
-
-+----+
-
- If your internal repository requires authentication, the <<<id>>> element can be used in your {{{../../settings.html#Servers}settings}} file
- to specify login information.
-
-* Deploying to the Internal Repository
-
- One of the most important reasons to have one or more internal repositories is to be able to publish
- your own private releases.
-
- To publish to the repository, you will need to have access via one of SCP, SFTP, FTP, WebDAV, or the filesystem. Connectivity is accomplished with the various
- {{{/wagon/wagon-providers/index.html}wagons}}. Some wagons may need to be added as {{{/ref/current/maven-model/maven.html#class_extension}extension}} to your build.
-~~ For example, to set up an SCP transfer.
-~~ show the scp example.
diff --git a/content/apt/guides/introduction/introduction-to-the-lifecycle.apt b/content/apt/guides/introduction/introduction-to-the-lifecycle.apt
deleted file mode 100644
index 93441420..00000000
--- a/content/apt/guides/introduction/introduction-to-the-lifecycle.apt
+++ /dev/null
@@ -1,470 +0,0 @@
- ------
- Introduction to the Build Lifecycle
- ------
- Brett Porter
- ------
- 2006-06-16
- 2015-04-04
- ------
-
- ~~ Copyright 2015 The Apache Software Foundation.
- ~~
- ~~ Licensed under the Apache License, Version 2.0 (the "License");
- ~~ you may not use this file except in compliance with the License.
- ~~ You may obtain a copy of the License at
- ~~
- ~~ 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
-
-Introduction to the Build Lifecycle
-
-%{toc|section=0|fromDepth=2|toDepth=2}
-
-* Build Lifecycle Basics
-
- Maven is based around the central concept of a build lifecycle. What this means is that the process for building
- and distributing a particular artifact (project) is clearly defined.
-
- For the person building a project, this means that it is only necessary to learn a small set of commands to build any
- Maven project, and the {{{./introduction-to-the-pom.html}POM}} will ensure they get the results they desired.
-
- There are three built-in build lifecycles: default, clean and site. The <<<default>>> lifecycle handles your project
- deployment, the <<<clean>>> lifecycle handles project cleaning, while the <<<site>>> lifecycle handles the creation of your
- project's web site.
-
-** A Build Lifecycle is Made Up of Phases
-
- Each of these build lifecycles is defined by a different list of build phases, wherein a build phase represents a
- stage in the lifecycle.
-
- For example, the default lifecycle comprises of the following phases (for a complete list of the lifecycle phases, refer
- to the {{{Lifecycle_Reference}Lifecycle Reference}}):
-
- * <<<validate>>> - validate the project is correct and all necessary information is available
-
- * <<<compile>>> - compile the source code of the project
-
- * <<<test>>> - test the compiled source code using a suitable unit testing framework. These tests should not
- require the code be packaged or deployed
-
- * <<<package>>> - take the compiled code and package it in its distributable format, such as a JAR.
-
- * <<<verify>>> - run any checks on results of integration tests to ensure quality criteria are met
-
- * <<<install>>> - install the package into the local repository, for use as a dependency in other projects locally
-
- * <<<deploy>>> - done in the build environment, copies the final package to the remote repository
- for sharing with other developers and projects.
-
- These lifecycle phases (plus the other lifecycle phases not shown here) are executed sequentially
- to complete the <<<default>>> lifecycle.
- Given the lifecycle phases above, this means that when the default lifecycle is used, Maven will first validate
- the project, then will try to compile the sources, run those against the tests, package the binaries (e.g. jar), run
- integration tests against that package, verify the integration tests, install the verified package to the local
- repository, then deploy the installed package to a remote repository.
-
- <{{{./introduction-to-the-lifecycle.html}[top]}}.>
-
-** Usual Command Line Calls
-
- You should select the phase that matches your outcome. If you want your jar, run <<<package>>>. If you want to run the
- unit tests, run <<<test>>>.
-
- If you are uncertain what you want, the preferred phase to call is
-
-------
-mvn verify
-------
-
- This command executes each default lifecycle phase in order (<<<validate>>>, <<<compile>>>, <<<package>>>, etc.),
- before executing <<<verify>>>. You only need to call the last build phase to be executed, in this case, <<<verify>>>.
- In most cases the effect is the same as <<<package>>>. However, in case there are integration tests, these will be
- executed as well. And during the <<<verify>>> phase additional checks can be done, e.g. if your code is written
- according to predefined checkstyle rules.
-
- In a build environment, use the following call to cleanly build and deploy artifacts into the shared repository.
-
-------
-mvn clean deploy
-------
-
- The same command can be used in a multi-module scenario (i.e. a project with one or more subprojects). Maven
- traverses into every subproject and executes <<<clean>>>, then executes <<<deploy>>> (including all of
- the prior build phase steps).
-
- <{{{./introduction-to-the-lifecycle.html}[top]}}.>
-
-** A Build Phase is Made Up of Plugin Goals
-
- However, even though a build phase is responsible for a specific step in the build lifecycle, the manner in which it
- carries out those responsibilities may vary. And this is done by declaring the plugin goals bound to those build phases.
-
- A plugin goal represents a specific task (finer than a build phase) which contributes to the building and managing of a
- project. It may be bound to zero or more build phases. A goal not bound to any build phase could be executed outside of
- the build lifecycle by direct invocation. The order of execution depends on the order in which the goal(s) and the build phase(s) are
- invoked. For example, consider the command below. The <<<clean>>> and <<<package>>> arguments are build phases, while the
- <<<dependency:copy-dependencies>>> is a goal (of a plugin).
-
-------
-mvn clean dependency:copy-dependencies package
-------
-
- If this were to be executed, the <<<clean>>> phase will be executed first (meaning it will run all preceding phases of the clean lifecycle,
- plus the <<<clean>>> phase itself), and then the <<<dependency:copy-dependencies>>> goal, before finally executing the
- <<<package>>> phase (and all its preceding build phases of the default lifecycle).
-
- Moreover, if a goal is bound to one or more build phases, that goal will be called in all those phases.
-
- Furthermore, a build phase can also have zero or more goals bound to it. If a build phase has no goals bound to it,
- that build phase will not execute. But if it has one or more goals bound to it, it will execute all those goals.
-~~~
- Multiple goals bound to a phase are executed in the same order as they are declared in the POM.
-
- It's possible to declare multiple executions for the same plugin - see {{{./guides/mini/guide-configuring-plugins.html#Configuring_Build_Plugins}Configuring plugins}} for more details.
- <<Note>>: This does <<not>> mean that it's allowed to declare the same plugin multiple times in {{{/pom.html#Plugins} <<<<plugins\>>>> declaration section}}!
- Declaring a plugin multiple times shows warnings using Maven 3 and fail the build using Maven 4.
-
-~~~
-
- <{{{./introduction-to-the-lifecycle.html}[top]}}.>
-
-** Some Phases Are Not Usually Called From the Command Line
-
- The phases named with hyphenated-words (<<<pre-*>>>, <<<post-*>>>, or <<<process-*>>>) are not usually directly
- called from the command line. These phases sequence the build, producing intermediate results that are not useful outside
- the build. In the case of invoking <<<integration-test>>>, the environment may be left in a hanging state.
-
- Code coverage tools such as Jacoco and execution container plugins such as Tomcat, Cargo, and Docker bind goals to the
- <<<pre-integration-test>>> phase to prepare the integration test container environment. These plugins also bind goals
- to the <<<post-integration-test>>> phase to collect coverage statistics or decommission the integration test container.
-
- Failsafe and code coverage plugins bind goals to <<<integration-test>>> and <<<verify>>> phases. The net result is
- test and coverage reports are available after the <<<verify>>> phase. If <<<integration-test>>> were to be called from the
- command line, no reports are generated. Worse is that the integration test container environment is left in a hanging
- state; the Tomcat webserver or Docker instance is left running, and Maven may not even terminate by itself.
-
- <{{{./introduction-to-the-lifecycle.html}[top]}}.>
-
-* Setting Up Your Project to Use the Build Lifecycle
-
- The build lifecycle is simple enough to use, but when you are constructing a Maven build for a project, how do you go
- about assigning tasks to each of those build phases?
-
-** Packaging
-
- The first, and most common way, is to set the packaging for your project via the equally named POM element <<<\<packaging\>>>>. Some of the valid
- packaging values are <<<jar>>>, <<<war>>>, <<<ear>>> and <<<pom>>>. If no packaging value has been specified, it will default
- to <<<jar>>>.
-
- Each packaging contains a list of goals to bind to a particular phase. For example, the <<<jar>>> packaging will bind the following
- goals to build phases of the default lifecycle.
-
-*------------------------------+---------------------------------------------------------------------------------------+
-|| Phase || plugin:goal for the <<<jar>>> packaging
-*------------------------------+---------------------------------------------------------------------------------------+
-| <<<process-resources>>> | <<<resources:resources>>>
-*------------------------------+---------------------------------------------------------------------------------------+
-| <<<compile>>> | <<<compiler:compile>>>
-*------------------------------+---------------------------------------------------------------------------------------+
-| <<<process-test-resources>>> | <<<resources:testResources>>>
-*------------------------------+---------------------------------------------------------------------------------------+
-| <<<test-compile>>> | <<<compiler:testCompile>>>
-*------------------------------+---------------------------------------------------------------------------------------+
-| <<<test>>> | <<<surefire:test>>>
-*------------------------------+---------------------------------------------------------------------------------------+
-| <<<package>>> | <<<jar:jar>>>
-*------------------------------+---------------------------------------------------------------------------------------+
-| <<<install>>> | <<<install:install>>>
-*------------------------------+---------------------------------------------------------------------------------------+
-| <<<deploy>>> | <<<deploy:deploy>>>
-*------------------------------+---------------------------------------------------------------------------------------+
-
- This is an almost {{{/ref/current/maven-core/default-bindings.html}standard set of bindings}};
- however, some packagings handle them differently. For example, a project
- that is purely metadata (packaging value is <<<pom>>>) only binds goals to the <<<install>>> and <<<deploy>>> phases (for a
- complete list of goal-to-build-phase bindings of some of the packaging types, refer to the
- {{{Lifecycle_Reference}Lifecycle Reference}}).
-
- Note that for some packaging types to be available, you may also need to include a particular plugin in the
- <<<\<build\>>>> section of your POM and specify <<<\<extensions\>true\</extensions\>>>> for that plugin.
- One example of a plugin that requires this is the Plexus plugin, which provides a <<<plexus-application>>> and
- <<<plexus-service>>> packaging.
-
- <{{{./introduction-to-the-lifecycle.html}[top]}}.>
-
-** Plugins
-
- The second way to add goals to phases is to configure plugins in your project. Plugins are artifacts that provide
- goals to Maven. Furthermore, a plugin may have one or more goals wherein each goal represents a capability of that
- plugin. For example, the Compiler plugin has two goals: <<<compile>>> and <<<testCompile>>>. The former
- compiles the source code of your main code, while the latter compiles the source code of your test code.
-
- As you will see in the later sections, plugins can contain information that indicates which lifecycle phase to bind a
- goal to. Note that adding the plugin on its own is not enough information - you must also specify the goals you want
- to run as part of your build.
-
- The goals that are configured will be added to the goals already bound to the lifecycle from the packaging selected.
- If more than one goal is bound to a particular phase, the order used is that those from the packaging are executed
- first, followed by those configured in the POM. Note that you can use the <<<\<executions\>>>> element to gain more
- control over the order of particular goals.
-
- For example, the Modello plugin binds by default its goal <<<modello:java>>> to the <<<generate-sources>>> phase (Note: The
- <<<modello:java>>> goal generates Java source codes). So to use the Modello plugin and have it generate sources from
- a model and incorporate that into the build, you would add the following to your POM in the <<<\<plugins\>>>> section of
- <<<\<build\>>>>:
-
-+----+
- <plugin>
- <groupId>org.codehaus.modello</groupId>
- <artifactId>modello-maven-plugin</artifactId>
- <version>1.8.1</version>
- <executions>
- <execution>
- <configuration>
- <models>
- <model>src/main/mdo/maven.mdo</model>
- </models>
- <version>4.0.0</version>
- </configuration>
- <goals>
- <goal>java</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
-+----+
-
- You might be wondering why that <<<\<executions\>>>> element is there. That is so that you can run the same goal multiple times
- with different configuration if needed. Separate executions can also be given an ID so that during inheritance or the
- application of profiles you can control whether goal configuration is merged or turned into an additional execution.
-
- See {{{./guides/mini/guide-configuring-plugins.html#Configuring_Build_Plugins}Configuring plugins}} for more details about the configuration of multiple executions and their execution order.
-
- Now, in the case of <<<modello:java>>>, it only makes sense in the <<<generate-sources>>> phase. But some goals can be
- used in more than one phase, and there may not be a sensible default. For those, you can specify the phase yourself.
- For example, let's say you have a goal <<<display:time>>> that echos the current time to the commandline, and you want
- it to run in the <<<process-test-resources>>> phase to indicate when the tests were started. This would be configured
- like so:
-
-+----+
- <plugin>
- <groupId>com.mycompany.example</groupId>
- <artifactId>display-maven-plugin</artifactId>
- <version>1.0</version>
- <executions>
- <execution>
- <phase>process-test-resources</phase>
- <goals>
- <goal>time</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
-+----+
-
- <{{{./introduction-to-the-lifecycle.html}[top]}}.>
-
-* Lifecycle Reference
-
- The following lists all build phases of the <<<default>>>, <<<clean>>> and <<<site>>> lifecycles, which are executed in the order given
- up to the point of the one specified.
-
-** Clean Lifecycle
-
-*-------------------------------+---------------------------------------------------------------------------------------+
-|| Phase || Description
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<pre-clean>>> | execute processes needed prior to the actual project cleaning
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<clean>>> | remove all files generated by the previous build
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<post-clean>>> | execute processes needed to finalize the project cleaning
-*-------------------------------+--------------------------------------------------------------------------------------+
-
-** Default Lifecycle
-
-*-------------------------------+---------------------------------------------------------------------------------------+
-|| Phase || Description
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<validate>>> | validate the project is correct and all necessary information is available.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<initialize>>> | initialize build state, e.g. set properties or create directories.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<generate-sources>>> | generate any source code for inclusion in compilation.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<process-sources>>> | process the source code, for example to filter any values.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<generate-resources>>> | generate resources for inclusion in the package.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<process-resources>>> | copy and process the resources into the destination directory, ready for packaging.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<compile>>> | compile the source code of the project.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<process-classes>>> | post-process the generated files from compilation, for example to do bytecode enhancement on Java classes.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<generate-test-sources>>> | generate any test source code for inclusion in compilation.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<process-test-sources>>> | process the test source code, for example to filter any values.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<generate-test-resources>>> | create resources for testing.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<process-test-resources>>> | copy and process the resources into the test destination directory.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<test-compile>>> | compile the test source code into the test destination directory
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<process-test-classes>>> | post-process the generated files from test compilation, for example to do bytecode enhancement on Java classes.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<test>>> | run tests using a suitable unit testing framework. These tests should not require the code be packaged or deployed.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<prepare-package>>> | perform any operations necessary to prepare a package before the actual packaging. This often results in an unpacked, processed version of the package.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<package>>> | take the compiled code and package it in its distributable format, such as a JAR.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<pre-integration-test>>> | perform actions required before integration tests are executed. This may involve things such as setting up the required environment.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<integration-test>>> | process and deploy the package if necessary into an environment where integration tests can be run.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<post-integration-test>>> | perform actions required after integration tests have been executed. This may including cleaning up the environment.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<verify>>> | run any checks to verify the package is valid and meets quality criteria.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<install>>> | install the package into the local repository, for use as a dependency in other projects locally.
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<deploy>>> | done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects.
-*-------------------------------+--------------------------------------------------------------------------------------+
-
-** Site Lifecycle
-
-*-------------------------------+---------------------------------------------------------------------------------------+
-|| Phase || Description
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<pre-site>>> | execute processes needed prior to the actual project site generation
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<site>>> | generate the project's site documentation
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<post-site>>> | execute processes needed to finalize the site generation, and to prepare for site deployment
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<site-deploy>>> | deploy the generated site documentation to the specified web server
-*-------------------------------+--------------------------------------------------------------------------------------+
-
- <{{{./introduction-to-the-lifecycle.html}[top]}}.>
-
-* Built-in Lifecycle Bindings
-
- Some phases have goals bound to them by default. And for the default lifecycle, these bindings depend on
- the packaging value. Here are some of the goal-to-build-phase bindings.
-
-** Clean Lifecycle Bindings
-
-*-------------------------------+--------------------------------------------------------------------------------------+
-|| Phase || plugin:goal
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<clean>>> | <<<clean:clean>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-
-** Default Lifecycle Bindings - Packaging <<<ejb>>> / <<<jar>>> / <<<rar>>> / <<<war>>>
-
-*-------------------------------+--------------------------------------------------------------------------------------+
-|| Phase || plugin:goal
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<process-resources>>> | <<<resources:resources>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<compile>>> | <<<compiler:compile>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<process-test-resources>>> | <<<resources:testResources>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<test-compile>>> | <<<compiler:testCompile>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<test>>> | <<<surefire:test>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<package>>> | <<<ejb:ejb>>> <or> <<<jar:jar>>> <or> <<<rar:rar>>> <or> <<<war:war>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<install>>> | <<<install:install>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<deploy>>> | <<<deploy:deploy>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-
-** Default Lifecycle Bindings - Packaging <<<ear>>>
-
-*-------------------------------+--------------------------------------------------------------------------------------+
-|| Phase || plugin:goal
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<generate-resources>>> | <<<ear:generate-application-xml>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<process-resources>>> | <<<resources:resources>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<package>>> | <<<ear:ear>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<install>>> | <<<install:install>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<deploy>>> | <<<deploy:deploy>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-
-** Default Lifecycle Bindings - Packaging <<<maven-plugin>>>
-
-*-------------------------------+--------------------------------------------------------------------------------------+
-|| Phase || plugin:goal
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<generate-resources>>> | <<<plugin:descriptor>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<process-resources>>> | <<<resources:resources>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<compile>>> | <<<compiler:compile>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<process-test-resources>>> | <<<resources:testResources>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<test-compile>>> | <<<compiler:testCompile>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<test>>> | <<<surefire:test>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<package>>> | <<<jar:jar>>> <and> <<<plugin:addPluginArtifactMetadata>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<install>>> | <<<install:install>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<deploy>>> | <<<deploy:deploy>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-
-** Default Lifecycle Bindings - Packaging <<<pom>>>
-
-*-------------------------------+--------------------------------------------------------------------------------------+
-|| Phase || plugin:goal
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<package>>> |
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<install>>> | <<<install:install>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<deploy>>> | <<<deploy:deploy>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-
-** Site Lifecycle Bindings
-
-*-------------------------------+--------------------------------------------------------------------------------------+
-|| Phase || plugin:goal
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<site>>> | <<<site:site>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-| <<<site-deploy>>> | <<<site:deploy>>>
-*-------------------------------+--------------------------------------------------------------------------------------+
-
-** References
-
- The full Maven lifecycle is defined by the <<<components.xml>>> file in the <<<maven-core>>> module, with
- {{{/ref/current/maven-core/lifecycles.html}associated documentation}} for reference.
-
- Default lifecycle bindings are defined in a separate
- <<<{{{https://github.com/apache/maven/blob/master/maven-core/src/main/resources/META-INF/plexus/default-bindings.xml}default-bindings.xml}}>>>
- descriptor.
-
- See {{{/ref/current/maven-core/lifecycles.html}Lifecycles Reference}} and
- {{{/ref/current/maven-core/default-bindings.html}Plugin Bindings for default Lifecycle Reference}} for latest documentation taken directly from
- source code.
-
- <{{{./introduction-to-the-lifecycle.html}[top]}}.>
diff --git a/content/apt/guides/introduction/introduction-to-the-pom.apt b/content/apt/guides/introduction/introduction-to-the-pom.apt
deleted file mode 100644
index 753f1fc0..00000000
--- a/content/apt/guides/introduction/introduction-to-the-pom.apt
+++ /dev/null
@@ -1,543 +0,0 @@
- ------
- Introduction to the POM
- ------
- Jason van Zyl
- Franz Allan Valencia See
- Brett Porter
- ------
- 2009-02-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
-
-Introduction to the POM
-
-%{toc|section=0|fromDepth=2|toDepth=3}
-
-* What is a POM?
-
- A Project Object Model or POM is the fundamental unit of work in Maven. It is an XML file that contains information
- about the project and configuration details used by Maven to build the project. It contains default values for most projects.
- Examples for this is the build directory, which is <<<target>>>; the source directory, which is <<<src/main/java>>>; the test
- source directory, which is <<<src/test/java>>>; and so on. When executing a task or goal, Maven
- looks for the POM in the current directory. It reads the POM, gets the needed configuration information, then executes the
- goal.
-
- Some of the configuration that can be specified in the POM are the project dependencies, the plugins or goals that
- can be executed, the build profiles, and so on. Other information such as the project version, description, developers,
- mailing lists and such can also be specified.
-
- {{{./introduction-to-the-pom.html}[top]}}
-
-* Super POM
-
- The Super POM is Maven's default POM. All POMs extend the Super POM unless explicitly set, meaning the configuration specified
- in the Super POM is inherited by the POMs you created for your projects.
-
- You can see the {{{/maven-model-builder/super-pom.html}Super POM for the latest Maven 3 release}} in Maven Core reference documentation.
-
- {{{./introduction-to-the-pom.html}[top]}}
-
-* Minimal POM
-
- The minimum requirement for a POM are the following:
-
- * <<<project>>> root
-
- * <<<modelVersion>>> - should be set to 4.0.0
-
- * <<<groupId>>> - the id of the project's group.
-
- * <<<artifactId>>> - the id of the artifact (project)
-
- * <<<version>>> - the version of the artifact under the specified group
-
- []
-
- Here's an example:
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1</version>
-</project>
-+-----+
-
- A POM requires that its groupId, artifactId, and version be configured. These three values form the project's fully
- qualified artifact name. This is in the form of \<groupId\>:\<artifactId\>:\<version\>. As for the example above, its
- fully qualified artifact name is "com.mycompany.app:my-app:1".
-
- Also, as mentioned in the {{{What_is_a_POM}first section}}, if the configuration details
- are not specified, Maven will use their defaults. One of these default values is the packaging type. Every Maven project
- has a packaging type. If it is not specified in the POM, then the default value "jar" would be used.
-
- Furthermore, you can see that in the minimal POM the <repositories> were not specified. If you build your project using the minimal POM,
- it would inherit the <repositories> configuration in the Super POM. Therefore when Maven sees the dependencies in
- the minimal POM, it would know that these dependencies will be downloaded from <<<https://repo.maven.apache.org/maven2>>> which was specified
- in the Super POM.
-
- {{{./introduction-to-the-pom.html}[top]}}
-
-* Project Inheritance
-
- Elements in the POM that are merged are the following:
-
- * dependencies
-
- * developers and contributors
-
- * plugin lists (including reports)
-
- * plugin executions with matching ids
-
- * plugin configuration
-
- * resources
-
- []
-
- The Super POM is one example of project inheritance, however you can also introduce your own parent POMs by specifying
- the parent element in the POM, as demonstrated in the following examples.
-
- []
-
-** Example 1
-
-*** The Scenario
-
- As an example, let us reuse our previous artifact, com.mycompany.app:my-app:1. And let us introduce another artifact,
- com.mycompany.app:my-module:1.
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-module</artifactId>
- <version>1</version>
-</project>
-+-----+
-
- And let us specify their directory structure as the following:
-
------
-.
- |-- my-module
- | `-- pom.xml
- `-- pom.xml
------
-
- <<Note:>> <<<my-module/pom.xml>>> is the POM of com.mycompany.app:my-module:1 while <<<pom.xml>>> is the POM of
- com.mycompany.app:my-app:1
-
-*** The Solution
-
- Now, if we were to turn com.mycompany.app:my-app:1 into a parent artifact of com.mycompany.app:my-module:1,we will have to
- modify com.mycompany.app:my-module:1's POM to the following configuration:
-
- <<com.mycompany.app:my-module:1's POM>>
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1</version>
- </parent>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-module</artifactId>
- <version>1</version>
-</project>
-+-----+
-
- Notice that we now have an added section, the parent section. This section allows us to specify which artifact is the
- parent of our POM. And we do so by specifying the fully qualified artifact name of the parent POM. With this setup, our
- module can now inherit some of the properties of our parent POM.
-
- Alternatively, if you want the groupId or the version of your modules to be the same as their parents, you can
- remove the groupId or the version identity of your module in its POM.
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1</version>
- </parent>
-
- <artifactId>my-module</artifactId>
-</project>
-+-----+
-
- This allows the module to inherit the groupId or the version of its parent POM.
-
- {{{./introduction-to-the-pom.html}[top]}}
-
-** Example 2
-
-*** The Scenario
-
- However, that would work if the parent project was already installed in our local repository or was in that specific
- directory structure (parent <<<pom.xml>>> is one directory higher than that of the module's <<<pom.xml>>>).
-
- But what if the parent is not yet installed and if the directory structure is as in the following example?
-
------
-.
- |-- my-module
- | `-- pom.xml
- `-- parent
- `-- pom.xml
------
-
-*** The Solution
-
- To address this directory structure (or any other directory structure), we would have to add the <<<\<relativePath\>>>> element to
- our parent section.
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1</version>
- <relativePath>../parent/pom.xml</relativePath>
- </parent>
-
- <artifactId>my-module</artifactId>
-</project>
-+-----+
-
- As the name suggests, it's the relative path from the module's <<<pom.xml>>> to the parent's <<<pom.xml>>>.
-
-* Project Aggregation
-
- Project Aggregation is similar to {{{Project_Inheritance}Project Inheritance}}. But
- instead of specifying the parent POM from the module, it specifies the modules from the parent POM. By doing so, the
- parent project now knows its modules, and if a Maven command is invoked against the parent project, that Maven command
- will then be executed to the parent's modules as well. To do Project Aggregation, you must do the following:
-
- * Change the parent POMs packaging to the value "pom".
-
- * Specify in the parent POM the directories of its modules (children POMs).
-
- []
-
- {{{./introduction-to-the-pom.html}[top]}}
-
-** Example 3
-
-*** The Scenario
-
- Given the previous original artifact POMs and directory structure:
-
- <<com.mycompany.app:my-app:1's POM>>
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1</version>
-</project>
-+-----+
-
- <<com.mycompany.app:my-module:1's POM>>
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-module</artifactId>
- <version>1</version>
-</project>
-+-----+
-
- <<directory structure>>
-
------
-.
- |-- my-module
- | `-- pom.xml
- `-- pom.xml
------
-
-*** The Solution
-
- If we are to aggregate my-module into my-app, we would only have to modify my-app.
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1</version>
- <packaging>pom</packaging>
-
- <modules>
- <module>my-module</module>
- </modules>
-</project>
-+-----+
-
- In the revised com.mycompany.app:my-app:1, the packaging section and the modules sections were added. For
- the packaging, its value was set to "pom", and for the modules section, we have the element
- <<<\<module\>my-module\</module\>>>>. The value of <<<\<module\>>>> is the relative path from the com.mycompany.app:my-app:1
- to com.mycompany.app:my-module:1's POM (<by practice, we use the module's artifactId as the module directory's name>).
-
- Now, whenever a Maven command processes com.mycompany.app:my-app:1, that same Maven command would be ran against
- com.mycompany.app:my-module:1 as well. Furthermore, some commands (goals specifically) handle project aggregation
- differently.
-
- {{{./introduction-to-the-pom.html}[top]}}
-
-** Example 4
-
-*** The Scenario
-
- But what if we change the directory structure to the following:
-
------
-.
- |-- my-module
- | `-- pom.xml
- `-- parent
- `-- pom.xml
------
-
- How would the parent POM specify its modules?
-
-*** The Solution
-
- The answer? - the same way as Example 3, by specifying the path to the module.
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1</version>
- <packaging>pom</packaging>
-
- <modules>
- <module>../my-module</module>
- </modules>
-</project>
-+-----+
-
-* Project Inheritance vs Project Aggregation
-
- If you have several Maven projects, and they all have similar configurations, you can refactor your projects by pulling
- out those similar configurations and making a parent project. Thus, all you have to do is to let your Maven projects
- inherit that parent project, and those configurations would then be applied to all of them.
-
- And if you have a group of projects that are built or processed together, you can create a parent project and have that
- parent project declare those projects as its modules. By doing so, you'd only have to build the parent and the rest
- will follow.
-
- But of course, you can have both Project Inheritance and Project Aggregation. Meaning, you can have your modules
- specify a parent project, and at the same time, have that parent project specify those Maven projects as its modules.
- You'd just have to apply all three rules:
-
- * Specify in every child POM who their parent POM is.
-
- * Change the parent POMs packaging to the value "pom" .
-
- * Specify in the parent POM the directories of its modules (children POMs)
-
- []
-
- {{{./introduction-to-the-pom.html}[top]}}
-
-** Example 5
-
-*** The Scenario
-
- Given the previous original artifact POMs again,
-
- <<com.mycompany.app:my-app:1's POM>>
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1</version>
-</project>
-+-----+
-
- <<com.mycompany.app:my-module:1's POM>>
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-module</artifactId>
- <version>1</version>
-</project>
-+-----+
-
- and this <<directory structure>>
-
------
-.
- |-- my-module
- | `-- pom.xml
- `-- parent
- `-- pom.xml
------
-
-*** The Solution
-
- To do both project inheritance and aggregation, you only have to apply all three rules.
-
- <<com.mycompany.app:my-app:1's POM>>
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
-
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1</version>
- <packaging>pom</packaging>
-
- <modules>
- <module>../my-module</module>
- </modules>
-</project>
-+-----+
-
- <<com.mycompany.app:my-module:1's POM>>
-
-+-----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- <modelVersion>4.0.0</modelVersion>
-
- <parent>
- <groupId>com.mycompany.app</groupId>
- <artifactId>my-app</artifactId>
- <version>1</version>
- <relativePath>../parent/pom.xml</relativePath>
- </parent>
-
- <artifactId>my-module</artifactId>
-</project>
-+-----+
-
- <<NOTE:>> Profile inheritance the same inheritance strategy as used for the POM itself.
-
- {{{./introduction-to-the-pom.html}[top]}}
-
-* Project Interpolation and Variables
-
- One of the practices that Maven encourages is <don't repeat yourself>. However, there are circumstances where you will need to use the same value in several different locations.
- To assist in ensuring the value is only specified once, Maven allows you to use both your own and pre-defined variables in the POM.
-
- For example, to access the <<<project.version>>> variable, you would reference it like so:
-
-+----+
- <version>${project.version}</version>
-+----+
-
- One factor to note is that these variables are processed <after> inheritance as outlined above. This means that if a parent project uses a variable, then its definition in the child, not the parent, will be the one eventually used.
-
-** Available Variables
-
-*** Project Model Variables
-
- Any field of the model that is a single value element can be referenced as a variable. For example, <<<$\{project.groupId\}>>>, <<<$\{project.version\}>>>, <<<$\{project.build.sourceDirectory\}>>> and so on.
- Refer to the {{{/pom.html}POM reference}} to see a full list of properties.
-
- These variables are all referenced by the prefix "<<<project.>>>". You may also see references with <<<pom.>>> as the prefix, or the prefix omitted entirely - these forms are now deprecated and should not be used.
-
-*** Special Variables
-
-*-----------------------------------+--------------------------------------+
-| <<<project.basedir>>> | The directory that the current project resides in. |
-*-----------------------------------+--------------------------------------+
-| <<<project.baseUri>>> | The directory that the current project resides in, represented as an URI. <Since Maven 2.1.0> |
-*-----------------------------------+--------------------------------------+
-| <<<maven.build.timestamp>>> | The timestamp that denotes the start of the build (UTC). <Since Maven 2.1.0-M1> |
-*-----------------------------------+--------------------------------------+
-
- The format of the build timestamp can be customized by declaring the property <<<maven.build.timestamp.format>>> as
- shown in the example below:
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <properties>
- <maven.build.timestamp.format>yyyy-MM-dd'T'HH:mm:ss'Z'</maven.build.timestamp.format>
- </properties>
- ...
-</project>
-+----+
-
- The format pattern has to comply with the rules given in the API documentation for
- {{{https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html}SimpleDateFormat}}.
- If the property is not present, the format defaults to the value already given in the example.
-
-*** Properties
-
- You are also able to reference any properties defined in the project as a variable. Consider the following example:
-
-+----+
-<project xmlns="http://maven.apache.org/POM/4.0.0">
- ...
- <properties>
- <mavenVersion>3.0</mavenVersion>
- </properties>
-
- <dependencies>
- <dependency>
- <groupId>org.apache.maven</groupId>
- <artifactId>maven-artifact</artifactId>
- <version>${mavenVersion}</version>
- </dependency>
- <dependency>
- <groupId>org.apache.maven</groupId>
- <artifactId>maven-core</artifactId>
- <version>${mavenVersion}</version>
- </dependency>
- </dependencies>
- ...
-</project>
-+----+
-
- {{{./introduction-to-the-pom.html}[top]}}
-
diff --git a/content/apt/guides/introduction/introduction-to-the-standard-directory-layout.apt b/content/apt/guides/introduction/introduction-to-the-standard-directory-layout.apt
deleted file mode 100644
index 531208bc..00000000
--- a/content/apt/guides/introduction/introduction-to-the-standard-directory-layout.apt
+++ /dev/null
@@ -1,86 +0,0 @@
- ------
- Introduction to the Standard Directory Layout
- ------
- Jason van Zyl
- ------
- 2014-03-09
- ------
-
-~~ 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
-
-Introduction to the Standard Directory Layout
-
- Having a common directory layout allows users familiar with one Maven project to immediately feel
- at home in another Maven project. The advantages are analogous to adopting a site-wide look-and-feel.
-
- The next section documents the directory layout expected by Maven and the directory layout created by
- Maven. Try to conform to this structure as much as possible. However, if you can't, these settings can
- be overridden via the project descriptor.
-
-*-----------------------------------+-----------------------------------------------+
-| <<<src/main/java>>> | Application/Library sources
-*-----------------------------------+-----------------------------------------------+
-| <<<src/main/resources>>> | Application/Library resources
-*-----------------------------------+-----------------------------------------------+
-| <<<src/main/filters>>> | Resource filter files
-*-----------------------------------+-----------------------------------------------+
-| <<<src/main/webapp>>> | Web application sources
-*-----------------------------------+-----------------------------------------------+
-| <<<src/test/java>>> | Test sources
-*-----------------------------------+-----------------------------------------------+
-| <<<src/test/resources>>> | Test resources
-*-----------------------------------+-----------------------------------------------+
-| <<<src/test/filters>>> | Test resource filter files
-*-----------------------------------+-----------------------------------------------+
-| <<<src/it>>> | Integration Tests (primarily for plugins)
-*-----------------------------------+-----------------------------------------------+
-| <<<src/assembly>>> | Assembly descriptors
-*-----------------------------------+-----------------------------------------------+
-| <<<src/site>>> | Site
-*-----------------------------------+-----------------------------------------------+
-| <<<LICENSE.txt>>> | Project's license
-*-----------------------------------+-----------------------------------------------+
-| <<<NOTICE.txt>>> | Notices and attributions required by libraries that the project depends on
-*-----------------------------------+-----------------------------------------------+
-| <<<README.txt>>> | Project's readme
-*-----------------------------------+-----------------------------------------------+
-
-
- At the top level, files descriptive of the project: a <<<pom.xml>>> file.
- In addition, there are textual documents meant for the user to be able to
- read immediately on receiving the source: <<<README.txt>>>, <<<LICENSE.txt>>>, etc.
-
- There are just two subdirectories of this structure: <<<src>>> and <<<target>>>. The only other
- directories that would be expected here are metadata like <<<CVS>>>, <<<.git>>> or <<<.svn>>>, and any
- subprojects in a multiproject build (each of which would be laid out as above).
-
- The <<<target>>> directory is used to house all output of the build.
-
- The <<<src>>> directory contains all of the source material for building the project, its site and so on.
- It contains a subdirectory for each type: <<<main>>> for the main build artifact, <<<test>>> for
- the unit test code and resources, <<<site>>> and so on.
-
- Within artifact producing source directories (ie. <<<main>>> and <<<test>>>), there is one
- directory for the language <<<java>>> (under which the normal package hierarchy exists), and one for
- <<<resources>>> (the structure which is copied to the target classpath given the default resource definition).
-
- If there are other contributing sources to the artifact build, they would be under other subdirectories. For
- example <<<src/main/antlr>>> would contain Antlr grammar definition files.
diff --git a/content/markdown/guides/development/guide-testing-releases.md b/content/markdown/guides/development/guide-testing-releases.md
index e7d2ded2..d86725c2 100644
--- a/content/markdown/guides/development/guide-testing-releases.md
+++ b/content/markdown/guides/development/guide-testing-releases.md
@@ -109,7 +109,7 @@ If you are using the repository mirroring technique to lock down to the reposito
If you regularly test staged releases and want to have a more convenient way to add the repository to a build without modifying your POM, you may add a profile to your `~/.m2/settings.xml`:
-```unknown
+```xml
...
<profiles>
<profile>
diff --git a/content/markdown/guides/getting-started/index.md b/content/markdown/guides/getting-started/index.md
new file mode 100644
index 00000000..00a07de8
--- /dev/null
+++ b/content/markdown/guides/getting-started/index.md
@@ -0,0 +1,1029 @@
+<!--
+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 Getting Started Guide
+
+This guide is intended as a reference for those working with Maven for the first time, but is also intended to serve as a cookbook with self-contained references and solutions for common use cases. For first time users, it is recommended that you step through the material in a sequential fashion. For users more familiar with Maven, this guide endeavours to provide a quick solution for the need at hand. It is assumed at this point that you have downloaded Maven and installed Maven on your [...]
+
+Ok, so you now have Maven installed and we're ready to go. Before we jump into our examples we'll very briefly go over what Maven is and how it can help you with your daily work and collaborative efforts with team members. Maven will, of course, work for small projects, but Maven shines in helping teams operate more effectively by allowing team members to focus on what the stakeholders of a project require. You can leave the build infrastructure to Maven!
+
+# Sections
+
+<!-- MACRO{toc|section=0|fromDepth=2|toDepth=3} -->
+
+## What is Maven?
+
+At first glance Maven can appear to be many things, but in a nutshell Maven is an attempt _to apply patterns to a project's build infrastructure in order to promote comprehension and productivity by providing a clear path in the use of best practices_. Maven is essentially a project management and comprehension tool and as such provides a way to help with managing:
+
+- Builds
+- Documentation
+- Reporting
+- Dependencies
+- SCMs
+- Releases
+- Distribution
+
+If you want more background information on Maven you can check out [The Philosophy of Maven](../../background/philosophy-of-maven.html) and [The History of Maven](../../background/history-of-maven.html). Now let's move on to how you, the user, can benefit from using Maven.
+
+## How can Maven benefit my development process?
+
+Maven can provide benefits for your build process by employing standard conventions and practices to accelerate your development cycle while at the same time helping you achieve a higher rate of success.
+
+Now that we have covered a little bit of the history and purpose of Maven let's get into some real examples to get you up and running with Maven!
+
+## How do I setup Maven?
+
+The defaults for Maven are often sufficient, but if you need to change the cache location or are behind a HTTP proxy, you will need to create configuration. See the [Guide to Configuring Maven](../mini/guide-configuring-maven.html) for more information.
+
+## How do I make my first Maven project?
+
+We are going to jump headlong into creating your first Maven project! To create our first Maven project we are going to use Maven's archetype mechanism. An archetype is defined as _an original pattern or model from which all other things of the same kind are made_. In Maven, an archetype is a template of a project which is combined with some user input to produce a working Maven project that has been tailored to the user's requirements. We are going to show you how the archetype mechanis [...]
+
+On to creating your first project! In order to create the simplest of Maven projects, execute the following from the command line:
+
+```
+mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.5 -DinteractiveMode=false
+```
+
+Once you have executed this command, you will notice a few things have happened. First, you will notice that a directory named `my-app` has been created for the new project, and this directory contains a file named `pom.xml` that should look like this:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1.0-SNAPSHOT</version>
+
+ <name>my-app</name>
+ <!-- FIXME change it to the project's website -->
+ <url>http://www.example.com</url>
+
+ <properties>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ <maven.compiler.release>17</maven.compiler.release>
+ </properties>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.junit</groupId>
+ <artifactId>junit-bom</artifactId>
+ <version>5.11.0</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.junit.jupiter</groupId>
+ <artifactId>junit-jupiter-api</artifactId>
+ <scope>test</scope>
+ </dependency>
+ <!-- Optionally: parameterized tests support -->
+ <dependency>
+ <groupId>org.junit.jupiter</groupId>
+ <artifactId>junit-jupiter-params</artifactId>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <pluginManagement><!-- lock down plugins versions to avoid using Maven defaults (may be moved to parent pom) -->
+ ... lots of helpful plugins
+ </pluginManagement>
+ </build>
+</project>
+```
+
+`pom.xml` contains the Project Object Model (POM) for this project. The POM is the basic unit of work in Maven. This is important to remember because Maven is inherently project-centric in that everything revolves around the notion of a project. In short, the POM contains every important piece of information about your project and is essentially one-stop-shopping for finding anything related to your project. Understanding the POM is important and new users are encouraged to refer to the [...]
+
+This is a very simple POM but still displays the key elements every POM contains, so let's walk through each of them to familiarize you with the POM essentials:
+
+- **project** This is the top-level element in all Maven `pom.xml` files.
+- **modelVersion** This element indicates what version of the object model this POM is using. The version of the model itself changes very infrequently but it is mandatory in order to ensure stability of use if and when the Maven developers deem it necessary to change the model.
+- **groupId** This element indicates the unique identifier of the organization or group that created the project. The groupId is one of the key identifiers of a project and is typically based on the fully qualified domain name of your organization. For example `org.apache.maven.plugins` is the designated groupId for all Maven plugins.
+- **artifactId** This element indicates the unique base name of the primary artifact being generated by this project. The primary artifact for a project is typically a JAR file. Secondary artifacts like source bundles also use the artifactId as part of their final name. A typical artifact produced by Maven would have the form <artifactId>-<version>.<extension> (for example, `myapp-1.0.jar`).
+- **version** This element indicates the version of the artifact generated by the project. Maven goes a long way to help you with version management and you will often see the `SNAPSHOT` designator in a version, which indicates that a project is in a state of development. We will discuss the use of [snapshots](./index.html#what-is-a-snapshot-version) and how they work further on in this guide.
+- **name** This element indicates the display name used for the project. This is often used in Maven's generated documentation.
+- **url** This element indicates where the project's site can be found. This is often used in Maven's generated documentation.
+- **properties** This element contains value placeholders accessible anywhere within a POM.
+- **dependencies** This element's children list [dependencies](/pom.html#dependencies). The cornerstone of the POM.
+- **build** This element handles things like declaring your project's directory structure and managing plugins.
+
+For a complete reference of what elements are available for use in the POM please refer to our [POM Reference](/ref/current/maven-model/maven.html). Now let's get back to the project at hand.
+
+After the archetype generation of your first project you will also notice that the following directory structure has been created:
+
+```
+my-app
+|-- pom.xml
+`-- src
+ |-- main
+ | `-- java
+ | `-- com
+ | `-- mycompany
+ | `-- app
+ | `-- App.java
+ `-- test
+ `-- java
+ `-- com
+ `-- mycompany
+ `-- app
+ `-- AppTest.java
+```
+
+As you can see, the project created from the archetype has a POM, a source tree for your application's sources and a source tree for your test sources. This is the standard layout for Maven projects (the application sources reside in `${project.basedir}/src/main/java` and test sources reside in `${project.basedir}/src/test/java`, where `${project.basedir}` represents the directory containing `pom.xml`).
+
+If you were to create a Maven project by hand this is the directory structure that we recommend using. This is a Maven convention and to learn more about it you can read our [Introduction to the Standard Directory Layout](../introduction/introduction-to-the-standard-directory-layout.html).
+
+Now that we have a POM, some application sources, and some test sources you are probably asking...
+
+## How do I compile my application sources?
+
+Change to the directory where `pom.xml` is created by archetype:generate and execute the following command to compile your application sources:
+
+```
+mvn compile
+```
+
+Upon executing this command you should see output like the following:
+
+```
+[INFO] Scanning for projects...
+[INFO]
+[INFO] ----------------------< com.mycompany.app:my-app >----------------------
+[INFO] Building my-app 1.0-SNAPSHOT
+[INFO] --------------------------------[ jar ]---------------------------------
+[INFO]
+[INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ my-app ---
+[INFO] Using 'UTF-8' encoding to copy filtered resources.
+[INFO] skip non existing resourceDirectory <dir>/my-app/src/main/resources
+[INFO]
+[INFO] --- maven-compiler-plugin:3.8.0:compile (default-compile) @ my-app ---
+[INFO] Changes detected - recompiling the module!
+[INFO] Compiling 1 source file to <dir>/my-app/target/classes
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 0.899 s
+[INFO] Finished at: 2020-07-12T11:31:54+01:00
+[INFO] ------------------------------------------------------------------------
+```
+
+The first time you execute this (or any other) command, Maven will need to download all the plugins and related dependencies it needs to fulfill the command. From a clean installation of Maven, this can take quite a while (in the output above, it took almost 4 minutes). If you execute the command again, Maven will now have what it needs, so it won't need to download anything new and will be able to execute the command much more quickly.
+
+As you can see from the output, the compiled classes were placed in `${project.basedir}/target/classes`, which is another standard convention employed by Maven. So, if you're a keen observer, you'll notice that by using the standard conventions, the POM above is very small and you haven't had to tell Maven explicitly where any of your sources are or where the output should go. By following the standard Maven conventions, you can get a lot done with very little effort! Just as a casual co [...]
+
+Now, this is simply to compile a single tree of application sources and the Ant script shown is pretty much the same size as the POM shown above. But we'll see how much more we can do with just that simple POM!
+
+## How do I compile my test sources and run my unit tests?
+
+Now you're successfully compiling your application's sources and now you've got some unit tests that you want to compile and execute (because every programmer always writes and executes their unit tests *nudge nudge wink wink*).
+
+Execute the following command:
+
+```
+mvn test
+```
+
+Upon executing this command you should see output like the following:
+
+```
+[INFO] Scanning for projects...
+[INFO]
+[INFO] ----------------------< com.mycompany.app:my-app >----------------------
+[INFO] Building my-app 1.0-SNAPSHOT
+[INFO] --------------------------------[ jar ]---------------------------------
+[INFO]
+[INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ my-app ---
+[INFO] Using 'UTF-8' encoding to copy filtered resources.
+[INFO] skip non existing resourceDirectory <dir>/my-app/src/main/resources
+[INFO]
+[INFO] --- maven-compiler-plugin:3.8.0:compile (default-compile) @ my-app ---
+[INFO] Nothing to compile - all classes are up to date
+[INFO]
+[INFO] --- maven-resources-plugin:3.0.2:testResources (default-testResources) @ my-app ---
+[INFO] Using 'UTF-8' encoding to copy filtered resources.
+[INFO] skip non existing resourceDirectory <dir>/my-app/src/test/resources
+[INFO]
+[INFO] --- maven-compiler-plugin:3.8.0:testCompile (default-testCompile) @ my-app ---
+[INFO] Changes detected - recompiling the module!
+[INFO] Compiling 1 source file to <dir>/my-app/target/test-classes
+[INFO]
+[INFO] --- maven-surefire-plugin:2.22.1:test (default-test) @ my-app ---
+[INFO]
+[INFO] -------------------------------------------------------
+[INFO] T E S T S
+[INFO] -------------------------------------------------------
+[INFO] Running com.mycompany.app.AppTest
+[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.025 s - in com.mycompany.app.AppTest
+[INFO]
+[INFO] Results:
+[INFO]
+[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
+[INFO]
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 1.881 s
+[INFO] Finished at: 2020-07-12T12:00:33+01:00
+[INFO] ------------------------------------------------------------------------
+```
+
+Some things to notice about the output:
+
+- Maven downloads more dependencies this time. These are the dependencies and plugins necessary for executing the tests (it already has the dependencies it needs for compiling and won't download them again).
+- Before compiling and executing the tests Maven compiles the main code (all these classes are up to date because we haven't changed anything since we compiled last).
+
+If you simply want to compile your test sources (but not execute the tests), you can execute the following:
+
+```
+mvn test-compile
+```
+
+Now that you can compile your application sources, compile your tests, and execute the tests, you'll want to move on to the next logical step so you'll be asking ...
+
+## How do I create a JAR and install it in my local repository?
+
+Making a JAR file is straight forward enough and can be accomplished by executing the following command:
+
+<!-- How to skip tests ... jvz-->
+
+```
+mvn package
+```
+
+You can now take a look in the `${project.basedir}/target` directory and you will see the generated JAR file.
+
+Now you'll want to install the artifact you've generated (the JAR file) in your local repository (`${user.home}/.m2/repository` is the default location). For more information on repositories you can refer to our [Introduction to Repositories](../introduction/introduction-to-repositories.html) but let's move on to installing our artifact! To do so execute the following command:
+
+```
+mvn install
+```
+
+Upon executing this command you should see the following output:
+
+```
+[INFO] Scanning for projects...
+[INFO]
+[INFO] ----------------------< com.mycompany.app:my-app >----------------------
+[INFO] Building my-app 1.0-SNAPSHOT
+[INFO] --------------------------------[ jar ]---------------------------------
+[INFO]
+[INFO] --- maven-resources-plugin:3.0.2:resources (default-resources) @ my-app ---
+...
+[INFO] --- maven-compiler-plugin:3.8.0:compile (default-compile) @ my-app ---
+[INFO] Nothing to compile - all classes are up to date
+[INFO]
+[INFO] --- maven-resources-plugin:3.0.2:testResources (default-testResources) @ my-app ---
+...
+[INFO] --- maven-compiler-plugin:3.8.0:testCompile (default-testCompile) @ my-app ---
+[INFO] Nothing to compile - all classes are up to date
+[INFO]
+[INFO] --- maven-surefire-plugin:2.22.1:test (default-test) @ my-app ---
+[INFO]
+[INFO] -------------------------------------------------------
+[INFO] T E S T S
+[INFO] -------------------------------------------------------
+[INFO] Running com.mycompany.app.AppTest
+[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.025 s - in com.mycompany.app.AppTest
+[INFO]
+[INFO] Results:
+[INFO]
+[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
+[INFO]
+[INFO]
+[INFO] --- maven-jar-plugin:3.0.2:jar (default-jar) @ my-app ---
+[INFO] Building jar: <dir>/my-app/target/my-app-1.0-SNAPSHOT.jar
+[INFO]
+[INFO] --- maven-install-plugin:2.5.2:install (default-install) @ my-app ---
+[INFO] Installing <dir>/my-app/target/my-app-1.0-SNAPSHOT.jar to <local-repository>/com/mycompany/app/my-app/1.0-SNAPSHOT/my-app-1.0-SNAPSHOT.jar
+[INFO] Installing <dir>/my-app/pom.xml to <local-repository>/com/mycompany/app/my-app/1.0-SNAPSHOT/my-app-1.0-SNAPSHOT.pom
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 1.678 s
+[INFO] Finished at: 2020-07-12T12:04:45+01:00
+[INFO] ------------------------------------------------------------------------
+```
+
+Note that the surefire plugin (which executes the test) looks for tests contained in files with a particular naming convention. By default the tests included are:
+
+- `**/*Test.java`
+- `**/Test*.java`
+- `**/*TestCase.java`
+
+And the default excludes are:
+
+- `**/Abstract*Test.java`
+- `**/Abstract*TestCase.java`
+
+You have walked through the process for setting up, building, testing, packaging, and installing a typical Maven project. This is likely the vast majority of what projects will be doing with Maven and if you've noticed, everything you've been able to do up to this point has been driven by an 18-line file, namely the project's model or POM. If you look at a typical Ant [build file](../../ant/build-a1.xml) that provides the same functionality that we've achieved thus far you'll notice it's [...]
+
+So what else can you get for free? There are a great number of Maven plugins that work out of the box with even a simple POM like we have above. We'll mention one here specifically as it is one of the highly prized features of Maven: without any work on your part this POM has enough information to generate a web site for your project! You will most likely want to customize your Maven site but if you're pressed for time all you need to do to provide basic information about your project is [...]
+
+```
+mvn site
+```
+
+There are plenty of other standalone goals that can be executed as well, for example:
+
+```
+mvn clean
+```
+
+This will remove the `target` directory with all the build data before starting so that it is fresh.
+
+## What is a SNAPSHOT version?
+
+Notice the value of the **version** tag in the `pom.xml` file shown below has the suffix: `-SNAPSHOT`.
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ ...
+ <groupId>...</groupId>
+ <artifactId>my-app</artifactId>
+ ...
+ <version>1.0-SNAPSHOT</version>
+ <name>Maven Quick Start Archetype</name>
+ ...
+```
+
+The `SNAPSHOT` value refers to the 'latest' code along a development branch, and provides no guarantee the code is stable or unchanging. Conversely, the code in a 'release' version (any version value without the suffix `SNAPSHOT`) is unchanging.
+
+In other words, a SNAPSHOT version is the 'development' version before the final 'release' version. The SNAPSHOT is "older" than its release.
+
+During the [release](../../plugins/maven-release-plugin/) process, a version of **x.y-SNAPSHOT** changes to **x.y**. The release process also increments the development version to **x.(y+1)-SNAPSHOT**. For example, version **1.0-SNAPSHOT** is released as version **1.0**, and the new development version is version **1.1-SNAPSHOT**.
+
+## How do I use plugins?
+
+Whenever you want to customise the build for a Maven project, this is done by adding or reconfiguring plugins.
+
+For this example, we will configure the Java compiler to allow JDK 5.0 sources. This is as simple as adding this to your POM:
+
+```xml
+...
+<build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>3.3</version>
+ <configuration>
+ <source>1.5</source>
+ <target>1.5</target>
+ </configuration>
+ </plugin>
+ </plugins>
+</build>
+...
+```
+
+You'll notice that all plugins in Maven look much like a dependency - and in some ways they are. This plugin will be automatically downloaded and used - including a specific version if you request it (the default is to use the latest available).
+
+The `configuration` element applies the given parameters to every goal from the compiler plugin. In the above case, the compiler plugin is already used as part of the build process and this just changes the configuration. It is also possible to add new goals to the process, and configure specific goals. For information on this, see the [Introduction to the Build Lifecycle](../introduction/introduction-to-the-lifecycle.html).
+
+To find out what configuration is available for a plugin, you can see the [Plugins List](../../plugins/) and navigate to the plugin and goal you are using. For general information about how to configure the available parameters of a plugin, have a look at the [Guide to Configuring Plugins](../mini/guide-configuring-plugins.html).
+
+## How do I add resources to my JAR?
+
+Another common use case that can be satisfied which requires no changes to the POM that we have above is packaging resources in the JAR file. For this common task, Maven again relies on the [Standard Directory Layout](../introduction/introduction-to-the-standard-directory-layout.html), which means by using standard Maven conventions you can package resources within JARs simply by placing those resources in a standard directory structure.
+
+You see below in our example we have added the directory `${project.basedir}/src/main/resources` into which we place any resources we wish to package in our JAR. The simple rule employed by Maven is this: any directories or files placed within the `${project.basedir}/src/main/resources` directory are packaged in your JAR with the exact same structure starting at the base of the JAR.
+
+```
+my-app
+|-- pom.xml
+`-- src
+ |-- main
+ | |-- java
+ | | `-- com
+ | | `-- mycompany
+ | | `-- app
+ | | `-- App.java
+ | `-- resources
+ | `-- META-INF
+ | `-- application.properties
+ `-- test
+ `-- java
+ `-- com
+ `-- mycompany
+ `-- app
+ `-- AppTest.java
+```
+
+So you can see in our example that we have a `META-INF` directory with an `application.properties` file within that directory. If you unpacked the JAR that Maven created for you and took a look at it you would see the following:
+
+```
+|-- META-INF
+| |-- MANIFEST.MF
+| `-- application.properties
+| `-- maven
+| `-- com.mycompany.app
+| `-- my-app
+| |-- pom.properties
+| `-- pom.xml
+`-- com
+ `-- mycompany
+ `-- app
+ `-- App.class
+```
+
+As you can see, the contents of `${project.basedir}/src/main/resources` can be found starting at the base of the JAR and our `application.properties` file is there in the `META-INF` directory. You will also notice some other files there like `META-INF/MANIFEST.MF` as well as a `pom.xml` and `pom.properties` file. These come standard with generation of a JAR in Maven. You can create your own manifest if you choose, but Maven will generate one by default if you don't. (You can also modify [...]
+
+```
+#Generated by Maven
+#Tue Oct 04 15:43:21 GMT-05:00 2005
+version=1.0-SNAPSHOT
+groupId=com.mycompany.app
+artifactId=my-app
+```
+
+To add resources to the classpath for your unit tests, you follow the same pattern as you do for adding resources to the JAR except the directory you place resources in is `${project.basedir}/src/test/resources`. At this point you would have a project directory structure that would look like the following:
+
+```
+my-app
+|-- pom.xml
+`-- src
+ |-- main
+ | |-- java
+ | | `-- com
+ | | `-- mycompany
+ | | `-- app
+ | | `-- App.java
+ | `-- resources
+ | `-- META-INF
+ | |-- application.properties
+ `-- test
+ |-- java
+ | `-- com
+ | `-- mycompany
+ | `-- app
+ | `-- AppTest.java
+ `-- resources
+ `-- test.properties
+```
+
+In a unit test you could use a simple snippet of code like the following to access the resource required for testing:
+
+```xml
+...
+
+// Retrieve resource
+InputStream is = getClass().getResourceAsStream( "/test.properties" );
+
+// Do something with the resource
+
+...
+```
+
+## How do I filter resource files?
+
+Sometimes a resource file will need to contain a value that can only be supplied at build time. To accomplish this in Maven, put a reference to the property that will contain the value into your resource file using the syntax `${<property name>}`. The property can be one of the values defined in your `pom.xml`, a value defined in the user's `settings.xml`, a property defined in an external properties file, or a system property.
+
+To have Maven filter resources when copying, simply set `filtering` to true for the resource directory in your `pom.xml`:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+
+ <name>Maven Quick Start Archetype</name>
+ <url>http://maven.apache.org</url>
+
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>4.11</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <resources>
+ <resource>
+ <directory>src/main/resources</directory>
+ <filtering>true</filtering>
+ </resource>
+ </resources>
+ </build>
+</project>
+```
+
+You'll notice that we had to add the `build`, `resources`, and `resource` elements which weren't there before. In addition, we had to explicitly state that the resources are located in the `src/main/resources` directory. All of this information was provided as default values previously, but because the default value for `filtering` is false, we had to add this to our `pom.xml` in order to override that default value and set `filtering` to true.
+
+To reference a property defined in your `pom.xml`, the property name uses the names of the XML elements that define the value, with "pom" being allowed as an alias for the project (root) element. So `${project.name}` refers to the name of the project, `${project.version}` refers to the version of the project, `${project.build.finalName}` refers to the final name of the file created when the built project is packaged, etc. Note that some elements of the POM have default values, so don't n [...]
+
+To continue our example, let's add a couple of properties to the `application.properties` file (which we put in the `src/main/resources` directory) whose values will be supplied when the resource is filtered:
+
+```
+# application.properties
+application.name=${project.name}
+application.version=${project.version}
+```
+
+With that in place, you can execute the following command (process-resources is the build lifecycle phase where the resources are copied and filtered):
+
+```
+mvn process-resources
+```
+
+and the `application.properties` file under `target/classes` (and will eventually go into the jar) looks like this:
+
+```
+# application.properties
+application.name=Maven Quick Start Archetype
+application.version=1.0-SNAPSHOT
+```
+
+To reference a property defined in an external file, all you need to do is add a reference to this external file in your `pom.xml`. First, let's create our external properties file and call it `src/main/filters/filter.properties`:
+
+```
+# filter.properties
+my.filter.value=hello!
+```
+
+Next, we'll add a reference to this new file in the `pom.xml`:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+
+ <name>Maven Quick Start Archetype</name>
+ <url>http://maven.apache.org</url>
+
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>4.11</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <filters>
+ <filter>src/main/filters/filter.properties</filter>
+ </filters>
+ <resources>
+ <resource>
+ <directory>src/main/resources</directory>
+ <filtering>true</filtering>
+ </resource>
+ </resources>
+ </build>
+</project>
+```
+
+Then, if we add a reference to this property in the `application.properties` file:
+
+```
+# application.properties
+application.name=${project.name}
+application.version=${project.version}
+message=${my.filter.value}
+```
+
+the next execution of the `mvn process-resources` command will put our new property value into `application.properties`. As an alternative to defining the my.filter.value property in an external file, you could also have defined it in the `properties` section of your `pom.xml` and you'd get the same effect (notice I don't need the references to `src/main/filters/filter.properties` either):
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+
+ <name>Maven Quick Start Archetype</name>
+ <url>http://maven.apache.org</url>
+
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>4.11</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <resources>
+ <resource>
+ <directory>src/main/resources</directory>
+ <filtering>true</filtering>
+ </resource>
+ </resources>
+ </build>
+
+ <properties>
+ <my.filter.value>hello</my.filter.value>
+ </properties>
+</project>
+```
+
+Filtering resources can also get values from system properties; either the system properties built into Java (like `java.version` or `user.home`) or properties defined on the command line using the standard Java -D parameter. To continue the example, let's change our `application.properties` file to look like this:
+
+```
+# application.properties
+java.version=${java.version}
+command.line.prop=${command.line.prop}
+```
+
+Now, when you execute the following command (note the definition of the command.line.prop property on the command line), the `application.properties` file will contain the values from the system properties.
+
+```
+mvn process-resources "-Dcommand.line.prop=hello again"
+```
+
+## How do I use external dependencies?
+
+You've probably already noticed a `dependencies` element in the POM we've been using as an example. You have, in fact, been using an external dependency all this time, but here we'll talk about how this works in a bit more detail. For a more thorough introduction, please refer to our [Introduction to Dependency Mechanism](../introduction/introduction-to-dependency-mechanism.html).
+
+The `dependencies` section of the `pom.xml` lists all of the external dependencies that our project needs in order to build (whether it needs that dependency at compile time, test time, run time, or whatever). Right now, our project is depending on JUnit only (I took out all of the resource filtering stuff for clarity):
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+
+ <name>Maven Quick Start Archetype</name>
+ <url>http://maven.apache.org</url>
+
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>4.11</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+For each external dependency, you'll need to define at least 4 things: groupId, artifactId, version, and scope. The groupId, artifactId, and version are the same as those given in the `pom.xml` for the project that built that dependency. The scope element indicates how your project uses that dependency, and can be values like `compile`, `test`, and `runtime`. For more information on everything you can specify for a dependency, see the [Project Descriptor Reference](/ref/current/maven-mod [...]
+
+<!--DJ: Does this link work? I can't find the document.-->
+
+For more information about the dependency mechanism as a whole, see [Introduction to Dependency Mechanism](../introduction/introduction-to-dependency-mechanism.html).
+
+With this information about a dependency, Maven will be able to reference the dependency when it builds the project. Where does Maven reference the dependency from? Maven looks in your local repository (`${user.home}/.m2/repository` is the default location) to find all dependencies. In a [previous section](#How_do_I_create_a_JAR_and_install_it_in_my_local_repository), we installed the artifact from our project (my-app-1.0-SNAPSHOT.jar) into the local repository. Once it's installed there [...]
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-other-app</artifactId>
+ ...
+ <dependencies>
+ ...
+ <dependency>
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <scope>compile</scope>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+What about dependencies built somewhere else? How do they get into my local repository? Whenever a project references a dependency that isn't available in the local repository, Maven will download the dependency from a remote repository into the local repository. You probably noticed Maven downloading a lot of things when you built your very first project (these downloads were dependencies for the various plugins used to build the project). By default, the remote repository Maven uses ca [...]
+
+Let's add another dependency to our project. Let's say we've added some logging to the code and need to add log4j as a dependency. First, we need to know what the groupId, artifactId, and version are for log4j. The appropriate directory on Maven Central is called [/maven2/log4j/log4j](https://repo.maven.apache.org/maven2/log4j/log4j/). In that directory is a file called maven-metadata.xml. Here's what the maven-metadata.xml for log4j looks like:
+
+```xml
+<metadata>
+ <groupId>log4j</groupId>
+ <artifactId>log4j</artifactId>
+ <version>1.1.3</version>
+ <versioning>
+ <versions>
+ <version>1.1.3</version>
+ <version>1.2.4</version>
+ <version>1.2.5</version>
+ <version>1.2.6</version>
+ <version>1.2.7</version>
+ <version>1.2.8</version>
+ <version>1.2.11</version>
+ <version>1.2.9</version>
+ <version>1.2.12</version>
+ </versions>
+ </versioning>
+</metadata>
+```
+
+From this file, we can see that the groupId we want is "log4j" and the artifactId is "log4j". We see lots of different version values to choose from; for now, we'll just use the latest version, 1.2.12 (some maven-metadata.xml files may also specify which version is the current release version: see [repository metadata reference](/ref/current/maven-repository-metadata/repository-metadata.html)). Alongside the maven-metadata.xml file, we can see a directory corresponding to each version of [...]
+
+Now that we know the information we need, we can add the dependency to our pom.xml:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+
+ <name>Maven Quick Start Archetype</name>
+ <url>http://maven.apache.org</url>
+
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>4.11</version>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <groupId>log4j</groupId>
+ <artifactId>log4j</artifactId>
+ <version>1.2.12</version>
+ <scope>compile</scope>
+ </dependency>
+ </dependencies>
+</project>
+```
+
+Now, when we compile the project (`mvn compile`), we'll see Maven download the log4j dependency for us.
+
+<!--DJ: Current-->
+
+## How do I deploy my jar in my remote repository?
+
+For deploying jars to an external repository, you have to configure the repository url in the `pom.xml` and the authentication information for connecting to the repository in the `settings.xml`.
+
+Here is an example using scp and username/password authentication:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+
+ <name>Maven Quick Start Archetype</name>
+ <url>http://maven.apache.org</url>
+
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>4.11</version>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.codehaus.plexus</groupId>
+ <artifactId>plexus-utils</artifactId>
+ <version>1.0.4</version>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <filters>
+ <filter>src/main/filters/filters.properties</filter>
+ </filters>
+ <resources>
+ <resource>
+ <directory>src/main/resources</directory>
+ <filtering>true</filtering>
+ </resource>
+ </resources>
+ </build>
+ <!--
+ |
+ |
+ |
+ -->
+ <distributionManagement>
+ <repository>
+ <id>mycompany-repository</id>
+ <name>MyCompany Repository</name>
+ <url>scp://repository.mycompany.com/repository/maven2</url>
+ </repository>
+ </distributionManagement>
+</project>
+```
+
+```xml
+<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
+ ...
+ <servers>
+ <server>
+ <id>mycompany-repository</id>
+ <username>jvanzyl</username>
+ <!-- Default value is ~/.ssh/id_dsa -->
+ <privateKey>/path/to/identity</privateKey> (default is ~/.ssh/id_dsa)
+ <passphrase>my_key_passphrase</passphrase>
+ </server>
+ </servers>
+ ...
+</settings>
+```
+
+Note that if you are connecting to an openssh ssh server which has the parameter "PasswordAuthentication" set to "no" in the sshd\_config, you will have to type your password each time for username/password authentication (although you can log in using another ssh client by typing in the username and password). You might want to switch to public key authentication in this case.
+
+Care should be taken if using passwords in `settings.xml`. For more information, see [Password Encryption](../mini/guide-encryption.html).
+
+## How do I create documentation?
+
+To get you jump started with Maven's documentation system you can use the archetype mechanism to generate a site for your existing project using the following command:
+
+```
+mvn archetype:generate \
+ -DarchetypeGroupId=org.apache.maven.archetypes \
+ -DarchetypeArtifactId=maven-archetype-site \
+ -DgroupId=com.mycompany.app \
+ -DartifactId=my-app-site
+```
+
+Now head on over to the [Guide to creating a site](../mini/guide-site.html) to learn how to create the documentation for your project.
+
+## How do I build other types of projects?
+
+Note that the lifecycle applies to any project type. For example, back in the base directory we can create a simple web application:
+
+```
+mvn archetype:generate \
+ -DarchetypeGroupId=org.apache.maven.archetypes \
+ -DarchetypeArtifactId=maven-archetype-webapp \
+ -DgroupId=com.mycompany.app \
+ -DartifactId=my-webapp
+```
+
+Note that these must all be on a single line. This will create a directory called `my-webapp` containing the following project descriptor:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-webapp</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>war</packaging>
+
+ <dependencies>
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>4.11</version>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <finalName>my-webapp</finalName>
+ </build>
+</project>
+```
+
+Note the `<packaging>` element - this tells Maven to build as a WAR. Change into the webapp project's directory and try:
+
+```
+mvn package
+```
+
+You'll see `target/my-webapp.war` is built, and that all the normal steps were executed.
+
+## How do I build more than one project at once?
+
+The concept of dealing with multiple modules is built in to Maven. In this section, we will show how to build the WAR above, and include the previous JAR as well in one step.
+
+Firstly, we need to add a parent `pom.xml` file in the directory above the other two, so it should look like this:
+
+```
++- pom.xml
++- my-app
+| +- pom.xml
+| +- src
+| +- main
+| +- java
++- my-webapp
+| +- pom.xml
+| +- src
+| +- main
+| +- webapp
+```
+
+The POM file you'll create should contain the following:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>app</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>pom</packaging>
+
+ <modules>
+ <module>my-app</module>
+ <module>my-webapp</module>
+ </modules>
+</project>
+```
+
+We'll need a dependency on the JAR from the webapp, so add this to `my-webapp/pom.xml`:
+
+```xml
+...
+<dependencies>
+ <dependency>
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ </dependency>
+ ...
+</dependencies>
+```
+
+Finally, add the following `<parent>` element to both of the other `pom.xml` files in the subdirectories:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <parent>
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>app</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ </parent>
+ ...
+```
+
+Now, try it... from the top level directory, run:
+
+```
+mvn verify
+```
+
+The WAR has now been created in `my-webapp/target/my-webapp.war`, and the JAR is included:
+
+```
+$ jar tvf my-webapp/target/my-webapp-1.0-SNAPSHOT.war
+ 0 Fri Jun 24 10:59:56 EST 2005 META-INF/
+ 222 Fri Jun 24 10:59:54 EST 2005 META-INF/MANIFEST.MF
+ 0 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/
+ 0 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/
+ 0 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/my-webapp/
+3239 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/my-webapp/pom.xml
+ 0 Fri Jun 24 10:59:56 EST 2005 WEB-INF/
+ 215 Fri Jun 24 10:59:56 EST 2005 WEB-INF/web.xml
+ 123 Fri Jun 24 10:59:56 EST 2005 META-INF/maven/com.mycompany.app/my-webapp/pom.properties
+ 52 Fri Jun 24 10:59:56 EST 2005 index.jsp
+ 0 Fri Jun 24 10:59:56 EST 2005 WEB-INF/lib/
+2713 Fri Jun 24 10:59:56 EST 2005 WEB-INF/lib/my-app-1.0-SNAPSHOT.jar
+```
+
+How does this work? Firstly, the parent POM created (called `app`), has a packaging of `pom` and a list of modules defined. This tells Maven to run all operations over the set of projects instead of just the current one (to override this behaviour, you can use the `--non-recursive` command line option).
+
+Next, we tell the WAR that it requires the `my-app` JAR. This does a few things: it makes it available on the classpath to any code in the WAR (none in this case), it makes sure the JAR is always built before the WAR, and it indicates to the WAR plugin to include the JAR in its library directory.
+
+You may have noticed that `junit-4.11.jar` was a dependency, but didn't end up in the WAR. The reason for this is the `<scope>test</scope>` element - it is only required for testing, and so is not included in the web application as the compile time dependency `my-app` is.
+
+The final step was to include a parent definition. This ensures that the POM can always be located even if the project is distributed separately from its parent by looking it up in the repository.
+
diff --git a/content/markdown/guides/getting-started/maven-in-five-minutes.md b/content/markdown/guides/getting-started/maven-in-five-minutes.md
new file mode 100644
index 00000000..01231dec
--- /dev/null
+++ b/content/markdown/guides/getting-started/maven-in-five-minutes.md
@@ -0,0 +1,254 @@
+<!--
+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 in 5 Minutes
+
+## Prerequisites
+
+You must understand how to install software on your computer. If you do not know how to do this, please ask someone at your office, school, etc. or pay someone to explain this to you. The Maven mailing lists are not the best place to ask for this advice.
+
+## Installation
+
+_Maven is a Java tool, so you must have [Java](https://www.oracle.com/technetwork/java/javase/downloads/index.html) installed in order to proceed._
+
+First, [download Maven](../../download.html) and follow the [installation instructions](../../install.html). After that, type the following in a terminal or in a command prompt:
+
+```
+mvn --version
+```
+
+It should print out your installed version of Maven, for example:
+
+```
+Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f)
+Maven home: D:\apache-maven-3.6.3\apache-maven\bin..
+Java version: 1.8.0_232, vendor: AdoptOpenJDK, runtime: C:\Program Files\AdoptOpenJDK\jdk-8.0.232.09-hotspot\jre
+Default locale: en_US, platform encoding: Cp1250
+OS name: "windows 10", version: "10.0", arch: "amd64", family: "windows"
+```
+
+Depending upon your network setup, you may require extra configuration. Check out the [Guide to Configuring Maven](../mini/guide-configuring-maven.html) if necessary.
+
+**If you are using Windows, you should look at** [Windows Prerequisites](./windows-prerequisites.html) **to ensure that you are prepared to use Maven on Windows.**
+
+## Creating a Project
+
+You need somewhere for your project to reside. Create a directory somewhere and start a shell in that directory. On your command line, execute the following Maven goal:
+
+```
+mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.5 -DinteractiveMode=false
+```
+
+_If you have just installed Maven, it may take a while on the first run. This is because Maven is downloading the most recent artifacts (plugin jars and other files) into your local repository. You may also need to execute the command a couple of times before it succeeds. This is because the remote server may time out before your downloads are complete. Don't worry, there are ways to fix that._
+
+You will notice that the _generate_ goal created a directory with the same name given as the artifactId. Change into that directory.
+
+```
+cd my-app
+```
+
+Under this directory you will notice the following [standard project structure](../introduction/introduction-to-the-standard-directory-layout.html).
+
+```
+my-app
+|-- pom.xml
+`-- src
+ |-- main
+ | `-- java
+ | `-- com
+ | `-- mycompany
+ | `-- app
+ | `-- App.java
+ `-- test
+ `-- java
+ `-- com
+ `-- mycompany
+ `-- app
+ `-- AppTest.java
+```
+
+The `src/main/java` directory contains the project source code, the `src/test/java` directory contains the test source, and the `pom.xml` file is the project's Project Object Model, or POM.
+
+### The POM
+
+The `pom.xml` file is the core of a project's configuration in Maven. It is a single configuration file that contains the majority of information required to build a project in just the way you want. The POM is huge and can be daunting in its complexity, but it is not necessary to understand all of the intricacies just yet to use it effectively. This project's POM should look like this:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1.0-SNAPSHOT</version>
+
+ <name>my-app</name>
+ <!-- FIXME change it to the project's website -->
+ <url>http://www.example.com</url>
+
+ <properties>
+ <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+ <maven.compiler.release>17</maven.compiler.release>
+ </properties>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.junit</groupId>
+ <artifactId>junit-bom</artifactId>
+ <version>5.11.0</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.junit.jupiter</groupId>
+ <artifactId>junit-jupiter-api</artifactId>
+ <scope>test</scope>
+ </dependency>
+ <!-- Optionally: parameterized tests support -->
+ <dependency>
+ <groupId>org.junit.jupiter</groupId>
+ <artifactId>junit-jupiter-params</artifactId>
+ <scope>test</scope>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <pluginManagement><!-- lock down plugins versions to avoid using Maven defaults (may be moved to parent pom) -->
+ ... lots of helpful plugins
+ </pluginManagement>
+ </build>
+</project>
+```
+
+### What did I just do?
+
+You executed the Maven goal _archetype:generate_, and passed in various parameters to that goal. The prefix _archetype_ is the [plugin](../../plugins/index.html) that provides the goal. If you are familiar with [Ant](http://ant.apache.org), you may conceive of this as similar to a task. This _archetype:generate_ goal created a simple project based upon a [maven-archetype-quickstart](/archetypes/maven-archetype-quickstart/) archetype. Suffice it to say for now that a _plugin_ is a collect [...]
+
+### Build the Project
+
+```
+mvn package
+```
+
+The command line will print out various actions, and end with the following:
+
+```
+ ...
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time: 2.953 s
+[INFO] Finished at: 2019-11-24T13:05:10+01:00
+[INFO] ------------------------------------------------------------------------
+```
+
+Unlike the first command executed (_archetype:generate_), the second is simply a single word - _package_. Rather than a _goal_, this is a _phase_. A phase is a step in the [build lifecycle](../introduction/introduction-to-the-lifecycle.html), which is an ordered sequence of phases. When a phase is given, Maven executes every phase in the sequence up to and including the one defined. For example, if you execute the _compile_ phase, the phases that actually get executed are:
+
+1. validate
+2. generate-sources
+3. process-sources
+4. generate-resources
+5. process-resources
+6. compile
+
+You may test the newly compiled and packaged JAR with the following command:
+
+```
+java -cp target/my-app-1.0-SNAPSHOT.jar com.mycompany.app.App
+```
+
+Which will print the quintessential:
+
+```
+Hello World!
+```
+
+## Java 9 or later
+
+By default your version of Maven might use an old version of the `maven-compiler-plugin` that is not compatible with Java 9 or later versions. To target Java 9 or later, you should at least use version 3.6.0 of the `maven-compiler-plugin` and set the `maven.compiler.release` property to the Java release you are targetting (e.g. 9, 10, 11, 12, etc.).
+
+In the following example, we have configured our Maven project to use version 3.8.1 of `maven-compiler-plugin` and target Java 11:
+
+```xml
+ <properties>
+ <maven.compiler.release>11</maven.compiler.release>
+ </properties>
+
+ <build>
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>3.8.1</version>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+ </build>
+```
+
+To learn more about `javac`'s `--release` option, see [JEP 247](https://openjdk.java.net/jeps/247).
+
+## Running Maven Tools
+
+### Maven Phases
+
+Although hardly a comprehensive list, these are the most common _default_ lifecycle phases executed.
+
+- **validate**: validate the project is correct and all necessary information is available
+- **compile**: compile the source code of the project
+- **test**: test the compiled source code using a suitable unit testing framework. These tests should not require the code be packaged or deployed
+- **package**: take the compiled code and package it in its distributable format, such as a JAR.
+- **integration-test**: process and deploy the package if necessary into an environment where integration tests can be run
+- **verify**: run any checks to verify the package is valid and meets quality criteria
+- **install**: install the package into the local repository, for use as a dependency in other projects locally
+- **deploy**: done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects.
+
+There are two other Maven lifecycles of note beyond the _default_ list above. They are
+
+- **clean**: cleans up artifacts created by prior builds
+- **site**: generates site documentation for this project
+
+Phases are actually mapped to underlying goals. The specific goals executed per phase is dependant upon the packaging type of the project. For example, _package_ executes _jar:jar_ if the project type is a JAR, and _war:war_ if the project type is - you guessed it - a WAR.
+
+An interesting thing to note is that phases and goals may be executed in sequence.
+
+```
+mvn clean dependency:copy-dependencies package
+```
+
+This command will clean the project, copy dependencies, and package the project (executing all phases up to _package_, of course).
+
+### Generating the Site
+
+```
+mvn site
+```
+
+This phase generates a site based upon information on the project's pom. You can look at the documentation generated under `target/site`.
+
+## Conclusion
+
+We hope this quick overview has piqued your interest in the versatility of Maven. Note that this is a very truncated quick-start guide. Now you are ready for more comprehensive details concerning the actions you have just performed. Check out the [Maven Getting Started Guide](./index.html).
+
diff --git a/content/markdown/guides/getting-started/windows-prerequisites.md b/content/markdown/guides/getting-started/windows-prerequisites.md
new file mode 100644
index 00000000..41ae58c3
--- /dev/null
+++ b/content/markdown/guides/getting-started/windows-prerequisites.md
@@ -0,0 +1,47 @@
+<!--
+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 on Windows
+
+Maven is a command-line tool for building Java (and other) programs. The Maven project provides a simple ZIP file containing a precompiled version of Maven for your convenience. There is no installer. It's up to you to set up your prerequisites and environment to run Maven on Windows.
+
+## Prerequisites
+
+Maven is written in Java (and primarily used to build Java programs). Thus, the major prerequisite is the Java SDK. You need to install the Java SDK (e.g. from [Oracle's download site](https://www.oracle.com/technetwork/java/javase/downloads/index.html)).
+
+Once Java is installed, you must ensure that the commands from the Java SDK are in your PATH environment variable. Running, for example,
+
+```
+java -version
+```
+
+must show the right version number.
+
+## Maven Unpacked
+
+You need to unpack the Maven distribution. Don't unpack it in the middle of your source code; pick some location and unpack it there. Let's assume that the path is `${maven.home}`.
+
+## Maven in PATH
+
+You run Maven by invoking a command-line tool: `mvn.cmd` from the `bin` directory of the Maven. To do this conveniently, `${maven.home}\bin` must be in your PATH, just like the Java SDK commands. You can add directories to your `PATH` in the control panel; the details vary by Windows version.
+
+## Firewalls and Anti-virus
+
+Firewall and Anti-virus sometimes prevent Java from running properly, or Windows Firewall (and various other Firewalls) actively prevent Java.exe from reaching out to the Internet to "download stuff" which is a key part of Maven. You may need to configure the Firewall or Anti-virus to add exceptions to allow such actions.
+
diff --git a/content/markdown/guides/introduction/introduction-to-archetypes.md b/content/markdown/guides/introduction/introduction-to-archetypes.md
new file mode 100644
index 00000000..aab31a5b
--- /dev/null
+++ b/content/markdown/guides/introduction/introduction-to-archetypes.md
@@ -0,0 +1,62 @@
+<!--
+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 to Archetypes
+
+# What is Archetype?
+
+In short, Archetype is a Maven project templating toolkit. An archetype is defined as _an original pattern or model from which all other things of the same kind are made_. The name fits as we are trying to provide a system that provides a consistent means of generating Maven projects. Archetype will help authors create Maven project templates for users, and provides users with the means to generate parameterized versions of those project templates.
+
+Using archetypes provides a great way to enable developers work quickly in a way consistent with best practices employed by your project or organization. Within the Maven project, we use archetypes to try and get our users up and running as quickly as possible by providing a sample project that demonstrates many of the features of Maven, while introducing new users to the best practices employed by Maven. In a matter of seconds, a new user can have a working Maven project to use as a jum [...]
+
+You may want to standardize J2EE development within your organization, so you may want to provide archetypes for EJBs, or WARs, or for your web services. Once these archetypes are created and deployed in your organization's repository, they are available for use by all developers within your organization.
+
+## Using an Archetype
+
+To create a new project based on an Archetype, you need to call `mvn archetype:generate` goal, like the following:
+
+```
+mvn archetype:generate
+```
+
+Please refer to [Archetype Plugin page](/archetype/maven-archetype-plugin/).
+
+## Provided Archetypes
+
+Maven provides several Archetype artifacts:
+
+| Archetype ArtifactIds | Description |
+|:----------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| maven-archetype-archetype | An archetype to generate a sample archetype project. |
+| maven-archetype-j2ee-simple | An archetype to generate a simplifed sample J2EE application. |
+| maven-archetype-plugin | An archetype to generate a sample Maven plugin. |
+| maven-archetype-plugin-site | An archetype to generate a sample Maven plugin site. |
+| maven-archetype-portlet | An archetype to generate a sample JSR-268 Portlet. |
+| maven-archetype-quickstart | An archetype to generate a sample Maven project. |
+| maven-archetype-simple | An archetype to generate a simple Maven project. |
+| maven-archetype-site | An archetype to generate a sample Maven site which demonstrates some of the supported document types like APT, XDoc, and FML and demonstrates how to i18n your site. |
+| maven-archetype-site-simple | An archetype to generate a sample Maven site. |
+| maven-archetype-webapp | An archetype to generate a sample Maven Webapp project. |
+
+For more information on these archetypes, please refer to the [Maven Archetype Bundles page](/archetypes/index.html).
+
+## What makes up an Archetype?
+
+Archetypes are packaged up in a JAR and they consist of the archetype metadata which describes the contents of archetype, and a set of [Velocity](http://velocity.apache.org/) templates which make up the prototype project. If you would like to know how to make your own archetypes, please refer to our [Guide to creating archetypes](../mini/guide-creating-archetypes.html).
+
diff --git a/content/markdown/guides/introduction/introduction-to-dependency-mechanism.md b/content/markdown/guides/introduction/introduction-to-dependency-mechanism.md
new file mode 100644
index 00000000..ed455d85
--- /dev/null
+++ b/content/markdown/guides/introduction/introduction-to-dependency-mechanism.md
@@ -0,0 +1,760 @@
+<!--
+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 to the Dependency Mechanism
+
+Dependency management is a core feature of Maven. Managing dependencies for a single project is easy. Managing dependencies for multi-module projects and applications that consist of hundreds of modules is possible. Maven helps a great deal in defining, creating, and maintaining reproducible builds with well-defined classpaths and library versions.
+
+Learn more about:
+
+<!-- MACRO{toc|section=0|fromDepth=2|toDepth=3} -->
+
+## Transitive Dependencies
+
+Maven avoids the need to discover and specify the libraries that your own dependencies require by including transitive dependencies automatically.
+
+This feature is facilitated by reading the project files of your dependencies from the remote repositories specified. In general, all dependencies of those projects are used in your project, as are any that the project inherits from its parents, or from its dependencies, and so on.
+
+There is no limit to the number of levels that dependencies can be gathered from. A problem arises only if a cyclic dependency is discovered.
+
+With transitive dependencies, the graph of included libraries can quickly grow quite large. For this reason, there are additional features that limit which dependencies are included:
+
+- _Dependency mediation_ - this determines what version of an artifact will be chosen when multiple versions are encountered as dependencies. Maven picks the "nearest definition". That is, it uses the version of the closest dependency to your project in the tree of dependencies. You can always guarantee a version by declaring it explicitly in your project's POM. Note that if two dependency versions are at the same depth in the dependency tree, the first declaration wins.
+ - "nearest definition" means that the version used will be the closest one to your project in the tree of dependencies. Consider this tree of dependencies:
+
+ ```
+ A
+ ├── B
+ │ └── C
+ │ └── D 2.0
+ └── E
+ └── D 1.0
+
+ ```
+
+ In text, dependencies for A, B, and C are defined as A -> B -> C -> D 2.0 and A -> E -> D 1.0, then D 1.0 will be used when building A because the path from A to D through E is shorter. You could explicitly add a dependency to D 2.0 in A to force the use of D 2.0, as shown here:
+
+ ```
+ A
+ ├── B
+ │ └── C
+ │ └── D 2.0
+ ├── E
+ │ └── D 1.0
+ │
+ └── D 2.0
+
+ ```
+- _Dependency management_ - this allows project authors to directly specify the versions of artifacts to be used when they are encountered in transitive dependencies or in dependencies where no version has been specified. In the example in the preceding section a dependency was directly added to A even though it is not directly used by A. Instead, A can include D as a dependency in its dependencyManagement section and directly control which version of D is used when, or if, it is ever re [...]
+- _Dependency scope_ - this allows you to only include dependencies appropriate for the current stage of the build. This is described in more detail below.
+- _Excluded dependencies_ - If project X depends on project Y, and project Y depends on project Z, the owner of project X can explicitly exclude project Z as a dependency, using the "exclusion" element.
+- _Optional dependencies_ - If project Y depends on project Z, the owner of project Y can mark project Z as an optional dependency, using the "optional" element. When project X depends on project Y, X will depend only on Y and not on Y's optional dependency Z. The owner of project X may then explicitly add a dependency on Z, at her option. (It may be helpful to think of optional dependencies as "excluded by default.")
+
+Although transitive dependencies can implicitly include desired dependencies, it is a good practice to explicitly specify the dependencies your source code uses directly. This best practice proves its value especially when the dependencies of your project change their dependencies.
+
+For example, assume that your project A specifies a dependency on another project B, and project B specifies a dependency on project C. If you are directly using components in project C, and you don't specify project C in your project A, it may cause build failure when project B suddenly updates/removes its dependency on project C.
+
+Another reason to directly specify dependencies is that it provides better documentation for your project: one can learn more information by just reading the POM file in your project, or by executing **mvn dependency:tree**.
+
+Maven also provides [dependency:analyze](/plugins/maven-dependency-plugin/analyze-mojo.html) plugin goal for analyzing the dependencies: it helps making this best practice more achievable.
+
+## Dependency Scope
+
+Dependency scope is used to limit the transitivity of a dependency and to determine when a dependency is included in a classpath.
+
+There are 6 scopes:
+
+- **compile**
+ This is the default scope, used if none is specified. Compile dependencies are available in all classpaths of a project. Furthermore, those dependencies are propagated to dependent projects.
+- **provided**
+ This is much like `compile`, but indicates you expect the JDK or a container to provide the dependency at runtime. For example, when building a web application for the Java Enterprise Edition, you would set the dependency on the Servlet API and related Java EE APIs to scope `provided` because the web container provides those classes. A dependency with this scope is added to the classpath used for compilation and test, but not the runtime classpath. It is not transitive.
+- **runtime**
+ This scope indicates that the dependency is not required for compilation, but is for execution. Maven includes a dependency with this scope in the runtime and test classpaths, but not the compile classpath.
+- **test**
+ This scope indicates that the dependency is not required for normal use of the application, and is only available for the test compilation and execution phases. This scope is not transitive. Typically this scope is used for test libraries such as JUnit and Mockito. It is also used for non-test libraries such as Apache Commons IO if those libraries are used in unit tests (src/test/java) but not in the model code (src/main/java).
+- **system**
+ This scope indicates that the dependency is required for compilation and execution. However, Maven will not download the dependency from the repository system. Instead it looks for a jar in the local file system at a specified path.
+- **import**
+ This scope is only supported on a dependency of type `pom` in the `<dependencyManagement>` section. It indicates the dependency is to be replaced with the effective list of dependencies in the specified POM's `<dependencyManagement>` section. Since they are replaced, dependencies with a scope of `import` do not actually participate in limiting the transitivity of a dependency.
+
+Each of the scopes (except for `import`) affects transitive dependencies in different ways, as is demonstrated in the table below. If a dependency is set to the scope in the left column, a transitive dependency of that dependency with the scope across the top row results in a dependency in the main project with the scope listed at the intersection. If no scope is listed, it means the dependency is omitted.
+
+| | | | | |
+|:---------|:-----------|:---------|:---------|:-----|
+| | compile | provided | runtime | test |
+| compile | compile(*) | \- | runtime | \- |
+| provided | provided | \- | provided | \- |
+| runtime | runtime | \- | runtime | \- |
+| test | test | \- | test | \- |
+
+**(*) Note:** it is intended that this should be runtime scope instead, so that all compile dependencies must be explicitly listed. However, if a library you depend on extends a class from another library, both must be available at compile time. For this reason, compile time dependencies remain as compile scope even when they are transitive.
+
+## Dependency Management
+
+The dependency management section is a mechanism for centralizing dependency information. When you have a set of projects that inherit from a common parent, it's possible to put all information about the dependency in the common POM and have simpler references to the artifacts in the child POMs. The mechanism is best illustrated through some examples. Given these two POMs which extend the same parent:
+
+Project A:
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>group-a</groupId>
+ <artifactId>artifact-a</artifactId>
+ <version>1.0</version>
+ <exclusions>
+ <exclusion>
+ <groupId>group-c</groupId>
+ <artifactId>excluded-artifact</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+ <dependency>
+ <groupId>group-a</groupId>
+ <artifactId>artifact-b</artifactId>
+ <version>1.0</version>
+ <type>bar</type>
+ <scope>runtime</scope>
+ </dependency>
+ </dependencies>
+</project>
+
+```
+
+Project B:
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>group-c</groupId>
+ <artifactId>artifact-b</artifactId>
+ <version>1.0</version>
+ <type>war</type>
+ <scope>runtime</scope>
+ </dependency>
+ <dependency>
+ <groupId>group-a</groupId>
+ <artifactId>artifact-b</artifactId>
+ <version>1.0</version>
+ <type>bar</type>
+ <scope>runtime</scope>
+ </dependency>
+ </dependencies>
+</project>
+
+```
+
+These two example POMs share a common dependency and each has one non-trivial dependency. This information can be put in the parent POM like this:
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>group-a</groupId>
+ <artifactId>artifact-a</artifactId>
+ <version>1.0</version>
+
+ <exclusions>
+ <exclusion>
+ <groupId>group-c</groupId>
+ <artifactId>excluded-artifact</artifactId>
+ </exclusion>
+ </exclusions>
+
+ </dependency>
+
+ <dependency>
+ <groupId>group-c</groupId>
+ <artifactId>artifact-b</artifactId>
+ <version>1.0</version>
+ <type>war</type>
+ <scope>runtime</scope>
+ </dependency>
+
+ <dependency>
+ <groupId>group-a</groupId>
+ <artifactId>artifact-b</artifactId>
+ <version>1.0</version>
+ <type>bar</type>
+ <scope>runtime</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+</project>
+
+```
+
+Then the two child POMs become much simpler:
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>group-a</groupId>
+ <artifactId>artifact-a</artifactId>
+ </dependency>
+
+ <dependency>
+ <groupId>group-a</groupId>
+ <artifactId>artifact-b</artifactId>
+ <!-- This is not a jar dependency, so we must specify type. -->
+ <type>bar</type>
+ </dependency>
+ </dependencies>
+</project>
+
+```
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>group-c</groupId>
+ <artifactId>artifact-b</artifactId>
+ <!-- This is not a jar dependency, so we must specify type. -->
+ <type>war</type>
+ </dependency>
+
+ <dependency>
+ <groupId>group-a</groupId>
+ <artifactId>artifact-b</artifactId>
+ <!-- This is not a jar dependency, so we must specify type. -->
+ <type>bar</type>
+ </dependency>
+ </dependencies>
+</project>
+
+```
+
+**NOTE:** In two of these dependency references, we had to specify the <type/> element. This is because the minimal set of information for matching a dependency reference against a dependencyManagement section is actually **{groupId, artifactId, type, classifier}**. In many cases, these dependencies will refer to jar artifacts with no classifier. This allows us to shorthand the identity set to **{groupId, artifactId}**, since the default for the type field is `jar`, and the default [...]
+
+A second, and very important use of the dependency management section is to control the versions of artifacts used in transitive dependencies. As an example consider these projects:
+
+Project A:
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>maven</groupId>
+ <artifactId>A</artifactId>
+ <packaging>pom</packaging>
+ <name>A</name>
+ <version>1.0</version>
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>test</groupId>
+ <artifactId>a</artifactId>
+ <version>1.2</version>
+ </dependency>
+ <dependency>
+ <groupId>test</groupId>
+ <artifactId>b</artifactId>
+ <version>1.0</version>
+ <scope>compile</scope>
+ </dependency>
+ <dependency>
+ <groupId>test</groupId>
+ <artifactId>c</artifactId>
+ <version>1.0</version>
+ <scope>compile</scope>
+ </dependency>
+ <dependency>
+ <groupId>test</groupId>
+ <artifactId>d</artifactId>
+ <version>1.2</version>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+</project>
+
+```
+
+Project B:
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <parent>
+ <artifactId>A</artifactId>
+ <groupId>maven</groupId>
+ <version>1.0</version>
+ </parent>
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>maven</groupId>
+ <artifactId>B</artifactId>
+ <packaging>pom</packaging>
+ <name>B</name>
+ <version>1.0</version>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>test</groupId>
+ <artifactId>d</artifactId>
+ <version>1.0</version>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+
+ <dependencies>
+ <dependency>
+ <groupId>test</groupId>
+ <artifactId>a</artifactId>
+ <version>1.0</version>
+ <scope>runtime</scope>
+ </dependency>
+ <dependency>
+ <groupId>test</groupId>
+ <artifactId>c</artifactId>
+ <scope>runtime</scope>
+ </dependency>
+ </dependencies>
+</project>
+
+```
+
+When maven is run on project B, version 1.0 of artifacts a, b, c, and d will be used regardless of the version specified in their POM.
+
+- a and c both are declared as dependencies of the project so version 1.0 is used due to dependency mediation. Both also have runtime scope since it is directly specified.
+- b is defined in B's parent's dependency management section and since dependency management takes precedence over dependency mediation for transitive dependencies, version 1.0 will be selected should it be referenced in a or c's POM. b will also have compile scope.
+- Finally, since d is specified in B's dependency management section, should d be a dependency (or transitive dependency) of a or c, version 1.0 will be chosen - again because dependency management takes precedence over dependency mediation and also because the current POM's declaration takes precedence over its parent's declaration.
+
+**NOTE:** The dependency management won't affect the (transitive) dependencies of any _plugins_ used in the same effective POM but only the (transitive) project dependencies.
+
+The reference information about the dependency management tags is available from the [project descriptor reference](../../ref/current/maven-model/maven.html#class_DependencyManagement).
+
+### Importing Dependencies
+
+The examples in the previous section describe how to specify managed dependencies through inheritance. However, in larger projects it may be impossible to accomplish this since a project can only inherit from a single parent. To accommodate this, projects can import managed dependencies from other projects. This is accomplished by declaring a POM artifact as a dependency with a scope of "import".
+
+Project B:
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>maven</groupId>
+ <artifactId>B</artifactId>
+ <packaging>pom</packaging>
+ <name>B</name>
+ <version>1.0</version>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>maven</groupId>
+ <artifactId>A</artifactId>
+ <version>1.0</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>test</groupId>
+ <artifactId>d</artifactId>
+ <version>1.0</version>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+
+ <dependencies>
+ <dependency>
+ <groupId>test</groupId>
+ <artifactId>a</artifactId>
+ <version>1.0</version>
+ <scope>runtime</scope>
+ </dependency>
+ <dependency>
+ <groupId>test</groupId>
+ <artifactId>c</artifactId>
+ <scope>runtime</scope>
+ </dependency>
+ </dependencies>
+</project>
+
+```
+
+Assuming A is the POM defined in the preceding example, the end result would be the same. All of A's managed dependencies would be incorporated into B except for d since it is defined in this POM.
+
+Project X:
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>maven</groupId>
+ <artifactId>X</artifactId>
+ <packaging>pom</packaging>
+ <name>X</name>
+ <version>1.0</version>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>test</groupId>
+ <artifactId>a</artifactId>
+ <version>1.1</version>
+ </dependency>
+ <dependency>
+ <groupId>test</groupId>
+ <artifactId>b</artifactId>
+ <version>1.0</version>
+ <scope>compile</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+</project>
+
+```
+
+Project Y:
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>maven</groupId>
+ <artifactId>Y</artifactId>
+ <packaging>pom</packaging>
+ <name>Y</name>
+ <version>1.0</version>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>test</groupId>
+ <artifactId>a</artifactId>
+ <version>1.2</version>
+ </dependency>
+ <dependency>
+ <groupId>test</groupId>
+ <artifactId>c</artifactId>
+ <version>1.0</version>
+ <scope>compile</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+</project>
+
+```
+
+Project Z:
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>maven</groupId>
+ <artifactId>Z</artifactId>
+ <packaging>pom</packaging>
+ <name>Z</name>
+ <version>1.0</version>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>maven</groupId>
+ <artifactId>X</artifactId>
+ <version>1.0</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ <dependency>
+ <groupId>maven</groupId>
+ <artifactId>Y</artifactId>
+ <version>1.0</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+</project>
+
+```
+
+In the example above Z imports the managed dependencies from both X and Y. However, both X and Y contain dependency a. Here, version 1.1 of a would be used since X is declared first and a is not declared in Z's dependencyManagement.
+
+This process is recursive. For example, if X imports another POM, Q, when Z is processed it will simply appear that all of Q's managed dependencies are defined in X.
+
+### Bill of Materials (BOM) POMs
+
+Imports are most effective when used for defining a "library" of related artifacts that are generally part of a multiproject build. It is fairly common for one project to use one or more artifacts from these libraries. However, it has sometimes been difficult to keep the versions in the project using the artifacts in synch with the versions distributed in the library. The pattern below illustrates how a "bill of materials" (BOM) can be created for use by other projects.
+
+The root of the project is the BOM POM. It defines the versions of all the artifacts that will be created in the library. Other projects that wish to use the library should import this POM into the dependencyManagement section of their POM.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>com.test</groupId>
+ <artifactId>bom</artifactId>
+ <version>1.0.0</version>
+ <packaging>pom</packaging>
+ <properties>
+ <project1Version>1.0.0</project1Version>
+ <project2Version>1.0.0</project2Version>
+ </properties>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>com.test</groupId>
+ <artifactId>project1</artifactId>
+ <version>${project1Version}</version>
+ </dependency>
+ <dependency>
+ <groupId>com.test</groupId>
+ <artifactId>project2</artifactId>
+ <version>${project2Version}</version>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+
+ <modules>
+ <module>parent</module>
+ </modules>
+</project>
+
+```
+
+The parent subproject has the BOM POM as its parent. It is a normal multiproject pom.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <parent>
+ <groupId>com.test</groupId>
+ <version>1.0.0</version>
+ <artifactId>bom</artifactId>
+ </parent>
+
+ <groupId>com.test</groupId>
+ <artifactId>parent</artifactId>
+ <version>1.0.0</version>
+ <packaging>pom</packaging>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>log4j</groupId>
+ <artifactId>log4j</artifactId>
+ <version>1.2.12</version>
+ </dependency>
+ <dependency>
+ <groupId>commons-logging</groupId>
+ <artifactId>commons-logging</artifactId>
+ <version>1.1.1</version>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+ <modules>
+ <module>project1</module>
+ <module>project2</module>
+ </modules>
+</project>
+
+```
+
+Next are the actual project POMs.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <parent>
+ <groupId>com.test</groupId>
+ <version>1.0.0</version>
+ <artifactId>parent</artifactId>
+ </parent>
+ <groupId>com.test</groupId>
+ <artifactId>project1</artifactId>
+ <version>${project1Version}</version>
+ <packaging>jar</packaging>
+
+ <dependencies>
+ <dependency>
+ <groupId>log4j</groupId>
+ <artifactId>log4j</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <parent>
+ <groupId>com.test</groupId>
+ <version>1.0.0</version>
+ <artifactId>parent</artifactId>
+ </parent>
+ <groupId>com.test</groupId>
+ <artifactId>project2</artifactId>
+ <version>${project2Version}</version>
+ <packaging>jar</packaging>
+
+ <dependencies>
+ <dependency>
+ <groupId>commons-logging</groupId>
+ <artifactId>commons-logging</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+
+```
+
+The project that follows shows how the library can now be used in another project without having to specify the dependent project's versions.
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>com.test</groupId>
+ <artifactId>use</artifactId>
+ <version>1.0.0</version>
+ <packaging>jar</packaging>
+
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>com.test</groupId>
+ <artifactId>bom</artifactId>
+ <version>1.0.0</version>
+ <type>pom</type>
+ <scope>import</scope>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>com.test</groupId>
+ <artifactId>project1</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>com.test</groupId>
+ <artifactId>project2</artifactId>
+ </dependency>
+ </dependencies>
+</project>
+
+```
+
+Finally, when creating projects that import dependencies, beware of the following:
+
+- Do not attempt to import a POM that is defined in a submodule of the current POM. Attempting to do that will result in the build failing since it won't be able to locate the POM.
+- Never declare the POM importing a POM as the parent (or grandparent, etc) of the target POM. There is no way to resolve the circularity and an exception will be thrown.
+- When referring to artifacts whose POMs have transitive dependencies, the project needs to specify versions of those artifacts as managed dependencies. Not doing so results in a build failure since the artifact may not have a version specified. (This should be considered a best practice in any case as it keeps the versions of artifacts from changing from one build to the next).
+
+Starting from Maven 4.0, a new specific BOM packaging has been introduced. It allows defining a BOM which is not used as a parent in a project leveraging the newer 4.1.0 model, while still providing full compatibility with Maven 3.X clients and projects. This BOM packaging is translated into a more usual POM packaging at installation / deployment time, leveraging the build/consumer POM feature from Maven 4. This thus provides full compatibility with Maven 3.x.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.1.0 https://maven.apache.org/xsd/maven-4.1.0.xsd">
+ <parent>
+ <groupId>com.test</groupId>
+ <version>1.0.0</version>
+ <artifactId>parent</artifactId>
+ </parent>
+ <groupId>com.test</groupId>
+ <artifactId>bom</artifactId>
+ <version>1.0.0</version>
+ <packaging>bom</packaging>
+ <properties>
+ <project1Version>1.0.0</project1Version>
+ <project2Version>1.0.0</project2Version>
+ </properties>
+ <dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>com.test</groupId>
+ <artifactId>project1</artifactId>
+ <version>${project1Version}</version>
+ </dependency>
+ <dependency>
+ <groupId>com.test</groupId>
+ <artifactId>project2</artifactId>
+ <version>${project2Version}</version>
+ </dependency>
+ </dependencies>
+ </dependencyManagement>
+ </project>
+
+```
+
+## System Dependencies
+
+`Important note: This is deprecated.`
+
+Dependencies with the scope _system_ are not looked up in the Maven repository system. Instead the `dependency` element contains a `systemPath` pointing to a jar on the local file system.
+
+The system scope is commonly used to tell Maven about dependencies provided by the JDK or the VM. System dependencies are especially useful for resolving dependencies on artifacts which are now provided by the JDK, but were available as separate downloads earlier. A typical examples is the Java Authentication and Authorization Service (JAAS):
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>javax.security</groupId>
+ <artifactId>jaas</artifactId>
+ <version>1.0.01</version>
+ <scope>system</scope>
+ <systemPath>${java.home}/lib/rt.jar</systemPath>
+ </dependency>
+ </dependencies>
+ ...
+</project>
+
+```
+
+If your artifact is provided by the JDK's `tools.jar`, the system path would be defined as follows:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>sun.jdk</groupId>
+ <artifactId>tools</artifactId>
+ <version>1.5.0</version>
+ <scope>system</scope>
+ <systemPath>${java.home}/../lib/tools.jar</systemPath>
+ </dependency>
+ </dependencies>
+ ...
+</project>
+```
+
diff --git a/content/markdown/guides/introduction/introduction-to-optional-and-excludes-dependencies.md b/content/markdown/guides/introduction/introduction-to-optional-and-excludes-dependencies.md
new file mode 100644
index 00000000..f6f432ba
--- /dev/null
+++ b/content/markdown/guides/introduction/introduction-to-optional-and-excludes-dependencies.md
@@ -0,0 +1,235 @@
+<!--
+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
+
+This section discusses optional dependencies and dependency exclusions. This will help users to understand what they are and when and how to use them. It also explains why exclusions are made on a per dependency basis instead of at the POM level.
+
+## Optional Dependencies
+
+Optional dependencies are used when it's not possible (for whatever reason) to split a project into sub-modules. The idea is that some of the dependencies are only used for certain features in the project and will not be needed if that feature isn't used. Ideally, such a feature would be split into a sub-module that depends on the core functionality project. This new subproject would have only non-optional dependencies, since you'd need them all if you decided to use the subproject's fun [...]
+
+However, since the project cannot be split up (again, for whatever reason), these dependencies are declared optional. If a user wants to use functionality related to an optional dependency, they have to redeclare that optional dependency in their own project. This is not the clearest way to handle this situation, but both optional dependencies and dependency exclusions are stop-gap solutions.
+
+### Why use optional dependencies?
+
+Optional dependencies save space and memory. They prevent problematic jars that violate a license agreement or cause classpath issues from being bundled into a WAR, EAR, fat jar, or the like.
+
+### How do I use the optional tag?
+
+A dependency is declared optional by setting the `<optional>` element to true in its dependency declaration:
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <dependencies>
+ <!-- declare the dependency to be set as optional -->
+ <dependency>
+ <groupId>sample.ProjectA</groupId>
+ <artifactId>Project-A</artifactId>
+ <version>1.0</version>
+ <scope>compile</scope>
+ <optional>true</optional> <!-- value will be true or false only -->
+ </dependency>
+ </dependencies>
+</project>
+
+```
+
+### How do optional dependencies work?
+
+```
+
+Project-A -> Project-B
+
+```
+
+The diagram above says that Project-A depends on Project-B. When A declares B as an optional dependency in its POM, this relationship remains unchanged. It's just like a normal build where Project-B will be added in Project-A's classpath.
+
+```
+
+Project-X -> Project-A
+
+```
+
+When another project (Project-X) declares Project-A as a dependency in its POM, the optional nature of the dependency takes effect. Project-B is not included in the classpath of Project-X. You need to declare it directly in the POM of Project X for B to be included in X's classpath.
+
+### Example
+
+Suppose there is a project named _X2_ that has similar functionality to _Hibernate_. It supports many databases such as MySQL, PostgreSQL, and several versions of Oracle. Each supported database requires an additional dependency on a driver jar. All of these dependencies are needed at compile time to build X2. However your project only uses one specific database and doesn't need drivers for the others. X2 can declare these dependencies as optional, so that when your project declares X2 a [...]
+
+## Dependency Exclusions
+
+Since Maven resolves dependencies transitively, it is possible for unwanted dependencies to be included in your project's classpath. For example, a certain older jar may have security issues or be incompatible with the Java version you're using. To address this, Maven allows you to exclude specific dependencies. Exclusions are set on a specific dependency in your POM, and are targeted at a specific groupId and artifactId. When you build your project, that artifact will not be added to yo [...]
+
+### How to use dependency exclusions
+
+Add an `<exclusions>` element in the `<dependency>` element by which the problematic jar is included.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>sample.ProjectA</groupId>
+ <artifactId>Project-A</artifactId>
+ <version>1.0</version>
+ <scope>compile</scope>
+ <exclusions>
+ <exclusion> <!-- declare the exclusion here -->
+ <groupId>sample.ProjectB</groupId>
+ <artifactId>Project-B</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+ </dependencies>
+</project>
+
+```
+
+### How dependency exclusion works and when to use it **( as a last resort! )**
+
+```
+
+Project-A
+ -> Project-B
+ -> Project-D <! -- This dependency should be excluded -->
+ -> Project-E
+ -> Project-F
+ -> Project C
+
+```
+
+The diagram shows that Project-A depends on both Project-B and C. Project-B depends on Project-D. Project-D depends on both Project-E and F. By default, Project A's classpath will include:
+
+```
+B, C, D, E, F
+```
+
+Suppose you don't want project D and its dependencies to be added to Project A's classpath because some of Project-D's dependencies are missing from the repository, and you don't need the functionality in Project-B that depends on Project-D anyway. Project-B's developers could have marked the dependency on Project-D `<optional>true</optional>`:
+
+```xml
+<dependency>
+ <groupId>sample.ProjectD</groupId>
+ <artifactId>ProjectD</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <optional>true</optional>
+</dependency>
+```
+
+Unfortunately, they didn't. As a last resort, you can exclude it on your own POM for Project-A like this:
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>sample.ProjectA</groupId>
+ <artifactId>Project-A</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>sample.ProjectB</groupId>
+ <artifactId>Project-B</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <exclusions>
+ <exclusion>
+ <groupId>sample.ProjectD</groupId> <!-- Exclude Project-D from Project-B -->
+ <artifactId>Project-D</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+ </dependencies>
+</project>
+
+```
+
+If you deploy Project-A to a repository, and Project-X declares a normal dependency on Project-A, will Project-D still be excluded from the classpath?
+
+```
+
+Project-X -> Project-A
+
+```
+
+The answer is **Yes**. Project-A has declared that it doesn't need Project-D to run, so it won't be brought in as a transitive dependency of Project-A.
+
+Now, consider that Project-X depends on Project-Y, as in the diagram below:
+
+```
+
+Project-X -> Project-Y
+ -> Project-B
+ -> Project-D
+ ...
+
+```
+
+Project-Y also has a dependency on Project-B, and it does need the features supported by Project-D. Therefore, it will NOT place an exclusion on Project-D in its dependency list. It may also supply an additional repository, from which it can resolve Project-E. In this case, it's important that Project-D **is not** excluded globally, since it is a legitimate dependency of Project-Y.
+
+As another scenario, suppose the dependency you don't want is Project-E instead of Project-D. How do you exclude it? See the diagram below:
+
+```
+
+Project-A
+ -> Project-B
+ -> Project-D
+ -> Project-E <!-- Exclude this dependency -->
+ -> Project-F
+ -> Project C
+
+```
+
+Exclusions work on the entire dependency graph below the point where they are declared. If you want to exclude Project-E instead of Project-D, simply change the exclusion to point at Project-E, but you don't move the exclusion down to Project-D. You cannot change Project-D's POM. If you could, you would use optional dependencies instead of exclusions, or split Project-D up into multiple subprojects, each with nothing but normal dependencies.
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>sample.ProjectA</groupId>
+ <artifactId>Project-A</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <packaging>jar</packaging>
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>sample.ProjectB</groupId>
+ <artifactId>Project-B</artifactId>
+ <version>1.0-SNAPSHOT</version>
+ <exclusions>
+ <exclusion>
+ <groupId>sample.ProjectE</groupId> <!-- Exclude Project-E from Project-B -->
+ <artifactId>Project-E</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+ </dependencies>
+</project>
+
+```
+
+### Why exclusions are made on a per-dependency basis, rather than at the POM level
+
+This is mainly to be sure the dependency graph is predictable, and to keep inheritance effects from excluding a dependency that should not be excluded. If you get to the method of last resort and have to put in an exclusion, you should be absolutely certain which of your dependencies is bringing in that unwanted transitive dependency.
+
+If you truly want to ensure that a particular dependency appears nowhere in your classpath, regardless of path, the [banned dependencies rule](/enforcer/enforcer-rules/bannedDependencies.html) can be configured to fail the build if a problematic dependency is found. When the build fails, you'll need to add specific exclusions on each path the enforcer finds.
+
diff --git a/content/markdown/guides/introduction/introduction-to-plugins.md b/content/markdown/guides/introduction/introduction-to-plugins.md
new file mode 100644
index 00000000..536be8ed
--- /dev/null
+++ b/content/markdown/guides/introduction/introduction-to-plugins.md
@@ -0,0 +1,46 @@
+<!--
+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 to Maven Plugin Development
+
+Maven consists of a core engine which provides basic project-processing capabilities and build-process management, and a host of plugins which are used to execute the actual build tasks.
+
+## What is a Plugin?
+
+"Maven" is really just a core framework for a collection of Maven Plugins. In other words, plugins are where much of the real action is performed, plugins are used to: create jar files, create war files, compile code, unit test code, create project documentation, and on and on. Almost any action that you can think of performing on a project is implemented as a Maven plugin.
+
+Plugins are the central feature of Maven that allow for the reuse of common build logic across multiple projects. They do this by executing an "action" (i.e. creating a WAR file or compiling unit tests) in the context of a project's description - the Project Object Model (POM). Plugin behavior can be customized through a set of unique parameters which are exposed by a description of each plugin goal (or Mojo).
+
+One of the simplest plugins in Maven is the Clean Plugin. The [Maven Clean plugin](../../plugins/maven-clean-plugin/) (maven-clean-plugin) is responsible for removing the target directory of a Maven project. When you run "mvn clean", Maven executes the "clean" goal as defined in the Clean plug-in, and the target directory is removed. The Clean plugin [defines a parameter](../../plugins/maven-clean-plugin/clean-mojo.html) which can be used to customize plugin behavior, this parameter is c [...]
+
+## What is a Mojo (_And Why the H--- is it Named 'Mojo'_)?
+
+A Mojo is really just a **goal** in Maven, and plug-ins consist of any number of goals (Mojos). Mojos can be defined as annotated Java classes or Beanshell script. A Mojo specifies metadata about a goal: a goal name, which phase of the lifecycle it fits into, and the parameters it is expecting.
+
+MOJO is a play on POJO (Plain-old-Java-object), substituting "Maven" for "Plain". Mojo is also an interesting word (see [definition](http://www.answers.com/mojo&r=67)). From [Wikipedia](http://www.wikipedia.org), a "mojo" is defined as: "...a small bag worn by a person under the clothes (also known as a mojo hand). Such bags were thought to have supernatural powers, such as protecting from evil, bringing good luck, etc."
+
+## What is the Build Lifecycle? (Overview)
+
+The build lifecycle is a series of common **stage**s through which all project builds naturally progress. Plugin goals are bound to specific stages in the lifecycle.
+
+# Resources
+
+1. [Plugin Development Center](/plugin-developers/index.html)
+2. [Configuring plugins](../mini/guide-configuring-plugins.html)
+
diff --git a/content/markdown/guides/introduction/introduction-to-profiles.md b/content/markdown/guides/introduction/introduction-to-profiles.md
new file mode 100644
index 00000000..0722aaf4
--- /dev/null
+++ b/content/markdown/guides/introduction/introduction-to-profiles.md
@@ -0,0 +1,635 @@
+<!--
+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 to Build Profiles
+
+<!-- MACRO{toc|section=0|fromDepth=2|toDepth=5} -->
+
+Apache Maven goes to great lengths to ensure that builds are portable. Among other things, this means allowing build configuration inside the POM, avoiding **all** filesystem references (in inheritance, dependencies, and other places), and leaning much more heavily on the local repository to store the metadata needed to make this possible.
+
+However, sometimes portability is not entirely possible. Under certain conditions, plugins may need to be configured with local filesystem paths. Under other circumstances, a slightly different dependency set will be required, and the project's artifact name may need to be adjusted slightly. And at still other times, you may even need to include a whole plugin in the build lifecycle depending on the detected build environment.
+
+To address these circumstances, Maven supports build profiles. Profiles are specified using a subset of the elements available in the POM itself (plus one extra section), and are triggered in any of a variety of ways. They modify the POM at build time, and are meant to be used in complementary sets to give equivalent-but-different parameters for a set of target environments (providing, for example, the path of the appserver root in the development, testing, and production environments). [...]
+
+## What are the different types of profile? Where is each defined?
+
+- Per Project
+
+ \- Defined in the POM itself `(pom.xml)`.
+
+- Per User
+
+ \- Defined in the [Maven-settings](/ref/current/maven-settings/settings.html) `(%USER_HOME%/.m2/settings.xml)`.
+
+- Global
+
+ \- Defined in the [global Maven-settings](/ref/current/maven-settings/settings.html) `(${maven.home}/conf/settings.xml)`.
+
+## Profile Inheritance
+
+The profiles are not inherited as other POM elements by child POMs. Instead they are resolved very early by the [Maven Model Builder](/ref/current/maven-model-builder/) and only the effects of active profiles are inherited (e.g. the plugins defined in the profile). That also leads to the fact that implicit profile activation only has an effect on the surrounding profile container but never on any other profile (even if it has the same id).
+
+## How can a profile be triggered? How does this vary according to the type of profile being used?
+
+A profile can be activated in several ways:
+
+- Explicitly
+- Implicitly
+ - Based on OS
+ - Based on system properties
+ - Based on presence of files
+
+Refer to the sections below for details.
+
+### Details on profile activation
+
+#### Explicit profile activation
+
+Profiles can be explicitly specified using the `-P` command line flag.
+
+This flag is followed by a comma-delimited list of profile IDs to use. The profile(s) specified in the option are activated in addition to any profiles which are activated by their activation configuration or the `<activeProfiles>` section in `settings.xml`. From Maven 4 onward, Maven will refuse to activate or deactivate a profile that cannot be resolved. To prevent this, prefix the profile identifier with an `?`, marking it as optional:
+
+```
+mvn groupId:artifactId:goal -P profile-1,profile-2,?profile-3
+```
+
+Profiles can be activated in the Maven settings, via the `<activeProfiles>` section. This section takes a list of `<activeProfile>` elements, each containing a profile-id inside.
+
+```xml
+<settings>
+ ...
+ <activeProfiles>
+ <activeProfile>profile-1</activeProfile>
+ </activeProfiles>
+ ...
+</settings>
+```
+
+Profiles listed in the `<activeProfiles>` tag would be activated by default every time a project use it.
+
+Profiles can also be active by default using a configuration like the following in a POM:
+
+```xml
+<profiles>
+ <profile>
+ <id>profile-1</id>
+ <activation>
+ <activeByDefault>true</activeByDefault>
+ </activation>
+ ...
+ </profile>
+</profiles>
+```
+
+This profile will automatically be active for all builds unless another profile in the same POM is activated using one of the previously described methods. All profiles that are active by default are automatically deactivated when a profile in the POM is activated on the command line or through its activation config.
+
+#### Implicit profile activation
+
+Profiles can be automatically triggered based on the detected state of the build environment. These triggers are specified via an `<activation>` section in the profile itself. Currently, this detection is limited to JDK version matching, operating system matching or the presence/the value of a system property. The implicit profile activation always only refers to the container profile (and not to profiles in other modules with the same id). Here are some examples.
+
+##### JDK
+
+The following configuration will trigger the profile when the JDK's version _starts with_ "1.4" (eg. "1.4.0\_08", "1.4.2\_07", "1.4"), in particular it _won't be active_ for **newer** versions like "1.8" or "11":
+
+```xml
+<profiles>
+ <profile>
+ <activation>
+ <jdk>1.4</jdk>
+ </activation>
+ ...
+ </profile>
+</profiles>
+```
+
+[Ranges](/enforcer/enforcer-rules/versionRanges.html) can also be used. Range values must start with either `[` or `(`. Otherwise, the value is interpreted as a prefix. The following honours versions 1.3, 1.4 and 1.5.
+
+```xml
+<profiles>
+ <profile>
+ <activation>
+ <jdk>[1.3,1.6)</jdk>
+ </activation>
+ ...
+ </profile>
+</profiles>
+```
+
+_Note:_ an upper bound such as `,1.5]` is likely not to include most releases of 1.5, since they will have an additional "patch" release such as `_05` that is not taken into consideration in the above range.
+
+##### OS
+
+This next one will activate based on the detected operating system. See the [Maven Enforcer Plugin](/enforcer/enforcer-rules/requireOS.html) for more details about OS values.
+
+```xml
+<profiles>
+ <profile>
+ <activation>
+ <os>
+ <name>Windows XP</name>
+ <family>Windows</family>
+ <arch>x86</arch>
+ <version>5.1.2600</version>
+ </os>
+ </activation>
+ ...
+ </profile>
+</profiles>
+```
+
+The values are interpreted as Strings and are matched against the [Java System properties](https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html) `os.name`, `os.arch`, `os.version` and the family being derived from those.
+
+Each value can be prefixed with `!` to negate the matching. The values match if they are (not) equal to the actual String value (**case insensitive**). All given OS conditions must match for the profile to be considered for activation.
+
+Since [Maven 3.9.7](https://issues.apache.org/jira/browse/MNG-5726) the value for `version` may be prefixed with `regex:`. In that case [regular pattern matching](https://docs.oracle.com/javase/tutorial/essential/regex/) is applied for the version matching and applied against the **lower case** `os.version` value.
+
+The actual OS values which need to match the given values are emitted when executing `mvn --version`.
+
+##### Property
+
+The profile below will be activated when the system property "debug" is specified with any value:
+
+```xml
+<profiles>
+ <profile>
+ <activation>
+ <property>
+ <name>debug</name>
+ </property>
+ </activation>
+ ...
+ </profile>
+</profiles>
+```
+
+The following profile will be activated when the system property "debug" is not defined at all:
+
+```xml
+<profiles>
+ <profile>
+ <activation>
+ <property>
+ <name>!debug</name>
+ </property>
+ </activation>
+ ...
+ </profile>
+</profiles>
+```
+
+The following profile will be activated when the system property "debug" is defined with no value, or is defined with the value "true".
+
+```xml
+<profiles>
+ <profile>
+ <activation>
+ <property>
+ <name>debug</name>
+ <value>true</value>
+ </property>
+ </activation>
+ ...
+ </profile>
+</profiles>
+```
+
+To activate this you would type one of those on the command line:
+
+```
+mvn groupId:artifactId:goal -Ddebug
+mvn groupId:artifactId:goal -Ddebug=true
+```
+
+The following profile will be activated when the system property "debug" is not defined, or is defined with a value which is not "true".
+
+```xml
+<profiles>
+ <profile>
+ <activation>
+ <property>
+ <name>debug</name>
+ <value>!true</value>
+ </property>
+ </activation>
+ ...
+ </profile>
+</profiles>
+```
+
+To activate this you would type one of those on the command line:
+
+```
+mvn groupId:artifactId:goal
+mvn groupId:artifactId:goal -Ddebug=false
+```
+
+The next example will trigger the profile when the system property "environment" is specified with the value "test":
+
+```xml
+<profiles>
+ <profile>
+ <activation>
+ <property>
+ <name>environment</name>
+ <value>test</value>
+ </property>
+ </activation>
+ ...
+ </profile>
+</profiles>
+```
+
+To activate this you would type this on the command line:
+
+```
+mvn groupId:artifactId:goal -Denvironment=test
+```
+
+Profiles in the POM can also be activated based on properties from active profiles from the `settings.xml`.
+
+**Note**: Environment variables like `FOO` are available as properties of the form `env.FOO`. Further note that environment variable names are normalized to all upper-case on Windows.
+
+Since Maven 3.9.0 one can also evaluate the POM's packaging value by referencing property `packaging`. This is only useful where the profile activation is defined in a common parent POM which is reused among multiple Maven projects. The next example will trigger the profile when a project with packaging `war` is built:
+
+```xml
+<profiles>
+ <profile>
+ <activation>
+ <property>
+ <name>packaging</name>
+ <value>war</value>
+ </property>
+ </activation>
+ ...
+ </profile>
+</profiles>
+```
+
+##### Files
+
+This example will trigger the profile when the generated file `target/generated-sources/axistools/wsdl2java/org/apache/maven` is missing.
+
+```xml
+<profiles>
+ <profile>
+ <activation>
+ <file>
+ <missing>target/generated-sources/axistools/wsdl2java/org/apache/maven</missing>
+ </file>
+ </activation>
+ ...
+ </profile>
+</profiles>
+```
+
+The tags `<exists>` and `<missing>` can be interpolated. Supported variables are system properties like `${user.home}` and environment variables like `${env.HOME}`. Please note that properties and values defined in the POM itself are not available for interpolation here, e.g. the above example activator cannot use `${project.build.directory}` but needs to hard-code the path `target`.
+
+#### Multiple conditions
+
+Different implicit activation types can be combined in one profile. The profile is then only active if all conditions are met (since Maven 3.2.2, [MNG-4565](https://issues.apache.org/jira/browse/MNG-4565)). Using the same type more than once in the same profile is not supported ([MNG-5909](https://issues.apache.org/jira/browse/MNG-5909), [MNG-3328](https://issues.apache.org/jira/browse/MNG-3328)).
+
+### Deactivating a profile
+
+One or more profiles can be deactivated using the command line by prefixing their identifier with either the character '!' or '-' as shown below.
+
+**Note** that `!` needs to be escaped with `\` or quoted in Bash, ZSH and other shells as it has [a special meaning](https://www.gnu.org/software/bash/manual/html_node/Event-Designators.html). Also there is a known bug with command line option values starting with `-` ([CLI-309](https://issues.apache.org/jira/browse/CLI-309)), therefore it is recommended to use it with the syntax `-P=-profilename`.
+
+```
+mvn groupId:artifactId:goal -P !profile-1,!profile-2,!?profile-3
+```
+
+or
+
+```
+mvn groupId:artifactId:goal -P=-profile-1,-profile-2,-?profile-3
+```
+
+This can be used to deactivate profiles marked as activeByDefault or profiles that would otherwise be activated through their activation config.
+
+## Which areas of a POM can be customized by each type of profile? Why?
+
+Now that we've talked about where to specify profiles, and how to activate them, it will be useful to talk about _what_ you can specify in a profile. As with the other aspects of profile configuration, this answer is not straightforward.
+
+Depending on where you choose to configure your profile, you will have access to varying POM configuration options.
+
+### Profiles in external files
+
+Profiles specified in external files (i.e in `settings.xml` or `profiles.xml`) are not portable in the strictest sense. Anything that seems to stand a high chance of changing the result of the build is restricted to the inline profiles in the POM. Things like repository lists could simply be a proprietary repository of approved artifacts, and won't change the outcome of the build. Therefore, you will only be able to modify the `<repositories>` and `<pluginRepositories>` sections, plus an [...]
+
+The `<properties>` section allows you to specify free-form key-value pairs which will be included in the interpolation process for the POM. This allows you to specify a plugin configuration in the form of `${profile.provided.path}`.
+
+### Profiles in POMs
+
+On the other hand, if your profiles can be reasonably specified _inside_ the POM, you have many more options. The trade-off, of course, is that you can only modify _that_ project and its sub-modules. Since these profiles are specified inline, and therefore have a better chance of preserving portability, it's reasonable to say you can add more information to them without the risk of that information being unavailable to other users.
+
+Profiles specified in the POM can modify [the following POM elements](/ref/current/maven-model/maven.html):
+
+- `<repositories>`
+- `<pluginRepositories>`
+- `<dependencies>`
+- `<plugins>`
+- `<properties>` (not actually available in the main POM, but used behind the scenes)
+- `<modules>`
+- `<reports>`
+- `<reporting>`
+- `<dependencyManagement>`
+- `<distributionManagement>`
+- a subset of the `<build>` element, which consists of:
+ - `<defaultGoal>`
+ - `<resources>`
+ - `<testResources>`
+ - `<directory>`
+ - `<finalName>`
+ - `<filters>`
+ - `<pluginManagement>`
+ - `<plugins>`
+
+### POM elements outside <profiles>
+
+We don't allow modification of some POM elements outside of POM-profiles because these runtime modifications will not be distributed when the POM is deployed to the repository system, making that person's build of that project completely unique from others. While you can do this to some extent with the options given for external profiles, the danger is limited. Another reason is that this POM info is sometimes being reused from the parent POM.
+
+External files such as `settings.xml` and `profiles.xml` also do not support elements outside the POM-profiles. Let us take this scenario for elaboration. When the effective POM is deployed to a remote repository, any person can pickup its info out of the repository and use it to build a Maven project directly. Now, imagine that if we can set profiles in dependencies, which is very important to a build, or in any other elements outside POM-profiles in `settings.xml` then most probably we [...]
+
+## Profile Order
+
+All profile elements in a POM from active profiles overwrite the global elements with the same name of the POM or extend those in case of collections. In case multiple profiles are active in the same POM or external file, the ones which are defined **later** take precedence over the ones defined **earlier** (independent of their profile id and activation order).
+
+Example:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <repositories>
+ <repository>
+ <id>global-repo</id>
+ ...
+ </repository>
+ </repositories>
+ ...
+ <profiles>
+ <profile>
+ <id>profile-1</id>
+ <activation>
+ <activeByDefault>true</activeByDefault>
+ </activation>
+ <repositories>
+ <repository>
+ <id>profile-1-repo</id>
+ ...
+ </repository>
+ </repositories>
+ </profile>
+ <profile>
+ <id>profile-2</id>
+ <activation>
+ <activeByDefault>true</activeByDefault>
+ </activation>
+ <repositories>
+ <repository>
+ <id>profile-2-repo</id>
+ ...
+ </repository>
+ </repositories>
+ </profile>
+ ...
+ </profiles>
+ ...
+</project>
+```
+
+This leads to the repository list: `profile-2-repo, profile-1-repo, global-repo`.
+
+## Profile Pitfalls
+
+We've already mentioned the fact that adding profiles to your build has the potential to break portability for your project. We've even gone so far as to highlight circumstances where profiles are likely to break project portability. However, it's worth reiterating those points as part of a more coherent discussion about some pitfalls to avoid when using profiles.
+
+There are two main problem areas to keep in mind when using profiles. First are external properties, usually used in plugin configurations. These pose the risk of breaking portability in your project. The other, more subtle area is the incomplete specification of a natural set of profiles.
+
+### External Properties
+
+External property definition concerns any property value defined outside the `pom.xml` but not defined in a corresponding profile inside it. The most obvious usage of properties in the POM is in plugin configuration. While it is certainly possible to break project portability without properties, these critters can have subtle effects that cause builds to fail. For example, specifying appserver paths in a profile that is specified in the `settings.xml` may cause your integration test plug [...]
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.myco.plugins</groupId>
+ <artifactId>spiffy-integrationTest-plugin</artifactId>
+ <version>1.0</version>
+ <configuration>
+ <appserverHome>${appserver.home}</appserverHome>
+ </configuration>
+ </plugin>
+ ...
+ </plugins>
+ </build>
+ ...
+</project>
+```
+
+Now, in your local `${user.home}/.m2/settings.xml`, you have:
+
+```xml
+<settings>
+ ...
+ <profiles>
+ <profile>
+ <id>appserverConfig</id>
+ <properties>
+ <appserver.home>/path/to/appserver</appserver.home>
+ </properties>
+ </profile>
+ </profiles>
+
+ <activeProfiles>
+ <activeProfile>appserverConfig</activeProfile>
+ </activeProfiles>
+ ...
+</settings>
+```
+
+When you build the **integration-test** lifecycle phase, your integration tests pass, since the path you've provided allows the test plugin to install and test this web application.
+
+_However_, when your colleague attempts to build to **integration-test**, his build fails spectacularly, complaining that it cannot resolve the plugin configuration parameter `<appserverHome>`, or worse, that the value of that parameter - literally `${appserver.home}` - is invalid (if it warns you at all).
+
+Congratulations, your project is now non-portable. Inlining this profile in your `pom.xml` can help alleviate this, with the obvious drawback that each project hierarchy (allowing for the effects of inheritance) now have to specify this information. Since Maven provides good support for project inheritance, it's possible to stick this sort of configuration in the `<pluginManagement>` section of a team-level POM or similar, and simply inherit the paths.
+
+Another, less attractive answer might be standardization of development environments. However, this will tend to compromise the productivity gain that Maven is capable of providing.
+
+### Incomplete Specification of a Natural Profile Set
+
+In addition to the above portability-breaker, it's easy to fail to cover all cases with your profiles. When you do this, you're usually leaving one of your target environments high and dry. Let's take the example `pom.xml` snippet from above one more time:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.myco.plugins</groupId>
+ <artifactId>spiffy-integrationTest-plugin</artifactId>
+ <version>1.0</version>
+ <configuration>
+ <appserverHome>${appserver.home}</appserverHome>
+ </configuration>
+ </plugin>
+ ...
+ </plugins>
+ </build>
+ ...
+</project>
+```
+
+Now, consider the following profile, which would be specified inline in the `pom.xml`:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <profiles>
+ <profile>
+ <id>appserverConfig-dev</id>
+ <activation>
+ <property>
+ <name>env</name>
+ <value>dev</value>
+ </property>
+ </activation>
+ <properties>
+ <appserver.home>/path/to/dev/appserver</appserver.home>
+ </properties>
+ </profile>
+
+ <profile>
+ <id>appserverConfig-dev-2</id>
+ <activation>
+ <property>
+ <name>env</name>
+ <value>dev-2</value>
+ </property>
+ </activation>
+ <properties>
+ <appserver.home>/path/to/another/dev/appserver2</appserver.home>
+ </properties>
+ </profile>
+ </profiles>
+ ..
+</project>
+```
+
+This profile looks quite similar to the one from the last example, with a few important exceptions: it's plainly geared toward a development environment, a new profile named `appserverConfig-dev-2` is added and it has an activation section that will trigger its inclusion when the system properties contain "env=dev" for a profile named `appserverConfig-dev` and "env=dev-2" for a profile named `appserverConfig-dev-2`. So, executing:
+
+```
+mvn -Denv=dev-2 integration-test
+```
+
+will result in a successful build, applying the properties given by profile named `appserverConfig-dev-2`. And when we execute
+
+```
+mvn -Denv=dev integration-test
+```
+
+it will result in a successful build applying the properties given by the profile named `appserverConfig-dev`. However, executing:
+
+```
+mvn -Denv=production integration-test
+```
+
+will not do a successful build. Why? Because, the resulting non-interpolated literal value of `${appserver.home}` will not be a valid path for deploying and testing your web application. We haven't considered the case for the production environment when writing our profiles. The "production" environment (env=production), along with "test" and possibly even "local" constitute a natural set of target environments for which we may want to build the integration-test lifecycle phase. The inco [...]
+
+As a quick aside, it's possible for user-specific profiles to act in a similar way. This means that profiles for handling different environments which are keyed to the user can act up when the team adds a new developer. While I suppose this _could_ act as useful training for the newbie, it just wouldn't be nice to throw them to the wolves in this way. Again, be sure to think of the _whole_ set of profiles.
+
+## How can I tell which profiles are in effect during a build?
+
+Determining active profiles will help the user to know what particular profiles has been executed during a build. We can use the [Maven Help Plugin](/plugins/maven-help-plugin/) to tell what profiles are in effect during a build.
+
+```
+mvn help:active-profiles
+```
+
+Let us have some small samples that will help us to understand more on the _active-profiles_ goal of that plugin.
+
+From the last example of profiles in the `pom.xml`, you'll notice that there are two profiles named `appserverConfig-dev` and `appserverConfig-dev-2` which has been given different values for properties. If we go ahead and execute:
+
+```
+mvn help:active-profiles -Denv=dev
+```
+
+The result will be a bulleted list of the id of the profile with an activation property of "env=dev" together with the source where it was declared. See sample below.
+
+```
+The following profiles are active:
+
+ - appserverConfig-dev (source: pom)
+```
+
+Now if we have a profile declared in `settings.xml` (refer to the sample of profile in `settings.xml`) and that have been set to be an active profile and execute:
+
+```
+mvn help:active-profiles
+```
+
+The result should be something like this
+
+```
+The following profiles are active:
+
+ - appserverConfig (source: settings.xml)
+```
+
+Even though we don't have an activation property, a profile has been listed as active. Why? Like we mentioned before, a profile that has been set as an active profile in the `settings.xml` is automatically activated.
+
+Now if we have something like a profile in the `settings.xml` that has been set as an active profile and also triggered a profile in the POM. Which profile do you think will have an effect on the build?
+
+```
+mvn help:active-profiles -P appserverConfig-dev
+```
+
+This will list the activated profiles:
+
+```
+The following profiles are active:
+
+ - appserverConfig-dev (source: pom)
+ - appserverConfig (source: settings.xml)
+```
+
+Even though it listed the two active profiles, we are not sure which one of them has been applied. To see the effect on the build execute:
+
+```
+mvn help:effective-pom -P appserverConfig-dev
+```
+
+This will print the effective POM for this build configuration out to the console. Take note that profiles in the `settings.xml` takes higher priority than profiles in the POM. So the profile that has been applied here is `appserverConfig` not `appserverConfig-dev`.
+
+If you want to redirect the output from the plugin to a file called `effective-pom.xml`, use the command-line option `-Doutput=effective-pom.xml`.
+
+## Naming Conventions
+
+By now you've noticed that profiles are a natural way of addressing the problem of different build configuration requirements for different target environments. Above, we discussed the concept of a "natural set" of profiles to address this situation, and the importance of considering the whole set of profiles that will be required.
+
+However, the question of how to organize and manage the evolution of that set is non-trivial as well. Just as a good developer strives to write self-documenting code, it's important that your profile id's give a hint to their intended use. One good way to do this is to use the common system property trigger as part of the name for the profile. This might result in names like **env-dev**, **env-test**, and **env-prod** for profiles that are triggered by the system property **env**. Such a [...]
+
+```
+mvn -Denv=test <phase>
+```
+
+The right command-line option can be had by simply substituting "=" for "-" in the profile id.
+
diff --git a/content/markdown/guides/introduction/introduction-to-repositories.md b/content/markdown/guides/introduction/introduction-to-repositories.md
new file mode 100644
index 00000000..ad03c6dc
--- /dev/null
+++ b/content/markdown/guides/introduction/introduction-to-repositories.md
@@ -0,0 +1,113 @@
+<!--
+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 to Repositories
+
+## Artifact Repositories
+
+A repository in Maven holds build artifacts of varying types.
+
+There are exactly two types of repositories: **local** and **remote**:
+
+1. the **local** repository is a directory on the computer where Maven runs. It caches remote downloads and contains temporary build artifacts that you have not yet released.
+2. **remote** repositories refer to any other type of repository, accessed by a variety of protocols such as `file://` and `https://`. These repositories might be a truly remote repository set up by a third party to provide their artifacts for downloading (for example, [repo.maven.apache.org](https://repo.maven.apache.org/maven2/)). Other "remote" repositories may be internal repositories set up on a file or HTTP server within your company, used to share private artifacts between develop [...]
+
+Local and remote repositories are structured the same way so that scripts can run on either side, or they can be synced for offline use. The layout of the repositories is completely transparent to the Maven user, however.
+
+## Using Repositories
+
+In general, you should not need to do anything with the local repository on a regular basis, except clean it out if you are short on disk space (or erase it completely if you are willing to download everything again).
+
+For the remote repositories, they are used for both downloading and uploading (if you have the permission to do so).
+
+### Downloading from a Remote Repository
+
+Downloading in Maven is triggered by a project declaring a dependency that is not present in the local repository (or for a `SNAPSHOT`, when the remote repository contains one that is newer). By default, Maven will download from the [central](https://repo.maven.apache.org/maven2/) repository.
+
+To override this, you need to specify a `mirror` as shown in [Using Mirrors for Repositories](../mini/guide-mirror-settings.html).
+
+You can set this in your `settings.xml` file to globally use a certain mirror. However, it is common for a project to [customise the repository in its `pom.xml`](../mini/guide-multiple-repositories.html) and that your setting will take precedence. If dependencies are not being found, check that you have not overridden the remote repository.
+
+For more information on dependencies, see [Dependency Mechanism](./introduction-to-dependency-mechanism.html).
+
+### Using Mirrors for the Central Repository
+
+There are [several official Central repositories](/repository/) geographically distributed. You can make changes to your `settings.xml` file to use one or more mirrors. Instructions for this can be found in the guide [Using Mirrors for Repositories](../mini/guide-mirror-settings.html).
+
+## Building Offline
+
+If you are temporarily disconnected from the internet and you need to build your projects offline, you can use the offline switch on the CLI:
+
+```
+mvn -o package
+```
+
+Many plugins honor the offline setting and do not perform any operations that connect to the internet. Some examples are resolving Javadoc links and link checking the site.
+
+## Uploading to a Remote Repository
+
+While this is possible for any type of remote repository, you must have the permission to do so. To have someone upload to the Central Maven repository, see [Repository Center](../../repository/index.html).
+
+## Internal Repositories
+
+When using Maven, particularly in a corporate environment, connecting to the internet to download dependencies is not acceptable for security, speed or bandwidth reasons. For that reason, it is desirable to set up an internal repository to house a copy of artifacts, and to publish private artifacts to.
+
+Such an internal repository can be downloaded using HTTP or the file system (with a `file://` URL), and uploaded to using SCP, FTP, or a file copy.
+
+As far as Maven is concerned, there is nothing special about this repository: it is another **remote repository** that contains artifacts to download to a user's local cache, and is a publish destination for artifact releases.
+
+Additionally, you may want to share the repository server with your generated project sites. For more information on creating and deploying sites, see [Creating a Site](../mini/guide-site.html).
+
+## Setting up the Internal Repository
+
+Setting up an internal repository just requires that you have a place to put it, and then copy required artifacts there using the same layout as in a remote repository such as [repo.maven.apache.org](https://repo.maven.apache.org/maven2/).
+
+Do _not_ scrape or `rsync://` a full copy of central as there is a large amount of data there and doing so will get you banned. You can use a program such as those described on the [Repository Management](../../repository-management.html) page to run your internal repository's server, download from the internet as required, and then hold the artifacts in your internal repository for faster downloading later.
+
+The other options are to manually download and vet releases, then copy them to the internal repository; or to have Maven download them for a user, then manually upload the vetted artifacts to the internal repository which is used for releases. This step is useful for artifacts whose license forbids their automatic distribution, such as several J2EE JARs.
+
+## Using the Internal Repository
+
+Using the internal repository is quite simple. Simply make a change to add a `repositories` element:
+
+```xml
+
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <repositories>
+ <repository>
+ <id>my-internal-site</id>
+ <url>https://myserver/repo</url>
+ </repository>
+ </repositories>
+ ...
+</project>
+
+```
+
+If your internal repository requires authentication, the `id` element can be used in your [settings](../../settings.html#Servers) file to specify login information.
+
+## Deploying to the Internal Repository
+
+One of the most important reasons to have one or more internal repositories is to be able to publish your own private releases.
+
+To publish to the repository, you will need to have access via one of SCP, SFTP, FTP, WebDAV, or the filesystem. Connectivity is accomplished with the various [wagons](/wagon/wagon-providers/index.html). Some wagons may need to be added as [extension](/ref/current/maven-model/maven.html#class_extension) to your build.
+
+<!-- For example, to set up an SCP transfer.-->
+<!-- show the scp example.-->
diff --git a/content/markdown/guides/introduction/introduction-to-the-lifecycle.md b/content/markdown/guides/introduction/introduction-to-the-lifecycle.md
new file mode 100644
index 00000000..6b72ef5a
--- /dev/null
+++ b/content/markdown/guides/introduction/introduction-to-the-lifecycle.md
@@ -0,0 +1,312 @@
+<!--
+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 to the Build Lifecycle
+
+<!-- MACRO{toc|section=0|fromDepth=2|toDepth=2} -->
+
+## Build Lifecycle Basics
+
+Maven is based around the central concept of a build lifecycle. What this means is that the process for building and distributing a particular artifact (project) is clearly defined.
+
+For the person building a project, this means that it is only necessary to learn a small set of commands to build any Maven project, and the [POM](./introduction-to-the-pom.html) will ensure they get the results they desired.
+
+There are three built-in build lifecycles: default, clean and site. The `default` lifecycle handles your project deployment, the `clean` lifecycle handles project cleaning, while the `site` lifecycle handles the creation of your project's web site.
+
+### A Build Lifecycle is Made Up of Phases
+
+Each of these build lifecycles is defined by a different list of build phases, wherein a build phase represents a stage in the lifecycle.
+
+For example, the default lifecycle comprises of the following phases (for a complete list of the lifecycle phases, refer to the [Lifecycle Reference](#Lifecycle_Reference)):
+
+- `validate` - validate the project is correct and all necessary information is available
+- `compile` - compile the source code of the project
+- `test` - test the compiled source code using a suitable unit testing framework. These tests should not require the code be packaged or deployed
+- `package` - take the compiled code and package it in its distributable format, such as a JAR.
+- `verify` - run any checks on results of integration tests to ensure quality criteria are met
+- `install` - install the package into the local repository, for use as a dependency in other projects locally
+- `deploy` - done in the build environment, copies the final package to the remote repository for sharing with other developers and projects.
+
+These lifecycle phases (plus the other lifecycle phases not shown here) are executed sequentially to complete the `default` lifecycle. Given the lifecycle phases above, this means that when the default lifecycle is used, Maven will first validate the project, then will try to compile the sources, run those against the tests, package the binaries (e.g. jar), run integration tests against that package, verify the integration tests, install the verified package to the local repository, then [...]
+
+_[top](./introduction-to-the-lifecycle.html)._
+
+### Usual Command Line Calls
+
+You should select the phase that matches your outcome. If you want your jar, run `package`. If you want to run the unit tests, run `test`.
+
+If you are uncertain what you want, the preferred phase to call is
+
+```
+mvn verify
+```
+
+This command executes each default lifecycle phase in order (`validate`, `compile`, `package`, etc.), before executing `verify`. You only need to call the last build phase to be executed, in this case, `verify`. In most cases the effect is the same as `package`. However, in case there are integration tests, these will be executed as well. And during the `verify` phase additional checks can be done, e.g. if your code is written according to predefined checkstyle rules.
+
+In a build environment, use the following call to cleanly build and deploy artifacts into the shared repository.
+
+```
+mvn clean deploy
+```
+
+The same command can be used in a multi-module scenario (i.e. a project with one or more subprojects). Maven traverses into every subproject and executes `clean`, then executes `deploy` (including all of the prior build phase steps).
+
+_[top](./introduction-to-the-lifecycle.html)._
+
+### A Build Phase is Made Up of Plugin Goals
+
+However, even though a build phase is responsible for a specific step in the build lifecycle, the manner in which it carries out those responsibilities may vary. And this is done by declaring the plugin goals bound to those build phases.
+
+A plugin goal represents a specific task (finer than a build phase) which contributes to the building and managing of a project. It may be bound to zero or more build phases. A goal not bound to any build phase could be executed outside of the build lifecycle by direct invocation. The order of execution depends on the order in which the goal(s) and the build phase(s) are invoked. For example, consider the command below. The `clean` and `package` arguments are build phases, while the `dep [...]
+
+```
+mvn clean dependency:copy-dependencies package
+```
+
+If this were to be executed, the `clean` phase will be executed first (meaning it will run all preceding phases of the clean lifecycle, plus the `clean` phase itself), and then the `dependency:copy-dependencies` goal, before finally executing the `package` phase (and all its preceding build phases of the default lifecycle).
+
+Moreover, if a goal is bound to one or more build phases, that goal will be called in all those phases.
+
+Furthermore, a build phase can also have zero or more goals bound to it. If a build phase has no goals bound to it, that build phase will not execute. But if it has one or more goals bound to it, it will execute all those goals.
+
+<!--~-->
+
+Multiple goals bound to a phase are executed in the same order as they are declared in the POM.
+
+It's possible to declare multiple executions for the same plugin - see [Configuring plugins](./guides/mini/guide-configuring-plugins.html#Configuring_Build_Plugins) for more details. **Note**: This does **not** mean that it's allowed to declare the same plugin multiple times in [`<plugins>` declaration section](/pom.html#Plugins)! Declaring a plugin multiple times shows warnings using Maven 3 and fail the build using Maven 4.
+
+<!--~-->
+
+_[top](./introduction-to-the-lifecycle.html)._
+
+### Some Phases Are Not Usually Called From the Command Line
+
+The phases named with hyphenated-words (`pre-*`, `post-*`, or `process-*`) are not usually directly called from the command line. These phases sequence the build, producing intermediate results that are not useful outside the build. In the case of invoking `integration-test`, the environment may be left in a hanging state.
+
+Code coverage tools such as Jacoco and execution container plugins such as Tomcat, Cargo, and Docker bind goals to the `pre-integration-test` phase to prepare the integration test container environment. These plugins also bind goals to the `post-integration-test` phase to collect coverage statistics or decommission the integration test container.
+
+Failsafe and code coverage plugins bind goals to `integration-test` and `verify` phases. The net result is test and coverage reports are available after the `verify` phase. If `integration-test` were to be called from the command line, no reports are generated. Worse is that the integration test container environment is left in a hanging state; the Tomcat webserver or Docker instance is left running, and Maven may not even terminate by itself.
+
+_[top](./introduction-to-the-lifecycle.html)._
+
+## Setting Up Your Project to Use the Build Lifecycle
+
+The build lifecycle is simple enough to use, but when you are constructing a Maven build for a project, how do you go about assigning tasks to each of those build phases?
+
+### Packaging
+
+The first, and most common way, is to set the packaging for your project via the equally named POM element `<packaging>`. Some of the valid packaging values are `jar`, `war`, `ear` and `pom`. If no packaging value has been specified, it will default to `jar`.
+
+Each packaging contains a list of goals to bind to a particular phase. For example, the `jar` packaging will bind the following goals to build phases of the default lifecycle.
+
+| Phase | plugin:goal for the `jar` packaging |
+|:-------------------------|:------------------------------------|
+| `process-resources` | `resources:resources` |
+| `compile` | `compiler:compile` |
+| `process-test-resources` | `resources:testResources` |
+| `test-compile` | `compiler:testCompile` |
+| `test` | `surefire:test` |
+| `package` | `jar:jar` |
+| `install` | `install:install` |
+| `deploy` | `deploy:deploy` |
+
+This is an almost [standard set of bindings](/ref/current/maven-core/default-bindings.html); however, some packagings handle them differently. For example, a project that is purely metadata (packaging value is `pom`) only binds goals to the `install` and `deploy` phases (for a complete list of goal-to-build-phase bindings of some of the packaging types, refer to the [Lifecycle Reference](#Lifecycle_Reference)).
+
+Note that for some packaging types to be available, you may also need to include a particular plugin in the `<build>` section of your POM and specify `<extensions>true</extensions>` for that plugin. One example of a plugin that requires this is the Plexus plugin, which provides a `plexus-application` and `plexus-service` packaging.
+
+_[top](./introduction-to-the-lifecycle.html)._
+
+### Plugins
+
+The second way to add goals to phases is to configure plugins in your project. Plugins are artifacts that provide goals to Maven. Furthermore, a plugin may have one or more goals wherein each goal represents a capability of that plugin. For example, the Compiler plugin has two goals: `compile` and `testCompile`. The former compiles the source code of your main code, while the latter compiles the source code of your test code.
+
+As you will see in the later sections, plugins can contain information that indicates which lifecycle phase to bind a goal to. Note that adding the plugin on its own is not enough information - you must also specify the goals you want to run as part of your build.
+
+The goals that are configured will be added to the goals already bound to the lifecycle from the packaging selected. If more than one goal is bound to a particular phase, the order used is that those from the packaging are executed first, followed by those configured in the POM. Note that you can use the `<executions>` element to gain more control over the order of particular goals.
+
+For example, the Modello plugin binds by default its goal `modello:java` to the `generate-sources` phase (Note: The `modello:java` goal generates Java source codes). So to use the Modello plugin and have it generate sources from a model and incorporate that into the build, you would add the following to your POM in the `<plugins>` section of `<build>`:
+
+```xml
+<plugin>
+ <groupId>org.codehaus.modello</groupId>
+ <artifactId>modello-maven-plugin</artifactId>
+ <version>1.8.1</version>
+ <executions>
+ <execution>
+ <configuration>
+ <models>
+ <model>src/main/mdo/maven.mdo</model>
+ </models>
+ <version>4.0.0</version>
+ </configuration>
+ <goals>
+ <goal>java</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+```
+
+You might be wondering why that `<executions>` element is there. That is so that you can run the same goal multiple times with different configuration if needed. Separate executions can also be given an ID so that during inheritance or the application of profiles you can control whether goal configuration is merged or turned into an additional execution.
+
+See [Configuring plugins](./guides/mini/guide-configuring-plugins.html#Configuring_Build_Plugins) for more details about the configuration of multiple executions and their execution order.
+
+Now, in the case of `modello:java`, it only makes sense in the `generate-sources` phase. But some goals can be used in more than one phase, and there may not be a sensible default. For those, you can specify the phase yourself. For example, let's say you have a goal `display:time` that echos the current time to the commandline, and you want it to run in the `process-test-resources` phase to indicate when the tests were started. This would be configured like so:
+
+```xml
+<plugin>
+ <groupId>com.mycompany.example</groupId>
+ <artifactId>display-maven-plugin</artifactId>
+ <version>1.0</version>
+ <executions>
+ <execution>
+ <phase>process-test-resources</phase>
+ <goals>
+ <goal>time</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+```
+
+_[top](./introduction-to-the-lifecycle.html)._
+
+## Lifecycle Reference
+
+The following lists all build phases of the `default`, `clean` and `site` lifecycles, which are executed in the order given up to the point of the one specified.
+
+### Clean Lifecycle
+
+| Phase | Description |
+|:-------------|:--------------------------------------------------------------|
+| `pre-clean` | execute processes needed prior to the actual project cleaning |
+| `clean` | remove all files generated by the previous build |
+| `post-clean` | execute processes needed to finalize the project cleaning |
+
+### Default Lifecycle
+
+| Phase | Description |
+|:--------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `validate` | validate the project is correct and all necessary information is available. |
+| `initialize` | initialize build state, e.g. set properties or create directories. |
+| `generate-sources` | generate any source code for inclusion in compilation. |
+| `process-sources` | process the source code, for example to filter any values. |
+| `generate-resources` | generate resources for inclusion in the package. |
+| `process-resources` | copy and process the resources into the destination directory, ready for packaging. |
+| `compile` | compile the source code of the project. |
+| `process-classes` | post-process the generated files from compilation, for example to do bytecode enhancement on Java classes. |
+| `generate-test-sources` | generate any test source code for inclusion in compilation. |
+| `process-test-sources` | process the test source code, for example to filter any values. |
+| `generate-test-resources` | create resources for testing. |
+| `process-test-resources` | copy and process the resources into the test destination directory. |
+| `test-compile` | compile the test source code into the test destination directory |
+| `process-test-classes` | post-process the generated files from test compilation, for example to do bytecode enhancement on Java classes. |
+| `test` | run tests using a suitable unit testing framework. These tests should not require the code be packaged or deployed. |
+| `prepare-package` | perform any operations necessary to prepare a package before the actual packaging. This often results in an unpacked, processed version of the package. |
+| `package` | take the compiled code and package it in its distributable format, such as a JAR. |
+| `pre-integration-test` | perform actions required before integration tests are executed. This may involve things such as setting up the required environment. |
+| `integration-test` | process and deploy the package if necessary into an environment where integration tests can be run. |
+| `post-integration-test` | perform actions required after integration tests have been executed. This may including cleaning up the environment. |
+| `verify` | run any checks to verify the package is valid and meets quality criteria. |
+| `install` | install the package into the local repository, for use as a dependency in other projects locally. |
+| `deploy` | done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects. |
+
+### Site Lifecycle
+
+| Phase | Description |
+|:--------------|:---------------------------------------------------------------------------------------------|
+| `pre-site` | execute processes needed prior to the actual project site generation |
+| `site` | generate the project's site documentation |
+| `post-site` | execute processes needed to finalize the site generation, and to prepare for site deployment |
+| `site-deploy` | deploy the generated site documentation to the specified web server |
+
+_[top](./introduction-to-the-lifecycle.html)._
+
+## Built-in Lifecycle Bindings
+
+Some phases have goals bound to them by default. And for the default lifecycle, these bindings depend on the packaging value. Here are some of the goal-to-build-phase bindings.
+
+### Clean Lifecycle Bindings
+
+| Phase | plugin:goal |
+|:--------|:--------------|
+| `clean` | `clean:clean` |
+
+### Default Lifecycle Bindings - Packaging `ejb` / `jar` / `rar` / `war`
+
+| Phase | plugin:goal |
+|:-------------------------|:-------------------------------------------------------|
+| `process-resources` | `resources:resources` |
+| `compile` | `compiler:compile` |
+| `process-test-resources` | `resources:testResources` |
+| `test-compile` | `compiler:testCompile` |
+| `test` | `surefire:test` |
+| `package` | `ejb:ejb` _or_ `jar:jar` _or_ `rar:rar` _or_ `war:war` |
+| `install` | `install:install` |
+| `deploy` | `deploy:deploy` |
+
+### Default Lifecycle Bindings - Packaging `ear`
+
+| Phase | plugin:goal |
+|:---------------------|:-------------------------------|
+| `generate-resources` | `ear:generate-application-xml` |
+| `process-resources` | `resources:resources` |
+| `package` | `ear:ear` |
+| `install` | `install:install` |
+| `deploy` | `deploy:deploy` |
+
+### Default Lifecycle Bindings - Packaging `maven-plugin`
+
+| Phase | plugin:goal |
+|:-------------------------|:---------------------------------------------------|
+| `generate-resources` | `plugin:descriptor` |
+| `process-resources` | `resources:resources` |
+| `compile` | `compiler:compile` |
+| `process-test-resources` | `resources:testResources` |
+| `test-compile` | `compiler:testCompile` |
+| `test` | `surefire:test` |
+| `package` | `jar:jar` _and_ `plugin:addPluginArtifactMetadata` |
+| `install` | `install:install` |
+| `deploy` | `deploy:deploy` |
+
+### Default Lifecycle Bindings - Packaging `pom`
+
+| Phase | plugin:goal |
+|:----------|:------------------|
+| `package` ||
+| `install` | `install:install` |
+| `deploy` | `deploy:deploy` |
+
+### Site Lifecycle Bindings
+
+| Phase | plugin:goal |
+|:--------------|:--------------|
+| `site` | `site:site` |
+| `site-deploy` | `site:deploy` |
+
+### References
+
+The full Maven lifecycle is defined by the `components.xml` file in the `maven-core` module, with [associated documentation](/ref/current/maven-core/lifecycles.html) for reference.
+
+Default lifecycle bindings are defined in a separate [`default-bindings.xml`](https://github.com/apache/maven/blob/master/maven-core/src/main/resources/META-INF/plexus/default-bindings.xml) descriptor.
+
+See [Lifecycles Reference](/ref/current/maven-core/lifecycles.html) and [Plugin Bindings for default Lifecycle Reference](/ref/current/maven-core/default-bindings.html) for latest documentation taken directly from source code.
+
+_[top](./introduction-to-the-lifecycle.html)._
+
diff --git a/content/markdown/guides/introduction/introduction-to-the-pom.md b/content/markdown/guides/introduction/introduction-to-the-pom.md
new file mode 100644
index 00000000..597a9530
--- /dev/null
+++ b/content/markdown/guides/introduction/introduction-to-the-pom.md
@@ -0,0 +1,465 @@
+<!--
+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 to the POM
+
+<!-- MACRO{toc|section=0|fromDepth=2|toDepth=3} -->
+
+## What is a POM?
+
+A Project Object Model or POM is the fundamental unit of work in Maven. It is an XML file that contains information about the project and configuration details used by Maven to build the project. It contains default values for most projects. Examples for this is the build directory, which is `target`; the source directory, which is `src/main/java`; the test source directory, which is `src/test/java`; and so on. When executing a task or goal, Maven looks for the POM in the current directo [...]
+
+Some of the configuration that can be specified in the POM are the project dependencies, the plugins or goals that can be executed, the build profiles, and so on. Other information such as the project version, description, developers, mailing lists and such can also be specified.
+
+[top](./introduction-to-the-pom.html)
+
+## Super POM
+
+The Super POM is Maven's default POM. All POMs extend the Super POM unless explicitly set, meaning the configuration specified in the Super POM is inherited by the POMs you created for your projects.
+
+You can see the [Super POM for the latest Maven 3 release](/maven-model-builder/super-pom.html) in Maven Core reference documentation.
+
+[top](./introduction-to-the-pom.html)
+
+## Minimal POM
+
+The minimum requirement for a POM are the following:
+
+- `project` root
+- `modelVersion` - should be set to 4.0.0
+- `groupId` - the id of the project's group.
+- `artifactId` - the id of the artifact (project)
+- `version` - the version of the artifact under the specified group
+
+Here's an example:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1</version>
+</project>
+```
+
+A POM requires that its groupId, artifactId, and version be configured. These three values form the project's fully qualified artifact name. This is in the form of <groupId>:<artifactId>:<version>. As for the example above, its fully qualified artifact name is "com.mycompany.app:my-app:1".
+
+Also, as mentioned in the [first section](#What_is_a_POM), if the configuration details are not specified, Maven will use their defaults. One of these default values is the packaging type. Every Maven project has a packaging type. If it is not specified in the POM, then the default value "jar" would be used.
+
+Furthermore, you can see that in the minimal POM the _repositories_ were not specified. If you build your project using the minimal POM, it would inherit the _repositories_ configuration in the Super POM. Therefore when Maven sees the dependencies in the minimal POM, it would know that these dependencies will be downloaded from `https://repo.maven.apache.org/maven2` which was specified in the Super POM.
+
+[top](./introduction-to-the-pom.html)
+
+## Project Inheritance
+
+Elements in the POM that are merged are the following:
+
+- dependencies
+- developers and contributors
+- plugin lists (including reports)
+- plugin executions with matching ids
+- plugin configuration
+- resources
+
+The Super POM is one example of project inheritance, however you can also introduce your own parent POMs by specifying the parent element in the POM, as demonstrated in the following examples.
+
+### Example 1
+
+#### The Scenario
+
+As an example, let us reuse our previous artifact, com.mycompany.app:my-app:1. And let us introduce another artifact, com.mycompany.app:my-module:1.
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-module</artifactId>
+ <version>1</version>
+</project>
+```
+
+And let us specify their directory structure as the following:
+
+```
+.
+ |-- my-module
+ | `-- pom.xml
+ `-- pom.xml
+```
+
+**Note:** `my-module/pom.xml` is the POM of com.mycompany.app:my-module:1 while `pom.xml` is the POM of com.mycompany.app:my-app:1
+
+#### The Solution
+
+Now, if we were to turn com.mycompany.app:my-app:1 into a parent artifact of com.mycompany.app:my-module:1,we will have to modify com.mycompany.app:my-module:1's POM to the following configuration:
+
+**com.mycompany.app:my-module:1's POM**
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1</version>
+ </parent>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-module</artifactId>
+ <version>1</version>
+</project>
+```
+
+Notice that we now have an added section, the parent section. This section allows us to specify which artifact is the parent of our POM. And we do so by specifying the fully qualified artifact name of the parent POM. With this setup, our module can now inherit some of the properties of our parent POM.
+
+Alternatively, if you want the groupId or the version of your modules to be the same as their parents, you can remove the groupId or the version identity of your module in its POM.
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1</version>
+ </parent>
+
+ <artifactId>my-module</artifactId>
+</project>
+```
+
+This allows the module to inherit the groupId or the version of its parent POM.
+
+[top](./introduction-to-the-pom.html)
+
+### Example 2
+
+#### The Scenario
+
+However, that would work if the parent project was already installed in our local repository or was in that specific directory structure (parent `pom.xml` is one directory higher than that of the module's `pom.xml`).
+
+But what if the parent is not yet installed and if the directory structure is as in the following example?
+
+```
+.
+ |-- my-module
+ | `-- pom.xml
+ `-- parent
+ `-- pom.xml
+```
+
+#### The Solution
+
+To address this directory structure (or any other directory structure), we would have to add the `<relativePath>` element to our parent section.
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1</version>
+ <relativePath>../parent/pom.xml</relativePath>
+ </parent>
+
+ <artifactId>my-module</artifactId>
+</project>
+```
+
+As the name suggests, it's the relative path from the module's `pom.xml` to the parent's `pom.xml`.
+
+## Project Aggregation
+
+Project Aggregation is similar to [Project Inheritance](#Project_Inheritance). But instead of specifying the parent POM from the module, it specifies the modules from the parent POM. By doing so, the parent project now knows its modules, and if a Maven command is invoked against the parent project, that Maven command will then be executed to the parent's modules as well. To do Project Aggregation, you must do the following:
+
+- Change the parent POMs packaging to the value "pom".
+- Specify in the parent POM the directories of its modules (children POMs).
+
+[top](./introduction-to-the-pom.html)
+
+### Example 3
+
+#### The Scenario
+
+Given the previous original artifact POMs and directory structure:
+
+**com.mycompany.app:my-app:1's POM**
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1</version>
+</project>
+```
+
+**com.mycompany.app:my-module:1's POM**
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-module</artifactId>
+ <version>1</version>
+</project>
+```
+
+**directory structure**
+
+```
+.
+ |-- my-module
+ | `-- pom.xml
+ `-- pom.xml
+```
+
+#### The Solution
+
+If we are to aggregate my-module into my-app, we would only have to modify my-app.
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1</version>
+ <packaging>pom</packaging>
+
+ <modules>
+ <module>my-module</module>
+ </modules>
+</project>
+```
+
+In the revised com.mycompany.app:my-app:1, the packaging section and the modules sections were added. For the packaging, its value was set to "pom", and for the modules section, we have the element `<module>my-module</module>`. The value of `<module>` is the relative path from the com.mycompany.app:my-app:1 to com.mycompany.app:my-module:1's POM (_by practice, we use the module's artifactId as the module directory's name_).
+
+Now, whenever a Maven command processes com.mycompany.app:my-app:1, that same Maven command would be ran against com.mycompany.app:my-module:1 as well. Furthermore, some commands (goals specifically) handle project aggregation differently.
+
+[top](./introduction-to-the-pom.html)
+
+### Example 4
+
+#### The Scenario
+
+But what if we change the directory structure to the following:
+
+```
+.
+ |-- my-module
+ | `-- pom.xml
+ `-- parent
+ `-- pom.xml
+```
+
+How would the parent POM specify its modules?
+
+#### The Solution
+
+The answer? - the same way as Example 3, by specifying the path to the module.
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1</version>
+ <packaging>pom</packaging>
+
+ <modules>
+ <module>../my-module</module>
+ </modules>
+</project>
+```
+
+## Project Inheritance vs Project Aggregation
+
+If you have several Maven projects, and they all have similar configurations, you can refactor your projects by pulling out those similar configurations and making a parent project. Thus, all you have to do is to let your Maven projects inherit that parent project, and those configurations would then be applied to all of them.
+
+And if you have a group of projects that are built or processed together, you can create a parent project and have that parent project declare those projects as its modules. By doing so, you'd only have to build the parent and the rest will follow.
+
+But of course, you can have both Project Inheritance and Project Aggregation. Meaning, you can have your modules specify a parent project, and at the same time, have that parent project specify those Maven projects as its modules. You'd just have to apply all three rules:
+
+- Specify in every child POM who their parent POM is.
+- Change the parent POMs packaging to the value "pom" .
+- Specify in the parent POM the directories of its modules (children POMs)
+
+[top](./introduction-to-the-pom.html)
+
+### Example 5
+
+#### The Scenario
+
+Given the previous original artifact POMs again,
+
+**com.mycompany.app:my-app:1's POM**
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1</version>
+</project>
+```
+
+**com.mycompany.app:my-module:1's POM**
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-module</artifactId>
+ <version>1</version>
+</project>
+```
+
+and this **directory structure**
+
+```
+.
+ |-- my-module
+ | `-- pom.xml
+ `-- parent
+ `-- pom.xml
+```
+
+#### The Solution
+
+To do both project inheritance and aggregation, you only have to apply all three rules.
+
+**com.mycompany.app:my-app:1's POM**
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1</version>
+ <packaging>pom</packaging>
+
+ <modules>
+ <module>../my-module</module>
+ </modules>
+</project>
+```
+
+**com.mycompany.app:my-module:1's POM**
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>com.mycompany.app</groupId>
+ <artifactId>my-app</artifactId>
+ <version>1</version>
+ <relativePath>../parent/pom.xml</relativePath>
+ </parent>
+
+ <artifactId>my-module</artifactId>
+</project>
+```
+
+**NOTE:** Profile inheritance the same inheritance strategy as used for the POM itself.
+
+[top](./introduction-to-the-pom.html)
+
+## Project Interpolation and Variables
+
+One of the practices that Maven encourages is _don't repeat yourself_. However, there are circumstances where you will need to use the same value in several different locations. To assist in ensuring the value is only specified once, Maven allows you to use both your own and pre-defined variables in the POM.
+
+For example, to access the `project.version` variable, you would reference it like so:
+
+```xml
+<version>${project.version}</version>
+```
+
+One factor to note is that these variables are processed _after_ inheritance as outlined above. This means that if a parent project uses a variable, then its definition in the child, not the parent, will be the one eventually used.
+
+### Available Variables
+
+#### Project Model Variables
+
+Any field of the model that is a single value element can be referenced as a variable. For example, `${project.groupId}`, `${project.version}`, `${project.build.sourceDirectory}` and so on. Refer to the [POM reference](/pom.html) to see a full list of properties.
+
+These variables are all referenced by the prefix "`project.`". You may also see references with `pom.` as the prefix, or the prefix omitted entirely - these forms are now deprecated and should not be used.
+
+#### Special Variables
+
+| | |
+|:------------------------|:----------------------------------------------------------------------------------------------|
+| `project.basedir` | The directory that the current project resides in. |
+| `project.baseUri` | The directory that the current project resides in, represented as an URI. _Since Maven 2.1.0_ |
+| `maven.build.timestamp` | The timestamp that denotes the start of the build (UTC). _Since Maven 2.1.0-M1_ |
+
+The format of the build timestamp can be customized by declaring the property `maven.build.timestamp.format` as shown in the example below:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <properties>
+ <maven.build.timestamp.format>yyyy-MM-dd'T'HH:mm:ss'Z'</maven.build.timestamp.format>
+ </properties>
+ ...
+</project>
+```
+
+The format pattern has to comply with the rules given in the API documentation for [SimpleDateFormat](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html). If the property is not present, the format defaults to the value already given in the example.
+
+#### Properties
+
+You are also able to reference any properties defined in the project as a variable. Consider the following example:
+
+```xml
+<project xmlns="http://maven.apache.org/POM/4.0.0">
+ ...
+ <properties>
+ <mavenVersion>3.0</mavenVersion>
+ </properties>
+
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-artifact</artifactId>
+ <version>${mavenVersion}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.maven</groupId>
+ <artifactId>maven-core</artifactId>
+ <version>${mavenVersion}</version>
+ </dependency>
+ </dependencies>
+ ...
+</project>
+```
+
+[top](./introduction-to-the-pom.html)
+
diff --git a/content/markdown/guides/introduction/introduction-to-the-standard-directory-layout.md b/content/markdown/guides/introduction/introduction-to-the-standard-directory-layout.md
new file mode 100644
index 00000000..4cde0d24
--- /dev/null
+++ b/content/markdown/guides/introduction/introduction-to-the-standard-directory-layout.md
@@ -0,0 +1,53 @@
+<!--
+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 to the Standard Directory Layout
+
+Having a common directory layout allows users familiar with one Maven project to immediately feel at home in another Maven project. The advantages are analogous to adopting a site-wide look-and-feel.
+
+The next section documents the directory layout expected by Maven and the directory layout created by Maven. Try to conform to this structure as much as possible. However, if you can't, these settings can be overridden via the project descriptor.
+
+| | |
+|:---------------------|:---------------------------------------------------------------------------|
+| `src/main/java` | Application/Library sources |
+| `src/main/resources` | Application/Library resources |
+| `src/main/filters` | Resource filter files |
+| `src/main/webapp` | Web application sources |
+| `src/test/java` | Test sources |
+| `src/test/resources` | Test resources |
+| `src/test/filters` | Test resource filter files |
+| `src/it` | Integration Tests (primarily for plugins) |
+| `src/assembly` | Assembly descriptors |
+| `src/site` | Site |
+| `LICENSE.txt` | Project's license |
+| `NOTICE.txt` | Notices and attributions required by libraries that the project depends on |
+| `README.txt` | Project's readme |
+
+At the top level, files descriptive of the project: a `pom.xml` file. In addition, there are textual documents meant for the user to be able to read immediately on receiving the source: `README.txt`, `LICENSE.txt`, etc.
+
+There are just two subdirectories of this structure: `src` and `target`. The only other directories that would be expected here are metadata like `CVS`, `.git` or `.svn`, and any subprojects in a multiproject build (each of which would be laid out as above).
+
+The `target` directory is used to house all output of the build.
+
+The `src` directory contains all of the source material for building the project, its site and so on. It contains a subdirectory for each type: `main` for the main build artifact, `test` for the unit test code and resources, `site` and so on.
+
+Within artifact producing source directories (ie. `main` and `test`), there is one directory for the language `java` (under which the normal package hierarchy exists), and one for `resources` (the structure which is copied to the target classpath given the default resource definition).
+
+If there are other contributing sources to the artifact build, they would be under other subdirectories. For example `src/main/antlr` would contain Antlr grammar definition files.
+