Maven Build

Intro

In the early days of Scarab the build system was entirely based on Ant. We have recently switched over to use Maven as our primary build system. But for quite a few reasons we continue supporting an Ant based build.

The new Maven based build system allows to build a Scarab instance from the Source distribution and in addition adds all functionality to build the documentation-set, update the jar-repository and so on.

NOTE: Like Ant the Maven build can be customized with the file build.properties . But beware, the location of this file is now the Scarab root directory. Otherwise Maven would not see this file. The Ant build system has been modifyed to use the same build.properties file, hence you can even intermix the usage of Ant and Maven without any problems. If you are upgrading from an old system, please ensure, that your old build.properties file migrates to

$SCARAB_ROOT/build.properties

In most cases you will utilize Maven as follows: 

1:> cd $SCARAB_ROOT
2:> maven war:webapp -D maven.test.skip
3:> maven scarab:create-db
  • 1: cd $SCARAB_ROOT

    go to the root directory of your Scarab source installation.
  • 2: maven war:webapp -D maven.test.skip

    Create the webapp in target/scarab
  • 3: maven scarab:create-db

    Finally create the database. You will be prompted for input.
The relevant Maven goals have been summarized and described in the remainder of this text.

Generating Torque Objects

Because the the various Torque objects are not checked into CVS, but instead are generated based on your settings for the type of database, you still need to create the java files. 

maven java:compile
This will create in /src/java the various Torque objects.

Only after you have initially generated the Torque objects, you can perform all the various functions of Maven that you would expect like running unit tests, producing WAR files, etc.

Generating Database

You can generate your database by doing this: 

maven scarab:create-db
This will create in /target/sql the various SQL files that you need. It will also install the database for certain types of databases.

If you want to create the database without seed data (example data for test purposes) you can call maven as follows: 

maven -Dskip.seed.data=true scarab:create-db

Testing the code

To test that everything is working properly, you should run the unit tests! 

maven test
This will compile your newly generated Torque classes and run the unit tests. One thing to note is that in /src/test/ are some config files that you probably will need to update the database settings for.

Generating the documentation

If you want to generate the entire site documenation, then you can run 

maven site
or, if you don't want to execute the unit tests (maybe they are failing) 
maven site -Dmaven.test.skip

If you want to see only the subset of the documenation, which is generated from the xml-sources (the Scarab documentation manuals and Howto's), then you can run 

maven xdoc:transform
This call is significantly faster than generating the whole site (order of seconds vs. order of minutes).

Creating a WAR file

Once things are to your liking you can use Maven to generate your WAR file: 

maven war
This will compile Scarab, run the unit tests, and then generate in /target a WAR file that you can then use to deploy to any Servlet container.

If you don't already have a configured Tomcat servlet container setup, then you can use the embedded Tomcat that comes with Scarab. It is in the /tomcat directory. To set it up, you just need to put your WAR file in /tomcat/webapps/. Take the existing /tomcat/webapps/scarab.xml file and rename it scarab.xml.off, as it is used for inplace development.

In Place Development

Intro

Scarab is setup to do inplace development where the webapp is set to be run from the /src/webapp directory. This way you can change templates, edit config files and have the changes show up immediatly. No need to do a build/deploy/run.

Inplace development relies on the embedded Tomcat distribution at /tomcat. The maven scarab:inplace goal will automatically setup the correct scarab Context file in /tomcat/webapps/: 

maven war:inplace
This will customize the /tomcat/webapps/scarab.xml to point to /src/webapp as the root instead of /target/scarab.

If you are using an IDE like Eclipse, most changes like editing a .java file will automatically restart Turbine for you.

Updating the www/repository

The www/repository is mainly used for the Ant build, because with ant it is not so easy to dynamically grab jar files from the network. Besides this we decided to also support offline generation when an online access to the network is not available. Therefore the www/repository contains all bits and pieces needed to build Scarab.

It is not very handsome to maintain the www/repository by hand. Therefore we have provided a Maven goal, that automatically updates the www/repository according to the maven dependency file. If you want to perform such an update (e.g. because you want to check in a new jar file or simply want to maintain the repository) you can call: 

 maven scarab:update-repo
This goal will remove unneeded jars from the repository and add needed jars to it. Maven gathers the jars from the network if needed.

Eclipse Setup Directions

By default, Scarab is setup to use Eclipse as it's IDE. To setup Scarab in Eclipse first run the eclipse plugin to generate the required files. 

maven eclipse
In the secnd step you must generate the Torque Objects once, see "Generating Torque Objects". Finally you can open Eclipse and just import the Scarab directory. The .classpath and .project files will be created for you.

After you have imported Scarab into eclipse, do a build in Eclipse to ensure everything compiles.

You will then need to download and install the Sysdeo Tomcat plugin.

Restart Eclipse and then go to Window > Preferences and select the Tomcat option.

First select the Tomcat 4.1.x version of Tomcat, as that is what comes with Scarab.

Set the tomcat home to:C:\java\scarab\tomcat, then the configuration file should be set to: C:\java\scarab\tomcat\conf\server.xml.

Next you do the Maven part. There is a file called maven.xml that contains all the goals needed for setting up inplace development. For other IDE's you may need to tweak this.

From the root directory run the inplace setup goal. 

maven scarab:inplace
This copies all the jars, classes, config files needed into your /src/webapp/ directory, creating the /src/webapp/WEB-INF/classes and /src/webapp/WEB-INF/conf directories. This will also rename your /tomcat/webapps/scarab.xml to scarab.regular.xml.off and take the special inplace file scarab.inplace.xml.off and rename it scarab.xml.

Now, right click your project in Eclipse and choose properties and then Tomcat. Checkbox the "Is Tomcat Project", set the context name to scarab, and UNCHECK the update server.xml. Check the mark as reloadable and redirect logging to Eclipse options. Set the web application root to /src/webapp. Save the changes and start up the Tomcat plugin. Navigate in your browser to http://localhost:8080/scarab and you should see the login page!

Eclipse Setup Directions

Once you are done doing "in place" development, you can just run the goal to clean everything back up: 

maven clean
This will delete everything that was moved around by the inplace setup goal, as well as fix up your Scarab context entries as well. Now, when you run: 
maven scarab:inplace
Everything will be put back!