source: trunk/README @ 3439

$Id: README 3439 2015-11-20 05:41:52Z peter $

= About yat =

This directory contains the yat library. For an overview of the
project, visit

    http://dev.thep.lu.se/yat


= Configuring and building yat =

 1. If you checked out this project from the subversion repository you
    must run '`bootstrap`' to initialize the build system.
 2. Issue '`./configure`' to create the Makefiles. Optionally run
    configure with '`--enable-debug`', which will turn on debug
    options.
 3. Compile with '`make`'.
 4. '`make doc`' will generate documentation.
 5. Optionally do '`make check`' to run test programs.
 6. Issue '`make install`' to install the package on your system,
    documentation will not be installed if documentation was not
    generated above. Default installation location is `/usr/local`;
    this can be changed with
    '`./configure --prefix=/dir/to/install/to`'.
 7. Optionally do '`make installcheck`' to verify that intallation
    completed correctly.

The `configure` script has additional options; `./configure --help`
will offer you those choices or refer to Requirements below.

= Requirements =

Except for the obviously needed C++ compiler there are a few packages
and programs required for compiling yat and generate supporting
material. The configure script will look for required programs and
report failure to meet the requirements. Here we list some of the
requirements, but omit required standard utilities such as echo and
sed since these are normally available.

== Required packages ==

=== GSL ===

GNU Scientific Library, [http://www.gnu.org/software/gsl/ GSL] version
1.8 or later. If you have GSL installed in a non-standard location,
`./configure --with-gsl=DIR` can be useful to provide the location of
GSL. The `gsl-config` script, which is used to retrieve needed
compiler and linker flags, is expected to be found in `DIR/bin/`. The
check for existing GSL can be turned off with option
`--without-gsl`. This can be useful, for example, if gsl-config is not
available at configure time but header file will be available at make
time.

=== BLAS ===

A C implementation of Basic Linear Algebra Subprograms
([http://www.netlib.org/blas BLAS]) is required. GSL comes with a
reference implementation, but you should consider getting a hardware
optimized implementation. ATLAS provides optimized BLAS (see below).

The `configure` script searches for many different BLAS libraries in a
specific order (for details refer to `m4/yat_cblas.m4`). If you want
to use a specific CBLAS library, `./configure --with-cblas=LIB` may be
useful. Note, however, that the chosen/detected CBLAS library is not
hard-coded into the installed libyat, but a user can choose a
different CBLAS when she links her application. A way to access which
CBLAS was detected during the configuration is to access the
yat-config script directly or via the autoconf macros included in the
distribution. If you do want to hard-code a choice of CBLAS into the
installed libyat, you may provide the appropriate value to LIBS. The
following line, for example:

  #> ./configure LIBS=-lcblas

will hard-code the choice of -lcblas into libyat.

=== Boost ===

[http://www.boost.org Boost] version 1.35 or later. If you have Boost
installed in a non-standard location, `./configure --with-boost=DIR`
can be useful to provide the location of Boost. Boost header files are
expected to be found in `DIR/include/` and boost libraries are
expected to be found in `DIR/lib/`. The `configure` script tries to
detect libraries `boost_thread` and `boost_thread`. The name of a
boost library typically depends on its configuration (see boost's
naming convention) and there may be several versions/configurations of
the same library installed. The `configure` tries to pick one of the
available libraries, wchih can be overridden with `./configure
--with-boost-thread=foo` and `configure --with-boost-system=foo`,
respectively. The check for boost can be turned off with
`--without-boost`.

=== quiet nan ===

Quiet NaN's must be supported.

=== infinity ===

infinity for type double must be supported.

== Optional packages ==

=== HTSLIB ===

In order to enable functionality related to bam files, either htslib
(http://www.htslib.org) or its predecessor samtools
(http://samtools.sourceforge.net) must be available. Header file
<sam.h> is required as well as either 'libhts' or 'libbam'. The configure
script will try to detect whether <sam.h> is available as 'sam.h',
'htslib/sam.h', 'bam/sam.h', or 'samtools/sam.h'. If you have header
files installed outside compiler's search path, you can help the
compiler with `./configure CPPFLAGS=-I<include dir>` when header files
are found in directory `<include dir>`. Configure detects whether
header files are from htslib or old samtools and looks for either
libhts or libbam accordingly. If library is installed outside linker's
search path, in `<libdir>`, you can run `./configure LDFLAGS=-L<lib
dir>`. You can build yat without bam support by running `./configure
--without-samtools`.

The samtools program is needed for some tests related to bam
functionality. If samtools is not found by configure, these tests will
be skipped. If you have samtools available outside PATH, you can help
configure to find it with `./configure SAMTOOLS=/path/to/samtools`.

=== ZLIB ===

Zlib available from http://www.zlib.net/ is required to build samtools
and consequently needed to build yat too, unless you turn off samtools
support (please refer to samtools section above). Header file `zlib.h`
and library libz are required. If installed in an unconventional
location you can help the compiler/linker with `CPPFLAGS=-I<include
dir>` and `LDFLAGS=-L<lib dir>`, respectively.

=== ATLAS ===

GSL supplies a reference implementation of BLAS. You may want to
consider using hardware optimized BLAS. The
[http://math-atlas.sourceforge.net/ ATLAS] software provides an
automatic hardware optimized BLAS library.

The detection of ATLAS is supported by the yat configuration script
but in many cases the ATLAS libraries are installed in
non-conventional directory locations. As an example, on Fedora 8,
ATLAS libraries are
located in /usr/lib/atlas or /usr/lib64/atlas depending on your
hardware architecture. If you have ATLAS installed and the configure
script fails to locate it, try to add the location to the atlas
libraries when running configure:

  #> ./configure LDFLAGS="-L/usr/lib64/atlas"

=== Doxygen ===

[http://www.doxygen.org/ Doxygen] 1.5 (or newer) is required for
generation of the API documentation. If doxygen application is
missing, generation of API documentation is disabled.

= Documentation =

The API documentation for the latest release is available in HTML and
can be found through http://dev.thep.lu.se/yat. If you wish to build a
local copy, issue `make doc` and you will find the documents in
directory `doc/html/`.

= Developers =

See file README.developer for developer specific information.

= Mac OS X =

On Mac OS X you can create a universal library, a library that works
on multiple systems. You can do this by specifying multiple `-arch`
options to the compiler (but not to the preprocessor):

 #> ./configure CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
                CXXCPP="g++ -E" --disable-dependency-tracking

This will produce a universal yat library with 4 architectures. If
your OS X does not support both Power-PC and Intel-based processors,
you can omit these architectures. Also, required libraries, GSL and
CBLAS, need to be available as universal libraries with desired
architectures.

----------------------------------------------------------------------
{{{
Copyright (C) 2003 Jari Häkkinen, Peter Johansson
Copyright (C) 2004 Jari Häkkinen
Copyright (C) 2006, 2007, 2008 Jari Häkkinen, Peter Johansson
Copyright (C) 2009, 2010, 2011, 2012, 2013, 2014, 2015 Peter Johansson

This file is part of yat library, http://dev.thep.lu.se/yat

The yat library is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 3 of the
License, or (at your option) any later version.

The yat 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.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with yat. If not, see <http://www.gnu.org/licenses/>.
}}}