Internal DOCLIB Development Procedures

 

Last modified:          3/26/2007

Author :                     Tim Meyers

           

 

 

Overview

 

DOCLIB is a C++ toolkit that provides document/image analysis capabilities through a thoroughly documented, easy to use interface. This library seeks to provide a functional, stable, and robust environment that supports a plethora of image types whereby applications (research or production) can be built on top of.


Procedures have been identified and documented to assure that DOCLIB remains functional, stable and robust during development. Use this document to insure the stability of DOCLIB and its add-ons.

 

Subversion Content Management System (SVN)

 

CVS is used in the classified environment to help track different versions of DOCLIB source and header files during development.  This document will outline principle SVN  functions to help facilitate DOCLIB development and version control.  Please do not stray from the SVN environment when doing development to ensure that there is a single version of DOCLIB.



Preparing your development environment

1)      Create a directory for development. 
~/sandbox is popular, although any directory where you want to develop will do. (It is a good idea to keep DOCLIB and its add-ons in their own directory.  If you already use ~/sandbox for other development, ~/sandbox/doclib is recommended )  This directory will be referred to in the future as $DOCLIB.


2)      Check out the Latest Version of Doclib to $DOCLIB
Move into $DOCLIB
$: svn checkout $svnurl/DOCLIB/DOCLIB_<version>/trunk $DOCLIB/doclib


3)      Copy params and make.pl files
$: cp doclib/ReleaseDocs/params.* .
$: cp doclib/ReleaseDocs/make.pl  .


4)      Update params files to reflect development environment
The params file contains instructions on how to update it and what needs to be changed.  Specifically, the $DOCLIB environment variable needs to be set to the DOCLIB development directory chosen above.

5)      Test your development environment – Build DOCLIB
$: source params
$: ./make.pl 0 make

make.pl contains detailed use instructions if you simply run it without parameters.

6)      Check out any add-ons you plan on working on or using.
Obtain a list of current DOCLIB add-ons by using
$: svn list $svnurl/DOCLIB-ADDONS


Then check them out in the same fashion as doclib.  For example,
$: svn checkout $svnurl/DOCLIB-ADDONS/getLines/getLines_<version>/trunk $DOCLIB/getLinesDOCLIB

7)      Build the add-ons you plan on using and/or developing.
$: ./make.pl 0 make

At this point you should be ready for DOCLIB and DOCLIB add-on development.

 

Developing for DOCLIB core library and its Add-Ons

1)      Be sure to source your params file before beginning development

2)      Make all necessary changes (usually with regard to a Bug Ticket, for larger changes, make sure to inform a Primary DOCLIB Developer of what is being done) to DOCLIB source code and header files in your own development environment.

3)      Unit Test your changes to verify that the change works correctly and/or the issue has been sufficiently resolved.

4)      Run the provided DOCLIB regression tests to verify that you have not affected something you did not intend to.
Return to your development environment root directory ($DOCLIB) and rebuild DOCLIB and the Add-Ons with
$: make.pl 0 make

Now run the regression tests
$: cd doclib/script
$: ./runRegressionTest.sh

Each DOCLIB add-on has different testing procedures.  It is a future goal of the DOCLIB team to provide Regression Tests for each released Add-On.  However, at this time, the best you can do is consult the Add-on documentation and run given example code to verify it is still robust.

5)      If you have passed both Unit Testing and Regression Testing, commit your changes to CVS and inform a Primary DOCLIB Developer that changes have been made.
$: cd $DOCLIB
$: svn commit –m “What did you do?” DLRandomFileName.cpp


When the vi screen pops up, verify that it is attached to the files you want to commit.  Enter a detailed description of your changes to the top of the log file.  This is an important step to tracking DOCLIB progress and should not be overlooked.

6)      Other Considerations

i)       If your update was in reference to a Bug Ticket, and you have resolved the issue, please resolve or close the ticket in Mantis Bug Tracker.

ii)     If you are a Primary DOCLIB Developer, and have access to both the Classified and Unclassified Environments, it will likely behoove you to export your changes to the Unclassified Environment.  This will save you time when performing DIFFs during the next DOCLIB Synchronized Release