What is Craftsman?

The inevitable question is, "What exactly is Craftsman?" Along with that question comes several followup questions, like "Is Craftsman X or like Y?" Below we try to answer these questions and more.

Craftsman is a build system.

Craftsman is a "build system", not a "build tool". But what's the difference?

Ant is a build tool. Make is a build tool. A very complicated shell or perl script would be a kind of a build tool (albeit one that is very hard to maintain). A build system would be Maven or something like the GNU toolchain. Build systems impose generic layouts or patterns on how a project or module can be laid out. So you adhere to the generic layout (which may or may not be flexible), but you gain the ability to not have to manage many details or functions common to building software projects or modules.

For example, with a build tool, you can create a package for your application, but it is up to you to write the code, script, or macro in your tool to make the packaging happen. In a build system, you just call the appropriate target or use the correct command and the packaging happens automatically--you do not have to write any code, scripts, or macros to make it happen.

So Craftsman is much like Maven or the GNU toolchain's automake. It requires you adhere to its standard directory structure in order for it to be able to work with your project's source and build artifacts. But just like other build systems, it comes with a ton of "freebies" that makes adhering to this standard well worth your time.

Craftsman provides standard build life-cycle tasks for free.

A typical Java module using Craftsman has the following tasks done automatically for it when it is built:

• Any libraries defined in the module are located, retrieved (if not already present), and then registered in the Ant memory space for later reference.
• Any module dependencies are resolved, and if the module is not already built, it's build system is called.
• Any generated sources are created.
• The source is compiled, using the generated sources, libraries, and dependencies to resolve classpath dependencies.
• Any resources in the source directory are copied to the build artifacts destination directory (so if your module has a resource file or image in its source directory, these will make it into the final jar).
• The test source is compiled. Any test resources are copied to the test build artifact directory.
• The unit tests are executed and a report is produced. If the unit tests fail, the build is halted (default behavior--this can be overrode).
• The source is then verified using Checkstyle (can be skipped).
• The final build results are packaged into two jars: modulename-version.jar and modulename-test-version.jar.

As you can see, its a full and complete build life-cycle. And you get all that with the following lines in your build.xml:

<craftsmandef>
    <module moduleid="craftsman">
        <dependency moduleid="some-other-module" dir="../some-other-module"/>
        <library name="some-module-lib"/>
        <library name="junit" externaldir="../lib/junit" testlib="true"/>
    </module>
</craftsmandef>

Everything is created automatically for you based on the module definitions you create.

Craftsman is completely Ant based.

Unlike other build systems, Craftsman is not meant to replace Ant. On the contrary, most of what makes Craftsman work is Ant itself. Craftsman also leverages many plugins and extensions to Ant to provide services (such as Xdoclet's Ant tasks for EJB generation). Craftsman makes use of custom Ant tasks and generated build scripts to make a build cycle that performs the same from project to project.

There is nothing wrong with Ant. But because Ant is a build tool, and not a build system, you often find yourself doing all the work to get what you had on your last project. If you are sharp/lazy, you copy your the build files from your other project to save time--but you still have a lot of cut and past work to perform and a lot of maintenance ahead of you (especially if you try to maintain both the previous project and the current one).

Craftsman came out this usage pattern; that is, that Ant is great and flexible, but most of the time you don't need all that flexibility and some times you would just kill for an easier way to do it.

Craftsman is also Ant based because most Java developers know Ant--either in passing or intimately from trying to make their own build files. Since you can't forsee everything (well, not at first), Craftsman is built on Ant so that those who find something missing can either build Craftsman plugins or just hack together some targets in the build file and hook it into the existing Craftsman build cycle.

Craftsman Provides Many Standard Tools and Extensions Through One Interface

There are many tools available to today's developer, and all are aimed at making the developer's life easier. Many of the tools are built to do just one task, and one task well. This is an excellent goal, but many development tasks require many of the available tools, and sometimes in elaborate chains.

Craftsman provides many of the tools used by Java developers today in a standard way. So if you want to bundle your application in jars, use Xdoclet to generate code, and create API documentation, you can do it all via the Craftsman <craftsmandef> entries. Below is just a sample of some of the tools Craftsman integrates with:

• Javadoc for API generation.
• JUnit for unit testing and unit test reporting.
• Checkstyle for source verification.
• Xdoclet for EJB class and code generation.
• JWSDP for Java Web Service clients and server components.
• JSPWiki for manual, site, and general documentation (this page was made with this feature).

In addition to integrating with these tools, Craftsman also provides additional services to "fill in the gaps" left by integrating many disparate tools. Below are just some of the features Craftsman provides:

• Generating "bundles" to contain your finished jars and their corresponding documentation.
• Automatically generating Class-Path entries for the jars of Java applications and J2EE EJBs
• Generating application.xml files for J2EE Applications dynamically, based on what EJB and WAR modules are included at build time.
• Automatically generating Unit Test Reports in html and providing the link to the developer.
• Automatic library retrieval, removing the need to check in jars and zips into source control.
• And much, much more ;-)

And because Craftsman is Ant-based, you can add additional tool integration and capabilities all with standard Ant tasks.