----
 Maven Getting Started Guide
 -----
 Jason van Zyl
 -----
 12 October 2005
 -----     

Maven Getting Started Guide

 This guide is intended as a reference for those working with Maven for the first. It is also intended to serve as
 a cookbook with self-contained references and solutions for common usecases. For the first time user it is suggested that
 you step through the material in a sequential fashion, but for users more familiar with Maven the 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.

* 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

 * Managing dependencies

 * Managing documentation

 * Managing releases

 If you want to know about the Maven itself you can check out {{{../philosophy-of-maven.html}}The Philosophy of Maven} and
 the {{{../history-of-maven.html}}The History of Maven}. Now we want to move on to why you, the user, can benefit from
 using Maven.

* How can Maven benefit my development process?

 Maven can benefit your build process by using standard conventions and practices to accelerate your development
 process while at the same time helping you achieve a higher rate of success. For a more detailed look at how
 Maven can help you with your development process please refer to {{{../benefits-of-using-maven.apt}}The Benefits of Using Maven}.

* How do I make my first Maven project?

 We are going to jump head long into creating your first Maven project, but before doing that it is recommended that you
 understand what Maven's Project Object Model (POM) is all about. For this you can refer to the {{{../introduction-to-the-pom.html}}Introduction to the POM}.
 You can read this later if you want to jump right into seeing a working Maven build, but the POM is the primary unit of
 work in Maven and so understanding the POM can be highly useful!

 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 wishes. We are going to show you how the archetype mechanism works now, but if you would to know more about
 archetypes please refer to our {{{../introduction-to-archetypes}}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:

+-----+

m2 archetype:create -DgroupId=com.mycompany.app -DartifactId=my-app

+-----+

 Once you have executed this command you will have a directory structure that looks like the following:

+-----+

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 you applications sources and
 a source tree for your tests. This is the standard layout for Maven projects where the application sources
 reside in <<<${basedir}/src/main/java>>> and test sources reside in <<<${basedir}/src/test/java>>>.

 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 to the Standard Directory Layout}.

 So now that we have our first project let's take a look at the POM that was created for us by the archetype
 mechanism:

+-----+

 <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/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.mycompany.app</groupId>
  <artifactId>my-app</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>Maven Quick Start Archetype</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

+-----+

 This is a very simple POM but still displays the key elements every POM contains so lets walk through each of them
 to familiarize you with the POM essentials:

 * <<project>>

 * <<modelVersion>>

 * <<groupId>>

 * <<artifactId>>

 * <<packaging>>

 * <<version>>

 * <<name>>

 * <<url>>

 For a complete reference of what elements are available for use in the POM please refer to our {{{../../maven-model/maven.html}}POM Reference}.

 Now that we have a POM, some application sources, and some test sources you are probably asking ...

* How do I compile my application sources?

+-----+

m2 compile

+-----+

 Upon executing this command you should see output like the following:

+-----+

[INFO] ----------------------------------------------------------------------------
[INFO] Building Maven Quick Start Archetype
[INFO]    task-segment: [compile]
[INFO] ----------------------------------------------------------------------------
[INFO] artifact org.apache.maven.plugins:maven-resources-plugin: checking for updates from central
[INFO] artifact org.apache.maven.plugins:maven-compiler-plugin: checking for updates from central
[INFO] [resources:resources]
[INFO] [compiler:compile]
Compiling 1 source file to /tmp/my-app/target/classes
[INFO] ----------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ----------------------------------------------------------------------------
[INFO] Total time: 5 seconds
[INFO] Finished at: Fri Sep 23 15:48:34 GMT-05:00 2005
[INFO] Final Memory: 2M/6M
[INFO] ----------------------------------------------------------------------------

+-----+

 As you can see from the output the compiled classes where placed in <<<${basedir}/target/classes>>> which is
 another standard convention employed by Maven. So, if you're a keen observer you'll notice that using the
 standard conventions the POM above is very small and you haven't explicity had to tell Maven 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 comparison lets take a look at what you might have had to do
 in {{{http://ant.apache.org}}Ant} to accomplish the same thing:

+----+

<project default="compile">
  <target name="compile" description="o Compile the code" depends="get-deps">
    <mkdir dir="${classesdir}"/>
    <javac destdir="${classesdir}">
      <src>
        <pathelement location="src/main/java"/>
      </src>
    </javac>
  </target>
</project>

+----+

 Now this is simply to compile a single application source and the Ant script above 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 above!

~~* How do I compile my test sources?

+----+
+----+

~~* How do I create a JAR?

+----+
+----+

~~* How do I package resources inside my JAR?
~~  o EIDSL

~~* How do I filter resources against a properties file?

~~* How do I filter resources against my POM?

+-----+

FYI - In beta-2, while the other technique is still supported, the
recommended way is finally settled:

<build>
  <filters>
    <filtersFile>...</filtersFile>
  </filters>
</build>

+-----+

~~* How do use resources with my tests?
~~  o EIDSL

~~* How do I use external dependencies?
~~  o Explain the use of repositories, remote and local

~~* How do I setup a proxy if I'm behind a firewall so I can get my external dependencies?

~~* How do I install my JAR in my local repository?
~~  o Explain the standard layout of the m2 repository

~~* How do I deploy my jar in my remote repository?

~~* How do I deploy my jar in Ibiblio?

~~* How do I create documentation?
~~  o Explain the different formats APT/xdoc/docbook/FAQML

~~* How do I generate my site?

~~* How do I use plug-ins?
  o Explain that a plug-in consists of one or more mojos
~~* How do I control what version of plug-in I use?

~~* How do I generate reports?

~~* How do I internationalize my site?

~~http://docs.codehaus.org/display/MAVEN/Maven+Plugin+Matrix

+-----+

multiple repositories

<project>
...
  <repositories>
    <repository>
      <id>central</id>
      <name>Maven Repository Switchboard</name>
      <url>http://repo1.maven.org/maven2</url>
    </repository>
    <repository>
      <id>my-repo</id>
      <name>your custom repo</name>
      <url>http://jarsm2.dyndns.dk</url>
    </repository>
  </repositories>
...
</project>

==

Project properties

Actually, no. It's *like* the properties defined in profiles in syntax,
but this is a properties section that is specified as a direct child of
the <project> element. So:

<project>
~  ...
~  <properties>
~    <name>value</name>
~  </properties>
</project>

==

Profile inheritance the same as standard inheritence and resources sets are currently not
inherited.

DefaultModelInheritenceAssembler.

Merged:
- dependencies
- developers and contributors
- plugin lists (including reports)
- plugin executions with matching ids
- plugin configuration

==

System vars are accessed implicitly in m2...try:

<configuration>
  <debug>${build.debug}</debug>
  <source>${build.jdk}</source>
  <target>${build.jdk}</target>
</configuration>

==

How to attach sources to a release?

> How does the sources plugin realize that it is part of a snapshot
> build, and therefore not generate a sources JAR?
>
> I didn't notice anything obvious in the source code for the Mojo at

It only does so when the release profile (see the root POM) is activated.

==

How do I get the list of artifacts within my plugin?

You must use the @requiresDependencyResolution tag in your plugin.

+-----+