c_cpp/lib/htslib/INSTALL

   1                     Building and Installing HTSlib
   2                     ==============================
   3
   4 Requirements
   5 ============
   6
   7 Building HTSlib requires a few programs and libraries to be present.
   8 At least the following are required:
   9
  10     GNU make
  11     C compiler (e.g. gcc or clang)
  12
  13 In addition, building the configure script requires:
  14
  15     autoheader
  16     autoconf
  17
  18 Running the configure script uses awk, along with a number of
  19 standard UNIX tools (cat, cp, grep, mv, rm, sed, among others).  Almost
  20 all installations will have these already.
  21
  22 Running the test harness (make test) uses:
  23
  24     bash
  25     perl
  26
  27 HTSlib uses the following external libraries.  Building requires both the
  28 library itself, and include files needed to compile code that uses functions
  29 from the library.  Note that some Linux distributions put include files in
  30 a development ('-dev' or '-devel') package separate from the main library.
  31
  32     libz       (required)
  33     libbz2     (required, unless configured with --disable-bz2)
  34     liblzma    (required, unless configured with --disable-lzma)
  35     libcurl    (optional, but strongly recommended)
  36     libcrypto  (optional for Amazon S3 support; not needed on MacOS)
  37
  38 Disabling libbzip2 and liblzma will make some CRAM files unreadable, so
  39 is not recommended.
  40
  41 Using libcurl provides HTSlib with better network protocol support, for
  42 example it enables the use of https:// URLs.  It is also required if
  43 direct access to Amazon S3 or Google Cloud Storage is enabled.
  44
  45 Amazon S3 support requires an HMAC function to calculate a message
  46 authentication code.  On MacOS, the CCHmac function from the standard
  47 library is used.  Systems that do not have CChmac will get this from
  48 libcrypto.  libcrypto is part of OpenSSL or one of its derivatives (LibreSSL
  49 or BoringSSL).
  50
  51 Building Configure
  52 ==================
  53
  54 This step is only needed if configure.ac has been changed, or if configure
  55 does not exist (for example, when building from a git clone).  The
  56 configure script and config.h.in can be built by running:
  57
  58     autoheader
  59     autoconf
  60
  61 If you have a full GNU autotools install, you can alternatively run:
  62
  63     autoreconf
  64
  65 Basic Installation
  66 ==================
  67
  68 To build and install HTSlib, 'cd' to the htslib-1.x directory containing
  69 the package's source and type the following commands:
  70
  71     ./configure
  72     make
  73     make install
  74
  75 The './configure' command checks your build environment and allows various
  76 optional functionality to be enabled (see Configuration below).  If you
  77 don't want to select any optional functionality, you may wish to omit
  78 configure and just type 'make; make install' as for previous versions
  79 of HTSlib.  However if the build fails you should run './configure' as
  80 it can diagnose the common reasons for build failures.
  81
  82 The 'make' command builds the HTSlib library and and various useful
  83 utilities: bgzip, htsfile, and tabix.  If compilation fails you should
  84 run './configure' as it can diagnose problems with your build environment
  85 that cause build failures.
  86
  87 The 'make install' command installs the libraries, library header files,
  88 utilities, several manual pages, and a pkgconfig file to /usr/local.
  89 The installation location can be changed by configuring with --prefix=DIR
  90 or via 'make prefix=DIR install' (see Installation Locations below).
  91
  92
  93 Configuration
  94 =============
  95
  96 By default, './configure' examines your build environment, checking for
  97 requirements such as the zlib development files, and arranges for a plain
  98 HTSlib build.  The following configure options can be used to enable
  99 various features and specify further optional external requirements:
 100
 101 --enable-plugins
 102     Use plugins to implement exotic file access protocols and other
 103     specialised facilities.  This enables such facilities to be developed
 104     and packaged outwith HTSlib, and somewhat isolates HTSlib-using programs
 105     from their library dependencies.  By default (or with --disable-plugins),
 106     any enabled pluggable facilities (such as libcurl file access) are built
 107     directly within HTSlib.
 108
 109     The <https://github.com/samtools/htslib-plugins> repository contains
 110     several additional plugins, including the iRODS (<http://irods.org/>)
 111     file access plugin previously distributed with HTSlib.
 112
 113 --with-plugin-dir=DIR
 114     Specifies the directory into which plugins built while building HTSlib
 115     should be installed; by default, LIBEXECDIR/htslib.
 116
 117 --with-plugin-path=DIR:DIR:DIR...
 118     Specifies the list of directories that HTSlib will search for plugins.
 119     By default, only the directory specified via --with-plugin-dir will be
 120     searched; you can use --with-plugin-path='DIR:$(plugindir):DIR' and so
 121     on to cause additional directories to be searched.
 122
 123 --enable-libcurl
 124     Use libcurl (<http://curl.haxx.se/>) to implement network access to
 125     remote files via FTP, HTTP, HTTPS, etc.  By default, HTSlib uses its
 126     own simple networking code to provide access via FTP and HTTP only.
 127
 128 --enable-gcs
 129     Implement network access to Google Cloud Storage.  By default or with
 130     --enable-gcs=check, this is enabled when libcurl is enabled.
 131
 132 --enable-s3
 133     Implement network access to Amazon AWS S3.  By default or with
 134     --enable-s3=check, this is enabled when libcurl is enabled.
 135
 136 --disable-bz2
 137     Bzip2 is an optional compression codec format for CRAM, included
 138     in HTSlib by default.  It can be disabled with --disable-bz2, but
 139     be aware that not all CRAM files may be possible to decode.
 140
 141 --disable-lzma
 142     LZMA is an optional compression codec for CRAM, included in HTSlib
 143     by default.  It can be disabled with --disable-lzma, but be aware
 144     that not all CRAM files may be possible to decode.
 145
 146 The configure script also accepts the usual options and environment variables
 147 for tuning installation locations and compilers: type './configure --help'
 148 for details.  For example,
 149
 150     ./configure CC=icc --prefix=/opt/icc-compiled
 151
 152 would specify that HTSlib is to be built with icc and installed into bin,
 153 lib, etc subdirectories under /opt/icc-compiled.
 154
 155
 156 Installation Locations
 157 ======================
 158
 159 By default, 'make install' installs HTSlib libraries under /usr/local/lib,
 160 HTSlib header files under /usr/local/include, utility programs under
 161 /usr/local/bin, etc.  (To be precise, the header files are installed within
 162 a fixed 'htslib' subdirectory under the specified .../include location.)
 163
 164 You can specify a different location to install HTSlib by configuring
 165 with --prefix=DIR or specify locations for particular parts of HTSlib by
 166 configuring with --libdir=DIR and so on.  Type './configure --help' for
 167 the full list of such install directory options.
 168
 169 Alternatively you can specify different locations at install time by
 170 typing 'make prefix=DIR install' or 'make libdir=DIR install' and so on.
 171 Consult the list of prefix/exec_prefix/etc variables near the top of the
 172 Makefile for the full list of such variables that can be overridden.
 173
 174 You can also specify a staging area by typing 'make DESTDIR=DIR install',
 175 possibly in conjunction with other --prefix or prefix=DIR settings.
 176 For example,
 177
 178     make DESTDIR=/tmp/staging prefix=/opt
 179
 180 would install into bin, lib, etc subdirectories under /tmp/staging/opt.