maven for scala

Friday, January 4, 2008

Posted by David Bernard

I'll try to provide a mini-guide about maven for scala's project. For more info, go to maven home or plugin's home.

Introduction to maven

Maven is a builder like make or ant, written in java. It's a commande line tool, IDE (Eclipse, Netbeans, IDEA) have plugins to handle and integrate project powered by maven. It could be used to create lib (jar), webapps (ear) and any other type of "artifact". It prefers convention over configuration, and configuration over instruction. What that mean exactly ?

every action have a default configuration (= the convention).
every action is a goal defined into a plugin (aka mojo), and for common case, you will try to use existing plugin instead of calling (more) low level instruction (like copy file,...)

Before creating your first scala project, You need to know some info:

a command line tool
- "mvn" is the name of the command line tool to call maven 2.x. To display help, run mvn help
the project descriptor : the file [prj]/pom.xml
- It's the file when every project information are stored (name, version, dependencies, license, mailing-list,...)
the build lifecycle : The build lifecycle is defined by a sequence of phases, the main are:
- compile - compile the source code of the project
- test - test the compiled source code using a suitable unit testing framework. These tests should not require the code be packaged or deployed
- package - take the compiled code and package it in its distributable format, such as a JAR.
- integration-test - process and deploy the package if necessary into an environment where integration tests can be run
- install - install the package into the local repository, for use as a dependency in other projects locally
- deploy - done in an integration or release environment, copies the final package to the remote repository for sharing with other developers and projects.
A phase is depend of the previous one, so when you request the phase test, then the phase compile is done before,...
Directory layout
- see below for a scala project
repository
- Maven use repositories (local and remote) to store and to retrieve artifacts and their descriptor (pom). Artifacts are jar, war,... and they could be used as dependencies, maven plugin,...
- By default, maven search artifact in the central repository. A "dedicated" repository for Scala stuff is available at http://scala-tools.org/repo-releases/.

Your first scala project with maven

In the following, we will run maven for the first time. Maven download what it need to work from remote repositories, and cache the downloaded artifact into its local repository (default is $HOME/.m2/repository). It only download what it need for the requested phases/goals (lazy downloading). So the first runs could be very long.

Step 0: installation

install jdk 1.5+ (eg : on my box $HOME/bin/soft-linux/jdk-1.5.0_03)
install maven 2.0.8+ (eg : on my box $HOME/bin/soft-java/apache-maven-2.0.8)
- download it
- unarchive it
- add the apache-maven-2.0.8/bin directory to your PATH
- check that maven is in the path:
  - go into any directory outside the maven installation
  - run mvn help, you should see
```
usage: mvn [options] [<goal(s)>] [<phase(s)>]

Options:
-q,--quiet                    Quiet output - only show errors
...
```

Step 1: create a project

You could create a project skeleton with your favorite file system tools (following directory layout as below) or you could use archetypes. Maven Archetypes are project'skeleton that could be used to create new project.

mvn org.apache.maven.plugins:maven-archetype-plugin:1.0-alpha-7:create \
-DarchetypeGroupId=org.scala-tools.archetypes \
-DarchetypeArtifactId=scala-archetype-simple \
-DarchetypeVersion=1.1 \
-DremoteRepositories=http://scala-tools.org/repo-releases \
-DgroupId=your.proj.gid -DartifactId=your-proj-id

At the end of the process you should see something like

...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1 second
[INFO] Finished at: Sat Jan 05 17:39:47 CET 2008
[INFO] Final Memory: 6M/63M
[INFO] ------------------------------------------------------------------------

!! Success you now have a empty project under your-proj-id directory with the following directory layout :

your-proj-id/
|-- pom.xml
`-- src
|-- main
|   `-- scala
|       `-- your
|           `-- proj
|               `-- gid
|                   `-- App.scala
`-- test
    `-- scala
        `-- your
            `-- proj
                `-- gid
                    `-- AppTest.scala

In fact, the project is not empty it contains an helloworld application (App.scala) and a JUnit test (AppTest.scala).

In the next step, you will request phase (or goals). The results will be put under your-proj-id/target directory. The target directory is the working directory where every plugin put the result of computation. If you want to clean up, request the goal "clean"

mvn clean

Step 2: compile the project

# only compile
mvn compile

If it's the first time you use maven with scala, the build should failed with a message like

...
[ERROR] FATAL ERROR
[INFO]
------------------------------------------------------------------------
[INFO] The PluginDescriptor for the plugin Plugin [org.scala-tools:maven-scala-plugin] was not found.
[INFO]
...

Cause :: The pom.xml (autogenerated) doesn't specify wish version to use for maven-scala-plugin, so maven try to use the latest available localy, and none was previously downloaded.
Solutions :: Edit the pom.xml and define a version for the plugin.; Request to download the latest available on remote repositories.

I prefer the second solution (in this case):

# only compile
mvn -U compile

now you should see

...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
...

Step 3: compile and running test

The skeleton create a JUnit test AppTest.scala as sample, try to compile and run it

# compile + compile test + run test
mvn test

you should get :

...
-------------------------------------------------------
T E S T S
-------------------------------------------------------
Running your.proj.gid.AppTest
Tests run: 2, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 0.054 sec <<< FAILURE!

Results :

Failed tests:
testKO(your.proj.gid.AppTest)

Tests run: 2, Failures: 1, Errors: 0, Skipped: 0

[INFO] ------------------------------------------------------------------------
[ERROR] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] There are test failures.

Please refer to /home/dwayne/tmp/your-proj-id/target/surefire-reports for the individual test results.

BUILD FAILURE, it's not good! So read the log on console :

there is 2 tests and one of them failed
the failed test is the method testKO from the class your.proj.gid.AppTest
see the content of the directory .../your-proj-id/target/surefire-reports for details

So you could read the problem in .../your-proj-id/target/surefire-reports/your.proj.gid.AppTest.txt

...
testKO(your.proj.gid.AppTest)  Time elapsed: 0.01 sec  <<< FAILURE!
junit.framework.AssertionFailedError
    at junit.framework.Assert.fail(Assert.java:47)
    at junit.framework.Assert.assertTrue(Assert.java:20)
    at junit.framework.Assert.assertTrue(Assert.java:27)
    at your.proj.gid.AppTest.testKO(AppTest.scala:26)
    at your.proj.gid.AppTest.testKO(AppTest.scala:26)
...

So edit the test and fix it (it's easy), and rerun test until it pass. Why the empty project is created with a failed test? to check that test are running and are used.

Step 4: generate the jar

# compile + run test + generate the jar
mvn package

If you fixed the test in Step 3, then a jar should be generated under the target directory. The jar doesn't contains the test classes, only the classes from src/main/scala/...

Step 5: start coding

add scala file under src/main/scala/... or src/test/scala/...
run the phases or goal you wish,...
if you need more lib (dependencies), edit the pom.xml and add <dependecy> node. By default you could declare dependency available on central repo (I suggest to use mvnrepository as a search engine in central repo), or in http://scala-tools.org/repo-releases/ (browse the directory, no search engine available :()

Conclusion

I expect this overlook and quick tutorial could help you to start playing with maven and scala. I plan to write other articles about "maven for scala" (about, the pom.xml and repositories). If you want to know more about maven and don't want to wai futur article, I suggest you browse the documentation of maven. I also suggest you to take a look at the maven-scala-plugin 2.x documentation, you'll see how to generate scaladoc, choose the scala version, or run a scala console with the project dependencies.

If you have question ask, If you want I detail some point here or in a futur article, ask.

Overview

Examples

Project Documentation