Index: /trunk/doc/manual/manual.tex
===================================================================
--- /trunk/doc/manual/manual.tex	(revision 13909)
+++ /trunk/doc/manual/manual.tex	(revision 13910)
@@ -1,8 +1,8 @@
- %%% $Id: manual.tex,v 1.9 2007-06-19 21:38:53 eugene Exp $
+ %%% $Id: manual.tex,v 1.10 2007-06-20 03:24:44 eugene Exp $
 \documentclass[panstarrs,psreport,spec]{panstarrs}
 
 % basic document variables
 \title{Pan-STARRS Image Processing Pipeline}
-\subtitle{User Guide}
+\subtitle{User's Guide}
 \shorttitle{PS IPP UG}
 \author{Eugene A. Magnier, Paul A. Price, Joshua Hoblitt}
@@ -132,9 +132,15 @@
 The operating goals of the IPP can be broken down into several major categories:
 \begin{itemize}
-\item reduction, analysis, and calibration of individual astronomical science images.
-\item combinations (additions and subtractions) of groups of science image, along with their analysis and calibration.
-\item analysis of the ensemble properties of astronomical objects detected from many images, including improved astrometric and photometric calibrations.
-\item construction of the necessary master detrend images and other calibration information needed to perform the science analysis.
-\item enabling further investigation into the data characteristics by tracking sufficient metadata and providing tools for this analysis.
+\item reduction, analysis, and calibration of individual astronomical
+  science images.
+\item combinations (additions and subtractions) of groups of science
+image, along with their analysis and calibration.
+\item analysis of the ensemble properties of astronomical objects
+detected from many images, including improved astrometric and
+photometric calibrations.
+\item construction of the necessary master detrend images and other
+calibration information needed to perform the science analysis.
+\item enabling further investigation into the data characteristics by
+tracking sufficient metadata and providing tools for this analysis.
 \end{itemize}
 Furthermore, the IPP is designed to perform these tasks with a high
@@ -142,20 +148,27 @@
 instruments.
 
-A cartoon of the user's view on the IPP is seen in Figure~\ref{}.
-Images are injected into the IPP, either automatically by software
-interacting with the telescope systems or manually by the user.  The
-images are processed by the IPP through any number of analysis steps;
-the specifics of the analysis will depend on the type of image, the
-overall configuration, and additional requests the user may make.  The
-user may use the program \code{pantasks} to control and monitor the
-ongoing processing, or view summary result information in the
-ippMonitor web browser.  As science images are processed, the
-information about the objects detected in these images is passed to
-the DVO database.  The user may explore the results or perform further
-science analysis by interacting with the DVO database via the DVO
-Shell.  From this tool, the user may, for example, create
-color-magnitude diagrams of regions in the sky, or plot light curves
-of specific objects.  The DVO Shell makes it possible to performing
-data extraction and data visualization on the DVO database.
+\begin{figure}
+\psfig{file=userview.ps,width=6in,angle=0}
+\caption{User's view of the IPP}
+\label{fig:ipp-userview}
+\end{figure}
+
+A cartoon of the user's view on the IPP is seen in
+Figure~\ref{fig:ipp-userview}.  Images are injected into the IPP,
+either automatically by software interacting with the telescope
+systems or manually by the user.  The images are processed by the IPP
+through any number of analysis steps; the specifics of the analysis
+will depend on the type of image, the overall configuration, and
+additional requests the user may make.  The user may use the program
+\code{pantasks} to control and monitor the ongoing processing, or view
+summary result information in the ippMonitor web browser.  As science
+images are processed, the information about the objects detected in
+these images is passed to the DVO database.  The user may explore the
+results or perform further science analysis by interacting with the
+DVO database via the DVO Shell.  From this tool, the user may, for
+example, create color-magnitude diagrams of regions in the sky, or
+plot light curves of specific objects.  The DVO Shell makes it
+possible to performing data extraction and data visualization on the
+DVO database.
 
 Below, we discuss in more detail how a user would use the IPP in
@@ -199,7 +212,15 @@
 
 In this section, we introduce the user to the IPP user interface
-tools.
+tools.  These are the elements of the IPP which provide feedback to
+the user or allow the user to initiate a new type of analysis or to
+start and stop the automatic processing of the IPP.
 
 \subsubsection{ippMonitor}
+
+\begin{figure}
+\psfig{file=ippMonitor.eps,width=6in,angle=0}
+\caption{Example Screen Shot from the ippMonitor}
+\label{fig:ippMonitor}
+\end{figure}
 
 The \code{ippMonitor} is a web-based tool that allows the end-user to
@@ -234,10 +255,19 @@
 many cases if the command is typed without arguments.
 
-\begin{verbatim}
-catdir demo
+\begin{figure}
+\psfig{file=skycells.ps,width=4in,angle=0}
+\psfig{file=tau-region.ps,width=2in,angle=0}
+\caption{Example Plots from DVO}
+\label{fig:dvo-sample}
+\end{figure}
+
+\begin{verbatim}
+catdir skycells
 region -n view1 0 0 80 ait
 images
 
-region -n view2 10 40 2
+catdir taurus-project
+region -n view2 64.8 26.1 4.0
+images
 avextract ra,dec where (g - i > 2.0)
 cplot ra dec -c red
@@ -252,5 +282,5 @@
 \code{ait} (aitoff projection), \code{sin} (sin projection), ....  
 
-\subsubsection{pantasks}
+\subsubsection{Pantasks}
 
 Pantasks is the program which schedules the analysis to be performed
@@ -312,4 +342,7 @@
 \end{itemize}
 
+The collection of programs which are used to initiate different stages
+of the IPP analysis is called \code{ippTools}.  This suite of programs 
+
 \subsection{Operational Scenarios}
 
@@ -401,13 +434,15 @@
 of this fact by setting the FRINGE.FILTERS entry in the
 \code{ppImage.config} file.  Use a set of night-time sky images to
-generate a fringe frame. \note{how to specify more than one fringe
-  mode?}
+generate a fringe frame. \tbd{How to specify more than one fringe
+mode?}
 
 Activate the chip-level science analysis tasks in pantasks: chip.on.
 With this off, no data will be processed before the detrend images are
 ready.  Once this is turned on, the science images will start to be
-processed \note{discuss blocks; re-queue; versions}.
-
-\note{specifying the dvo output database}
+processed.
+
+\tbd{Discuss blocks, re-queuing science images, analysis versions}.
+
+\tbd{Illustrate how to specify the DVO output database}
 
 \subsubsection{Pipeline Reduction : PI-Oriented Observatory}
@@ -436,5 +471,5 @@
 so than in a single-user situation, it may be perfereable to use the
 Nebulous infrastructure to manage the location and copies of the image
-data.  \tdb{define an inject mechanism that uses Nebulous}.
+data.  \tbd{Define an inject mechanism that uses Nebulous}.
 
 Second, it is interesting to consider on what timescale to test and
@@ -501,11 +536,11 @@
 Standard IPP-wide command-line options (document elsewhere):
 \begin{itemize}
-\item C{-site site.mdc}
-\item C{-camera camera-name}
-\item C{-recipe NAME VALUE}
-\item C{-D KEY VALUE}
-\item C{-Df KEY VALUE}
-\item C{-Db KEY VALUE}
-\item C{-Di KEY VALUE}
+\item \code{-site site.mdc}
+\item \code{-camera camera-name}
+\item \code{-recipe NAME VALUE}
+\item \code{-D KEY VALUE}
+\item \code{-Df KEY VALUE}
+\item \code{-Db KEY VALUE}
+\item \code{-Di KEY VALUE}
 \end{itemize}
 
@@ -765,4 +800,893 @@
 
 \section{Installation}
+
+\subsection{psconfig}
+
+The psconfig system allows the user to build and install the IPP
+software suite into a location which is flexibly defined by the user.
+The tools here also set up the user's environment variables
+(\code{PATH}, \code{PERL5LIB}, \code{LIBRARY_PATH}, etc) to make use
+of the installed software.  With the psconfig tools, it is easy to
+switch between different installed versions or to recompile subsets of
+the IPP tree.  It is also possible for a user to install the complete
+IPP system without access to the root password.
+
+\subsubsection{Preparation}
+
+\paragraph{Unpack the IPP tarball.}  The IPP source code is
+distributed as a single tarball for all of the IPP software
+(ipp-M.NN.tgz, where M.NN is the version number, currently 2.1).  Use
+the command \code{tar xvzf ipp-M.NN.tgz} or \code{gzcat ipp-M.NN.tgz |
+tar xvz} on older platforms.  The tarball will unpack into a directory
+named ipp-M.NN.
+
+\paragraph{Unpack the external Perl modules.} If needed, the complete
+collection of Perl modules used by the IPP is also distributed from
+the IPP web site as a tarball, extperl.tgz.  Use the command \code{tar
+xvzf extperl.tgz}, which will unpack the tarball into a directory
+called \code{extperl}.  This must be at the same location as the top
+level directory.  The program \code{pscheckperl} below will identify
+any external Perl modules which are missing from your system.
+
+\paragraph{Download the external C libraries.}  If needed, the
+external libraries needed by the IPP are available from the IPP web
+pages. Download these as needed to a directory called \code{extlibs},
+again parallel to the \code{ipp-M.NN} directory.  The program
+\code{pschecklibs} below will identify any external C libraries which
+are missing from your system.
+
+\paragraph{Set up your account to use the psconfig system.}  The
+psconfig system provides a script which sets up the necessary UNIX
+environment variables and aliases, enabling the compiler and the
+programs to find your installed libraries and Perl modules.  The
+details depend on your UNIX shell:
+
+\subparagraph{csh users}
+
+To use the psconfig system, place the following line in your ~/.cshrc
+file:
+
+\code{alias psconfig "source ../ipp-M.NN/psconfig/psconfig.csh"}
+
+where ../ipp-M.NN is the location of the extracted ipp tarball.  If
+you prefer, you may copy the file psconfig.csh to another location.
+If, for example, you would like to remove the build directories after
+building the IPP, you will need a persistent copy of psconfig.csh.
+
+By default, the psconfig system places the installed IPP programs and
+configuration files in a directory in your home directory:
+\code{~/psconfig}.  To use a different location, place the following
+line in \code{~/.psconfigrc} (otherwise not needed):
+
+\code{set PSCONFDIR = INSTALL_PATH}
+
+where \code{INSTALL_PATH} is the top-level directory for all installed files.
+
+\subparagraph{bash users}
+
+Add the following line to your \code{~/.bashrc} file:
+
+\code{alias psconfig="source PATH/psconfig.bash"}
+
+It is also necessary to edit the file psconfig.bash to set the
+\code{PSCONFIG_DIR} variable to this directory as well.
+
+\tbd{set this up for better discovery}
+
+\paragraph {Set the installation version}
+
+The IPP is a large and complex software system.  A major goal of the
+IPP build system is to be user-friendly for those end users which do
+not have root access on their machines.  Using the IPP build tools, it
+is possible to install the complete system as a non-priviledged user.
+The build system also makes it possible to maintain multiple
+simultaneous installations with different versions of the
+software. This latter feature is particularly important for developers
+who need to be able to make tests and comparisons of different
+versions.
+
+With \code{psconfig}, you may have multiple, parallel installations of
+the IPP.  These may be different versions of the software, or
+installations for different computer architectures, or installations
+with different compilation options.  For example, you may want an
+installation with tracing and debug information turned on and a second
+with all optimizations turned on.  With the psconfig build system,
+each installation of the IPP software is placed in a directory
+identified by an installation name and the computer architecture.  The
+installation name is up to the person who compiles the IPP software,
+and is an arbtrary word or string.  For example, you may choose the
+install the optimized version under ipp-2.1-opt and the debug version
+under ipp-2.1-debug.  The psconfig system will create a directory in
+\code{~/psconfig} (or where ever \code{PSCONDIR} is set) called
+ipp-2.1-opt.linux (if building on a linux 32bit system), or something
+equivalent.
+
+Before running or compiling the IPP, it is necessary to use
+\code{psconfig} to set the installation name:
+%
+\code{psconfig (name)}
+%
+This command sets aliases and environment variables for the current
+shell to point at the named IPP installation, for the current 
+hardware.  For example:
+%
+\code{psconfig default}
+%
+will set the \code{PATH} to include
+\code{~/psconfig/default.linux/bin} on a 32-bit linux system, and the
+other paths to point at the corresponding installation directories.
+
+Users who wish to automatically have access to an IPP installation
+should add the psconfig line to their \code{~/.cshrc} or
+\code{~/.bashrc} files.  
+
+\subsubsection{Check External Dependencies}
+
+The IPP build system is run from the directory
+\code{../ipp-M.NN/psconfig}.  Within this directory are the build
+scripts and scripts to prove the build environment.  Before building
+the IPP suite, you should first check for the needed C libraries and
+Perl scripts.  Start by \code{cd}-ing into \code{ipp-M.NN/psconfig}.  
+
+\subsubsubsection{External C libraries}
+
+The program \code{pschecklibs} in the \code{ipp-M.NN/psconfig}
+directory will check for required system libraries and headers:
+%
+\code{pschecklibs}
+%
+It examines the system libraries, libraries defined by
+\code{LIBRARY_PATH}, and the installation library defined by psconfig.
+Any missing dependencies will be listed.  Tarballs for these libraries
+may be found on the Pan-STARRS web site at:
+%
+\code{http://pan-starrs.ifa.hawaii.edu/project/IPP/software/ext}
+%
+These should be installed so they will be available in the user's
+path.  This can be done with the \code{psconfig} tools by using
+\code{psconfigure} to replace the standard \code{configure} command.
+The \code{psconfigure} command applies the needed \code{--prefix}
+options to place the libraries within the IPP installation tree.
+There is also an equivalent for \code{autogen.sh}, \code{psautogen},
+if needed.
+
+\subsubsubsection{External Perl Modules}
+
+The program \code{pscheckperl} in the \code{ipp-M.NN/psconfig}
+directory will check for required Perl modules, and can be used to
+install them in the appropriate user location in the psconfig system.
+The command defaults to the latest perl installation table in the
+\code{tagsets} directory.  If you have CVS access and choose to check
+out an older IPP distribution, it is necessary to supply the
+distribution name to \code{pscheckperl}.  Otherwise, run it without arguments:
+%
+\code{pscheckperl}
+%
+This will test for the perl modules specified for the latest ipp
+release.  If any modules are missing, you should install the perl
+module tarball (see above), or they can be download from the
+Pan-STARRS web site:
+%
+\code{http://pan-starrs.ifa.hawaii.edu/project/IPP/software/extperl}
+
+The tarballs should be placed in a directory \code{extperl} parallel
+to the ipp directory (two levels up from this directory).  If the
+tarballs are in the correct location, they can be built by supplying
+the \code{-build} flag to \code{pscheckperl}:
+
+\code{pscheckperl -build}
+
+\subsubsection{Building IPP}
+
+To build the full IPP tree using the psconfig system, run
+\code{psbuild} in the \code{ipp-M.NN/psconfig} directory.  By default,
+\code{psbuild} will use the latest IPP distribution table, in the
+directory \code{tagsets}, and build the IPP components according to
+the rules in that distribution file.  The distribution files specify
+which versions (which CVS tags) of the different programs are to be
+built, and in which order, for a given distribution of the IPP.  If
+you have access to the IPP CVS tree and check out an old IPP
+distribution, it is possible to specify the file for that
+distribution, and build the software as it appeared for that older
+distribution.  It is also possible to use the tools in this directory
+to check out the older code and to build tarballs for the older
+distributions.  However, for the typical end user building the IPP
+from a distributed tarball, it is only necessary to run \code{psbuild}
+without additional arguments:
+%
+\code{psbuild ipp-1.2}
+%
+
+There are a number of command-line options to \code{psbuild} which
+control how the software is built or which components of the IPP to
+build:
+\begin{verbatim}
+ -version (version) : specify alternate psconfig installation version
+ -clean             : clean the source directories before building
+ -rebuild           : run 'autogen' (C code)
+ -optimize          : set flags for optimized code
+ -only (module)     : only build the specified module
+ -start (module)    : begin build at specified module
+ -stop (module)     : stop build after specified module
+\end{verbatim}
+
+Summary of psconfig operations:
+\begin{verbatim}
+psdist -tag        : tag CVS tree
+psdist -dist       : build tarball from tagged tree
+psdist -dist -head : build tarball from head
+psbuild            : build and install software in tree
+pschecklibs        : check for needed external software
+pscheckperl        : check for needed perl modules
+pscheckperl -build : build and install external modules
+\end{verbatim}
+
+\subsection{jhbuild}
+
+JH uses \code{jhbuild} even though the 'jh' in \code{jhbuild} doesn't
+really refer to him.
+
+\subsubsubsection{What is it?}
+
+According to the introduction on the \code{jhbuild} website:
+
+\begin{quote}
+\code{jhbuild} is a program that can be used to pull a number of
+modules from CVS and build them in the correct order. Unlike some
+build scripts, \code{jhbuild} lets you specify what modules you want
+built and it will then go and build those modules plus dependencies.
+
+Although \code{jhbuild} was originally developed to build
+\code{[WWW]Gnome}, it is now able to build a number of the modules in
+\code{freedesktop.org} CVS. Extending it to handle new modules is
+usually trivial (assuming the build infrastructure matches the other
+modules it handles).
+\end{quote}
+
+In additional to retrieving source code from various SCM's (CVS, SVN,
+arch, etc.), jhbuild has the ability to download tarballs via HTTP or
+FTP.
+
+\code{jhbuild} has been adopted as an official \code{freedesktop.org}
+project. You can find more information on the project's homepage
+(\code{http://www.freedesktop.org/Software/jhbuild}). Bugs can be
+filed in the Gnome Bugzilla (\code{http://bugzilla.gnome.org}).
+
+\subsubsubsection{Where to get it}
+
+It was necessary to slightly modify \code{jhbuild} for use with IPP
+software. Therefore, you must checkout the \code{jhbuild} module from
+the Pan-STARRS CVS tree. Please see the Pan-STARRS CVS Guide for help
+on setting up and using CVS. \code{jhbuild} will need to be able to
+find it's own source tree even after installation so you should choose
+a checkout path that can be permanent. Something along the lines of
+\code{$HOME/src} is recommended.
+
+\begin{verbatim}
+cd
+mkdir -p src
+cd src
+cvs co jhbuild
+\end{verbatim}
+
+After running CVS you should see something like this:
+
+\begin{verbatim}
+$ cvs co jhbuild
+cvs checkout: Updating jhbuild
+U jhbuild/.cvsignore
+U jhbuild/COPYING
+U jhbuild/ChangeLog
+U jhbuild/HACKING
+U jhbuild/Makefile
+U jhbuild/README
+U jhbuild/install-check.c
+.
+.
+\end{verbatim}
+
+\subsubsubsection{Installing jhbuild into your home directory}
+
+\code{jhbuild} should be installed locally under your home
+directory. This will require that you modify the \code{PATH}
+environment variable so that you can run jhbuild after it has been
+installed.
+
+\begin{verbatim}
+cd jhbuild
+make
+make install
+\end{verbatim}
+
+Which should look something like this:
+
+\begin{verbatim}
+$ make
+gcc -Wall -O2 -o install-check install-check.c
+Run "make install" to install.
+$ make install
+Creating /home/moanui/jhoblitt/bin/jhbuild
+Creating /home/moanui/jhoblitt/.gnome2/vfolders/applications/jhbuild.desktop
+install -m755 install-check /home/moanui/jhoblitt/bin/install-check
+install -m755 config.guess /home/moanui/jhoblitt/bin/config.guess
+\end{verbatim}
+
+That will install the \code{jhbuild} executable under
+\code{$HOME/bin}. You are responsible for including this path in your
+\code{PATH} environment variable. It is highly recommended that you
+add this to your \code{.bashrc} or equivalent shell login script.
+
+For the \code{bash} shell, place this line in your \code{.bashrc}:
+\begin{verbatim}
+export PATH=${HOME}/bin:${PATH}
+\end{verbatim}
+For the \code{tcsh} shell, place this line in your \code{.tschrc}:
+\begin{verbatim}
+setenv PATH ${HOME}/bin:${PATH}
+\end{verbatim}
+
+\subsubsubsection{Configuring jhbuild}
+
+\code{jhbuild} is configured via an rc file that lives at
+\code{${HOME}/.jhbuildrc}. Please note that this rc file is executed
+as Python code; be careful!
+
+Example \code{.jhbuildrc}, suitable for cut and paste:
+
+\begin{verbatim}
+# what profile to build?
+moduleset = 'http://pan-starrs.ifa.hawaii.edu/project/IPP/software/modulesets/ipp12.modules'
+
+# modules to build by default
+modules = [ 'pslib', 'psmodules' ]
+
+# where should working copies go?
+jhroot = os.environ['HOME'] + '/jhroot'
+
+# where should tarballs be kept?
+tarballdir = jhroot + '/src'
+
+# in what prefix should things be installed? (must be writable)
+target = os.popen('config.guess').read().rstrip()
+prefix = jhroot + '/' + target
+checkoutroot = prefix + '/build'
+
+# extra arguments to pass to the autogen.sh script?
+autogenargs = '--enable-maintainer-mode --disable-static'
+
+# use an alternative install program that preserves the
+# mtime on header files if they haven't changed.  Speeds
+# up rebuilds.
+os.environ['INSTALL'] = os.environ['HOME'] + '/bin/install-check'
+
+# don't try to use /usr/ucb/cc on Solaris
+import sys
+if sys.platform == 'sunos5':
+    os.environ['CC'] = 'gcc'
+\end{verbatim}
+
+\subsubsubsection{Running jhbuild}
+
+\code{Jhbuild} can be executed as \code{jhbuild build
+[modulename]}. Just \code{jhbuild} will build the packages specified
+in the \code{modules} variable from your rc file.
+\begin{verbatim}
+jhbuild
+\end{verbatim}
+or
+\begin{verbatim}
+jhbuild build pslib
+\end{verbatim}
+
+Run \code{jhbuild} list to get a list of the packages \code{jhbuild}
+knows how to build.
+
+\begin{verbatim}
+$ jhbuild list
+cfitsio
+gsl
+fftw
+libxml2
+mysql
+pslib
+psmodules
+\end{verbatim}
+
+\code{jhbuild} supports many other commands. Please see \code{jhbuild
+--help} for a complete list of options.
+
+\begin{verbatim}
+$ jhbuild --help
+usage: jhbuild [ -f config ] command [ options ... ]
+Build a set of CVS modules (such as GNOME).
+
+Global options:
+  -f, --file=CONFIG            use a non default configuration file
+  -m, --moduleset=URI          use a non default module set
+      --no-interact            do not prompt for input
+
+Commands:
+  gui                          build targets from a gui app
+  update                       update from cvs
+  updateone modules            update a fixed set of modules
+  build [ opts... ] [modules]  update and compile (the default)
+  buildone [ opts... ] modules build a single module
+  tinderbox [ opts... ]        build non-interactively with logging
+  run program [ args... ]      run a command in the build environment
+  shell                        start a shell in the build environment
+  sanitycheck                  check that required support tools exists
+  bootstrap                    build required support tools
+  list [ opts ... ] [modules]  list what modules would be built
+  dot [ modules ]              output a dot file of dependencies suitable
+                               for processing with graphviz
+  info modules...              prints information about modules
+
+Options valid for the build, buildone, tinderbox and update commands:
+  -s, --skip=MODULES           treat the given modules as up to date
+  -t, --start-at=MODULE        start building at the given module
+  -D date_spec                 set a sticky date when checking out modules
+
+Options valid for the build, buildone and tinderbox commands:
+  -a, --autogen                always run autogen.sh
+  -c, --clean                  run make clean before make
+  -n, --no-network             skip cvs update
+
+Options valid for the tinderbox command:
+  -o, --output=DIR             directory to save build logs in
+
+Options valid for the list command:
+  -r, --show-revision          show which revision will be built
+\end{verbatim}
+
+\subsubsubsection{Dependancies}
+
+\code{jhbuild} has a fairly minimal set of dependencies --- far less
+than what may be required to actually compile and install any
+packages. However, if your system can meet the base requirements,
+\code{jhbuild} should be able to bootstrap your build environment.
+\begin{itemize}
+\item A working C compiler (eg. \code{gcc})
+\item A working \code{libc} (eg. \code{glibc})
+\item Perl 5 with the \code{XML::Parser} module (needed by
+  \code{libtool})
+\item Python 2.?
+\item Either \code{wget} or \code{curl}
+\item GNU \code{M4} 1.4
+\item \code{tar}
+\item \code{gzip}
+\item \code{bzip2}
+\end{itemize}
+
+\subsubsubsection{Bootstrapping}
+
+\code{jhbuild} has a limited ability to install some of the necessary
+tools for maintaining software that configure its build environment
+with the GNU autotools.
+
+This step is probably required on OSX and Solaris. Your mileage will
+vary per Linux distribution but you can probably skip this step if
+your distribution is around RedHat 9 vintage or newer.
+
+\begin{verbatim}
+jhbuild bootstrap
+\end{verbatim}
+
+\code{jhbuild} will then will begin to build a series of packages.
+
+\subsubsubsection{Using the jhbuild enviroment}
+
+As you've already seen, \code{jhbuild} is capable of setting up an
+independent build environment under the (configurable) directory of
+your choice. In order to link non-\code{jhbuild} management software
+against this build environment a number of your shell's environment
+variable have to be modified. \code{jhbuild} is capable of doing this
+for you. The syntax for this is \code{jhbuild shell}, which as the
+syntax implies, spawns a new shell with the proper environment
+variables.
+
+This example demonstrates \code{jhbuild} setting up the dynamic
+linkers default search path for you.
+
+\begin{verbatim}
+$ echo $LD_LIBRARY_PATH
+
+$ jhbuild shell
+$ echo $LD_LIBRARY_PATH
+/home/moanui/jhoblitt/jhroot/i686-pc-linux-gnu/lib
+\end{verbatim}
+
+%$ --- Emacs needs this to balance out the dollar signs
+
+A fair number of other variables are also adjusted for you. Enough so
+that most (all?) \code{autoconf} configured software will be able to
+find it's dependencies.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{Aliases}
+
+PAP puts the following in his \code{~/.tcshrc}:
+\begin{verbatim}
+setenv SWDIR $HOME/local/`$HOME/bin/config.guess`/
+if (! -d $SWDIR) mkdir --parents $SWDIR
+alias ./autogen.sh './autogen.sh --prefix=$SWDIR CFLAGS="-I$SWDIR/include/ -g" LDFLAGS=-L$SWDIR/lib/'
+alias   autogen.sh './autogen.sh --prefix=$SWDIR CFLAGS="-I$SWDIR/include/ -g" LDFLAGS=-L$SWDIR/lib/'
+alias ./configure  './configure  --prefix=$SWDIR CFLAGS="-I$SWDIR/include/ -g" LDFLAGS=-L$SWDIR/lib/'
+alias   configure  './configure  --prefix=$SWDIR CFLAGS="-I$SWDIR/include/ -g" LDFLAGS=-L$SWDIR/lib/'
+setenv PATH ${PATH}:$SWDIR/bin/
+setenv LD_LIBRARY_PATH $SWDIR/lib/:$SWDIR/lib/mysql:$LD_LIBRARY_PATH
+setenv MANPATH $SWDIR/man:$MANPATH
+setenv PKG_CONFIG_PATH $SWDIR/lib/pkgconfig/:$PKG_CONFIG_PATH
+\end{verbatim}
+
+%$ --- Emacs needs this to balance out the dollar signs
+
+Here, \code{config.guess} is the common GNU script for guessing the
+build system triplet (e.g., \code{i686-pc-linux-gnu}).
+
+There are a couple of notes:
+\begin{itemize}
+\item To compile a binary, simply do \code{./configure}, then
+  \code{make && make install}.
+\item \code{Ohana} doesn't like this setup, so you need to build it
+  with: \code{\./configure --prefix=$SWDIR}
+\item Perl modules can be installed: \code{./Build install
+  --prefix=$SWDIR}.
+\end{itemize}
+
+\subsection{Manual Perl Module Installation}
+
+Here we describe setting up the Perl dependencies followed by the
+IPP components.
+
+\subsubsection{Dependencies}
+\label{sec:installing-perl-dependencies}
+
+If you have access to the \code{root} account, installation as
+\code{root} is much easier.  If not, you will have to go through
+the more flaky installation as an unprivileged user.
+
+\subsubsubsection{Installation as root}
+
+Many of the Perl dependencies are available from the Comprehensive
+Perl Archive Network (CPAN) at www.cpan.org.  If you have root access
+on your target machines, they can be very simply retrieved, built and
+installed (replacing \code{MODULE_NAME} for each module):
+
+\begin{verbatim}
+> su -
+Password:
+> cpan
+[...]
+cpan> install MODULE_NAME
+[...]
+cpan> quit
+\end{verbatim}
+
+Follow the prompts.  It's usually safe to accept the default (simply
+hit enter) in response to most questions.
+
+If you get into trouble, try: \code{force install MODULE_NAME}.
+
+You can also try to use the \code{Bundle::PS} as described below if
+you're feeling adventurous.
+
+\subsubsubsection{Installation as unprivileged user}
+
+To install modules from CPAN with the \code{CPAN.pm} interface, you
+need to setup a CPAN configuration file in your home directory.  Then
+\code{CPAN.pm} can walk you through setting up the most important
+configuration values.  Unfortunately, there is some variation in the
+behavior of the various versions of \code{CPAN.pm} that have shipped
+with Perl.  Some (most) of these variants will not correctly create a
+configuration files that allows a non-\code{root} user to install
+modules outside of "system" paths.  In order to make sure that you get
+a "correct" CPAN configuration file you need to ``prime'' it with a
+few values.
+
+First you need to create the directory in which the CPAN configuration file will live.
+\begin{verbatim}
+> mkdir -p .cpan/CPAN/
+\end{verbatim}
+
+Then we need to create a partial configuration file.  Note that this example
+assumes that you want to install your perl modules under
+\code{$HOME/local/lib/perl5}.
+
+\begin{verbatim}
+> echo "\$CPAN::Config = {" >> .cpan/CPAN/MyConfig.pm
+> echo "  makepl_arg => q[PREFIX=$HOME/local/]," >> .cpan/CPAN/MyConfig.pm
+> echo "  mbuildpl_arg => q[--install_base $HOME/local/]," >> .cpan/CPAN/MyConfig.pm
+> echo "};" >> .cpan/CPAN/MyConfig.pm
+> echo "1;" >> .cpan/CPAN/MyConfig.pm
+> echo "__END__" >> .cpan/CPAN/MyConfig.pm
+\end{verbatim}
+
+%$ --- Emacs needs this to balance the previous dollar sign
+
+Now you need to invoke \code{CPAN.pm} so it can walk you through
+configuring the rest of the required values.  This is an example of
+one possible configuration with \code{CPAN.pm} version 1.8802.
+\textbf{Your version of CPAN.pm may present you with different
+prompts.}  Use your common sense.  If in doubt, it is generally safe
+to simply hit enter (and accept the default).
+
+\begin{verbatim}
+> perl -MCPAN -e shell
+CPAN: File::HomeDir loaded ok
+Sorry, we have to rerun the configuration dialog for CPAN.pm due to
+the following indispensable but missing parameters:
+
+build_cache, build_dir, cache_metadata, cpan_home, ftp_proxy, http_proxy,
+index_expire, inhibit_startup_message, keep_source_where, make_arg,
+make_install_arg, mbuild_arg, mbuild_install_arg, mbuild_install_build_command,
+no_proxy, prerequisites_policy, scan_cache, urllist
+
+
+The following questions are intended to help you with the
+configuration. The CPAN module needs a directory of its own to cache
+important index files and maybe keep a temporary mirror of CPAN files.
+This may be a site-wide directory or a personal directory.
+
+
+
+I see you already have a  directory
+    /home/moanui/jhoblitt/.cpan
+Shall we use it as the general CPAN build and cache directory?
+
+CPAN build and cache directory? [/home/moanui/jhoblitt/.cpan]
+
+
+Unless you are accessing the CPAN via the filesystem directly CPAN.pm
+needs to keep the source files it downloads somewhere. Please supply a
+directory where the downloaded files are to be kept. [/home/moanui/jhoblitt/.cpan/sources]
+Directory where the build process takes place? [/home/moanui/jhoblitt/.cpan/build]
+
+
+How big should the disk cache be for keeping the build directories
+with all the intermediate files?
+
+Cache size for build directory (in MB)? [100]
+
+
+The CPAN indexes are usually rebuilt once or twice per hour, but the
+typical CPAN mirror mirrors only once or twice per day. Depending on
+the quality of your mirror and your desire to be on the bleeding edge,
+you may want to set the following value to more or less than one day
+(which is the default). It determines after how many days CPAN.pm
+downloads new indexes.
+
+Let the index expire after how many days? [1]
+
+
+By default, each time the CPAN module is started, cache scanning is
+performed to keep the cache size in sync. To prevent this, answer
+'never'.
+
+Perform cache scanning (atstart or never)? [atstart]
+
+
+To considerably speed up the initial CPAN shell startup, it is
+possible to use Storable to create a cache of metadata. If Storable
+is not available, the normal index mechanism will be used.
+
+Cache metadata (yes/no)? [yes]
+
+
+The CPAN module can detect when a module which you are trying to build
+depends on prerequisites. If this happens, it can build the
+prerequisites for you automatically ('follow'), ask you for
+confirmation ('ask'), or just ignore them ('ignore'). Please set your
+policy to one of the three values.
+
+Policy on building prerequisites (follow, ask or ignore)? [ask] follow
+
+
+Every Makefile.PL is run by perl in a separate process. Likewise we
+run 'make' and 'make install' in separate processes. If you have
+any parameters (e.g. PREFIX, LIB, UNINST or the like) you want to
+pass to the calls, please specify them here.
+
+If you don't understand this question, just press ENTER.
+Parameters for the 'make' command?
+Typical frequently used setting:
+
+    -j3              # dual processor system
+
+Your choice:  []
+Parameters for the 'make install' command?
+Typical frequently used setting:
+
+    UNINST=1         # to always uninstall potentially conflicting files
+
+Your choice:  [] UNINST=1
+
+
+The next questions deal with Module::Build support.
+
+A Build.PL is run by perl in a separate process. Likewise we run
+'./Build' and './Build install' in separate processes. If you have any
+parameters you want to pass to the calls, please specify them here.
+
+Parameters for the './Build' command?
+Setting might be:
+
+    --extra_linker_flags -L/usr/foo/lib  # non-standard library location
+
+Your choice:  []
+Do you want to use a different command for './Build install'?
+Sudo users will probably prefer:
+
+    su root -c ./Build
+or
+    sudo ./Build
+or
+    /path1/to/sudo -u admin_account ./Build
+
+or some such. Your choice:  [./Build]
+Parameters for the './Build install' command?
+Typical frequently used setting:
+
+    --uninst 1                           # uninstall conflicting files
+
+Your choice:  [] --uninst 1
+
+
+If you're accessing the net via proxies, you can specify them in the
+CPAN configuration or via environment variables. The variable in
+the $CPAN::Config takes precedence.
+
+Your ftp_proxy? []
+Your http_proxy? []
+Your no_proxy? []
+You have no /home/moanui/jhoblitt/.cpan/sources/MIRRORED.BY
+  I'm trying to fetch one
+CPAN: LWP::UserAgent loaded ok
+Fetching with LWP:
+  http://www.perl.org/CPAN/MIRRORED.BY
+
+
+Now we need to know where your favorite CPAN sites are located. Push
+a few sites onto the array (just in case the first on the array won't
+work). If you are mirroring CPAN to your local workstation, specify a
+file: URL.
+
+First, pick a nearby continent and country by typing in the number(s)
+in front of the item(s) you want to select. You can pick several of
+each, separated by spaces. Then, you will be presented with a list of
+URLs of CPAN mirrors in the countries you selected, along with
+previously selected URLs. Select some of those URLs, or just keep the
+old list. Finally, you will be prompted for any extra URLs -- file:,
+ftp:, or http: -- that host a CPAN mirror.
+
+(1) Africa
+(2) Asia
+(3) Central America
+(4) Europe
+(5) North America
+(6) Oceania
+(7) South America
+Select your continent (or several nearby continents) [] 5
+
+(1) Bahamas
+(2) Canada
+(3) Mexico
+(4) United States
+Select your country (or several nearby countries) [] 4
+
+(1) ftp://carroll.cac.psu.edu/pub/CPAN/
+(2) ftp://cpan-du.viaverio.com/pub/CPAN/
+(3) ftp://cpan-sj.viaverio.com/pub/CPAN/
+(4) ftp://cpan.calvin.edu/pub/CPAN
+(5) ftp://cpan.cs.utah.edu/pub/CPAN/
+(6) ftp://cpan.cse.msu.edu/
+(7) ftp://cpan.erlbaum.net/CPAN/
+(8) ftp://cpan.glines.org/pub/CPAN/
+(9) ftp://cpan.hostrack.net/pub/CPAN
+(10) ftp://cpan.llarian.net/pub/CPAN/
+(11) ftp://cpan.mirrors.redwire.net/pub/CPAN/
+(12) ftp://cpan.mirrors.tds.net/pub/CPAN
+(13) ftp://cpan.netnitco.net/pub/mirrors/CPAN/
+(14) ftp://cpan.pair.com/pub/CPAN/
+(15) ftp://cpan.teleglobe.net/pub/CPAN
+(16) ftp://cpan.uchicago.edu/pub/CPAN/
+40 more items, hit RETURN to show them
+Select as many URLs as you like (by number),
+put them on one line, separated by blanks, hyphenated ranges allowed
+ e.g. '1 4 5' or '7 1-4 8' [] 14 11 12
+
+Enter another URL or RETURN to quit: []
+New set of picks:
+  ftp://cpan.pair.com/pub/CPAN/
+  ftp://cpan.mirrors.redwire.net/pub/CPAN/
+  ftp://cpan.mirrors.tds.net/pub/CPAN
+
+
+Please remember to call 'o conf commit' to make the config permanent!
+
+
+cpan shell -- CPAN exploration and modules installation (v1.8802)
+ReadLine support enabled
+
+ cpan[1]> o conf commit
+commit: wrote '/home/moanui/jhoblitt/.cpan/CPAN/MyConfig.pm'
+\end{verbatim}
+
+%$ --- Emacs needs this to balance the previous dollar sign
+
+Now we need to install the module that installs the other modules.
+
+\begin{verbatim}
+cpan> install Module::Build
+\end{verbatim}
+
+Exit out of cpan:
+
+\begin{verbatim}
+cpan> exit
+\end{verbatim}
+
+In order to use of the installed modules, we need to setup an
+environment variable called \code{PERL5LIB} so that 'perl' can find
+them.  To do this, we need to know where under 'perl5' our modules
+were actually installed.  This will set variable with the version of
+Perl that you are using.  The easiest way to do this is just just look
+in the root of the path where we did the install.
+
+\begin{verbatim}
+> ls local/lib/perl5/
+5.8.8  site_perl
+\end{verbatim}
+
+That means we're using perl 5.8.8 and \code{PERL5LIB} needs to be
+setup as following:
+\begin{verbatim}
+export PERL5LIB=$HOME/local/lib/perl5/5.8.8:$HOME/local/lib/perl5/site_perl/5.8.8
+\end{verbatim}
+
+Now we should install the basic compliment of helper modules that
+\code{CPAN.pm} needs to function fully.  Go back into CPAN (\code{perl
+-MCPAN -e shell}) and:
+
+\begin{verbatim}
+cpan> install Bundle::CPAN
+\end{verbatim}
+
+You can quit out of the CPAN shell at this point with the `exit`
+command or do the following few steps in another shell We're ready to
+install the full set Perl module dependencies for IPP software.  In
+order to make this process a bit easier on the end user a "Bundle"
+module has been created.  In order to use it you need to create a
+directory (if it doesn't already exist) called Bundle under your .cpan
+directory.
+
+\begin{verbatim}
+> mkdir -p .cpan/Bundle
+\end{verbatim}
+
+The file \code{PS.pm} should copied into this directory:
+
+\begin{verbatim}
+cp /path/to/PS.pm .cpan/Bundle/
+\end{verbatim}
+
+Back in the CPAN shell, 'force' the install of the PS Bundle.  The
+'force' keyword instructs the shell to ignore any tests failures.
+This is necessary as some of the modules 'DBD::mysql'/etc. require a
+properly working database setup in order for the tests to pass.  You
+will most likely be prompted for input by several the modules.  It is
+safe to answer with a carriage return to all questions.  If it insists
+on a path to \code{httpd}, hit \code{CTRL-C} and it will go on to the
+next step.
+
+\begin{verbatim}
+cpan> force install Bundle:PS
+\end{verbatim}
+
+For further instructions on installing Perl modules from CPAN ''by
+hand', see:
+\begin{verbatim}
+http://www.cs.ucsc.edu/~you/notes/perl-module-install.html
+\end{verbatim}
 
 After the dependencies (\S\ref{sec:dependencies}) have been satisfied,
@@ -790,701 +1714,4 @@
 \item \code{config}
 \end{itemize}
-
-\subsection{psconfig}
-
-\note{use the write-up in psconfig for this section}
-
-\begin{verbatim}
-* pscheckperl : search for and install, if needed, external Perl modules
-* pschecklibs : search for and install, if needed, external C libraries
-* psconfig : set up the UNIX shell environment
-* psbuild : build and install the software
-* psdist : build IPP distributions (requires CVS access)
-* tagsets : tables defining the C and Perl components to be built
-\end{verbatim}
-
-The IPP is a large and complex software system.  A major goal of the
-IPP build system is to be user-friendly for those end users which do
-not have root access on their machines.  Using the IPP build tools, it
-is possible to install the complete system as a non-priviledged user.
-The build system also makes it possible to maintain multiple
-simultaneous installations with different versions of the
-software. This latter feature is particularly important for developers
-who need to be able to make tests and comparisons of different
-versions.
-
-\subsubsubsection{UNIX environment}
-
-With the psconfig system, the complete collection of libraries and 
-
-When building software 
-
-\subsection{jhbuild}
-
-JH uses \code{jhbuild} even though the 'jh' in \code{jhbuild} doesn't
-really refer to him.
-
-\subsubsubsection{What is it?}
-
-According to the introduction on the \code{jhbuild} website:
-
-\begin{quote}
-\code{jhbuild} is a program that can be used to pull a number of
-modules from CVS and build them in the correct order. Unlike some
-build scripts, \code{jhbuild} lets you specify what modules you want
-built and it will then go and build those modules plus dependencies.
-
-Although \code{jhbuild} was originally developed to build
-\code{[WWW]Gnome}, it is now able to build a number of the modules in
-\code{freedesktop.org} CVS. Extending it to handle new modules is
-usually trivial (assuming the build infrastructure matches the other
-modules it handles).
-\end{quote}
-
-In additional to retrieving source code from various SCM's (CVS, SVN,
-arch, etc.), jhbuild has the ability to download tarballs via HTTP or
-FTP.
-
-\code{jhbuild} has been adopted as an official \code{freedesktop.org}
-project. You can find more information on the project's homepage
-(\code{http://www.freedesktop.org/Software/jhbuild}). Bugs can be
-filed in the Gnome Bugzilla (\code{http://bugzilla.gnome.org}).
-
-\subsubsubsection{Where to get it}
-
-It was necessary to slightly modify \code{jhbuild} for use with IPP
-software. Therefore, you must checkout the \code{jhbuild} module from
-the Pan-STARRS CVS tree. Please see the Pan-STARRS CVS Guide for help
-on setting up and using CVS. \code{jhbuild} will need to be able to
-find it's own source tree even after installation so you should choose
-a checkout path that can be permanent. Something along the lines of
-\code{$HOME/src} is recommended.
-
-\begin{verbatim}
-cd
-mkdir -p src
-cd src
-cvs co jhbuild
-\end{verbatim}
-
-After running CVS you should see something like this:
-
-\begin{verbatim}
-$ cvs co jhbuild
-cvs checkout: Updating jhbuild
-U jhbuild/.cvsignore
-U jhbuild/COPYING
-U jhbuild/ChangeLog
-U jhbuild/HACKING
-U jhbuild/Makefile
-U jhbuild/README
-U jhbuild/install-check.c
-.
-.
-\end{verbatim}
-
-\subsubsubsection{Installing jhbuild into your home directory}
-
-\code{jhbuild} should be installed locally under your home
-directory. This will require that you modify the \code{PATH}
-environment variable so that you can run jhbuild after it has been
-installed.
-
-\begin{verbatim}
-cd jhbuild
-make
-make install
-\end{verbatim}
-
-Which should look something like this:
-
-\begin{verbatim}
-$ make
-gcc -Wall -O2 -o install-check install-check.c
-Run "make install" to install.
-$ make install
-Creating /home/moanui/jhoblitt/bin/jhbuild
-Creating /home/moanui/jhoblitt/.gnome2/vfolders/applications/jhbuild.desktop
-install -m755 install-check /home/moanui/jhoblitt/bin/install-check
-install -m755 config.guess /home/moanui/jhoblitt/bin/config.guess
-\end{verbatim}
-
-That will install the \code{jhbuild} executable under
-\code{$HOME/bin}. You are responsible for including this path in your
-\code{PATH} environment variable. It is highly recommended that you
-add this to your \code{.bashrc} or equivalent shell login script.
-
-For the \code{bash} shell, place this line in your \code{.bashrc}:
-\begin{verbatim}
-export PATH=${HOME}/bin:${PATH}
-\end{verbatim}
-For the \code{tcsh} shell, place this line in your \code{.tschrc}:
-\begin{verbatim}
-setenv PATH ${HOME}/bin:${PATH}
-\end{verbatim}
-
-\subsubsubsection{Configuring jhbuild}
-
-\code{jhbuild} is configured via an rc file that lives at
-\code{${HOME}/.jhbuildrc}. Please note that this rc file is executed
-as Python code; be careful!
-
-Example \code{.jhbuildrc}, suitable for cut and paste:
-
-\begin{verbatim}
-# what profile to build?
-moduleset = 'http://pan-starrs.ifa.hawaii.edu/project/IPP/software/modulesets/ipp12.modules'
-
-# modules to build by default
-modules = [ 'pslib', 'psmodules' ]
-
-# where should working copies go?
-jhroot = os.environ['HOME'] + '/jhroot'
-
-# where should tarballs be kept?
-tarballdir = jhroot + '/src'
-
-# in what prefix should things be installed? (must be writable)
-target = os.popen('config.guess').read().rstrip()
-prefix = jhroot + '/' + target
-checkoutroot = prefix + '/build'
-
-# extra arguments to pass to the autogen.sh script?
-autogenargs = '--enable-maintainer-mode --disable-static'
-
-# use an alternative install program that preserves the
-# mtime on header files if they haven't changed.  Speeds
-# up rebuilds.
-os.environ['INSTALL'] = os.environ['HOME'] + '/bin/install-check'
-
-# don't try to use /usr/ucb/cc on Solaris
-import sys
-if sys.platform == 'sunos5':
-    os.environ['CC'] = 'gcc'
-\end{verbatim}
-
-\subsubsubsection{Running jhbuild}
-
-\code{Jhbuild} can be executed as \code{jhbuild build
-[modulename]}. Just \code{jhbuild} will build the packages specified
-in the \code{modules} variable from your rc file.
-\begin{verbatim}
-jhbuild
-\end{verbatim}
-or
-\begin{verbatim}
-jhbuild build pslib
-\end{verbatim}
-
-Run \code{jhbuild} list to get a list of the packages \code{jhbuild}
-knows how to build.
-
-\begin{verbatim}
-$ jhbuild list
-cfitsio
-gsl
-fftw
-libxml2
-mysql
-pslib
-psmodules
-\end{verbatim}
-
-\code{jhbuild} supports many other commands. Please see \code{jhbuild
---help} for a complete list of options.
-
-\begin{verbatim}
-$ jhbuild --help
-usage: jhbuild [ -f config ] command [ options ... ]
-Build a set of CVS modules (such as GNOME).
-
-Global options:
-  -f, --file=CONFIG            use a non default configuration file
-  -m, --moduleset=URI          use a non default module set
-      --no-interact            do not prompt for input
-
-Commands:
-  gui                          build targets from a gui app
-  update                       update from cvs
-  updateone modules            update a fixed set of modules
-  build [ opts... ] [modules]  update and compile (the default)
-  buildone [ opts... ] modules build a single module
-  tinderbox [ opts... ]        build non-interactively with logging
-  run program [ args... ]      run a command in the build environment
-  shell                        start a shell in the build environment
-  sanitycheck                  check that required support tools exists
-  bootstrap                    build required support tools
-  list [ opts ... ] [modules]  list what modules would be built
-  dot [ modules ]              output a dot file of dependencies suitable
-                               for processing with graphviz
-  info modules...              prints information about modules
-
-Options valid for the build, buildone, tinderbox and update commands:
-  -s, --skip=MODULES           treat the given modules as up to date
-  -t, --start-at=MODULE        start building at the given module
-  -D date_spec                 set a sticky date when checking out modules
-
-Options valid for the build, buildone and tinderbox commands:
-  -a, --autogen                always run autogen.sh
-  -c, --clean                  run make clean before make
-  -n, --no-network             skip cvs update
-
-Options valid for the tinderbox command:
-  -o, --output=DIR             directory to save build logs in
-
-Options valid for the list command:
-  -r, --show-revision          show which revision will be built
-\end{verbatim}
-
-\subsubsubsection{Dependancies}
-
-\code{jhbuild} has a fairly minimal set of dependencies --- far less
-than what may be required to actually compile and install any
-packages. However, if your system can meet the base requirements,
-\code{jhbuild} should be able to bootstrap your build environment.
-\begin{itemize}
-\item A working C compiler (eg. \code{gcc})
-\item A working \code{libc} (eg. \code{glibc})
-\item Perl 5 with the \code{XML::Parser} module (needed by
-  \code{libtool})
-\item Python 2.?
-\item Either \code{wget} or \code{curl}
-\item GNU \code{M4} 1.4
-\item \code{tar}
-\item \code{gzip}
-\item \code{bzip2}
-\end{itemize}
-
-\subsubsubsection{Bootstrapping}
-
-\code{jhbuild} has a limited ability to install some of the necessary
-tools for maintaining software that configure its build environment
-with the GNU autotools.
-
-This step is probably required on OSX and Solaris. Your mileage will
-vary per Linux distribution but you can probably skip this step if
-your distribution is around RedHat 9 vintage or newer.
-
-\begin{verbatim}
-jhbuild bootstrap
-\end{verbatim}
-
-\code{jhbuild} will then will begin to build a series of packages.
-
-\subsubsubsection{Using the jhbuild enviroment}
-
-As you've already seen, \code{jhbuild} is capable of setting up an
-independent build environment under the (configurable) directory of
-your choice. In order to link non-\code{jhbuild} management software
-against this build environment a number of your shell's environment
-variable have to be modified. \code{jhbuild} is capable of doing this
-for you. The syntax for this is \code{jhbuild shell}, which as the
-syntax implies, spawns a new shell with the proper environment
-variables.
-
-This example demonstrates \code{jhbuild} setting up the dynamic
-linkers default search path for you.
-
-\begin{verbatim}
-$ echo $LD_LIBRARY_PATH
-
-$ jhbuild shell
-$ echo $LD_LIBRARY_PATH
-/home/moanui/jhoblitt/jhroot/i686-pc-linux-gnu/lib
-\end{verbatim}
-
-%$ --- Emacs needs this to balance out the dollar signs
-
-A fair number of other variables are also adjusted for you. Enough so
-that most (all?) \code{autoconf} configured software will be able to
-find it's dependencies.
-
-%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-\subsection{Aliases}
-
-PAP puts the following in his \code{~/.tcshrc}:
-\begin{verbatim}
-setenv SWDIR $HOME/local/`$HOME/bin/config.guess`/
-if (! -d $SWDIR) mkdir --parents $SWDIR
-alias ./autogen.sh './autogen.sh --prefix=$SWDIR CFLAGS="-I$SWDIR/include/ -g" LDFLAGS=-L$SWDIR/lib/'
-alias   autogen.sh './autogen.sh --prefix=$SWDIR CFLAGS="-I$SWDIR/include/ -g" LDFLAGS=-L$SWDIR/lib/'
-alias ./configure  './configure  --prefix=$SWDIR CFLAGS="-I$SWDIR/include/ -g" LDFLAGS=-L$SWDIR/lib/'
-alias   configure  './configure  --prefix=$SWDIR CFLAGS="-I$SWDIR/include/ -g" LDFLAGS=-L$SWDIR/lib/'
-setenv PATH ${PATH}:$SWDIR/bin/
-setenv LD_LIBRARY_PATH $SWDIR/lib/:$SWDIR/lib/mysql:$LD_LIBRARY_PATH
-setenv MANPATH $SWDIR/man:$MANPATH
-setenv PKG_CONFIG_PATH $SWDIR/lib/pkgconfig/:$PKG_CONFIG_PATH
-\end{verbatim}
-
-%$ --- Emacs needs this to balance out the dollar signs
-
-Here, \code{config.guess} is the common GNU script for guessing the
-build system triplet (e.g., \code{i686-pc-linux-gnu}).
-
-There are a couple of notes:
-\begin{itemize}
-\item To compile a binary, simply do \code{./configure}, then
-  \code{make && make install}.
-\item \code{Ohana} doesn't like this setup, so you need to build it
-  with: \code{\./configure --prefix=$SWDIR}
-\item Perl modules can be installed: \code{./Build install
-  --prefix=$SWDIR}.
-\end{itemize}
-
-\subsection{Manual Perl Module Installation}
-
-Here we describe setting up the Perl dependencies followed by the
-IPP components.
-
-\subsubsection{Dependencies}
-\label{sec:installing-perl-dependencies}
-
-If you have access to the \code{root} account, installation as
-\code{root} is much easier.  If not, you will have to go through
-the more flaky installation as an unprivileged user.
-
-\subsubsubsection{Installation as root}
-
-Many of the Perl dependencies are available from the Comprehensive
-Perl Archive Network (CPAN) at www.cpan.org.  If you have root access
-on your target machines, they can be very simply retrieved, built and
-installed (replacing \code{MODULE_NAME} for each module):
-
-\begin{verbatim}
-> su -
-Password:
-> cpan
-[...]
-cpan> install MODULE_NAME
-[...]
-cpan> quit
-\end{verbatim}
-
-Follow the prompts.  It's usually safe to accept the default (simply
-hit enter) in response to most questions.
-
-If you get into trouble, try: \code{force install MODULE_NAME}.
-
-You can also try to use the \code{Bundle::PS} as described below if
-you're feeling adventurous.
-
-\subsubsubsection{Installation as unprivileged user}
-
-To install modules from CPAN with the \code{CPAN.pm} interface, you
-need to setup a CPAN configuration file in your home directory.  Then
-\code{CPAN.pm} can walk you through setting up the most important
-configuration values.  Unfortunately, there is some variation in the
-behavior of the various versions of \code{CPAN.pm} that have shipped
-with Perl.  Some (most) of these variants will not correctly create a
-configuration files that allows a non-\code{root} user to install
-modules outside of "system" paths.  In order to make sure that you get
-a "correct" CPAN configuration file you need to ``prime'' it with a
-few values.
-
-First you need to create the directory in which the CPAN configuration file will live.
-\begin{verbatim}
-> mkdir -p .cpan/CPAN/
-\end{verbatim}
-
-Then we need to create a partial configuration file.  Note that this example
-assumes that you want to install your perl modules under
-\code{$HOME/local/lib/perl5}.
-
-\begin{verbatim}
-> echo "\$CPAN::Config = {" >> .cpan/CPAN/MyConfig.pm
-> echo "  makepl_arg => q[PREFIX=$HOME/local/]," >> .cpan/CPAN/MyConfig.pm
-> echo "  mbuildpl_arg => q[--install_base $HOME/local/]," >> .cpan/CPAN/MyConfig.pm
-> echo "};" >> .cpan/CPAN/MyConfig.pm
-> echo "1;" >> .cpan/CPAN/MyConfig.pm
-> echo "__END__" >> .cpan/CPAN/MyConfig.pm
-\end{verbatim}
-
-%$ --- Emacs needs this to balance the previous dollar sign
-
-Now you need to invoke \code{CPAN.pm} so it can walk you through
-configuring the rest of the required values.  This is an example of
-one possible configuration with \code{CPAN.pm} version 1.8802.
-\textbf{Your version of CPAN.pm may present you with different
-prompts.}  Use your common sense.  If in doubt, it is generally safe
-to simply hit enter (and accept the default).
-
-\begin{verbatim}
-> perl -MCPAN -e shell
-CPAN: File::HomeDir loaded ok
-Sorry, we have to rerun the configuration dialog for CPAN.pm due to
-the following indispensable but missing parameters:
-
-build_cache, build_dir, cache_metadata, cpan_home, ftp_proxy, http_proxy,
-index_expire, inhibit_startup_message, keep_source_where, make_arg,
-make_install_arg, mbuild_arg, mbuild_install_arg, mbuild_install_build_command,
-no_proxy, prerequisites_policy, scan_cache, urllist
-
-
-The following questions are intended to help you with the
-configuration. The CPAN module needs a directory of its own to cache
-important index files and maybe keep a temporary mirror of CPAN files.
-This may be a site-wide directory or a personal directory.
-
-
-
-I see you already have a  directory
-    /home/moanui/jhoblitt/.cpan
-Shall we use it as the general CPAN build and cache directory?
-
-CPAN build and cache directory? [/home/moanui/jhoblitt/.cpan]
-
-
-Unless you are accessing the CPAN via the filesystem directly CPAN.pm
-needs to keep the source files it downloads somewhere. Please supply a
-directory where the downloaded files are to be kept. [/home/moanui/jhoblitt/.cpan/sources]
-Directory where the build process takes place? [/home/moanui/jhoblitt/.cpan/build]
-
-
-How big should the disk cache be for keeping the build directories
-with all the intermediate files?
-
-Cache size for build directory (in MB)? [100]
-
-
-The CPAN indexes are usually rebuilt once or twice per hour, but the
-typical CPAN mirror mirrors only once or twice per day. Depending on
-the quality of your mirror and your desire to be on the bleeding edge,
-you may want to set the following value to more or less than one day
-(which is the default). It determines after how many days CPAN.pm
-downloads new indexes.
-
-Let the index expire after how many days? [1]
-
-
-By default, each time the CPAN module is started, cache scanning is
-performed to keep the cache size in sync. To prevent this, answer
-'never'.
-
-Perform cache scanning (atstart or never)? [atstart]
-
-
-To considerably speed up the initial CPAN shell startup, it is
-possible to use Storable to create a cache of metadata. If Storable
-is not available, the normal index mechanism will be used.
-
-Cache metadata (yes/no)? [yes]
-
-
-The CPAN module can detect when a module which you are trying to build
-depends on prerequisites. If this happens, it can build the
-prerequisites for you automatically ('follow'), ask you for
-confirmation ('ask'), or just ignore them ('ignore'). Please set your
-policy to one of the three values.
-
-Policy on building prerequisites (follow, ask or ignore)? [ask] follow
-
-
-Every Makefile.PL is run by perl in a separate process. Likewise we
-run 'make' and 'make install' in separate processes. If you have
-any parameters (e.g. PREFIX, LIB, UNINST or the like) you want to
-pass to the calls, please specify them here.
-
-If you don't understand this question, just press ENTER.
-Parameters for the 'make' command?
-Typical frequently used setting:
-
-    -j3              # dual processor system
-
-Your choice:  []
-Parameters for the 'make install' command?
-Typical frequently used setting:
-
-    UNINST=1         # to always uninstall potentially conflicting files
-
-Your choice:  [] UNINST=1
-
-
-The next questions deal with Module::Build support.
-
-A Build.PL is run by perl in a separate process. Likewise we run
-'./Build' and './Build install' in separate processes. If you have any
-parameters you want to pass to the calls, please specify them here.
-
-Parameters for the './Build' command?
-Setting might be:
-
-    --extra_linker_flags -L/usr/foo/lib  # non-standard library location
-
-Your choice:  []
-Do you want to use a different command for './Build install'?
-Sudo users will probably prefer:
-
-    su root -c ./Build
-or
-    sudo ./Build
-or
-    /path1/to/sudo -u admin_account ./Build
-
-or some such. Your choice:  [./Build]
-Parameters for the './Build install' command?
-Typical frequently used setting:
-
-    --uninst 1                           # uninstall conflicting files
-
-Your choice:  [] --uninst 1
-
-
-If you're accessing the net via proxies, you can specify them in the
-CPAN configuration or via environment variables. The variable in
-the $CPAN::Config takes precedence.
-
-Your ftp_proxy? []
-Your http_proxy? []
-Your no_proxy? []
-You have no /home/moanui/jhoblitt/.cpan/sources/MIRRORED.BY
-  I'm trying to fetch one
-CPAN: LWP::UserAgent loaded ok
-Fetching with LWP:
-  http://www.perl.org/CPAN/MIRRORED.BY
-
-
-Now we need to know where your favorite CPAN sites are located. Push
-a few sites onto the array (just in case the first on the array won't
-work). If you are mirroring CPAN to your local workstation, specify a
-file: URL.
-
-First, pick a nearby continent and country by typing in the number(s)
-in front of the item(s) you want to select. You can pick several of
-each, separated by spaces. Then, you will be presented with a list of
-URLs of CPAN mirrors in the countries you selected, along with
-previously selected URLs. Select some of those URLs, or just keep the
-old list. Finally, you will be prompted for any extra URLs -- file:,
-ftp:, or http: -- that host a CPAN mirror.
-
-(1) Africa
-(2) Asia
-(3) Central America
-(4) Europe
-(5) North America
-(6) Oceania
-(7) South America
-Select your continent (or several nearby continents) [] 5
-
-(1) Bahamas
-(2) Canada
-(3) Mexico
-(4) United States
-Select your country (or several nearby countries) [] 4
-
-(1) ftp://carroll.cac.psu.edu/pub/CPAN/
-(2) ftp://cpan-du.viaverio.com/pub/CPAN/
-(3) ftp://cpan-sj.viaverio.com/pub/CPAN/
-(4) ftp://cpan.calvin.edu/pub/CPAN
-(5) ftp://cpan.cs.utah.edu/pub/CPAN/
-(6) ftp://cpan.cse.msu.edu/
-(7) ftp://cpan.erlbaum.net/CPAN/
-(8) ftp://cpan.glines.org/pub/CPAN/
-(9) ftp://cpan.hostrack.net/pub/CPAN
-(10) ftp://cpan.llarian.net/pub/CPAN/
-(11) ftp://cpan.mirrors.redwire.net/pub/CPAN/
-(12) ftp://cpan.mirrors.tds.net/pub/CPAN
-(13) ftp://cpan.netnitco.net/pub/mirrors/CPAN/
-(14) ftp://cpan.pair.com/pub/CPAN/
-(15) ftp://cpan.teleglobe.net/pub/CPAN
-(16) ftp://cpan.uchicago.edu/pub/CPAN/
-40 more items, hit RETURN to show them
-Select as many URLs as you like (by number),
-put them on one line, separated by blanks, hyphenated ranges allowed
- e.g. '1 4 5' or '7 1-4 8' [] 14 11 12
-
-Enter another URL or RETURN to quit: []
-New set of picks:
-  ftp://cpan.pair.com/pub/CPAN/
-  ftp://cpan.mirrors.redwire.net/pub/CPAN/
-  ftp://cpan.mirrors.tds.net/pub/CPAN
-
-
-Please remember to call 'o conf commit' to make the config permanent!
-
-
-cpan shell -- CPAN exploration and modules installation (v1.8802)
-ReadLine support enabled
-
- cpan[1]> o conf commit
-commit: wrote '/home/moanui/jhoblitt/.cpan/CPAN/MyConfig.pm'
-\end{verbatim}
-
-%$ --- Emacs needs this to balance the previous dollar sign
-
-Now we need to install the module that installs the other modules.
-
-\begin{verbatim}
-cpan> install Module::Build
-\end{verbatim}
-
-Exit out of cpan:
-
-\begin{verbatim}
-cpan> exit
-\end{verbatim}
-
-In order to use of the installed modules, we need to setup an
-environment variable called \code{PERL5LIB} so that 'perl' can find
-them.  To do this, we need to know where under 'perl5' our modules
-were actually installed.  This will set variable with the version of
-Perl that you are using.  The easiest way to do this is just just look
-in the root of the path where we did the install.
-
-\begin{verbatim}
-> ls local/lib/perl5/
-5.8.8  site_perl
-\end{verbatim}
-
-That means we're using perl 5.8.8 and \code{PERL5LIB} needs to be
-setup as following:
-\begin{verbatim}
-export PERL5LIB=$HOME/local/lib/perl5/5.8.8:$HOME/local/lib/perl5/site_perl/5.8.8
-\end{verbatim}
-
-Now we should install the basic compliment of helper modules that
-\code{CPAN.pm} needs to function fully.  Go back into CPAN (\code{perl
--MCPAN -e shell}) and:
-
-\begin{verbatim}
-cpan> install Bundle::CPAN
-\end{verbatim}
-
-You can quit out of the CPAN shell at this point with the `exit`
-command or do the following few steps in another shell We're ready to
-install the full set Perl module dependencies for IPP software.  In
-order to make this process a bit easier on the end user a "Bundle"
-module has been created.  In order to use it you need to create a
-directory (if it doesn't already exist) called Bundle under your .cpan
-directory.
-
-\begin{verbatim}
-> mkdir -p .cpan/Bundle
-\end{verbatim}
-
-The file \code{PS.pm} should copied into this directory:
-
-\begin{verbatim}
-cp /path/to/PS.pm .cpan/Bundle/
-\end{verbatim}
-
-Back in the CPAN shell, 'force' the install of the PS Bundle.  The
-'force' keyword instructs the shell to ignore any tests failures.
-This is necessary as some of the modules 'DBD::mysql'/etc. require a
-properly working database setup in order for the tests to pass.  You
-will most likely be prompted for input by several the modules.  It is
-safe to answer with a carriage return to all questions.  If it insists
-on a path to \code{httpd}, hit \code{CTRL-C} and it will go on to the
-next step.
-
-\begin{verbatim}
-cpan> force install Bundle:PS
-\end{verbatim}
-
-For further instructions on installing Perl modules from CPAN ''by
-hand', see:
-\begin{verbatim}
-http://www.cs.ucsc.edu/~you/notes/perl-module-install.html
-\end{verbatim}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%