Index: /trunk/psLib/src/mainpage.dox =================================================================== --- /trunk/psLib/src/mainpage.dox (revision 3583) +++ /trunk/psLib/src/mainpage.dox (revision 3584) @@ -25,12 +25,10 @@ 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 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 line #include and linking using the '-lpslib' option -while linking. +the form of static and/or shared library, depending on the configuration options. +To assist in using the library, a script "pslib-config" is supplied that +provides the compiler and linker options. -@section extinstall Required 3rd Party Libraries +@section extinstall 3rd Party Libraries Before building psLib from source, several 3rd party software libraries must @@ -38,5 +36,5 @@ - GNU Scientific Library (GSL) - Available at http://www.gnu.org/software/gsl - - Compatibility tested with version is 1.4 + - Compatibility tested with version 1.4 - Fastest Fourier Transform in the West (FFTW), version 3, with single-precison float support - Available at http://www.fftw.org @@ -45,20 +43,25 @@ - C Flexible Image Transport System Input output (CFITSIO), version 2.480 or later - Available at http://heasarc.gsfc.nasa.gov/docs/software/fitsio - - Compatibility tested with version is 2.490 - - Versions earlier than 2.480 will not work as new functionality introduced in 2.480 is exercised - - Doxygen Documentation System - - Available at http://www.doxygen.org - - Compatibility tested with version 1.3.6 - - The optional companion package, GraphViz (a.k.a., the 'dot' command), is recommended to enable header-file dependency diagrams - - SLALIB - - Available at http://star-www.rl.ac.uk/ - - Compatibility tested with package version number 2.4-12 - - We tested with the Fortran version of the library; this may cause an additional step to get things to link on untested systems/compilers, as there is no one standard for how the function-names appear in the library to C code. The default way that psLib uses is all-lower case with a trailing '_', but one may need to add to CFLAGS in src/Makefile.Globals the following: - - '-DFORTRAN_UNDERSCORE_PREFIX' if a '_' needs to be prefixed to the function names, - - '-DFORTRAN_DOUBLE_UNDERSCORE_SUFFIX' if two the names needs two trailing '_'s., and/or - - '-DFORTRAN_UPPERCASE' if the names appear as uppercase. + - Compatibility tested with version 2.490, requires at least 2.480 - Gnome XML C parser and toolkit (libxml2) - Available at http://www.xmlsoft.org - - Compatibility tested with version 2-2.6.16-3 + - Compatibility tested with version 2.6.12 and 2.6.16 + +Though not required to build the base library, several 3rd party software +libraries are needed for particular functionality. + - Doxygen Documentation System + - Required for creation of documentation + - Available at http://www.doxygen.org + - Compatibility tested with version 1.3.2 and 1.3.8 + - The optional companion package, GraphViz (a.k.a., the 'dot' command), is recommended to enable header-file dependency diagrams + - MySQL + - Required for database functionality + - Available at http://dev.mysql.com + - Compatibility tested with version 4.1.10a, requires at least 4.1.2 + - A server running locally is required for testing. + - Autoconf/Automake + - Required only if making from CVS + - Available at http://www.gnu.org/software/autoconf and http://www.gnu.org/software/automake + - Compatibility tested with version 2.59 (autoconf) and 1.9.2 (automake) We recommend using the particular versions listed as compatibility tested, as @@ -68,5 +71,6 @@ functionality is compatible with the tested version. -@section install How to Build from Source + +@section obtain How to Obtain the Source Tested versions of psLib are put into a tar file and can be downloaded from: @@ -75,6 +79,6 @@ Though MHPCC recommends using the released packaged tar files descibed above, -both daily development snapshots and direct CVS access is available. The daily -snapshots are available at +both recent daily development snapshots and direct CVS access is available. +The recent daily snapshots are available at: https://mhpcc.pan-starrs.org/code/snapshots @@ -94,69 +98,48 @@ where: - USERNAME is your login name on the server - - RELEASEBRANCH is the desired release branch, e.g. rel1, rel2, rel3, or rel4. + - RELEASEBRANCH is the desired release branch, e.g. rel5. -@section build How to Build the psLib library +@section build How to Build and Test the psLib library +The source uses autoconf/automake to build control the build process. If, and +only if, the source came from CVS or a CVS snapshot, the configuration script +will have to be made via: +
+$ cd psLib
+$ make -f Makefile.cvs
+
+This creates the configure script and Makefile templates. -The source should build using the Makefile in the psLib/src directory. The -recommended steps are: +The recommended steps to build the library are: 
-$ cd psLib/src
+$ cd psLib
+$ ./configure
 $ make
+$ make check
 $ make install
-This builds and installs files to psLib/lib and psLib/include. +This builds, tests, and installs the library. -The make system of psLib allows users to specify specific locations for some of the -third party libraries (see "Required 3rd Party Libraries" for a list). If -a location is not specified, the cooresponding library is assumed to be in -the standard library paths, e.g., /usr or /usr/local. The following are the -environment variables that can be set before the make process above to force -the location of the third-party libraries: - - sladir: Location of SLALIB - - e.g., 
export sladir=/usr/local/star
- - xml2config: Location of the xml2-config configuration executable - - e.g., 
export xml2config=/usr/bin/xml2-config
+The configure step allows users to specify specific locations for the third +party libraries (see "3rd Party Libraries" for a list), disabling of select +functionality (e.g., database and perl module), installation location, etc. +An enumeration of the options for configure, and the default values, can be +obtained via "./configure --help". -Also, the installation location of the library can be set using environment -variables. The following are the supported variables for installation: - - prefix: the installation prefix (default: current psLib directory) - - e.g., 
export prefix=/usr/local
- - mandir: The man page installation location (default: $prefix/man) - - includedir: The installation location for the header files (default: $prefix/include) - - testbindir: Location for the test executables (default: $prefix/testbin) - - libexecdir: Location for the library files (default: $prefix/lib) - - TIME_CONFIG_FILE: Location of the 'psTime.config' configuration file (default: $(prefix)/config/psTime.config) - -@section run How to Build and Run Tests - -Since psLib is a library, there is no executable, per se. However, to test the -installation, users may execute the unit test suite. To build the unit test +Though 'make check' compiles and runs the test suite, one can also use custom +scripts to run all the tests and just a particular test. To run the unit test suite, do the following: 
 $ cd psLib/test
-$ make
-$ make install
-
-This builds and installs the unit test files to the psLib/testbin directory. - -To run the unit test suite, do the following: -
-$ cd psLib/testbin
 $ ./FullUnitTest
-or to run a particular test + +This has the advantage over 'make check' in that it does not stop when a test +fails and it collects some very basic statistics on the results. To run a +particular test, do the following: 
-$ ./runTest testfilename
+$ runTest testfilename
- -Note: one can also fun the FullUnitTest from anywhere within psLib/test -without performing the above 'make installtests' command first. To do this, -one needs to first set the PSLIB_ROOT environment variable to the top psLib -directory 'psLib'. FullUnitTest will search for tests in the subdirectories -the the execution directory, perform a build of them (via 'make'), and run them. -This can be useful if one wants to tweak the test code and doesn't desire to -perform an install of all the tests each time the test file is touched. @@ -166,8 +149,9 @@ documentation embedded in the code using the following commands: 
-$ cd psLib/src
+$ cd psLib
 $ make docs
-This places documentation in psLib/docs. +This places documentation in PREFIX/docs/psLib, where PREFIX is set using +the configure script. Also, a prebuilt set of code documentation for both the releases and last