Build Standards

This page was migrated from a javaranch.com.jsp


     
     
     JavaRanch Project Standards
     
   
 

 
 
 

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.

   
       targetrequired?possible description to be used in the target tagnotes
   

   
       buildrequiredincremental buildDefault target.  Compile production classes and build production artifacts such as jar/war/ear files.
   

   
       cleanrequireddelete the build dir
   

   
       dboptionalbuild a fresh databaseTarget exists only if there is a database for the project.  All tables are dropped and fresh tables are created.
   

   
       ffbuildrequiredforce full buildAlways depends on clean and build. Might also depend on "db" and some code generation targets.
   

   
       testrequiredcompile and run unit testsDoes not depend on build.
   

   
       vbuildrequiredverified build: compile classes, run unit tests, then finish the incremental buildCode quality can be verified before any jar/war/ear step.
   

   
       ffvbuildrequiredforce full verified build:  clean, compile classes, run unit tests, then finish the ffbuild 
   

   
       fntestoptionalcompile and run functional testsdoes not depend on test or build
   

   
       deployoptionala local deploy - to the same boxusually just a convenience for development
   








Standard Directory Structure


   projectname         /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:





         <property file="${user.home}/${project.name}.properties"/>      <property file="${user.home}/build.properties"/>      <property name="config.filename" value="${user.name}.properties"/>      <property file="config/${config.filename}"/>    
   (the ability to override "config.filename" in the home directory helps to prevent name collisions)






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:





         <property name="prop.message" value="must be defined, preferably in config/${config.filename}                                           (details at javaranch.com/props)"/>      <fail message="db.schema ${prop.message}" unless="db.schema"/>      <fail message="db.password ${prop.message}" unless="db.password"/>    





5)  Have as few properties outside of build.xml as possible!  (yes!  This is the same as 1!)

Database Standards

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.

 



Test Standards

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.