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