= Using Maven-based Build Tools =

[[TracNav]]
[[TOC(inline)]]

Maven is a Java-based system that provides a standard file format for
build information, well-defined build lifecycle, and plugin framework
for extensions.  There also exist standard repositories in which both
development and production packages (artifacts) can be maintained.
The maven plugins are also available through standard maven
repositories, allowing the core maven code to be very small.  Any real
build, however, will require a large number of additional plug-ins
that are downloaded automatically and cached on the user's machine.

== Installing Maven ==

To download and install maven see the [http://maven.apache.org/ maven website]. You must install maven 2.2.1 or later.  (There may be warnings with Maven 3.0 or later; these will be fixed in future releases.)

Essentially the only required dependency is a recent, certified
version of a Java Virtual Machine.  This installation provides a
command line interface to maven, the primary command being `mvn`.

Maven also integrates well with Eclipse.  The [http://m2eclipse.sonatype.org/ m2eclipse plugin] is recommended. 

== Running Maven ==

Running maven should be as simple as checking out the Quattor code and
then running `mvn package`.  This will prepare the sources, compile
them (if necessary), and package the results.  If on a machine which
supports RPM packaging, RPM packages will be produced.  In all cases,
appropriate tarballs will be generated.

== Directory structure to use with Maven ==

Quattor modules that should be built with Maven will have the
following structure:

 * ChangeLog
 * pom.xml (project file)
 * src
   * main
     * pan
       * components
       	 * <component name>	
           * config.pan: What users will tipically include from their
             profiles. Everything else is included directly or
             indirectly from here.
	   * schema.pan: Component's schema
	   * config-common.pan: Component's basic
             configuration. Usually it doesn't need any human
             edition. But if you need any extra files, include them
             here.
           * config-rpm.pan: Installs the component's RPM.
	   * config-xml.pan: If you don't want an RPM, but prefer to
             ship the component's code directly in its profile.
	     

     * perl
       * <component name>.pm: Code
       * <component name>.pod: Documentation.

Please note that there are no ".cin" files anymore. Files are not
renamed anymore with the new build tools.

== Using Maven to build an NCM component ==

=== Creating the basic structure for the component ===

You'll get the basic directory structure for the component with:

{{{#!sh
mvn archetype:generate \
    -DarchetypeArtifactId=cfg-module \
    -DarchetypeGroupId=org.quattor.maven \
    -DarchetypeVersion=1.16
}}}

With all this, you can now write your code!

Note that you no longer need to add the LAPP repository to your settings file.

Note also that you can check for the [[http://search.maven.org/#search%7Cgav%7C1%7Cg%3A%22org.quattor.maven%22%20AND%20a%3A%22cfg-module%22|latest version of the archetype]] by searching the central maven repository.  

=== Importing an existing component into the new structure ===

First of all, go to the old structure, with the old build tools and
run `make` there. It will expand all placeholders, and you'll get the
files you really want to import.

Next, remove all those heavy headers we used to have. Instead, the
following, lighter header:

{{{#!perl
# ${license-info}
# ${developer-info}
# ${author-info}
# ${build-info}
}}}

will give the same information, and will get expanded by Maven.

Now, copy the generated files into the correct places. Perl and pode
code are obvious. Then, your old `config.tpl` should become your new
`config-common.pan`, and your old `schema.tpl` should become your new
`schema.pan`.

And that's it. You can add the new hierarchy to SVN and get rid of the
old one. :)

== Actually building the software ==

To build it, you just need to be on the top level directory, and run:

{{{#!sh
mvn clean package 
}}}

It will ask a number of questions. If you want it to be completely
interactive, you can run it with `-batch`.

Now, all your files (tarballs, RPMs, whatever) are in the `target`
subdirectory.