Index: trunk/psLib/src/mainpage.dox =================================================================== --- trunk/psLib/src/mainpage.dox (revision 3040) +++ trunk/psLib/src/mainpage.dox (revision 3041) @@ -7,9 +7,9 @@ psLib. The intended use is to provide a set of basic software functions in 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 - - Isolation of functionality that may be subject to change +the benefits are: + - Reuse of code + - Simplification of testing + - Streamlining of code + - Isolation of functionality that may be subject to change The capabilities provided by psLib are grouped into the following areas which are @@ -21,11 +21,11 @@ - Astronomy -This list is sorted in hierarchical order: The later entries depend on the functions and +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, -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 +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. @@ -34,12 +34,13 @@ @section extinstall Required 3rd Party Libraries -Before building psLib from source, several 3rd party software libraries must -be installed. These include: +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 - Compatibility tested with version is 1.4 - - Fastest Fourier Transform in the West (FFTW), version 3 + - Fastest Fourier Transform in the West (FFTW), version 3, with single-precison float support - Available at http://www.fftw.org - Compatibility tested with version is 3.0.1 + - The '--enable-float' option is required in the configure step to enable single-precision float support. Use 'configure --help' for more information of the configuration options for this library. - C Flexible Image Transport System Input output (CFITSIO), version 2.480 or later - Available at http://heasarc.gsfc.nasa.gov/docs/software/fitsio @@ -50,18 +51,18 @@ - 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 + - 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. - - Available at http://star-www.rl.ac.uk/ - - Compatibility tested with package version number 2.4-12 - Gnome XML C parser and toolkit (libxml2) - Available at http://www.xmlsoft.org - Compatibility tested with version 2-2.6.16-3 -We recommend using the particular versions listed as compatibility tested, as -that is the only versions of the external libraries tested to work well with psLib. -Though it is quite possible that later versions of the libraries listed will also +We recommend using the particular versions listed as compatibility tested, as +that is the only versions of the external libraries tested to work well with psLib. +Though it is quite possible that later versions of the libraries listed will also work as well, care must be taken when upgrading these libraries to verify that its functionality is compatible with the tested version. @@ -79,11 +80,11 @@ https://mhpcc.pan-starrs.org/code/snapshots -These snapshots represents development code as found in CVS on the day +These snapshots represents development code as found in CVS on the day specified in the filename. This code set may not be functional, vary in -testing, etc. Reasonable efforts are made to ensure that the code does -actually compile, but given the nature of code development, even that is not +testing, etc. Reasonable efforts are made to ensure that the code does +actually compile, but given the nature of code development, even that is not always the case. Use snapshots with great caution. -If one has a login account on mhpcc.pan-starrs.org, direct CVS access is +If one has a login account on mhpcc.pan-starrs.org, direct CVS access is possible. Example of the commands required for direct CVS retrieval are as follows: @@ -93,8 +94,9 @@ where: - USERNAME is your login name on the server - - RELEASEBRANCH is the desired release branch, e.g. rel1, rel2, etc. - + - RELEASEBRANCH is the desired release branch, e.g. rel1, rel2, rel3, or rel4. + @section build How to Build the psLib library + The source should build using the Makefile in the psLib/src directory. The @@ -107,8 +109,28 @@ This builds and installs files to psLib/lib and psLib/include. +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
+ +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 +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 suite, do the following: @@ -141,5 +163,5 @@ @section doc How to Create Code Documentation -Both HTML and man page documentation may be generated from the inline +Both HTML and man page documentation may be generated from the inline documentation embedded in the code using the following commands: 
@@ -149,5 +171,5 @@
 This places documentation in psLib/docs.
 
-Also, a prebuilt set of code documentation for both the releases and last 
+Also, a prebuilt set of code documentation for both the releases and last
 CVS snapshot can be found at: