An Axiomatic Approach To Project Builds

An Axiomatic Approach To Project Environment and Buildfiles

Abstract: How can we be sure that the development environment for our Java project has been set up correctly? While there are many ways how to combine the capabilities of Eclipse, Ant, Maven, Tomcat etc., there are some general principles or axioms that a good environment should satisfy. So far we have had projects, which satisfy all of them. Since all technologies involve compromises, there are some cases, where there is a tradeoff between these requirements on the one hand, and simplicity and common sense on the other.

Requirement 1: "Modularity"

Development consists of several clearly separated "modules" (like portalCore, portalTest, etc.). Each module is a directory tree with a predictable structure and a configurable set of possible build targets. Each module goes through its own development lifecycle, can be separately tested, versioned and released.

Requirement 2: "Versioning" Versioning (with Subversion or Mercurial) should allow reverting to a certain revision number (and also - to a specific "named release"). All dependencies and external JAR files, which were used for that build should also follow. Therefore each module should always know, on which other modules (and external JARs) it is dependent.

Requirement 3: "Tomcat-friendliness" The build process should support instant redeployment of WAR modules, which is achieved by Tomcat (or Jetty)- friendly layout. No redeployment to the Web server, if the only thing we change is some template or some other static file in that module.

Requirement 4: "Testing should be easy" Running the automated tests for each module should be simple - a single DOS command or Eclipse-IDE event should run the component tests, or the system tests, or both. The result (tests pass or fail) should be easily visible before committing code.

Requirement 5: "One module->one artifact" Each module generates exactly one main artifact (e.g. JAR, WAR, SAR, EAR, ZIP). (Extra generated stuff like Javadoc doesn't count.) If we find that one module needs to generate several artifacts (e.g. a JAR + a WAR), we either find a way to combine the two into a one, or rather split the module into two dependent modules in order to reduce the chance of someone using incompatible pair of the two related artifacts.

Requirement 6: "Explicit publishing" Projects that develop artefacts should be decoupled from the projects that consume those artefacts and it should require an explicit publishing step to release a copy. The default should be that consumer projects build against the stable released version of the artefacts and don't rerun the artefact build from the producer projects.

Requirement 7: "Creating new modules is easy" It should be easy and mostly fail-proof to create a new module, e.g. a new WAR-portal with its own independent structure and configurable build system. For this purpose, Eclipse classpaths should be easy to keep in sync with the dependencies in the build file. (Editing build.properties or similar small file is OK, when we create a new module, but we do not want Copy+Paste+Change_a_Little for the build scripts or do many manual Eclipse IDE adjustments, since this is error prone and difficult to maintain.)

Requirement 8: "Consistent procedure for each target" The same build target is always performed by all developers in the same way to ensure consistency. (Nevetheless, it could be OK for some targets to use Ant, for some other ones - Maven, if these targets are not too tightly connected.)

Requirement 9: "Offline availability of build process" Build process may occasionally involve downloading external resources (e.g. JARs) over the Internet, but it should be such that:

1. build results do not depend on availability of some specific HP-related or remote host (e.g. some file repository)
2. builds should normally work also for an offline computer, e.g. a laptop. External JARs (and, possibly, DTD/Schema files, if we perform validation) are always available also on developers' machines, so that we do not rely on an Internet copy for the build to work.

Analyzing such and similar requirements could help to identify appropriate technical solutions - e.g.

• decide, what is the easiest directory layout in the version control?
• do we place the created JARs and similar artifacts in some repository or file-system, or do we copy them to the appropriate client-modules, when there is a new release?
• do we use Ant's or Maven's commands for a certain build target?
• how do we reuse static Web files (HTMLs, templates, scripts?) among projects?