Building GenomeTools
--------------------

Invoke GNU make, e.g.:

$ make [argument ...]

to build GenomeTools. You need at least version 3.80 of GNU make, you can check
which version you have by invoking

$ make --version

On *BSD GNU make is often called ``gmake''.

Possible arguments:

- 64bit=no         to compile a 32-bit version
- 32bit=yes        to compile a 32-bit version
- opt=no           to disable optimization
- assert=no        to disable assertions
- amalgamation=yes to compile as an amalgamation
- cairo=no         to disable AnnotationSketch, dropping Cairo/Pango deps
- errorcheck=no    to disable the handling of compiler warnings as errors
- useshared=yes    to use the system's shared libraries
- verbose=yes      to make the build more verbose


Example call to build GenomeTools without assertions on a system where GNU make
is called ``gmake'':

$ gmake assert=no

Please remember to always run `make cleanup' before rebuilding with changed make
parameters!


Building GenomeTools without the sketch tool:
---------------------------------------------

The AnnotationSketch engine requires the Cairo and Pango headers and libraries
to be installed in order to build GenomeTools. Please consult your operating
system's package manager for more information on how to install these. For
example, on Debian the packages ``libcairo2-dev'' and ``libpango1.0-dev'' must
be installed.
If Cairo and/or Pango headers are not installed on the system, and
AnnotationSketch support is not required, GenomeTools can be built without
graphics support by invoking make as above with the argument `cairo=no'.


Building GenomeTools on macOS:
-------------------------------------------

Make sure the command line developer tools are installed:

$ xcode-select --install

With these installed, you are ready to build GenomeTools without
AnnotationSketch support (cairo=no). To build GenomeTools with AnnotationSketch,
you can use Homebrew (http://brew.sh) to install the necessary dependencies
required for building:

$ brew install pango cairo libffi pkg-config

To start the build process, invoke make as stated above. You might need to set
the PKG_CONFIG_PATH environment variable to /usr/local/opt/libffi/lib/pkgconfig.


Building GenomeTools on Windows (using Cygwin):
-----------------------------------------------

Building GenomeTools with gcc on Windows occasionally results in a warning
regarding the '-fPIC' parameter. This can be ignored without problems. To ignore
this warning, please append the errorcheck=no option to your make call. All
other options given in this file can still be used.


Building GenomeTools using external shared libraries:
-----------------------------------------------------

The GenomeTools source distribution comes with the source code for some of the
external software it uses internally. This makes it easier to build a stand-alone
version of GenomeTools on a system that does not have these installed system-wide.
Another approach is to use the system provided copies of these libraries. This
makes any updates to these libraries, e.g. fixing bugs and security issues,
immediately available to GenomeTools without the need to recompile. For packaging
GenomeTools into distributions and pipeline containers, this should be the
preferred option.
Use the 'useshared=yes' make option to ignore the embedded code copies in the
GenomeTools source distribution and to use the system-wide versions. The following
libraries (and their development headers) are required to be present:

 - zlib (https://zlib.net/)
   Debian/Ubuntu: zlib1g-dev
 - bzlib2 (https://www.sourceware.org/bzip2/)
   Debian/Ubuntu: libbz2-dev
 - liblua5.1 (https://www.lua.org/)
   Debian/Ubuntu: liblua5.1-0-dev
 - lua-filesystem (https://keplerproject.github.io/luafilesystem/)
   Debian/Ubuntu: lua-filesystem-dev
 - lua-lpeg (http://www.inf.puc-rio.br/~roberto/lpeg/)
   Debian/Ubuntu: lua-lpeg-dev
 - lua-md5 (https://keplerproject.github.io/md5/)
   Debian/Ubuntu: lua-md5-dev
 - libexpat (https://github.com/libexpat/libexpat)
   Debian/Ubuntu: libexpat1-dev
 - libtre (https://github.com/laurikari/tre/)
   Debian/Ubuntu: libtre-dev
 - libcairo (only unless 'cairo=no' is used) (https://cairographics.org/)
   Debian/Ubuntu: libcairo2-dev
 - libpango (only unless 'cairo=no' is used) (https://www.pango.org/)
   Debian/Ubuntu: libpango1.0-dev
 - libsqlite3 (https://www.sqlite.org/)
   Debian/Ubuntu: libsqlite3-dev
 - libbam (http://www.htslib.org/)
   Debian/Ubuntu: libbam-dev


Testing GenomeTools (optional)
------------------------------

Call

$ make test

to make sure your GenomeTools build went fine. This step requires an installed
Ruby 1.8 interpreter (see http://www.ruby-lang.org/en/ for informations on
Ruby).

Please note that all make options given during the compilation must be repeated
in the `make test' invocation. For example, if you compiled GenomeTools with
the '64bit=no cairo=no' options, the correct installation command would be:

# make 64bit=no cairo=no test


Installing GenomeTools
----------------------

To install the ``gt'' binary and the ``libgenometools'' library
(plus header files) on your system invoke

$ make install

Per default the files are installed under /usr/local. You can change this with
the prefix argument. For example, to install under /usr, invoke

# make prefix=/usr install

Please note that all make options given during the compilation must be
given in the `make install' invocation again. For example, if you compiled
GenomeTools with the '64bit=no cairo=no' options, the correct installation
command would be:

# make prefix=/usr 64bit=no cairo=no install

Omitting these options is likely to lead to problems during installation.


Final note
-----------

Please look at http://genometools.org for updates and report bugs if you
encounter any.

Enjoy!