source: trunk/README

Last change on this file was 3999, checked in by Peter, 16 months ago

update copyright years

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
  • Property svn:mime-type set to text/x-trac-wiki
File size: 9.5 KB
RevLine 
[2734]1$Id: README 3999 2020-10-08 23:22:32Z peter $
[2]2
[1939]3= About yat =
[573]4
[1939]5This directory contains the yat library. For an overview of the
6project, visit
[2733]7
[1939]8    http://dev.thep.lu.se/yat
[573]9
[1939]10
11= Configuring and building yat =
12
[1262]13 1. If you checked out this project from the subversion repository you
14    must run '`bootstrap`' to initialize the build system.
15 2. Issue '`./configure`' to create the Makefiles. Optionally run
16    configure with '`--enable-debug`', which will turn on debug
17    options.
18 3. Compile with '`make`'.
[2213]19 4. '`make doc`' will generate documentation.
20 5. Optionally do '`make check`' to run test programs.
[1303]21 6. Issue '`make install`' to install the package on your system,
22    documentation will not be installed if documentation was not
[1939]23    generated above. Default installation location is `/usr/local`;
[1303]24    this can be changed with
25    '`./configure --prefix=/dir/to/install/to`'.
[2437]26 7. Optionally do '`make installcheck`' to verify that intallation
27    completed correctly.
[573]28
[1939]29The `configure` script has additional options; `./configure --help`
30will offer you those choices or refer to Requirements below.
[848]31
[3734]32= Compile Flag Variables =
33
34Compile flags (`CPPFLAGS` (preprocessor), `CXXFLAGS` (compiler),
35and LDFLAGS` (linker)) can be set at via configure, e.g.:
36
37  #> ./configure CPPFLAGS=-I/my/local/path/include
38
39This setting will be used both when building the source into libyat as
40well as propagated into script `yat-config`. If you only want the
41variable propagated to `yat-config`, you can instead set variables
42with prefix `YAT_CONFIG_`:
43
44
45  #> ./configure YAT_CONFIG_CXXFLAGS=
46
47Similarly, if you only want the variable used when building libyat,
48and not propagated to output of `yat-config` or `pkg-config`, you can
49use flags with prefix `INTERNAL_`:
50
51  #> ./configure INTERNAL_CXXFLAGS="-g 03"
52
[1059]53= Requirements =
54
[3939]55From version 0.18, yat needs a C++11 compliant compiler to build. In
56addition, there are a few packages and programs required for compiling
57yat and generate supporting material. The configure script will look
58for required programs and report failure to meet the
59requirements. Here we list some of the requirements, but omit required
60standard utilities such as echo and sed since these are normally
61available.
[1059]62
[1262]63== Required packages ==
[1059]64
[1262]65=== GSL ===
[1059]66
[1262]67GNU Scientific Library, [http://www.gnu.org/software/gsl/ GSL] version
[3907]681.13 or later. If you have GSL installed in a non-standard location,
[2129]69`./configure --with-gsl=DIR` can be useful to provide the location of
70GSL. The `gsl-config` script, which is used to retrieve needed
71compiler and linker flags, is expected to be found in `DIR/bin/`. The
72check for existing GSL can be turned off with option
73`--without-gsl`. This can be useful, for example, if gsl-config is not
74available at configure time but header file will be available at make
75time.
[1059]76
[1262]77=== BLAS ===
[1059]78
[1262]79A C implementation of Basic Linear Algebra Subprograms
80([http://www.netlib.org/blas BLAS]) is required. GSL comes with a
81reference implementation, but you should consider getting a hardware
82optimized implementation. ATLAS provides optimized BLAS (see below).
[1059]83
[1939]84The `configure` script searches for many different BLAS libraries in a
[2019]85specific order (for details refer to `m4/yat_cblas.m4`). If you want
86to use a specific CBLAS library, `./configure --with-cblas=LIB` may be
[2028]87useful. Note, however, that the chosen/detected CBLAS library is not
88hard-coded into the installed libyat, but a user can choose a
[2029]89different CBLAS when she links her application. A way to access which
[2028]90CBLAS was detected during the configuration is to access the
91yat-config script directly or via the autoconf macros included in the
92distribution. If you do want to hard-code a choice of CBLAS into the
93installed libyat, you may provide the appropriate value to LIBS. The
94following line, for example:
[1939]95
[2733]96  #> ./configure LIBS=-lcblas
[2028]97
[2410]98will hard-code the choice of -lcblas into libyat.
[2028]99
[1325]100=== Boost ===
101
[2153]102[http://www.boost.org Boost] version 1.35 or later. If you have Boost
[1939]103installed in a non-standard location, `./configure --with-boost=DIR`
104can be useful to provide the location of Boost. Boost header files are
[2786]105expected to be found in `DIR/include/` and boost libraries are
[2916]106expected to be found in `DIR/lib/`. The `configure` script tries to
[3763]107detect libraries `boost_thread`, `boost_thread` and
108`boost_iostreams`. The name of a boost library typically depends on
109its configuration (see boost's naming convention) and there may be
110several versions/configurations of the same library installed. The
111`configure` tries to pick one of the available libraries, wchih can be
112overridden with `./configure --with-boost-thread=foo`, `configure
113--with-boost-system=foo`, and `--with-boost-iostreams=foo`,
[2916]114respectively. The check for boost can be turned off with
115`--without-boost`.
[1325]116
[1262]117=== quiet nan ===
[1059]118
[1262]119Quiet NaN's must be supported.
[1059]120
[1353]121=== infinity ===
122
123infinity for type double must be supported.
124
[1262]125== Optional packages ==
[1059]126
[3492]127=== HTSLIB and Samtools ===
[2943]128
[3883]129In order to enable functionality related to bam files htslib
130(http://www.htslib.org) must be available. Header file <htslib/sam.h>
131is required as well as 'libhts'. If you have header files installed
132outside compiler's search path (in e.g. '/path/to/htslib/sam.h', you
133can help the compiler with `./configure CPPFLAGS=-I/path/to`. If
134library is installed outside linker's search path, in e.g. `<libdir>`,
135you can run `./configure LDFLAGS=-L<lib dir>`. You can build yat
136without bam support by running `./configure --without-htslib`.
[2943]137
[3500]138The samtools program (version 1.2 or newer) is needed for some tests
[3483]139related to bam functionality. If samtools is not found by configure,
140these tests will be skipped. If you have samtools available outside
141PATH, you can help configure to find it with `./configure
142SAMTOOLS=/path/to/samtools`.
[3364]143
[3763]144The bcftools program is needed for some tests. If bcftools is not
145found by configure, these tests will be skipped. If you have bcftools
146available outside your PATH, you can help configure to find it with
147`./configure BCFTOOLS=/path/to/bcftools`.
148
[2943]149=== ZLIB ===
150
151Zlib available from http://www.zlib.net/ is required to build samtools
152and consequently needed to build yat too, unless you turn off samtools
153support (please refer to samtools section above). Header file `zlib.h`
154and library libz are required. If installed in an unconventional
155location you can help the compiler/linker with `CPPFLAGS=-I<include
156dir>` and `LDFLAGS=-L<lib dir>`, respectively.
157
[1262]158=== ATLAS ===
159
[1059]160GSL supplies a reference implementation of BLAS. You may want to
[1262]161consider using hardware optimized BLAS. The
162[http://math-atlas.sourceforge.net/ ATLAS] software provides an
163automatic hardware optimized BLAS library.
[1059]164
165The detection of ATLAS is supported by the yat configuration script
166but in many cases the ATLAS libraries are installed in
[1262]167non-conventional directory locations. As an example, on Fedora 8,
168ATLAS libraries are
[1059]169located in /usr/lib/atlas or /usr/lib64/atlas depending on your
170hardware architecture. If you have ATLAS installed and the configure
171script fails to locate it, try to add the location to the atlas
[1078]172libraries when running configure:
[1059]173
[2733]174  #> ./configure LDFLAGS="-L/usr/lib64/atlas"
[1059]175
[3939]176=== C++11 Compliant Compiler ===
[3581]177
[3939]178The configure script will test that the compiler is in C++11 mode and
179supports features such as rvalue and std::atomic. If you run configure
180with option --enable-cxx11
[3581]181
[3602]182  #> ./configure --enable-cxx11
[3581]183
[3939]184and the compiler is not in C++11 mode, the configure script will try
185different options such as '-std=cxx11' to turn on support for C++11
186features.
[3581]187
[1262]188=== Doxygen ===
[1059]189
[1442]190[http://www.doxygen.org/ Doxygen] 1.5 (or newer) is required for
[2557]191generation of the API documentation. If doxygen application is
[3823]192missing, generation of API documentation is disabled. You can turn off
193doxygen usage with
[1262]194
[3823]195  #> ./configure DOXYGEN=no
196
[1272]197= Documentation =
[1262]198
[2488]199The API documentation for the latest release is available in HTML and
200can be found through http://dev.thep.lu.se/yat. If you wish to build a
201local copy, issue `make doc` and you will find the documents in
[2870]202directory `doc/html/`.
[1262]203
[1368]204= Developers =
205
[2733]206See file README.developer for developer specific information.
[1368]207
[2080]208= Mac OS X =
209
210On Mac OS X you can create a universal library, a library that works
211on multiple systems. You can do this by specifying multiple `-arch`
212options to the compiler (but not to the preprocessor):
213
214 #> ./configure CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
215                CXXCPP="g++ -E" --disable-dependency-tracking
216
217This will produce a universal yat library with 4 architectures. If
218your OS X does not support both Power-PC and Intel-based processors,
219you can omit these architectures. Also, required libraries, GSL and
220CBLAS, need to be available as universal libraries with desired
221architectures.
222
[1262]223----------------------------------------------------------------------
224{{{
[2119]225Copyright (C) 2003 Jari Häkkinen, Peter Johansson
226Copyright (C) 2004 Jari Häkkinen
227Copyright (C) 2006, 2007, 2008 Jari Häkkinen, Peter Johansson
[3999]228Copyright (C) 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Peter Johansson
[1262]229
[1437]230This file is part of yat library, http://dev.thep.lu.se/yat
[1262]231
232The yat library is free software; you can redistribute it and/or
233modify it under the terms of the GNU General Public License as
[1486]234published by the Free Software Foundation; either version 3 of the
[1262]235License, or (at your option) any later version.
236
237The yat library is distributed in the hope that it will be useful, but
238WITHOUT ANY WARRANTY; without even the implied warranty of
239MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
240General Public License for more details.
241
242You should have received a copy of the GNU General Public License
[1487]243along with yat. If not, see <http://www.gnu.org/licenses/>.
[1262]244}}}
Note: See TracBrowser for help on using the repository browser.