Index: /branches/rel1/psLib/src/mainpage.dox =================================================================== --- /branches/rel1/psLib/src/mainpage.dox (revision 1043) +++ /branches/rel1/psLib/src/mainpage.dox (revision 1044) @@ -1,75 +1,125 @@ -/** @mainpage psLib Image Processing Library +/** @mainpage psLib Image Processing Library - Release 1 @section intro Introduction -This library contains the Pan-STARRS Image Processing Pipeline (IPP) toolkit, -psLib. The intended use is to provide a library of basic software functions which -can be used throughout the Pan-STARRS project to simplify programming tasks. Among -the benefits are: reuse of code, simplification of testing, streamlining of code, -and isolation of functionality that may be subject to change. +This library contains the Pan-STARRS Library, "psLib". The intended use is to +provide a set of basic software functions which can be used throughout the +Pan-STARRS project to simplify programming tasks. Among the benefits are: + -The capabilities provided by psLib are grouped into the following areas which are -also reflected in the file system directory structure: - - System Utilities - - Data Collections - - Data Manipulation +The capabilities provided by psLib are grouped into the following areas which +are also reflected in the source files' directory structure: + -This list is sorted in hierarchical order: The later entries depend on the functions and -data types of the earlier entries. +This list is sorted in hierarchical order: The later entries depend on the +functions and data types of the earlier entries. -The installed code for psLib consists of header files and binary libraries in the form of static -(libpslib.a) and shared (libpslib.so or libpslib.dylib for OX/X.) Assuming these components -have been built and installed in the standard library path, psLib may be used within a program by -including the line #include and linking with -lpslib. - +The installed code for psLib consists of header files and binary libraries +in the form of static (libpslib.a) and shared (libpslib.so or libpslib.dylib +depending on the operating system). Assuming these components have been built +and installed in the standard library path, psLib may be used within a program +by including the pslib.h header in your C file and linking with -lpslib. @section extinstall Required 3rd Party Libraries -Before building psLib from source, several 3rd party software libraries must be installed. -These include: - - GNU Scientific Library (GSL), Available at http://www.gnu.org/software/gsl - - Fastest Fourier Transform in the West (FFTW), Available at http://www.fftw.org - - C Flexible Image Transport System Input output (CFITSIO), Available at http://heasarc.gsfc.nasa.gov/docs/software/fitsio +Before building psLib from source, several 3rd party software libraries must +be installed. These include: + -If you use a Darwin (Mac OS X) system, a dlfcn compatability library needs to be -installed on the system. This can be obtained from the Fink project on SourceForge -(the dlcompat package at http://www.sf.net/projects/fink). The Darwin 7.0 (OS X 10.3) -'devtools' package seems to also include dlfcn support, so explicit installation of a -dlfcn compatibility layer may not be required for this version of Darwin. +If you use a Macintosh OS X 10.2 or earlier system, a dlfcn compatability +library may need to be installed on the system. This can be obtained from the +Fink project on SourceForge (the dlcompat package at http://www.sf.net/projects/fink). +The Darwin 7.0 (OS X 10.3) 'devtools' package includes dlfcn support, so +explicit installation of a dlfcn compatibility layer may not be required for +this version of Darwin with the devtools package installed. -@section install How to Build from Source +@section obtain How to Obtain the Code -The psLib code should to be downloaded from either the tar file posted on: -https://gforge.mhpcc.hawaii.edu/projects/panstarrs/ or directly from the CVS server -with the following command: +The psLib code should to be downloaded from either the tar files posted the +MHPCC webserver or CVS. + + +https://mhpcc.pan-starrs.org/cgi-bin/viewcvs.cgi/releases/rel1 or CVS. + +Via the web server, point your browser to https://mhpcc.pan-starrs.org/cgi-bin/viewcvs.cgi/releases/rel1. +There are two files available there: + + +Download the appropriate package for your needs and untar the files where +one sees fit. + +To obtain the source directly from the CVS server with the following command: 
-$ cvs -d:ext:username@gforge.mhpcc.hawaii.edu:data/panstarrs/cvsroot co -P psLib
+$ export CVS_RSH=ssh
+$ cvs -d:ext:username@mhpcc.pan-starrs.org:/data/panstarrs/cvsroot export -r rel1_1 psLib
+This requires having an SSH login account on mhpcc.pan-starrs.org. - -The source should build from the Makefile in the psLib/src directory. The -recommended steps are: + +@section build How to Build from Source Code + +Once the release package is obtained, the library should build from the +Makefile in the psLib/src directory. The recommended steps are: 
+$ cd psLib/src
 $ make
 $ make install
-This builds and installs files to psLib/lib and psLib/include. +This builds the library and installs files to psLib/lib and psLib/include. -@section run How to Run Tests +@section buildTests How to Build the Tests -Since psLib is a library, there is no executable, per se. However, to test the installation, users -may execute the FullUnitTest script: +Since psLib is a library, there is no executable, per se. However, to test +the installation and functionality, users may create a suite of unit tests +with the following steps: 
 $ cd psLib/test
 $ make
 $ make install
-$ FullUnitTest
+$ make installtests
-This builds and executes test files for each of the psLib functional areas. +This builds and installs test files for each of the psLib functional areas +into the psLib/bin/test directory. + +@section runTests How to Run the Unit Tests + +To execute the unit test suite, after building them, users may use the +following steps: +
+$ cd psLib/bin/test
+$ ./FullUnitTest
+
+One can also run individual test executables, which concentrate on a logical +set of functionality of the library, via the 'runTest' script in the bin/test +directory or by executing the test from the shell. If running the test directly +in the shell, make sure that the LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH if on the +Macintosh) contains the path to the psLib/lib directory. @section doc How to Create Documentation @@ -80,5 +130,5 @@ $ make docs -This places documentation in psLib/docs. +This places the Doxygen generated documentation in psLib/docs. */