Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin

...

The SLAC CVS contains a sample module Maven project called ExampleMavenProject that can be used as a template for your own Maven-based projects.

Obtaining

To obtain the ExampleMavenProject module, execute this CVS command from a work directory.

No Format
cvs -d :pserver:anonymous@cvs.freehep.org:/cvs/lcd co ExampleMavenProject

This project is ready to use simple project can be used as a template for starting new project or as a platform for experimentation with package imports, Java code execution, etc.

Building

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.

No Format

src
test

The src dir is the root area for Java source code.

Tip
titleYour 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.

Tip
titleUnit 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.

No Format

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.

No Format

#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.

No Format

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.

No Format

ExampleMavenProject-1.0.jar

The "1.0" version number comes from the project.xml file.

ExampleMavenProject also includes a bash build scriptTo build the project from the command-line on Linux, Cygwin, etc.

No Format
cd ExampleMavenProject
./build.sh

Or you can use Maven directlyThis executes the following command.

Including both jar:install and jas:install is used only for illustrative purposes, as the jar:install target is executed by jas:install.
No Format
maven -Drun.install=$(pwd) -Dmaven.test.skip=true clean jar:install jas:install run:install
Note

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).

  1. Build the jar file.
    No Format
    
    maven
    
  2. Create the project run script.
    No Format
    
    maven -Drun.install=$(pwd) run:install
    
  3. Install the jar into the ~/.JAS3/extensions directory, so that JAS3 will automatically load a plugin when it starts up.
    No Format
    
    maven jas:install
    

Testing

Now, test the run script.

...

No Format
ExampleMavenProject - Hello world!
Info
titleFreehep 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.

...

Simply rerun the build command given above to compile any classes that you add.

Anatomy of the Project

The ExampleMavenProject module contains the following files essential files and directories.

No Format

build.sh
maven.xml
project.properties
project.xml
src
test

build.sh is a helper script for building the project with a set of maven commands.

maven.xml sets-up some project build defaults.

The project.properties file is used to set named variables that determine certain project behavior, such as whether deprecation warnings are shown.

The project.xml file is the primary Maven configuration file that lists all the project's meta-information and its dependencies.

The src dir contains Java source files.

The test directory contains unit tests that use the JUnit testing framework.

There are two additional test files.

No Format

src/ExampleMavenProject.java
test/ExampleMavenProjectTest.java

The src/ExampleMavenProject.java is a simple example of a Java source file.

The file test/ExampleMavenProjectTest.java is a basic test case template.

Using as a Template

To use ExampleMavenProject as a template for your own new project, replace the "ExampleMavenProject" string with the actual name of your own project in project.xml.

The CVS directories should all be removed.

No Format

find . -name "CVS" -exec rm -rf '{}' \; &> /dev/null

Then add to your CVS project all the files listed under the Anatomy section using CVS's import and add commands.

No Format

cvs import -m "Initial commit of MyProject" myProjectDir vendor initial

The above is an example only.

Using as a Template

First, create a directory for your project at the same level as the ExampleMavenProject directory.

No Format

mkdir MyProject
cd MyProject

Then you can copy all the files from ExampleMavenProject into your area, excluding CVS files, with a command like this.

No Format

bash
for f in $(find ../ExampleMavenProject -print | grep -v CVS); do cp $f .; done
tip
Tip
titleCVS Repositories

Contact your system administrator about adding a project to your local source code repository.

Or mail Contact Tony Johnson if you want to use the LCD CVS at SLAC.