Some notes about installing and using Maven
Maven is a project build and deployment utility, combining some modern ideas about software development with the success of utilities like Make and Ant. It is particularly suited to handle construction and deployment of Java servlets.
There is a nice introduction to Maven at http://www.theserverside.com/articles/article.tss?l=MavenMagic.
Contents:
Contents
1. Key ideas
Maven doesn't do anything that Ant cannot do, but it makes many things easier by imposing some conventions that make project structures more consistent, providing a framework for inheritance of project build information, decoupling project build details from the containing file system and de-coupling build procedures from project-specific dependencies. Maven also provides a basis for creating a java code and application repository framework analogous to Perl's CPAN.
There are two key Maven concepts with particular meanings: Project and Repository.
1.1. Projects
Each project defines a single "artifact" (constructed output), but may depend on any number of sub-projects. Multiple, separately defined goals may be applied to any (compatible?) project.
File layout within a project follows a defined teplate. Common plug-in goals assume certain things about the file layout within a project. Different goals (targets) are defined separately from the project details by plug-ins (and other places?). Jelly is used to script custom plug-ins (but not in Maven V2, where there is a move toward using java for coding plugins).
Maven has a framework for inheritance of project details, to avoid duplication of definitions across an enterprise or within a complex project. Subprojects can inherit from their containing master project, (which in turn can inherit from system-wide definitions and Maven defaults?).
1.2. Repositories
A local Maven repository is an area that provides a common structure for external packages upon which any project may depend. This helps to decoupling details of file system usage between systems. The repository layout is defined by group and project id values defined within the Maven project definition files.
External project dependencies are defined in terms of repository contents defined in terms of group and project id values.
Maven global repositories can be accessed by URI. Copies of software accessed from a global repository are cached in a local Maven repository.
2. Configuration files
Different configuration files are used with different scope:
- project.xml - defines project structure and properties
- maven.xml - (in a project base directory) defines general options and goals for maven applied that are to that project. This file customizes the build processes used by maven without reference to the project structure
- build.properties - project build properties local to the current environment. Projects may typically ship with a build.properties.sample that can be copied and customized for local requirements (e.g. where is Tomcat installed?)
- project.properties - project build properties that are not specific to a local build and deployment environment (e.g. locations for external dependencies)
3. Maven installation
- Download and run installer
Create repository; from the maven/bin directory:
install_repo dir, where dir is the chosen base directory for the Maven repository.
- Optionally, create personalized build.properties in your home directory. (This will override anything specified in a project.)
Running on Windows, I prefer to not store everything in my "home" directory, so I have used this to specify a common directory for my "personalized" maven options (e.g. C:\DEV\Maven). Remember to use '/' or '\\' for filename path separators in the propeprty file. So my home directory contains build.properties with the following contents:
# Maven build.properties
# See: http://maven.apache.org/reference/properties.html
# The directory on the local machine Maven uses to write user specific details to,
# such as expanded plugins and cache data.
# ${user.home}/.maven
maven.home.local = C:/DEV/Maven
# Where Maven can find it's plugins.
# ${maven.home}/plugins
# maven.plugin.dir =
# Where Maven can find plugins for this user only.
# ${maven.home.local}/plugins
# maven.plugin.user.dir
# Where Maven expands installed plugins for processing.
# ${maven.home.local}/cache
# maven.plugin.unpacked.dir =
# The repository on the local machine Maven should use to store downloaded artifacts (jars etc).
# ${maven.home.local}/repository
# maven.repo.local =
# (optional). Properties to use if you're behind a firewall
#maven.proxy.host =
#maven.proxy.port =
#maven.proxy.username =
#maven.proxy.password =
# DEPRECATED:
# The following have all been deprecated in favour of using the relevant elements in the POM,
# and the properties of the artifact plugin.
maven.ssh.executable = tortoiseplink
maven.scp.executable = pscp
# Location for Eclipse workspace files
maven.eclipse.workspace=D:/Cvs/Eclipse
# location of the Tomcat install where you want to deploy Pluto
# do not use backslashes in this path
maven.tomcat.home=C:/DEV/Apache Software Foundation/Tomcat 5.5
maven.tomcat.version.major=5
4. Importing a Maven project into Eclipse
See: http://radio.weblogs.com/0112098/stories/2003/02/12/usingEclipseAndMaven.html
Maven has a predefined goal for creating an Eclipse propject, but there are some gotchas to watch out for:
- First, build the project using Maven. This ensures all the project depednencies are loaded into the local maven repository.
Run maven eclipse: this creates the Eclipse project files
- Start Eclipse and import the project thus created.
In Eclipse, define the variable MAVEN_REPO to indicate the location of the Maven repository. The Maven-created Eclipse project should define external dependencies in terms of this variable. Use these commands and options: Window -> Preferences -> Java -> Build path -> Classpath variables.
Multiprojects are different. The maven command is: maven -Dgoal=eclipse multiproject:goal, which creates Eclipse project descriptions for all the sub-projects. Make sure that any .project and .classpath files in the multiproject root directory are removed, otherwise Eclipse does not see the sub-projects thus created. Now start Eclipse and import the sub-projects thus created. I'm not sure how to deal with nested multi-projects.
5. Maven 2.0
Maven 2.0 is a complete rewrite of Maven, not entirely compatible with maven 1.0 or 1.1. The project description is now in a file pom.xml, replacing project.xml. The repository layout is different. The maven.xml file is no more.
Note that there are incompatible pom.xml file format changes between Maven 2.0 beta releases and the final release.
Useful links:
http://maven.apache.org/maven2/ - Maven 2 homepage
http://www.developer.com/open/article.php/3552026 - introductory piece by David DeWolf, who also happens to be active in the Pluto project
http://docs.codehaus.org/pages/viewpage.action?pageId=22230 - repository layout (this should appear on the Maven 2 website fairly soon). This is very different to maven 1, though rumour has it that Maven 2 can also use Maven 1 repositories. I find the Maven 2 layout is more logical, since it more closely follows typical (java) code layout.
http://docs.codehaus.org/display/MAVEN/Maven+Plugin+Matrix - plug-inmatrix. (Plugins are how Maven knows how to build different kinds of software and other artifacts. Maven 2 plugins are typically written in java, and the old plugin scripting language (Jelly) is not part of the core system.)
http://maven.apache.org/maven2/developers/developing-plugins-with-marmalade.html - building a maven 2 plugin with marmalade (a jelly-like scripting language).
5.1. Configuration
Maven 2.0 does not use properties files (cf. Maven V1 uses build.properties files in the user home and project directoroes). Instead, Maven can be configured for the local environment by a conf/settings.xml in the maven 2.0 installation directory. With the final releave of V2.0, the Maven command is now mvn.
My system has file C:\DEV\Apache Software Foundation\maven-2.0\conf\settings.xml with the contents:
<settings> <localRepository>C:/DEV/M2/repository</localRepository> </settings>
The settings.xml file created by the Maven installation describes several other options.
-- GrahamKlyne 2005-10-23 10:06:46
