Changeset 3584

Timestamp:

Mar 30, 2005, 4:29:34 PM (21 years ago)

Author:

desonia

Message:

updated to current build procedures.

File:

• trunk/psLib/src/mainpage.dox (modified) (7 diffs)

trunk/psLib/src/mainpage.dox

@@ -25 +25 @@
 
 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 <pslib.h> 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 +36 @@
  - 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 +43 @@
  - 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 +71 @@
 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 +79 @@
 
 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 +98 @@
 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:
+<pre>
+$ cd psLib
+$ make -f Makefile.cvs
+</pre>
+<i>This creates the configure script and Makefile templates.</i>
 
-The source should build using the Makefile in the psLib/src directory.  The
-recommended steps are:
+The recommended steps to build the library are:
 <pre>
-$ cd psLib/src
+$ cd psLib
+$ ./configure
 $ make
+$ make check
 $ make install
 </pre>
-<i>This builds and installs files to psLib/lib and psLib/include.</i>
+<i>This builds, tests, and installs the library.</i>
 
-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., <pre>export sladir=/usr/local/star</pre>
-  - xml2config: Location of the xml2-config configuration executable
-      - e.g., <pre>export xml2config=/usr/bin/xml2-config</pre>
+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., <pre>export prefix=/usr/local</pre>
-  - 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:
 <pre>
 $ cd psLib/test
-$ make
-$ make install
-</pre>
-<i>This builds and installs the unit test files to the psLib/testbin directory.</i>
-
-To run the unit test suite, do the following:
-<pre>
-$ cd psLib/testbin
 $ ./FullUnitTest
 </pre>
-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:
 <pre>
-$ ./runTest testfilename
+$ runTest testfilename
 </pre>
-
-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 +149 @@
 documentation embedded in the code using the following commands:
 <pre>
-$ cd psLib/src
+$ cd psLib
 $ make docs
 </pre>
-<i>This places documentation in psLib/docs.</i>
+<i>This places documentation in PREFIX/docs/psLib, where PREFIX is set using
+the configure script.</i>
 
 Also, a prebuilt set of code documentation for both the releases and last