There are many ways to do things well. And there are at least as many ways to do the same things poorly.
When many developers come together to do one project, there can be long debates on which approach
is "best" or "right". These discussions can, in the long run, take hundreds of man hours to resolve. For larger
organizations, multiple projects will need to integrate - different ideas of "best" can lead to more debate and
serious integration issues.
This document is a feeble attempt to outline one approach to project build issues. Some goals of this document include:
reduce debate time within teams and between teams
provide vocabulary between developers and between teams
smooth integration between components developed by different teams
improve ramp time for new developers and developers that might be shifting between teams/projects
ease the integration of multiple projects into a continuous integration environment
Standard Ant Targets
Provide description attributes for all targets that are intended to be exercised directly by the developer. This makes only
those targets viewable under "ant -p". Many IDE's will take advantage of this also. Do not provide a description for
targets that are not to be exercised directly by the developer.
|target||required?||possible description to be used in the target tag||notes
|build||required||incremental build||Default target. Compile production classes and build production artifacts such as jar/war/ear files.
|clean||required||delete the build dir||
|db||optional||build a fresh database||Target exists only if there is a database for the project. All tables are dropped and fresh tables are created.
|ffbuild||required||force full build||Always depends on clean and build. Might also depend on "db" and some code generation targets.
|test||required||compile and run unit tests||Does not depend on build.
|vbuild||required||verified build: compile classes, run unit tests, then finish the incremental build||Code quality can be verified before any jar/war/ear step.
|ffvbuild||required||force full verified build: clean, compile classes, run unit tests, then finish the ffbuild||
|fntest||optional||compile and run functional tests||does not depend on test or build
|deploy||optional||a local deploy - to the same box||usually just a convenience for development
Standard Directory Structure
/src // production source
/java // java source. First directory in here is "com"
/db // database DDL (or .sql) files.
/web // html, jsp, image and any other files for a web site
/docs // non-web user documentation for this project
/test // test source
/unit // every class in this directory that starts with
// "Test" is run as a unit test
/functional // every class in this directory that starts with
// "Test" is run as a functional test
/nonregression // run stuff here manually during development
/lib // jar files and the like that the project uses
/production // stuff that will need to be copied into production
/development // stuff that is used only during development
// and should not find its way to production
/build // this dir does not go in version control.
// frequently deleted and re-created by ant
/gen-src // if your app generates any source, it goes in here
// (generated source never goes in VC!)
/classes // compiled production classes
/test-classes // compiled unit test code, functional test code,
// non-regression test code, mocks, shunts, etc.
/dist // the final artifacts destined for production.
// Usually a war file, ear file or jar file.
/config // developer build properties
build.xml // ant build file
readme.txt // notes between developers about this project
Standard Property Management
1) Have as few properties outside of build.xml as possible!
2) Properties are gathered with the following ant tasks:
3) Put all properties in the config directory unless there is a powerfully compelling reason to put them in the home directory.
4) Use "fail unless" tasks for all properties that need to be defined outside of build.xml:
5) Have as few properties outside of build.xml as possible! (yes! This is the same as 1!)
1) Each developer has a database instance on their own development system.
2) For each table and view in the database, there is one .sql file in the src/db directory for creating that table or view.
3) The ant target "db" will drop all tables and views from the database and recreate a fresh instance of the database.
1) "ant vbuild" must successfully run from the command line before checkin.
2) If cruise control is not yet running for the project, "ant ffvbuild fntest" must successfully run from the command line before checkin.