This package contains scripts that make it easy to build the HSC Analysis Pipeline.

Table of contents
=================
    - How to use
    - Offline install
    - Comments
    - Troubleshooting

How to use
==========

1. Preparation
    Read builder/pre-build.sh to prepare required packages by yum,
    apt-get, zypper, etc.

    Then, make a working directory anywhere you like.
    All later commands must be invoked from this directory.
    If /dev/shm is available and is larger than 8GB, we recommend
    that you use /dev/shm.

    [user@host ~]$ mkdir /dev/shm/work
    [user@host ~]$ cd /dev/shm/work

    Run builder/configure:

    [user@host work]$ /WHERE/SCRIPTS/ARE/configure --help
    [user@host work]$ /WHERE/SCRIPTS/ARE/configure --prefix=$HOME/ana/products

2 Build
    After the above preparation, run build.sh. The current directory
    must be the working directory you have made.

    [user@host work]$ bash build.sh

3 If the build fail
    After some remedy, you can start the build script build.sh again.
    The script will automatically skip what have succeeded in install.

    If you want to re-install forcibly what has already been 'succeeded'
    in install, you have to modify $builddir/progress.txt before re-executing
    build.sh.  If 'done###=true' in $builddir/progress.txt, the corresponding
    block in build.sh is skipped.

4 Post-build
    The purpose of this process (post-build.sh) is basically to make
    the installed tree relocatable for public distribution.  But even
    if you are not to make a distributable binary, still
        YOU MUST *ALWAYS* DO POST-BUILD.
    Otherwise, the built python will not work.

    [user@host work]$ bash post-build.sh

5 Post-install
    DO NOT execute post-install.sh if you have built the pipeline for
    yourself.  It is for users of a binary package.

Offline install
===============
    By default, the build and installation are done online: sources are
    downloaded from the Internet as needed.  However, in some restrictive
    environments, any accesses to (as well as from) outside are simply
    prohibited: https://, ftp://, git://, etc., for the cheapest security.
    This section copes with this problem.

    First, in another environment where accesses to outside are free,
    download sources that are needed.  Follow the instruction in [How to use]
    except you must run configure with --network-log= and --source-dir=

    [user@host work]$ /WHERE/SCRIPTS/ARE/configure \
        --prefix=/dev/shm/trash \
        --network-log=$PWD/network.log \
        --source-dir=/dev/shm/sources

    Once you finish post-build, you will have $PWD/network.log in
    which detected network accesses will have been written.

    Second, download the sources according to $PWD/network.log:

        bash download-sources.sh

    Sources will be stored in /dev/shm/sources.

    Third, copy /dev/shm/sources to the machine where you truely want to
    install the pipeline.

    Fourth, in the machine where you truely want to install the pipeline,
    follow the instruction in [How to use] except you must run configure
    with --source-dir=

    [user@host work]$ /WHERE/SCRIPTS/ARE/configure \
        --prefix=$HOME/ana/products \
        --source-dir="/WHERE/YOU/HAVE/COPIED/SOURCES/TO"

    The installer will use {source-dir} instead of the Internet.

    This functionality is incomplete: the installer will still access
    http:// due to python's easy_install.


Comments
============

$ bin/curl
    This is an alternative for the system's curl.  It appropriately sets
    User-Agent of HTTP headers.  With the curl's default User-Agent (and
    those which are used by build scripts of some of the constituent packages)
    GET requests are sometimes rejected.

$ fix_meas_mosaic
    OBSOLETE
    This is a quick-fix module that prevents MKL from SEGV.

$ fix_shellshock
    OBSOLETE
    This is a quick-fix that cope with the change in bash that was made
    due to the shell-shock vulnerability.

$ openblas
    This is an alternative to the Math Kernel Library, which seems to have
    ceased being available for free of charge.

$ updates
    This directory contains build files for later versions of third party
    libraries.

$ toppings
    This directory contains scripts with which users can install extra
    packages if they want them.

$ mybuilds/astrometry_net-0.30a_hsc.build
    OBSOLETE
    The header files that this package will install will interfere with lots
    of other packages to make them fail in build.
    This modified version installs the header files in a directory different
    from install/ so that other packages cannot see them.

$ mybuilds/atlas-3.10.1a_hsc.build
    OBSOLETE
    This modified version produces a truely optimized library.
    The default build file uses no-optimize (-O0) switch.

$ mybuilds/libjpeg-9.build
    This modified version installs README file into its install directory
    to make it re-distributable.

$ mybuilds/meas_astrom-HSC-2.8.0g_hsc.build
    OBSOLETE
    Since astrometry_net does not install header files properly (on purpose;
    see mybuilds/astrometry_net-0.30a_hsc.build), we have to cope with it.

$ mybuilds/meas_astrom-HSC-2.8.0h_hsc.build
    OBSOLETE
    See mybuilds/meas_astrom-HSC-2.8.0g_hsc.build

$ mybuilds/python-2.7.6.build
    This modified version enables python 2.7.6 to be built with a late
    readline.

$ mybuilds/toolchain-3.0.manifest
    The default manifest file is corrupted.

Troubleshooting
===============

- Doxygen doesn't compile.  The error message says something is wrong with flex.

    Your flex is too old.  Install the latest one from the source.
    If you have done ./configure --prefix=DIR, then modify config.rc as:

        -systemPath=/usr/bin:/bin
        +systemPath=DIR:/usr/bin:/bin

End
