You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by br...@apache.org on 2005/03/03 15:22:50 UTC
svn commit: r156040 - in maven/maven-1/core/trunk/xdocs:
reference/conventions.xml reference/scripting.xml using/bestpractices.xml
using/customising.xml
Author: brett
Date: Thu Mar 3 06:22:46 2005
New Revision: 156040
URL: http://svn.apache.org/viewcvs?view=rev&rev=156040
Log:
interpolation and inheritence
Modified:
maven/maven-1/core/trunk/xdocs/reference/conventions.xml
maven/maven-1/core/trunk/xdocs/reference/scripting.xml
maven/maven-1/core/trunk/xdocs/using/bestpractices.xml
maven/maven-1/core/trunk/xdocs/using/customising.xml
Modified: maven/maven-1/core/trunk/xdocs/reference/conventions.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/reference/conventions.xml?view=diff&r1=156039&r2=156040
==============================================================================
--- maven/maven-1/core/trunk/xdocs/reference/conventions.xml (original)
+++ maven/maven-1/core/trunk/xdocs/reference/conventions.xml Thu Mar 3 06:22:46 2005
@@ -31,11 +31,10 @@
<!-- Label referenced elsewhere -->
<section name="Directory Structure">
- <!-- TODO: Must explain reasons for the conventions (see ten-minute-test) -->
<p>...</p>
</section>
-<!--
+ <!-- TODO:
<section name="Naming Conventions">
<p>
This section outlines the naming conventions used in the Maven
Modified: maven/maven-1/core/trunk/xdocs/reference/scripting.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/reference/scripting.xml?view=diff&r1=156039&r2=156040
==============================================================================
--- maven/maven-1/core/trunk/xdocs/reference/scripting.xml (original)
+++ maven/maven-1/core/trunk/xdocs/reference/scripting.xml Thu Mar 3 06:22:46 2005
@@ -224,7 +224,7 @@
The current project is always available under the context variable
<code>${pom}</code>. This allows the retrieval
of project variables in your scripts. This is the same as how they are used within the project file itself when
- it is <!--a href="TODO"-->interpolated<!--/a-->.
+ it is <a href="../using/customising.html#Property_Substitution_in_the_Project_Descriptor">interpolated</a>.
</p>
<p>
The variables and functions you can access are those listed in the
Modified: maven/maven-1/core/trunk/xdocs/using/bestpractices.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/using/bestpractices.xml?view=diff&r1=156039&r2=156040
==============================================================================
--- maven/maven-1/core/trunk/xdocs/using/bestpractices.xml (original)
+++ maven/maven-1/core/trunk/xdocs/using/bestpractices.xml Thu Mar 3 06:22:46 2005
@@ -1,7 +1,7 @@
<?xml version="1.0"?>
<!--
/*
- * Copyright 2001-2004 The Apache Software Foundation.
+ * Copyright 2001-2005 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.
@@ -31,7 +31,20 @@
are several recommended steps to take in setting up your build and developing the project that will help
detailed here.
</p>
- <!-- TODO: more to come -->
+ <subsection name="Follow Conventions">
+ <p>
+ Many have complained that Maven forces a certain structure on a project. While this is not completely true
+ (most settings are still configurable), it certainly does make it easier to use defaults.
+ </p>
+ <p>
+ From the layout of your source code to the layout of your project documentation, and all the standard goals
+ in between, following conventions helps new users find their way around your project with minimal training
+ and additional documentation.
+ </p>
+ <p>
+ For more information, refer to the <a href="../reference/conventions.html">Conventions Reference</a>.
+ </p>
+ </subsection>
<subsection name="Reproduciblity">
<p>
It is important to make sure a build is reproducible. This means a few things:
@@ -81,6 +94,9 @@
configurable information such as database connection properties are in the deployment descriptor, provided
through JNDI outside of the webapp or other deployable item. This means the particular artifact can be
deployed identically into different servers, with just the external configuration differing.</li>
+ <li>Only interpolate values in the POM with other POM values, not properties that might be user or
+ environment specific.</li>
+ <li>Avoid the use of file entities in the POM.</li>
<li>Follow the other rules above - avoid including resources outside of the base directory of the project,
and don't use properties customised to a particular environment.</li>
</ul>
Modified: maven/maven-1/core/trunk/xdocs/using/customising.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/using/customising.xml?view=diff&r1=156039&r2=156040
==============================================================================
--- maven/maven-1/core/trunk/xdocs/using/customising.xml (original)
+++ maven/maven-1/core/trunk/xdocs/using/customising.xml Thu Mar 3 06:22:46 2005
@@ -25,7 +25,6 @@
</properties>
<body>
- <!-- TODO: talk about pom interpolation and pom inheritence, note that final values are interpolated when inheriting -->
<section name="Customising Maven">
<p>
Earlier in the User's Guide, you've seen how to configure a <code>project.xml</code> to build various different
@@ -66,6 +65,63 @@
<p>
Note that while properties are essential to configuring Maven and it's plugins, they can also be a source of
bad practices. See the <a href="bestpractices.html#Reproduciblity">Best Practices</a> guide for more information.
+ </p>
+ </subsection>
+ <subsection name="Property Substitution in the Project Descriptor">
+ <p>
+ It is often much easier to parameterise values in the project descriptor (or in the properties files) with other
+ properties or fields from the project descriptor than to redefine them each time.
+ This is particularly powerful when used with inheritence, as seen in the next section.
+ </p>
+ <p>
+ For example, you might set the URL based on the artifact ID:
+ </p>
+ <source><![CDATA[<project>
+ <artifactId>my-project</artifactId>
+ ...
+ <url>http://www.mycompany.com/mainproject/subprojects/${pom.artifactId}</url>
+</project>]]></source>
+ <p>
+ For more information on how to specify expressions to use for interpolating these values, see the
+ <a href="../reference/scripting.html#Jexl">Jexl section</a> of the Scripting Reference.
+ </p>
+ </subsection>
+ <subsection name="Project Inheritence">
+ <p>
+ When working with multiple projects that share some information, it would be quite tedious to have to enter the
+ same information into each project, or to maintain it afterwards.
+ </p>
+ <p>
+ For this reason, it is possible to extend a common project file:
+ </p>
+ <source><![CDATA[<project>
+ <extend>../project.xml</extend>
+ ...
+</project>]]></source>
+ <p>
+ All elements are inherited and merged in, with later definitions overriding any defined earlier.
+ Projects can be inherited to any level, but each can only extend one parent.
+ </p>
+ <p>
+ If there are any properties to be substituted into the parent POM or properties, the value will be evaluated
+ <i>after</i> inheritence has been completed. For instance, if in the parent POM with artifact ID
+ <code>my-parent</code> there was a description set like so:
+ </p>
+ <source><![CDATA[<description>This is ${pom.artifactId}</description>]]></source>
+ <p>
+ In the child project, if description were inherited and the artifact ID were <code>my-child</code> then
+ the description would be <code>This is my-child</code>.
+ </p>
+ <p>
+ In addition to the <code>project.xml</code> definition, properties files and <code>maven.xml</code> files
+ associated with the parent POM are inherited. Like the project descriptor properties and goals defined are
+ added to those defined in the subprojects, with the subproject properties and goals overriding those from
+ the parent if specified. <code>preGoal</code> and <code>postGoal</code> definitions that are inherited are
+ accumulated though - all specified hooks will be executed.
+ </p>
+ <p>
+ <b>Note:</b> lists in the POM will overwrite lists defined in parent projects, with the exception of
+ dependencies where the lists are accumulated.
</p>
</subsection>
<subsection name="Scripting Maven">
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org