You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by vs...@apache.org on 2008/01/05 14:44:42 UTC
svn commit: r609137 -
/maven/site/trunk/src/site/apt/guides/introduction/introduction-to-the-pom.apt
Author: vsiveton
Date: Sat Jan 5 05:44:00 2008
New Revision: 609137
URL: http://svn.apache.org/viewvc?rev=609137&view=rev
Log:
o fixed internal links
Modified:
maven/site/trunk/src/site/apt/guides/introduction/introduction-to-the-pom.apt
Modified: maven/site/trunk/src/site/apt/guides/introduction/introduction-to-the-pom.apt
URL: http://svn.apache.org/viewvc/maven/site/trunk/src/site/apt/guides/introduction/introduction-to-the-pom.apt?rev=609137&r1=609136&r2=609137&view=diff
==============================================================================
--- maven/site/trunk/src/site/apt/guides/introduction/introduction-to-the-pom.apt (original)
+++ maven/site/trunk/src/site/apt/guides/introduction/introduction-to-the-pom.apt Sat Jan 5 05:44:00 2008
@@ -4,47 +4,53 @@
Jason van Zyl
Franz Allan Valencia See
------
- 09 November 2006
+ January 2008
------
Introduction to the POM
- * {{{introduction-to-the-pom.html#What is a POM}What is a POM}}?
-
- * {{{introduction-to-the-pom.html#Super POM}Super POM}}
-
- * {{{introduction-to-the-pom.html#Minimal POM}Minimal POM}}
-
- * {{{introduction-to-the-pom.html#Project Inheritance}Project Inheritance}}
-
- * {{{introduction-to-the-pom.html#Example 1}Example 1}}
-
- * {{{introduction-to-the-pom.html#Example 2}Example 2}}
-
- * {{{introduction-to-the-pom.html#Project Aggregation}Project Aggregation}}
-
- * {{{introduction-to-the-pom.html#Example 3}Example 3}}
-
- * {{{introduction-to-the-pom.html#Example 4}Example 4}}
-
- * {{{introduction-to-the-pom.html#Project Inheritance vs Project Aggregation}Project Inheritance vs Project Aggregation}}
-
- * {{{introduction-to-the-pom.html#Example 5}Example 5}}
-
+ * {{{introduction-to-the-pom.html#What_is_a_POM}What is a POM}}?
+
+ * {{{introduction-to-the-pom.html#Super_POM}Super POM}}
+
+ * {{{introduction-to-the-pom.html#Minimal_POM}Minimal POM}}
+
+ * {{{introduction-to-the-pom.html#Project_Inheritance}Project Inheritance}}
+
+ * {{{introduction-to-the-pom.html#Example_1}Example 1}}
+
+ * {{{introduction-to-the-pom.html#Example_2}Example 2}}
+
+ []
+
+ * {{{introduction-to-the-pom.html#Project_Aggregation}Project Aggregation}}
+
+ * {{{introduction-to-the-pom.html#Example_3}Example 3}}
+
+ * {{{introduction-to-the-pom.html#Example_4}Example 4}}
+
+ []
+
+ * {{{introduction-to-the-pom.html#Project_Inheritance_vs_Project_Aggregation}Project Inheritance vs Project Aggregation}}
+
+ * {{{introduction-to-the-pom.html#Example_5}Example 5}}
+
+ []
+
[]
* {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
+ 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/main/test"; and so on.
-
+
The POM was renamed from project.xml in Maven 1 to pom.xml in Maven 2. Instead of having a maven.xml file that contains
- the goals that can be executed, the goals or plugins are now configured in the pom.xml. 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.
-
+ the goals that can be executed, the goals or plugins are now configured in the pom.xml. 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.
@@ -53,7 +59,7 @@
* {Super POM}
- The Super POM is Maven's default POM. All POMs extend the Super POM unless explicitly set, meaning the configuration specified
+ 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. The snippet below is the Super POM.
%{snippet|id=superpom|url=http://svn.apache.org/repos/asf/maven/components/trunk/maven-project/src/main/resources/org/apache/maven/project/pom-4.0.0.xml}
@@ -63,21 +69,21 @@
* {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.
-
+
+ * 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>
<modelVersion>4.0.0</modelVersion>
@@ -89,15 +95,15 @@
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 {{{introduction-to-the-pom.html#What is a POM}first section}}, if the configuration details
+ fully qualified artifact name is "com.mycompany.app:my-app:1".
+
+ Also, as mentioned in the {{{introduction-to-the-pom.html#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, as 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 http://repo1.maven.org/maven2 which was specified
+ the minimal POM, it would know that these dependencies will be downloaded from http://repo1.maven.org/maven2 which was specified
in the Super POM.
{{{introduction-to-the-pom.html}[top]}}
@@ -115,21 +121,21 @@
* 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,
+ 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.
+-----+
@@ -142,7 +148,7 @@
+-----+
And let us specify their directory structure as the following:
-
+
+-----+
.
|-- my-module
@@ -155,11 +161,11 @@
*** 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
+ 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>
<parent>
@@ -176,11 +182,11 @@
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 we want the groupId and / or the version of your modules to be the same as their parents, you can
+ module can now inherit some of the properties of our parent POM.
+
+ Alternatively, if we want the groupId and / or the version of your modules to be the same as their parents, you can
remove the groupId and / or the version identity of your module in its POM.
-
+
+-----+
<project>
<parent>
@@ -192,20 +198,20 @@
<artifactId>my-module</artifactId>
</project>
+-----+
-
+
This allows the module to inherit the groupId and / 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
+ 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
-
+
+-----+
.
|-- my-module
@@ -213,12 +219,12 @@
`-- parent
`-- pom.xml
+-----+
-
+
*** The Solution
- To address this directory structure (or any other directory structure), we would have to add the relativePath tag to
- our parent section.
-
+ To address this directory structure (or any other directory structure), we would have to add the relativePath tag to
+ our parent section.
+
+-----+
<project>
<parent>
@@ -233,22 +239,22 @@
+-----+
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 {{{introduction-to-the-pom.html#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
+ Project Aggregation is similar to {{{introduction-to-the-pom.html#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
@@ -256,7 +262,7 @@
Given the previous original artifact poms, and directory structure,
<<com.mycompany.app:my-app:1's POM>>
-
+
+-----+
<project>
<modelVersion>4.0.0</modelVersion>
@@ -267,7 +273,7 @@
+-----+
<<com.mycompany.app:my-module:1's POM>>
-
+
+-----+
<project>
<modelVersion>4.0.0</modelVersion>
@@ -278,7 +284,7 @@
+-----+
<<directory structure>>
-
+
+-----+
.
|-- my-module
@@ -289,7 +295,7 @@
*** The Solution
if we are to aggregate my-module into my-app, we would only have to modify my-app.
-
+
+-----+
<project>
<modelVersion>4.0.0</modelVersion>
@@ -305,22 +311,22 @@
+-----+
In the revised com.mycompany.app:my-app:1, the packaging section and the modules sections were added. For
- the packaging, it's value was set to "pom", and for the modules section, we have the element
+ the packaging, it's 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-module: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-module:1, that same maven command would be ran against
- com.mycompany.app:my-module:1 as well. Furthermore, some commands (goals specifically) handles project aggregation
- differently.
-
+ com.mycompany.app:my-module:1 as well. Furthermore, some commands (goals specifically) handles 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
@@ -330,11 +336,11 @@
+-----+
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>
<modelVersion>4.0.0</modelVersion>
@@ -352,27 +358,27 @@
* {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
+ 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
+ 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
+
+ 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
@@ -380,7 +386,7 @@
Given the previous original artifact poms again,
<<com.mycompany.app:my-app:1's POM>>
-
+
+-----+
<project>
<modelVersion>4.0.0</modelVersion>
@@ -391,7 +397,7 @@
+-----+
<<com.mycompany.app:my-module:1's POM>>
-
+
+-----+
<project>
<modelVersion>4.0.0</modelVersion>
@@ -402,7 +408,7 @@
+-----+
and this <<directory structure>>
-
+
+-----+
.
|-- my-module
@@ -410,13 +416,13 @@
`-- 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>
<modelVersion>4.0.0</modelVersion>
@@ -432,7 +438,7 @@
+-----+
<<com.mycompany.app:my-module:1's POM>>
-
+
+-----+
<project>
<parent>
@@ -447,6 +453,6 @@
+-----+
<<NOTE:>> Profile inheritance the same inheritance strategy as used for the POM itself.
-
+
{{{introduction-to-the-pom.html}[top]}}