System Requirements
===================

BCFtools and HTSlib depend on the following libraries:

  BCFtools:
    zlib       <http://zlib.net>
    gsl        <https://www.gnu.org/software/gsl/>
               (optional, for the 'polysomy' command)
    libperl    <http://www.perl.org/>
               (optional, to support filters using perl syntax)

  HTSlib:
    zlib       <http://zlib.net>
    libbz2     <http://bzip.org/>
    liblzma    <http://tukaani.org/xz/>
    libcurl    <https://curl.haxx.se/>
               (optional but strongly recommended, for network access)
    libcrypto  <https://www.openssl.org/>
               (optional, for Amazon S3 support; not needed on MacOS)

Building them requires development files to be installed on the build machine;
note that some Linux distributions package these separately from the library
itself.  See the "System Specific Details" below for guidance on how to install
these on a variety of systems.

The bzip2 and liblzma dependencies can be removed if full CRAM support
is not needed - see HTSlib's INSTALL file for details.

To build BCFtools, you will need:

    GNU make
    C compiler (e.g. gcc or clang)

In addition, building the configure script requires:

    autoheader
    autoconf

Running the configure script uses awk, along with a number of
standard UNIX tools (cat, cp, grep, mv, rm, sed, among others).  Almost
all installations will have these already.

Running the test harness (make test) uses:

    bash
    perl

Building Configure
==================

This step is only needed if configure.ac has been changed, or if configure
does not exist (for example, when building from a git clone).  The
configure script and config.h.in can be built by running:

    autoheader
    autoconf

If you have a full GNU autotools install, you can alternatively run:

    autoreconf

Warnings like "AC_CONFIG_SUBDIRS: you should use literals" can be ignored
or supressed using 'autoconf -Wno-syntax'.


Compilation
===========

'cd' to the bcftools directory containing the package's source and type:

    ./configure
    make

This BCFtools release contains a copy of HTSlib which will be used to build
BCFtools.  If you already have a system-installed HTSlib or another HTSlib
that you would prefer to build against, you can arrange this by using the
configure script's --with-htslib option.  Use --with-htslib=DIR to point
to an HTSlib source tree or installation in DIR; or --with-htslib=system
to use a system-installed HTSlib.


Optional Compilation with Perl
==============================

The '-i' and '-e' options can take external perl scripts for a more
sophisticated filtering. This option can be enabled by supplying the
--enable-perl-filters option to configure before running make:

    ./configure --enable-perl-filters

Optional Compilation with GSL
=============================

The 'polysomy' command depends on the GNU Scientific Library (GSL) and is not
enabled by default. In order to compile it, supply the --enable-libgsl
option to configure before running make:

    ./configure --enable-libgsl

The GNU Scientific Library depends on the cblas library.  The configure
script will look for both libcblas and libgslcblas, in that order.  If
you have more than one version of cblas installed and want to override its
choice you can do this by using either --with-cblas=cblas or
--with-cblas=gslcblas.

Note that GSL is distributed under the GNU General Public License (GPL).
When --enable-libgsl is used to compile bcftools, the resulting program
will also be GPL licensed.  If you want to distribute the program, you MUST
do so under terms compatible with that license.  A copy of the GPL is included
in the LICENSE file, or can be downloaded from
<http://www.gnu.org/copyleft/gpl.html>.

In the default compilation mode the program is dual licensed and you may
choose to be licensed under the terms of the MIT/Expat license or the
GNU General Public License (GPL).

Information on the GNU Scientific Library, including the rationale for
its choice of license can be found at <https://www.gnu.org/software/gsl/>.

Installation
============

Type 'make install' to install the bcftools executable and associated scripts
and a manual page.  The default is to install in /usr/local.  This can be
changed by using the configure script's --prefix option:

   ./configure --prefix=/path/to/install/dir

The install target also understands DESTDIR and the other usual installation
directory variables.

The bgzip and tabix utilities are provided by HTSlib.  If you have not also
installed HTSlib separately, you may wish to install these utilities by hand
by copying bcftools-1.x/htslib-1.x/{bgzip,tabix} to the same bin directory
to which you have installed bcftools et al.


System Specific Details
=======================

Installing the prerequisites is system dependent and there is more
than one correct way of satisfying these, including downloading them
from source, compiling and installing them yourself.

For people with super-user access, we provide an example set of commands
below for installing the dependencies on a variety of operating system
distributions.  Note these are not specific recommendations on distribution,
compiler or SSL implementation.  It is assumed you already have the core set
of packages for the given distribution - the lists may be incomplete if
this is not the case.

Debian / Ubuntu
---------------

sudo apt-get update  # Ensure the package list is up to date
sudo apt-get install autoconf automake make gcc perl zlib1g-dev libbz2-dev liblzma-dev libcurl4-gnutls-dev libssl-dev libperl-dev libgsl0-dev

Note: libcurl4-openssl-dev can be used as an alternative to libcurl4-gnutls-dev.

RedHat / CentOS
---------------

sudo yum install autoconf automake make gcc perl-Data-Dumper zlib-devel bzip2 bzip2-devel xz-devel curl-devel openssl-devel gsl-devel perl-ExtUtils-Embed

Alpine Linux
------------

sudo apk update  # Ensure the package list is up to date
sudo apk add autoconf automake make gcc musl-dev perl bash zlib-dev bzip2-dev xz-dev curl-dev libressl-dev gsl-dev perl-dev

OpenSUSE
--------

sudo zypper install autoconf automake make gcc perl zlib-devel libbz2-devel xz-devel libcurl-devel libopenssl-devel gsl-devel
