Index: /trunk/psLib/DEV_NOTES =================================================================== --- /trunk/psLib/DEV_NOTES (revision 3275) +++ /trunk/psLib/DEV_NOTES (revision 3275) @@ -0,0 +1,171 @@ +---- Developing in the autotools environment for non-autotools developers. ---- + + +There are many detailed resources on the web about the autotools (autoconf, +automake, libtools). Being GNU tools, the primary resources are found there +at: + o http://www.gnu.org/software/autoconf/manual/autoconf-2.57/autoconf.html + o http://www.gnu.org/software/automake/manual/automake.html + o http://www.gnu.org/software/libtool/manual.html + +This document will deal with only the basic required tasks for developing in +the autotools environment, namely: + o Creating the configuration environment from CVS check-out, + o Configuring the library, + o Making the library, + o Adding and removing a source code file, and + o Adding and removing a test code file. + + +Creating the configuration environment from CVS check-out +=============================================================================== + +The autotools as a group help you create software distributions which will +build reliably on a large variety of platforms. The minimum required contact +with the autotools is to generate the files which will let you configure a +freshly checked-out directory before working on it, since these configuration +files are not checked in to the repository. The Makefile.cvs makefile will do +this for you, but it can only do this if the autotools are installed (which is +commonly included into every Linux Distrobution as well as Mac OSX). + +The command sequence example for this step is as follows: + > cvs co psLib + > cd psLib + > make -f Makefile.cvs + +Configuring the library +=============================================================================== + +Running the configure script is basically very simple: ./configure. There are, +however, options and arguments which can help you, or catch you out. You can +see the full list of options with the command ./configure --help. + +You set the place where the configured component will be installed with the +--prefix option. This names a directory which will end up with the standard +directories bin, lib and so on. The default is `pwd` currently, but that may +change to something like $HOME in the future. + +The psLib autoconf adds a couple of extra options to ./configure that may be +of interest to a developer. + +--enable-perlmodule + enables the building of the perl module using SWIG. The default is to not + build the perl modules + +--enable-optimize + by default, the build disables compiler optimization for C files to speed up + the compile time. By adding this, '-O2' is added to CFLAGS. + +--enable-static + by default, only a shared, dynamically-linked, library is built. This option + enables the creation of a static library at the cost of doubling the compiling + time. To create only a static library, include the --disable-shared option + as well. + +--with-cfitsio=DIR + specifies the location of the CFITSIO installation prefix, e.g., /usr/local. + To specify the include and/or library directories directly, use the options + --with-cfitsio-include=DIR and --with-cfitsio-lib=DIR respectively. If not + specified, CFITSIO is assumed to have been installed in the standard paths + for the OS, e.g., /usr or /usr/local. + +--with-fftw3=DIR + specifies the location of the FFTW3 installation prefix, e.g., /usr/local. + To specify the include and/or library directories directly, use the options + --with-fftw3-include=DIR and --with-fftw3-lib=DIR respectively. If not + specified, FFTW3 is assumed to have been installed in the standard paths + for the OS, e.g., /usr or /usr/local. + +--with-gsl-config=FILE + specifies the gsl-config script to use to gather the GSL library information. + This is the full path to the gsl-config script included in the package's + installation, e.g., /usr/local/bin/gsl-config. If not specified, $PATH is + used to find the script. + +--with-xml2-config=FILE + specifies the xml2-config script to use to gather the XML2 library + information. This is the full path to the xml2-config script included in + the package's installation, e.g., /usr/local/bin/xml2-config. If not + specified, $PATH is used to find the script. + +--with-swig=FILE + specifies the swig executable to use to generate the SWIG wrapper code. + This is the full path to the swig executable, e.g., /usr/bin/swig. If not + specified, $PATH is used to find the executable. + +--with-perl=FILE + specifies the perl executable to use to generate the SWIG wrapper code. + This is the full path to the perl executable, e.g., /usr/bin/perl. If not + specified, $PATH is used to find the executable. + +--with-perlprefix=DIR + specifies the installation prefix for the perl module. If not + specified, the PREFIX as specified by the --prefix option (or its default) + is used. + + +The command sequence example for this step, using all default settings, is as +follows: + > ./configure + + +Adding and removing a source code file +=============================================================================== + +The library is built from a number of smaller, 'convienence' libraries, one +convienence library for each subdirectory off of src. To add a file to the +pslib library, you need to add it to one of convienence libraries in the +appropriate subdirectory + +To add functionality, you need to add the filenames to the Makefile.am in the +subdirectory in which the file is being added. + o The source filename needs to added to the libpslibSUBDIR_la_SOURCES + variable, where SUBDIR is the subdirectory name. + o Any header files needed to be installed (which is generally going to be + all header files) should be added to the pslibinclude_HEADERS variable. + o Any other file needed to be included in the distribution tarball but are + not to be installed should be included in the EXTRA_DIST variable. + +Upon saving Makefile.am, the existing Makefile will detect the change and +automagically perform any executation of automake/autoconf, so a simple +'make' should fold in these changes for you. + + +Adding and removing a test code file +=============================================================================== + +Tests are added into a subdirectory of the test directory which corresponds to +the functionality location under src being tested. For example, if testing +functionality found in src/astronomy/psFoo.c, you will need to add the +corresponding tests in test/astronomy/tst_psFoo.c. If the test driver code +file does not current exist, use test/tst_template.c as a template on how to +utilize the psLib test facilities. + +To add a test, you need to add the filenames to the Makefile.am in the +subdirectory in which the file is being added. + o The source filename minux the .c suffix needs to added to the + TESTS and variable. This specifies the executable target name. + o Using the name you added to TESTS, create a line of the form + tst_psFoo_SOURCES = tst_psFoo.c + This specifies the source files needed to create the test driver + executable (in the psLib test suite, this is generally just one file). + o Any test data file needs to be added to the check_DATA variable and + a rule needs to be created that will copy the file from the source + directory to the build directory. This is because the directory in + which your data file exists is not necessarily where the test executable + is built. The simpliest way to do this is to place the data file in + a subdirectory like 'verified' and create a rule like: + fBiOut.fits: verified/fBiOut.fits + cp $? $@ + Automake will determine that the target directory of the cp should be + the build directory, so the file will be copied to the same directory + as your executable (so that in the code, you can assume the path is '.') + + +Upon saving Makefile.am, the existing Makefile will detect the change and +automagically perform any executation of automake/autoconf, so a simple +'make' should fold in these changes for you. + +------------------------------------------------------------------------------- +N.B. this file is not to be included in distribution packages. + Index: /trunk/psLib/README =================================================================== --- /trunk/psLib/README (revision 3274) +++ /trunk/psLib/README (revision 3275) @@ -0,0 +1,47 @@ +Pan-STARRS Image Processing Pipeline Library +============================================ + +The is psLib, the Pan-STARRS Image Processing Pipeline Library, a base +collection of functions for the Pan-STARRS PS1 observatory. + +It was developed by the Maui High Performance Computing Center +(http://www.mhpcc.edu) for the University of Hawai'i Institute for Astronomy +(http://ifa.hawaii.edu). + +psLib is free software, you can redistribute it and/or modify it under +the terms of the GNU General Public License. + +The GNU General Public License does not permit this software to be +redistributed in proprietary programs. + +This library is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + +Availability +============ + +The current version of psLib is always available from +http://mhpcc.pan-starrs.org/code. + +Installation +============ + +psLib follows the standard GNU installation procedure. Please consult +the INSTALL file in this distribution for more detailed instructions. + +For information about specific platforms and compilers see the +"Compilation Notes" section in the INSTALL file. + +More information about Pan-STARRS +================================= + +The project homepage is http://www.pan-starrs.org. + +Reporting Bugs +============== + +If you find a bug, please report it via the project's Bugzilla webpage at +http://www.pan-starrs.org/bugzilla or email robert.desonia@mhpcc.hpc.mil. + + Index: /trunk/psLib/test/astronomy/Makefile.am =================================================================== --- /trunk/psLib/test/astronomy/Makefile.am (revision 3274) +++ /trunk/psLib/test/astronomy/Makefile.am (revision 3275) @@ -15,5 +15,5 @@ -check_PROGRAMS = tst_psTime_01 \ +TESTS = tst_psTime_01 \ tst_psTime_02 \ tst_psTime_03 \ @@ -31,4 +31,6 @@ tst_psAstrometry01 +check_PROGRAMS =$(TESTS) + check_DATA = test.config \ psTime.config \ @@ -43,19 +45,4 @@ TESTS_ENVIRONMENT = export PS_CONFIG_FILE="psTime.config" && perl $(top_srcdir)/test/runTest --verified=$(srcdir)/verified -TESTS = tst_psTime_01 \ - tst_psTime_02 \ - tst_psTime_03 \ - tst_psTime_04 \ - tst_psMetadataIO \ - tst_psMetadata_01 \ - tst_psMetadata_02 \ - tst_psMetadata_03 \ - tst_psMetadata_04 \ - tst_psMetadata_05 \ - tst_psMetadata_06 \ - tst_psMetadata_07 \ - tst_psAstrometry \ - tst_psCoord \ - tst_psAstrometry01 tests: $(check_DATA) $(TESTS) Index: /trunk/psLib/test/collections/Makefile.am =================================================================== --- /trunk/psLib/test/collections/Makefile.am (revision 3274) +++ /trunk/psLib/test/collections/Makefile.am (revision 3275) @@ -15,24 +15,4 @@ AM_LDFLAGS = -L$(top_builddir)/src -lpslib $(PSLIB_LIBS) -check_PROGRAMS = \ - tst_psVector \ - tst_psArray \ - tst_psArray01 \ - tst_psArray02 \ - tst_psBitSet \ - tst_psVectorSort_01 \ - tst_psVectorSort_02 \ - tst_psVectorSort_03 \ - tst_psVectorSort_04 \ - tst_psList \ - tst_psHash00 \ - tst_psHash01 \ - tst_psHash02 \ - tst_psHash03 \ - tst_psHash04 \ - tst_psHash05 \ - tst_psScalar - -TESTS_ENVIRONMENT = perl $(top_srcdir)/test/runTest -verified=$(srcdir)/verified TESTS = \ tst_psVector \ @@ -53,4 +33,9 @@ tst_psHash05 \ tst_psScalar + +check_PROGRAMS =$(TESTS) + +TESTS_ENVIRONMENT = perl $(top_srcdir)/test/runTest -verified=$(srcdir)/verified + tests: $(TESTS) Index: /trunk/psLib/test/dataIO/Makefile.am =================================================================== --- /trunk/psLib/test/dataIO/Makefile.am (revision 3274) +++ /trunk/psLib/test/dataIO/Makefile.am (revision 3275) @@ -16,12 +16,11 @@ AM_CFLAGS = -DUTC_DAT_FILE="\"$(top_srcdir)/share/pslib/tai_utc.dat\"" -check_PROGRAMS = \ +TESTS = \ tst_psLookupTable_01 \ tst_psFits +check_PROGRAMS = $(TESTS) + TESTS_ENVIRONMENT = perl $(top_srcdir)/test/runTest -verified=$(srcdir)/verified -TESTS = \ - tst_psLookupTable_01 \ - tst_psFits tests: $(TESTS) Index: /trunk/psLib/test/dataManip/Makefile.am =================================================================== --- /trunk/psLib/test/dataManip/Makefile.am (revision 3274) +++ /trunk/psLib/test/dataManip/Makefile.am (revision 3275) @@ -15,5 +15,5 @@ AM_LDFLAGS = -L$(top_builddir)/src -lpslib $(PSLIB_LIBS) -check_PROGRAMS = \ +TESTS = \ tst_psFunc00 \ tst_psFunc01 \ @@ -57,46 +57,8 @@ tst_psVectorFFT +check_PROGRAMS = $(TESTS) + TESTS_ENVIRONMENT = perl $(top_srcdir)/test/runTest -verified=$(srcdir)/verified -TESTS = \ - tst_psFunc00 \ - tst_psFunc01 \ - tst_psFunc02 \ - tst_psFunc03 \ - tst_psFunc04 \ - tst_psFunc05 \ - tst_psFunc07 \ - tst_psHist00 \ - tst_psHist01 \ - tst_psHist02 \ - tst_psHist03 \ - tst_psMatrix01 \ - tst_psMatrix02 \ - tst_psMatrix03 \ - tst_psMatrix04 \ - tst_psMatrix05 \ - tst_psMatrix06 \ - tst_psMatrix07 \ - tst_psMatrixVectorArithmetic01 \ - tst_psMatrixVectorArithmetic02 \ - tst_psMatrixVectorArithmetic03 \ - tst_psMatrixVectorArithmetic04 \ - tst_psMinimize04 \ - tst_psMinimize04_F32 \ - tst_psMinimize04b \ - tst_psMinimize04b_F32 \ - tst_psMinimize05 \ - tst_psMinimize06 \ - tst_psMinimize07 \ - tst_psStats00 \ - tst_psStats01 \ - tst_psStats02 \ - tst_psStats03 \ - tst_psStats05 \ - tst_psStats06 \ - tst_psStats07 \ - tst_psStats08 \ - tst_psStats09 \ - tst_psRandom \ - tst_psVectorFFT + tests: $(TESTS) Index: /trunk/psLib/test/fileUtils/Makefile.am =================================================================== --- /trunk/psLib/test/fileUtils/Makefile.am (revision 3274) +++ /trunk/psLib/test/fileUtils/Makefile.am (revision 3275) @@ -16,12 +16,11 @@ AM_CFLAGS = -DUTC_DAT_FILE="\"$(top_srcdir)/share/pslib/tai_utc.dat\"" -check_PROGRAMS = \ +TESTS = \ tst_psLookupTable_01 \ tst_psFits +check_PROGRAMS = $(TESTS) + TESTS_ENVIRONMENT = perl $(top_srcdir)/test/runTest -verified=$(srcdir)/verified -TESTS = \ - tst_psLookupTable_01 \ - tst_psFits tests: $(TESTS) Index: /trunk/psLib/test/image/Makefile.am =================================================================== --- /trunk/psLib/test/image/Makefile.am (revision 3274) +++ /trunk/psLib/test/image/Makefile.am (revision 3275) @@ -15,5 +15,5 @@ AM_LDFLAGS = -L$(top_builddir)/src -lpslib $(PSLIB_LIBS) -check_PROGRAMS = \ +TESTS = \ tst_psImage \ tst_psImageFFT \ @@ -29,4 +29,6 @@ tst_psImageInterpolate +check_PROGRAMS =$(TESTS) + check_DATA = \ fBiOut.fits \ @@ -36,17 +38,5 @@ TESTS_ENVIRONMENT = perl $(top_srcdir)/test/runTest -verified=$(srcdir)/verified -TESTS = \ - tst_psImage \ - tst_psImageFFT \ - tst_psImageManip \ - tst_psImageStats00 \ - tst_psImageStats01 \ - tst_psImageStats02 \ - tst_psImageStats03 \ - tst_psImageStats04 \ - tst_psImageExtraction \ - tst_psImageConvolve \ - tst_psImageIO \ - tst_psImageInterpolate + tests: $(TESTS) Index: /trunk/psLib/test/sysUtils/Makefile.am =================================================================== --- /trunk/psLib/test/sysUtils/Makefile.am (revision 3274) +++ /trunk/psLib/test/sysUtils/Makefile.am (revision 3275) @@ -15,5 +15,5 @@ AM_LDFLAGS = -L$(top_builddir)/src -lpslib $(PSLIB_LIBS) -check_PROGRAMS = \ +TESTS = \ tst_psAbort \ tst_psMemory \ @@ -24,13 +24,8 @@ tst_psConfigure +check_PROGRAMS =$(TESTS) + TESTS_ENVIRONMENT = perl $(top_srcdir)/test/runTest -verified=$(srcdir)/verified -TESTS = \ - tst_psAbort \ - tst_psMemory \ - tst_psError \ - tst_psLogMsg \ - tst_psStringCopy \ - tst_psTrace \ - tst_psConfigure + tests: $(TESTS)