Building & Installing craftsman

craftsman uses the Craftsman Build System. Craftsman makes use of ant, so this project is built using the supplied ant script. The build is configured to automatically download any required libraries from on-line sources. If the build requires a local library or toolkit to be in place in order to build, it will be documented in the BUILDING.txt file found in the root of the source tree.

If you do not have Craftsman installed, the Craftsman bootstrap process will walk you through the steps of downloading and installing the Craftsman libraries into the local directory.

Please see the guide for using Craftsman if you have any questions about using the ant build script.

Building

Building the project

To build the project, issue the following command:

ant clean build

This will compile, test, and build the project. The resulting jars will be in the individual modules' build/jar directories.

Skipping Unit Tests

While it is not recommended to skip unit tests (as test failure usually indicates a problem), some unit tests cannot function without special setup (such as a test database or a test application server). The project will not build unless the unit tests pass, so this can sometimes be an issue.

To skip unit testing, use the "skip.tests=1" option with your build:

ant -Dskip.tests=1 clean build

You can also make this setting permanent for your local build by adding the following to your build.properties file (if you do not have one, just create it in the top directory where the build.xml and craftsman.xml files live):

skip.tests=1

This setting will skip executing the unit tests (but the build will still compile them).

Generating documentation

Issue the following command to generate documentation for the project:

ant doc

Creating bundles for distribution or use

Craftsman allows project modules to be distributed in bundles. These bundles could contain the jars, wars, or ears from the project modules. These bundles are configured in the build.xml by the project maintainer.

To create this bundles, issue the following command:

ant clean build bundle

This will create any configured bundles and place them in the current directory.

When in doubt ...

If you still aren't sure what you should do or what you should call, either go see the guide or issue the following command:

ant -projecthelp

Installation

Craftsman creates several bundles that are used to install the final Craftsman build system. You normally install craftsman by making use of the bootstrap, which downloads the craftsman libraries and modules from the official site.

You can install Craftsman manually by taking all the of the generated bundles and unpacking them into the directory you intend to be your Craftsman library directory.

1. Find a directory that you want to be your craftsman home. A local directory will do fine (we recommend lib/craftsman). Create this directory.

2. Create a lib directory in your new craftsman home directory. So if you chose lib/craftsman, you now should have a lib/craftsman/lib directory.

3. Unpack the craftsman-$version.zip and all the craftsman-ext-*-$version.zip files into the lib directory (so, following the previous example, into lib/craftsman/lib).

4. Copy the craftsman-install.xml file into the lib directory (so, following the previous example, into lib/craftsman/lib).

5. Declare your craftsman home directory in the environment or in your local build file. Set the CRAFTSMAN_HOME to the full path of your craftsman home directory (say /home/you/src/lib/craftsman or C:/craftsman) and make sure it shows up in the environment. If you do not want to set a global environment variable, set the variable craftsman.home to the full path in your craftsman.properties file:

# your craftsman.properties file
craftsman.home=C:/craftsman

6. Now execute a craftsman build to make sure that the build can find it the craftsman installation ok. It will execute normally if it does. Otherwise, the bootstrap will ask you where it is. Try telling it your full-pathname again and see if that works. If bootstrap insists that isn't a good craftsman installation, you have the wrong directory or you have missed something vital. Review the above steps and make sure you have at least the craftsman-$version.zip file in the right place.