Using Craftsman to Build Projects

If you have a project that is configured to use Craftsman, you may have some initial questions about how to build the project. Please see the information below.

Craftsman Installation

If your project has a properly configured Craftsman Bootstrap included, installing Craftsman is easy. If your project does not have the bootstrap, contact the project administrator to make sure it isn't an error. Otherwise, see the Quick Start guide for information on how to install the bootstrap or Craftsman by hand.

If everything is configured properly, you should just be able to call the following, and the bootstrap will install Craftsman for you:

ant clean build

You will see the bootstrap start up. It will then follow the following steps. Note, all the steps of the installation wizard are listed to be clear and help you get through it, but in reality, it is not all that complicated or confused :-)

1. Upon starting, the bootstrap loads the properties from the local environment. This includes the System environment, the build.properties file, and the craftsman.properties file, where the files are in the current working directory.
2. Bootstrap looks in the settings for a Craftsman home property (either CRAFTSMAN_HOME in the environment or craftsman.home in the properties files).
   1. if bootstrap finds the Craftsman home, it attempts to load Craftsman from that directory. If it succeeds, bootstrap is finished and the build will continue. If it fails and starts with the next stage.
   2. if bootstrap does not find a Craftsman home, it goes to the next stage.
3. With no Craftsman home (or no valid Craftsman home), bootstrap asks if Craftsman is installed on the local machine. If answered yes, bootstrap prompts the user for an alternate location. If it finds and loads Craftsman from the alternate location, the bootstrap is finished and the build continutes. If it can't find Craftsman at the entered location, it will prompt for another location until it succeeds or the you enter nothing.
4. If the you answer no to whether there is another Craftsman installation or if bootstrap is unable to find a vallid one, bootstrap will then ask you if you want to install Craftsman. If the user answers no, the build aborts and the project will not be built. You will be prompted by bootstrap again the next time they try to build. If you answer yes, bootstrap continues.
5. Bootstrap will now ask for a location to install Craftsman to. The default will place it in lib/craftsman. The location you choose will be a Craftsman home directory when finished. If the directory specified doesn't exist, the bootstrap will create it.
6. Bootstrap will now download the core module. Once this is downloaded, it is verified.
7. With the core module installed, bootstrap will now prompt you for whether to install any of the optional support modules. It is recommended you answer "All" (the letter "A") at this point, as the modules are small and easily downloaded over any broadband connection. If you do not choose "All", you can select the numbers of the modules you want to install.
8. Once you are finished downloading the modules, choose "None" (the letter "N") to exit module installation.
9. After all the downloads are complete, bootstrap will attempt to load Craftsman from the downloaded components. If it fails, the build aborts. If it succeeds, bootstrap records the new location as craftsman.home in the build.properties file. The build now continues normally.

Downloading required libraries

This will be automatic (it is one of the features of Craftsman). If Craftsman cannot find the libraries described in the build.xml, it will use the library definitions to go out and find the libraries from local or remote sources.

You can trigger the library download by issuing the following command:

ant init

This process will only happen once. After they are downloaded, Craftsman will skip downloading them again. If for some reason you think you need new libraries or want updated libraries, you can issue the following command:

ant update-libraries

Building the project

To build the project, simply call:

ant clean build

This will build all the modules.

Skipping Unit Tests

Sometimes the project requires special setup for its unit tests to pass (such as a database). You can skip these tests by issuing the following command:

ant clean build -Dskip.tests=1

If you always want to skip tests, you can add the following to the build.properties file:

skip.tests=1

This will skip all tests for the project.

Generating documentation

To generate documentation for the project, call the following:

ant doc

When in doubt ...

If you aren't sure what to call, issue the following:

ant -projecthelp

This will list all the targets of interest.