Example Maven Project
Overview
The SLAC CVS contains a sample Maven project called ExampleMavenProject.
Obtaining
To obtain the ExampleMavenProject module, execute this CVS command from a work directory.
cvs -d :pserver:anonymous@cvs.freehep.org:/cvs/lcd co ExampleMavenProject
This simple project can be used as a template for starting new project or as a platform for experimentation with package imports, scratch Java code, and JAS3 plugins.
Anatomy of the Project
Directories
The directory into which the project was checked-out will be called the "base" directory. By default, it will be called "Example Maven Project".
This directory should contain two subdirectories.
src test
The src dir is the root area for Java source code.
Your Source Code
All the code for your project should be placed someplace under src.
The test dir contains unit tests. LCSim uses the JUnit test framework.
Unit Tests
Ideally, each of your Java classes should have a unit test.
These directories can be customized or additional ones can be added by modifying the project.xml file. (which is beyond the scope of this tutorial)
Maven Build Files
The ExampleMavenProject module contains the following Maven files, which should be included in a new Maven project.
maven.xml project.properties project.xml
The project.xml file is the primary Maven configuration file that lists all the project's meta-information and its dependencies.
The project.properties file is used to set named variables (properties) that determine certain project behavior, such as whether deprecation warnings are shown or the tests are skipped. You can put any custom
maven settings into this file.
For instance, to show Java deprecation messages when compiling, remove the "#" from in front of this line in the project.properties file.
#maven.compile.deprecation=on
maven.xml sets-up some project build defaults.
build.sh is a non-essential helper script demonstrating a project build with a set of maven commands.
Example Code
Two Java files are included within the sample project.
The src/ExampleMavenProject.java is a simple example of a Java source file.
The file test/ExampleMavenProjectTest.java is a very basic test case example that runs the main of a project class with some dummy arguments.
Building
This is the simplest way to build a Maven project.
cd ExampleMavenProject maven
(It doesn't get much easier than that.)
The maven.xml file sets the default build target to create a jar in the target directory.
ExampleMavenProject-1.0.jar
The "1.0" version number comes from the project.xml file.
ExampleMavenProject also includes a bash build script.
cd ExampleMavenProject ./build.sh
This executes the following command.
maven -Drun.install=$(pwd) -Dmaven.test.skip=true clean jar:install jas:install run:install
This command builds the jar file, skipping tests, and installs the run script into the current directory. It also makes the jar available to JAS3.
This would be the step-by-step build procedure (leaving out the skipping of tests).
- Build the jar file.
maven
- Create the project run script.
maven -Drun.install=$(pwd) run:install
- Install the jar into the ~/.JAS3/extensions directory, so that JAS3 will automatically load a plugin when it starts up.
maven jas:install
Testing
Now, test the run script.
./bin/ExampleMavenProject
This message should be printed to the screen.
ExampleMavenProject - Hello world!
Freehep Run Plugin
The cross-platform script creation is done using the Freehep Run Plugin, which is listed as a dependency in the project.xml file.
Java files can be added into src or test.
Classes placed here can access packages in the org.lcsim framework and all of its dependencies.
Simply rerun the build command given above to compile any classes that you add.
Using as a Template
First, create a directory for your project at the same level as the ExampleMavenProject directory.
mkdir MyProject cd MyProject
Then you can copy all the files from ExampleMavenProject into your area, excluding CVS files, with a command like this.
bash for f in $(find ../ExampleMavenProject -print | grep -v CVS); do cp $f .; done
CVS Repositories
Contact your system administrator about adding a project to your source code repository.
Or mail Tony Johnson if you want to use the LCD CVS at SLAC.
4 Comments
Jan Strube
Does this pull in the org.lcsim dependency from the web? And when you have org.lcsim on your disk somewhere it automagically uses that?
What exactly is in the jar file that gets created? I assume that the jas:install target also installs the GeomConverter.jar and the lcsim.jar, but what if the project just consists of a bunch of Drivers? I wouldn't need to install those into the extensions dir, but I probably would still have to run the jas:install target?
Jeremy McCormick
Hi, Jan.
I just updated ExampleMavenProject. Update to cvs head please.
> Does this pull in the org.lcsim dependency from the web? And when you have org.lcsim on your disk somewhere it automagically uses that?
No, you still have to follow the build instructions for lcsim and geomconverter which are installed at ~/.maven/repository. It will use the versions it finds there. This is actually the best way to do it, as you get CVS head versions that way. We don't really maintain a maven repository for lcsim and geomconverter but we should!
> What exactly is in the jar file that gets created?
Not much, but it should be able to run in JAS3 provided that jas:install is run once or the necessary dependencies are there. They probably will be there if lcsim was ever installed as a plugin.
Or you can use the ./bin/ExampleMavenProject run script.
> I assume that the jas:install target also installs the GeomConverter.jar and the lcsim.jar, but what if the project just consists of a bunch of Drivers?
The jas:install target does this.
The jar for any dependency with this property in project.xml will be copied into .JAS3/extensions
For example...
You could set this to false if you didn't want to copy lcsim into .JAS3/extensions when jas:install is run.
Jan Strube
Hmm. I get the error
./ExampleMavenProject
Exception in thread "main" java.lang.NoClassDefFoundError: HitPositionTest
Jeremy McCormick
That was a problem with a properties file that I just fixed. The mainclass should actually be ExampleMavenProject.