src/site/apt/examples/pom.apt

 ------
 Pom
 ------
 Brett Porter
 Hervé Boutemy
 Paul Gier
 ------
 2009-05-06
 ------

 ~~ 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

  The pom task can be used in one of two ways, either to read an existing pom file
  (typically pom.xml), or to define an in memory pom object.  Either technique
  can be used to resolve build dependencies, build the project classpath, and/or
  define project properties.

Reading an existing POM file

  An example pom is provided here:

-----
<project>
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.mycompany.project</groupId>
  <artifactId>project-model</artifactId>
  <version>1.0-SNAPSHOT</version>

  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.2</version>
      <scope>test</scope>
    </dependency>

    <dependency>
      <groupId>org.codehaus.modello</groupId>
      <artifactId>modello-core</artifactId>
      <version>1.0-alpha-2-SNAPSHOT</version>
    </dependency>

    <dependency>
      <groupId>javax.servlet</groupId>
      <artifactId>servlet-api</artifactId>
      <version>2.4</version>
      <scope>provided</scope>
    </dependency>
  </dependencies>
</project>
-----

  These elements represent:

    * <modelVersion> - this is the version of the POM layout in use, currently <<<4.0.0>>>.

    * <groupId> - the group ID represents your organisation and project name, much like a Java package name.
      This must be universally unique. This becomes the base directory in the repository as well.

    * <artifactId> - the artifact ID represents the current build unit. It usually equals the filename of the
      resulting file, and must be unique within the group.

    * <version> - the version of the artifact you are building.

    * <dependencies> - the artifacts that this project is dependent on.

  This is all that is required for most projects. However, it is also possible to use other fields available in
  Maven to describe your project, and reference them from your build script.

  Once the pom file is created, it can be read by the pom task.

-----
  <artifact:pom id="mypom" file="pom.xml" />
-----

Defining a POM in Ant

  If a POM file is not available, the ant task can also be used to define an in-memory pom.

----
  <artifact:pom id="mypom" groupId="org.acme" artifactId="project1" version="1.0">
    <dependency groupId="junit" artifactId="junit" version="4.1"/>
    <dependency groupId="org.codehaus.plexus" artifactId="plexus-utils" version="1.5.5"/>
    <license name="apache" url="http://www.apache.org"/>
  </artifact:pom>
----

Accessing POM information

  To access a part of the POM as an Ant property, you must define it as a reference. For example, to access the version from a POM,
  you can use the following:

-----
  <artifact:pom id="mypom" file="pom.xml" />

  <echo>The version is ${mypom.version}</echo>
-----

  You can also access nested parts of the POM. For example, you can read the default value of the <<<directory>>>
  element within the <<<build>>> element using a <<<.>>> separator.

-----
  <artifact:pom id="mypom" file="pom.xml" />

  <echo>The build directory is ${mypom.build.directory}</echo>
-----

  For more information on the elements available in the POM, see the
  {{{http://maven.apache.org/ref/current/maven-model/maven.html} descriptor reference}}.

Accessing dependencies in the POM

  The <<<pom>>> task can be used in combination with the <<<dependencies>>> task to declare a list of dependencies.

-----
  <artifact:pom id="mypom" file="pom.xml" />

  <artifact:dependencies filesetId="mydeps" pomRefId="mypom" />
-----

  In this example, the <<<dependencies>>> task will resolve the list of dependencies in the pom
  and add them to the fileset.

Using profiles in the POM

  POM profiles can be activated or deactivated using the nested profile element.  For example
  to activate a profile called <<<my-profile>>>.

-----
    <artifact:pom id="maven.project" file="pom.xml">
      <profile id="my-profile"/>
    </artifact:pom>
-----

  This can also be used to deactivate a POM profile that is active by default.

-----
    <artifact:pom id="maven.project" file="pom.xml">
      <profile id="my-default-profile" active="false"/>
    </artifact:pom>
-----