Installing SINA
***************

You can install SINA

* using Bioconda (simple, recommended)

* from pre-compiled tarballs (alternative if conda is misbehaving
  for you)

* or build SINA from source (for developers)


Install using Bioconda
======================

SINA is available as a Conda package in the Bioconda channel. Check
the package info page for more information.

To install, follow these steps:

1. Install Miniconda (skip if you've got conda already)

   Download the Miniconda installer (links for MacOS and Linux),
   execute it and follow the instructions it shows in the shell:

      if test $(uname) == Linux; then
        wget https://repo.continuum.io/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
      else
        wget https://repo.continuum.io/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
      fi
      sh Miniconda3-lastest-*-x86_64.sh

2. Add the Conda-Forge and Bioconda channels:

      conda config --add channels defaults
      conda config --add channels bioconda
      conda config --add channels conda-forge

3. Install SINA into a conda environment:

      conda create -n sina sina

4. Activate and use environment:

      conda activate sina
      sina --help

SINA should also work fine if installed with conda into the "base"
environment. If you encounter problems, try the separate environment.


Install from pre-compiled tarballs
==================================

Tar archives containing pre-compiled binaries and requisite libraries
are available on the SINA releases page at Github. Head on over there
and download the Linux or Macos one. Inside the folder created by
unpacking the archive, you should find a *sina* executable:

   tar xf ~/Downloads/sina-1.4.0-linux.tar.gz
   ~/Downloads/sina-1.4.0-linux/sina --help

To install SINA system wide, place the contents of the archive in
*/opt* and create symlinks into */usr/local/bin*:

   wget https://github.com/epruesse/SINA/releases/download/v1.4.0/sina-1.4.0-linux.tar.gz
   sudo tar xf sina-1.4.0-linux.tar.gz -C /opt
   rm sina-1.4.0-linux.tar.gz
   sudo ln -s /opt/sina-1.4.0-linux /opt/sina
   sudo ln -s /opt/sina/bin/sina /usr/local/bin/sina


Build from source code
======================

Building SINA from source can be challenging because SINA depends on
the ARB development libraries. Pre-compiled versions of these are
currently only available from Bioconda, so you may have to start by
building ARB from source.


Prerequisites
-------------

When building from a source tar ball from the SINA releases page, you
will need to install:

* ARB >= 6.0.0

* Boost >= 1.62 - Boost Thread - Boost Program Options - Boost IO
  Streams - Boost Filesystem - Boost Serialization (SINA < 1.5) -
  Boost System - Boost Unit Test Framework (when building / running
  tests)

* TBB >= 2017

* zlib

When building from the raw git source code directly, you will
additionally need:

* Autoconf

* Automake

* Libtool

* pkg-config

To build the documentation, you need:

* Sphinx >= 1.8

The easiest way to get all requirements is using Conda:

   if test $(uname) == Linux; then
     dist_extra="gcc patchelf coreutils"
   else
     dist_extra="llvm"
   fi
   conda create -n sina_build automake autoconf libtool pkg-config boost arb-bio-devel \
                   git tbb tbb-devel glib libiconv bc sed sphinx $dist_extra


Building
--------

1. If you are building from git, start by checking out the source
   code and generating the *configure* script:

      git clone https://github.com/epruesse/SINA.git sina
      cd sina
      autoreconf --force --install

2. Run the configure script, pointing it at all required libraries
   as necessary and choosing features and build types:

      ./configure --prefix=install_location \
                  --with-arbhome=path_to_arbhome \
                  --with-boost=path_to_boost_install \
                  --with-boost-libdir=path_to_boost_libs

   If you used conda to install your dependencies, this line should
   work:

      conda activate sina_build
      mkdir build
      cd build
      ../configure --prefix `pwd`/install \
                   --disable-docs \
                   --with-tbb=$CONDA_PREFIX \
                   --with-boost=$CONDA_PREFIX \
                   --with-boost-libdir=$CONDA_PREFIX/lib \
                   --with-arbhome=$CONDA_PREFIX/lib/arb \
                   LDFLAGS="$LDFLAGS -Wl,-rpath,$CONDA_PREFIX/lib"

   Essential options to **configure**:

   --prefix=PATH (/usr/local)

      Set the folder under which "./bin/sina", "./lib/libsina.so" (or
      ".dylib"), etc. will be installed.

   --with-tbb=PATH

      Set the location of libraries and headers for the Intel
      Threading Building Blocks library.

   --with-boost=PATH

      Set the location of the boost header files (without the
      "include/" part).

   --with-boost-libdir=PATH

      Set the location of the boost lib folder. Often, this is the
      value you used for "--with-boost" with "/lib" appended.

   --with-arbhome=PATH

      Set the location of the ARB build directory. Not needed if you
      have "$ARBHOME" set to point to the place you built ARB. When
      using the Bioconda package *arb-bio-devel*, use
      *$CONDA_PREFOX/lib/arb* where "$CONDA_PREFIX" is the root of the
      environment you installed ARB into.

   --with-buildinfo=TEXT

      Set an additional string to be added to the version to identify
      your build.

   --enable-code-coverage

      Add compiler flags to collect code coverage statistics.

   --enable-debug

      Enable debug options (sets "-DDEBUG -O0 -ggdb3" instead of
      "-DNDEBUG -O2 -g").

   --enable-asan

      Enable address sanitizer (sets *-fsanitize=address*).

   --enable-fat-tar

      Alters the build so that "make bindist-gzip" constructs a fully
      contained tar archive of the build.

   --enable-profiling

      Add compiler flags collecting profiling statistics ("-pg").

   --disable-docs

      Do not build the documentation.

   If you installed the dependencies in system wide, standard FHS
   locations, the **configure** script should detect the locations
   correctly. Otherwise you may have to use the "--with-something"
   options to point it at the right places. If things go wrong, the
   full error messages will be in "config.log".

3. Build SINA (replace "<number of cpus" with however many cores
   you've got):

      make -j<number of cpus>
      make install

   To build binary archives (see also "--enable-fat-tar"), use:

      make bindist-gzip2

   To run unit tests, call:

      make check

   To run only part of the tests, call:

      make check-filtered P=pattern

   where "pattern" matches the name(s) of the test you wish to
   (re)run.

   To run unit tests collecting code coverage, call:

      make check-code-coverage

   To see the full command line of compiler and linker instead of the
   abbreviated display, append "V=1" to the "make" commandline.
