Craftsman Quick-Start Guide

So you want to use Craftsman, but if you can't get it working in 15 minutes you aren't going to use it anymore? Ok, fair enough. If you are trying to setup a simple Java project, we can have you running in under 10 minutes.

Let's say your project is called "Foobar" and you have some java source code for it already. Below are the steps you would use to get your Foobar building.

Configuring Foobar to use Craftsman

1. Create your project directory, called "foobar".

This is your "module" or "project" directory. We will be creating a standard Craftsman directory structure under this directory in the steps that follow.

2. Create a directory called "src".

This should be in your module directory from step 1. Move your source into this directory. This directory is your "root" package or "default" package for Java code. If you had a configuration file that needs to be at "/config.properties" in the classpath, it would be at foobar/src/config.properties.

3. Create a directory called "test".

This should be in your module directory from step 1. Move any unit tests into this directory. So, if you mixed your module source and your unit test source in the same directory originally, now move the unit test source to test. Create any package directories that you had in the src dir.

4. Create a directory called "lib"

This should be in your module directory from step 1. Now take any libraries your Foobar module depended on and make a directory for them under lib. For example, if you depended on the jakarta-commons libraries from Apache, create a directory called "jakarta-commons" under lib.

You should now have a directory structure that looks something like this:

+ foobar
  + src
    + com
      + yourcompany
        + foobar
            SomeClass1
            SomeClass2
            ...
  + test
    + com
      + yourcompany
        + foobar
            SomeClass1Test
            SomeClass2Test
            ...
  + lib
    + jakarta-commons
        commons-lang.jar
        ...

5. Add the Craftsman Bootstrap libraries.

You should be creating a directory called "bootstrap" under your lib directory from step 4. Download the Craftsman bootstrap bundle into this directory and unpack it. Your bootstrap directory should look something like this:

commons-logging.jar
craftsman-bootstrap.jar
craftsman-bootstrap.xml
craftsman-io.jar
craftsman-library.jar
rsh-ant.jar
rsh-commons.jar
rsh-config.jar
rsh-logging.jar
rsh-utils.jar

PLEASE NOTE: The bootstrap is a separate entity from your Craftsman installation. Do not place your bootstrap in the same directory with your Craftsman build system libs or vice versa.

6. Create a bootstrap.xml file.

Create a bootstrap.xml file in your module directory. You can find a sample bootstrap.xml on as directed on the Craftsman bootstrap page. Change the project name to "foobar-bootstrap" and the "lib.bootstrap.dir" value to "lib/bootstrap".

7. Create a "build.xml" file.

Create teh build.xml in your module directory. This will be your Ant build file for the project. Craftsman will piggy-back off this file to get its job done.

You should now have a directory structure that looks something like this:

+ foobar
    bootstrap.xml
    build.xml
  + src
    + com
      + yourcompany
        + foobar
            SomeClass1
            SomeClass2
            ...
  + test
    + com
      + yourcompany
        + foobar
            SomeClass1Test
            SomeClass2Test
            ...
  + lib
    + jakarta-commons
        commons-lang.jar
        ...

8. Create your module and build settings.

Populate your build.xml with the bootstrap settings and the module definitions. Place the following in build.xml file

<project name="foobar">
    <import file="bootstrap.xml" optional="true"/>

    <!-- Libraries common to all modules -->
    <library id="jakarta-commons" name="jakarta-commons"/>

    <!-- define the modules for this package -->
    <craftsmandef>
        <module moduleid="foobar">
            <library refid="jakarta-commons"/>
        </module>
    </craftsmandef>

    <!--
        Import the tasks for this package and its modules as
        defined by craftsman.
     -->
    <import file="craftsman.xml"/>

</project>

9. Build the Foobar.

You are now all set! Just change to your module directory. Execute "ant". You should see something like the following:

 $ ant
Buildfile: build.xml
Craftsman Build System version 0.3.8
Copyright (C) 2005 by Matt Luker.  All rights reserved.
[*] module foobar defined and registered.
[craftsmandef] creating craftsman.xml ...

build-foobar:

clean-foobar-for-build:

prep-foobar:

precompile-foobar:

compile-foobar:
[compilemodule] Compiling module foobar ...
    [mkdir] Created dir: /Users/kostya/src/foobar/build/module
    [mkdir] Created dir: /Users/kostya/src/foobar/build/gensrc
[compilemodule] ... finished compiling module foobar.

postcompile-foobar:

copy-foobar-resources:

precompile-foobar-tests:

compile-foobar-tests:
[compiletest] Compiling module foobar test cases ...
    [mkdir] Created dir: /Users/kostya/src/foobar/build/test
[compiletest] ... finished compiling module foobar test cases.

postcompile-foobar-tests:

copy-foobar-test-resources:

pretest-foobar:

test-foobar:
[testmodule] ?? No tests to run ??
[testmodule] (aborting testing ...)

posttest-foobar:

verify-foobar-source:

prepackage-foobar:

package-foobar:
    [mkdir] Created dir: /Users/kostya/src/foobar/build/jar
[packagemodule] Building MANIFEST-only jar: ...
[packagemodule] Building MANIFEST-only jar: ...
[conditionalbuild] ===================================
[conditionalbuild] Module foobar built SUCCESSFULLY!
[conditionalbuild] ===================================

build-all:

all:

BUILD SUCCESSFUL
Total time: 7 seconds

10. Tweak and adjust.

Take a look at the Craftsman HOWTO resources for additional configuration examples and other ways to build and extend your project.