vimwiki/tech/maven.wiki

= Maven =

Maven uses a Project object model to manage a software project. It manages

* reporting
* documentation
* building

Maven can

* build multiple projects together
* can manage:
  * builds
  * documentation
  * reporting
  * dependencies
  * SCMs
  * Releases
  * distribution
  * mailing lists

*All maven project structure is in an xml file called pom.xml*

For a quickstart, go to [[#Creating a project]]

Maven uses sensible defaults, requiring minimal configuration on the part of
the developer. Some defaults are below

| Item                    | Default             |
| source                  | /src/main/java      |
| resources               | /src/main/resources |
| tests                   | /src/test           |
| compiled byte code (.o) | /target             |
| jar                     | /target/classes     |


== pom.xml ==

This is the configuration file for maven, it lives in the base directory of the
project as pom.xml. There is a single POM file for each project

A POM requires a

* groupId
* artifactId
* version

With this notation, all projects are notated as
`groupId:artifactId:version`

Example 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.companyname.project-group</groupId>
   <artifactId>project</artifactId>
   <version>1.0</version>
</project>
  }}}

=== Super POM ===

All POM files inheret from the Super POM, this file is the default
configuration of all projects.

To view the current configuration, run `mvn help:effective-pom`

== Creating a project ==

Maven uses archetype plugins to create projects. These are essentially
templates.

To create a simple java application, run the following command

{{{
mvn archetype:generate \
 -DgroudId = com.company.subcompany \
 -DartifactId = ProjectName \
 -DarchetypeArtifactId = maven-archetype-quickstart \
 -DinteractiveMode = false
  }}}

This command specifies,

* the group
* the project
* the type of template to use (quickstarrt)
* to not be interactive

== Build lifecycle ==

The general lifecycle, or sequence of phases that maven takes are as follows

| phase             | handles                           |
| prepare-resources | resource copying                  |
| validate          | validate if all resources present |
| compile           | compilation                       |
| test              | testing with a framework          |
| package           | packaging (into jar)              |
| install           | installing in local repo          |
| deploy            | copy final package to remote repo |

== Plugins ==

All functionality in maven is in frameworks, making it modular. Maven built in
plugins due most basic operations including

* creating jar files
* create war file
* compile code files
* unit testing
* create documenation
* create reports

Some built in plugins include,

| name     | job                          |
| clean    | clean up target              |
| compiler | compile java source          |
| surefire | run JUnit tests              |
| jar      | build JAR file               |
| war      | build WAR file               |
| javadoc  | create javadoc               |
| antrun   | run ant tasks from any phase |

=== Site ===

Site is a plugin to create documentation to create reports, deploy site, etc

== Build profiles ==

Build profiles can be specified with the `-P` flag when `mvn` is called.
Profiles can be configured with the `<profiles>` tag. A more thurough example
is below

{{{
   <profiles>
      <profile>
         <id>test</id>
         <build>
            <plugins>
               <plugin>
                  <groupId>org.apache.maven.plugins</groupId>
                  <artifactId>maven-antrun-plugin</artifactId>
                  <version>1.1</version>
                  <executions>
                     <execution>
                        <phase>test</phase>
                        <goals>
                           <goal>run</goal>
                        </goals>
                        <configuration>
                           <tasks>
                              <echo>Using env.test.properties</echo>
                              <copy file="src/main/resources/env.test.properties"
                                 tofile="${project.build.outputDirectory}/env.properties"/>
                           </tasks>
                        </configuration>
                     </execution>
                  </executions>
               </plugin>
            </plugins>
         </build>
      </profile>
   </profiles>
  }}}

Note that at the `<tasks>` tag, you can specify what happens when that profile
is selected. In this instance, it copies a properties files to the correct
directory. The name of the profile that is passed on the command line is
configured with the `<id>` tag.

Activation elements can be added to build profiles with the `<activation>` tag.
This tag can take arguments or paramaters to check against in the enviroment it
is running, to automatically determine what profile to activate. Below are some
examples

Via enviroment var

{{{
<profile>
   <id>test</id>
   <activation>
      <property>
         <name>env</name>
         <value>test</value>
      </property>
   </activation>
</profile>
  }}}

Via OS (the example tirrgers on Windows XP)

{{{
<profile>
   <id>test</id>
   <activation>
      <os>
         <name>Windows XP</name>
         <family>Windows</family>
         <arch>x86</arch>
         <version>5.1.2600</version>
      </os>
   </activation>
</profile>
  }}}

Via present/missing files (the example checks the path in the `<missing>` tag)

{{{
<profile>
   <id>test</id>
   <activation>
      <file>
         <missing>target/generated-sources/axistools/wsdl2java/
           com/companyname/group</missing>
      </file>
   </activation>
</profile>
  }}}

== Repositories ==

A repository in maven terminology is a directory where project jars, library
jars, plugins, etc are stored and used by maven. There are three types

* local
* central
* remote

=== Local ===

A local maven repo is created first time you run maven on your machine. When
`mvn build` is run for the first time, it downloads all dependency jars

=== Central ===

The central repo is one provided by the maven community, it contains common
libraries. When a dependency is not found in the local repo, it automatically
searches the central repo.

In general key concepts,

* managed by maven community
* not required to be configured
* must have internet

=== Remote ===

A remote repo is only searched when specified via the `<repositories>` tag in
the pom.xml file. It specifies a url for maven to search on. These repos are
usually internal repos maintained by companies internally.