1 Building and Installing HTSlib 2 ============================== 3 4Requirements 5============ 6 7Building HTSlib requires a few programs and libraries to be present. 8At least the following are required: 9 10 GNU make 11 C compiler (e.g. gcc or clang) 12 13In addition, building the configure script requires: 14 15 autoheader 16 autoconf 17 18Running the configure script uses awk, along with a number of 19standard UNIX tools (cat, cp, grep, mv, rm, sed, among others). Almost 20all installations will have these already. 21 22Running the test harness (make test) uses: 23 24 bash 25 perl 26 27HTSlib uses the following external libraries. Building requires both the 28library itself, and include files needed to compile code that uses functions 29from the library. Note that some Linux distributions put include files in 30a 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 38Disabling libbzip2 and liblzma will make some CRAM files unreadable, so 39is not recommended. 40 41Using libcurl provides HTSlib with better network protocol support, for 42example it enables the use of https:// URLs. It is also required if 43direct access to Amazon S3 or Google Cloud Storage is enabled. 44 45Amazon S3 support requires an HMAC function to calculate a message 46authentication code. On MacOS, the CCHmac function from the standard 47library is used. Systems that do not have CChmac will get this from 48libcrypto. libcrypto is part of OpenSSL or one of its derivatives (LibreSSL 49or BoringSSL). 50 51Building Configure 52================== 53 54This step is only needed if configure.ac has been changed, or if configure 55does not exist (for example, when building from a git clone). The 56configure script and config.h.in can be built by running: 57 58 autoheader 59 autoconf 60 61If you have a full GNU autotools install, you can alternatively run: 62 63 autoreconf 64 65Basic Installation 66================== 67 68To build and install HTSlib, 'cd' to the htslib-1.x directory containing 69the package's source and type the following commands: 70 71 ./configure 72 make 73 make install 74 75The './configure' command checks your build environment and allows various 76optional functionality to be enabled (see Configuration below). If you 77don't want to select any optional functionality, you may wish to omit 78configure and just type 'make; make install' as for previous versions 79of HTSlib. However if the build fails you should run './configure' as 80it can diagnose the common reasons for build failures. 81 82The 'make' command builds the HTSlib library and and various useful 83utilities: bgzip, htsfile, and tabix. If compilation fails you should 84run './configure' as it can diagnose problems with your build environment 85that cause build failures. 86 87The 'make install' command installs the libraries, library header files, 88utilities, several manual pages, and a pkgconfig file to /usr/local. 89The installation location can be changed by configuring with --prefix=DIR 90or via 'make prefix=DIR install' (see Installation Locations below). 91 92 93Configuration 94============= 95 96By default, './configure' examines your build environment, checking for 97requirements such as the zlib development files, and arranges for a plain 98HTSlib build. The following configure options can be used to enable 99various 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 146The configure script also accepts the usual options and environment variables 147for tuning installation locations and compilers: type './configure --help' 148for details. For example, 149 150 ./configure CC=icc --prefix=/opt/icc-compiled 151 152would specify that HTSlib is to be built with icc and installed into bin, 153lib, etc subdirectories under /opt/icc-compiled. 154 155 156Installation Locations 157====================== 158 159By default, 'make install' installs HTSlib libraries under /usr/local/lib, 160HTSlib header files under /usr/local/include, utility programs under 161/usr/local/bin, etc. (To be precise, the header files are installed within 162a fixed 'htslib' subdirectory under the specified .../include location.) 163 164You can specify a different location to install HTSlib by configuring 165with --prefix=DIR or specify locations for particular parts of HTSlib by 166configuring with --libdir=DIR and so on. Type './configure --help' for 167the full list of such install directory options. 168 169Alternatively you can specify different locations at install time by 170typing 'make prefix=DIR install' or 'make libdir=DIR install' and so on. 171Consult the list of prefix/exec_prefix/etc variables near the top of the 172Makefile for the full list of such variables that can be overridden. 173 174You can also specify a staging area by typing 'make DESTDIR=DIR install', 175possibly in conjunction with other --prefix or prefix=DIR settings. 176For example, 177 178 make DESTDIR=/tmp/staging prefix=/opt 179 180would install into bin, lib, etc subdirectories under /tmp/staging/opt. 181