Maven

Introduction

Maven is a command line tool to help the software build process. In short, it's an advanced version of Ant. Cytoscape 3 project is based on this software, so you need to learn how to use this to develop Cytoscape 3 and its plugins.

General Information

• The maven website: http://maven.apache.org/

• Loads of documentation: http://maven.apache.org/guides/index.html

  • Quick Tutorial: http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html

  • Getting Started: http://maven.apache.org/guides/getting-started/index.html

• Most thorough guide so far: http://www.sonatype.com/book

Download & Install

Make sure you get Maven 2.x (not 1.x).

http://maven.apache.org/download.html

Installation instructions (from the site linked above):

Windows 2000/XP

Unzip maven-2.0.7-bin.zip to the directory you wish to install Maven 2.0.7. These instructions assume you chose C:\Program Files\Apache Software Foundation\maven-2.0.7 Add the bin directory to your path, by opening up the system properties (WinKey + Pause), selecting the "Advanced" tab, and the "Environment Variables" button, then editing the PATH variable in the user variables. eg. "C:\Program Files\Apache Software Foundation\maven-2.0.7\bin";%PATH% In the same dialog, make sure that JAVA_HOME is set to the location of your JDK, eg. C:\Program Files\Java\jdk1.5.0_02 Run mvn --version to verify that it is correctly installed:

C:\Documents and Settings\k>mvn -version
Maven version: 2.0.9
Java version: 1.6.0_07
OS name: "windows xp" version: "5.1" arch: "x86" Family: "windows"

C:\Documents and Settings\k>

Unix-based Operating Systems (Linux, Solaris, etc.)

Extract the distribution archive to the directory you wish to install Maven 2.0.7. These instructions assume you chose /usr/local/maven-2.0.7 . The directory maven-2.0.7 will be created from the archive. Add the bin directory to your path, eg. export PATH=/usr/local/maven-2.0.7/bin:$PATH Make sure that JAVA_HOME is set to the location of your JDK, eg. export JAVA_HOME=/usr/java/jdk1.5.0_02 Run mvn --version to verify that it is correctly installed.

Mac OS X

The easiest way to install maven on Mac OS X is using MacPorts. It is a package management system for unix and other command line tools. First, install MacPorts itself, and then use port command to install maven. Quick tutorial is available here.

Maven Plugins for IDE's

Maven Integration for Eclipse (m2eclipse plugin)

There is a plugin to integrate maven to eclipse. Use the following url for a "New Remote Site" in eclipse "Help->Software Updates":

• http://m2eclipse.sonatype.org/update/

Complete documentation for this plugin is available here.

• The following section is out-of-date and you do not have to do the following if you use the latest version of m2eclipse plugin.

  1. If your maven repository is not in your user home directory under .m2 you need to tell Eclipse where it is (and it's worth double checking it's set it up right either way. See here for instructions.

     • This can be done by setting up M2_REPO classpath variavle. Select Window → Preferences... → Java → Build Path → Classpath Variables and add new variable M2_REPO and set the path to your .m2/repository directory.

     

  2. Right-click on your project, choose Maven2 and 'enable' to use the plugin on a per-project basis. This will set up your local Maven repository (under the /<users.home>/.m2 directory) as a library in Eclipse.

Note: If you have more than one pom file in a project you must have a parent pom in order for the maven plugin to recognize all of the poms. You can create a basic pom then add it as a parent to all of the other pom files (you do not have to add them as modules to your parent, it's just a little simpler sometimes).

1. You can run maven commands by right-clicking on any pom file (assuming you've correctly parented them) and choosing the commands to run. Generally to run a full compile and all tests I run "clean package". If you run into problems running within Eclipse you can run the same commands from command line, often you will get easier to understand errors that way as well.

In your eclipse project you should see a library now called "Maven Dependencies" or something similar. If you expand it all of your libraries listed as dependencies in the pom files should be listed.

Cytoscape, Eclipse & Maven

Each time you update run "maven install" from your top level cytoscape directory. This installs the poms for the corelib modules and any other dependencies within the project to your local repository. If you don't do this Eclipse will continue to mark the parts of your code that it can't find with red and it will be unable to compile. This is temporary as various layers and modules are being added and moved around.

If you continue to have problems with updates not being recognized go to your .m2/repository directory. Delete the directory org/cytoscape and re-run "maven install". If version numbers are not updated in pom files or if versions are not marked as "SNAPSHOT" then the latest updates may not correctly install, removing this directory forces a fresh install regardless.

IntelliJ

The newest version of IDEA comes ready to use maven, but here are the plugins if you need to load them:

IntelliJ plugins:

• http://mevenide.codehaus.org/mevenide-idea/downloads.html

• http://plugins.intellij.net/plugin/?id=1166

This is easier to use than maven+eclipse but it also requires that if you have multiple poms a parent is set up.

NetBeans

NetBeans 5.0+:

• http://mevenide.codehaus.org/m2-site/

FAQs

OK, I have installed maven and downloaded the Cytoscape 3 source code. What's next?

Once you have Maven installed, and have downloaded the Cytoscape 3 source, you can build and run cytoscape.

• mvn pax:run

If that doesn't work, try:

• mvn clean install pax:run

When I run mvn install, I see a list of unit test failures. Can I still get Cytoscape to run, even in the face of these unit test failures?

If running mvn install fails due to failed unit tests, you have two options:

• Fix the errors! or

• Force maven to skip the unit tests: mvn -Dmaven.test.skip=true install Doing this skips all the unit tests, but enables you to fully build and run cytoscape. After running this, proceed with mvn pax:run  as noted above.

Does the 1.5 constraint in the compile plugin really use 1.5 to compile?

Probably not, the javac in your JAVA_HOME/bin will still be used. This is a way of saying "Use 1.5 or better, but 1.5 syntax is going to be enforced, other developers may be using 1.5, don't put 1.6 specific stuff in the code".

If you have trouble with compiling or running Cytoscape and you are using java 1.6 trying pointing JAVA_HOME back to 1.5.

Test running (or not!)

You can always run all tests in a project by just typing "mvn test". However, if you want to run just a single test or a set of specific tests you can also do it. http://maven.apache.org/plugins/maven-surefire-plugin/examples/single-test.html

Single Test Note that you do not append .class or .java to the test name, you also do not need the path. Maven knows the path from the pom.

mvn -Dtest=MyTestName test

Specific Set of Tests Do not put a space between commans and the next test name.

mvn -Dtest=MyTest,MyOtherTest,MyThirdTest

WildCards You can also use wildcards to run a set of tests with matching names.

mvn -Dtest=My*Test

Skipping Tests You can skip running tests or run them but continue the build after a failed test. http://maven.apache.org/plugins/maven-surefire-plugin/examples/skipping-test.html

Skip Tests If you are using IDEA to run your maven tasks note that in the maven screen there is an icon to toggle skipping tests.

mvn -DskipTests

-- or --

mvn -Dmaven.skip.test=true package

I need to find a dependency listing but I don't know where to look!

If you know at least the fully qualified name of a single class you need to use from a library go to http://javacio.us/ and paste it in. You will then get the option to "Find pom dependencies" if there is a public maven repository listing for the library you need. You can copy-paste the <dependency> listing it produces into your pom file. If it is not found in repo1.maven.org you will need to add a <repository> tag to the pom file as well.

If javacio.us cannot find the library it may be necessary to install it into the Cytoscape repository. Before doing this please check with the group and see if anyone else has found it. There are many maven repositories and it is possible not all are represented by that site.