#

A Tour of NTL: Obtaining and Installing NTL for UNIX

The following procedures for building, installing, and using NTL work on most Unix or Unix-like platforms (including Linux, Mac OS, and Windows with MinGW or Cygwin tools) .

To obtain the source code and documentation for NTL, download `ntl-xxx.tar.gz`, placing it a directory, and then, working in this directory, do the following.

       % tar -xf ntl-xxx.tar.gz
       % cd ntl-xxx/src
       % ./configure [ variable=value ]...
       % make
       % make install

Here, "`xxx`" denotes the current version number.

Note that NTL's configure script does not follow the normal autotools syntax for passing options to the script. Rather, each option is of the form `variable=value`. The most common and important options:

- `GMP_PREFIX=/path/to/gmp/installation`
  - by default, NTL relies on GMP, the GNU multi-precision library, and you will typically have to specify where GMP is installed
  - the header file `gmp.h` should be located in `$(GMP_PREFIX)/include`, and the library file(s) `libgmp.{a,so}` should be in `$(GMP_PREFIX)/lib`
  - note that for best performance, you should build GMP from source, rather than rely on a system installation, which is often not tuned to your particular machine — especially on common x86 Linux distributions, where GMP is often compiled to target a generic x86 instruction set
  - see this page for more details about installing GMP
  - if you really do not want to use GMP, you can use the option `NTL_GMP_LIP=off` — however, this is not recommended for applications where high performance is important

- `PREFIX=/path/to/ntl/installation`
  - typically, you will have to specify where you want to install NTL
  - "`make install`" will copy
    - NTL header files to `$(PREFIX)/include/NTL`,
    - library file(s) `libntl.{a,so}` to `$(PREFIX)/lib`,
    - documentation files to `$(PREFIX)/doc/NTL`, and
    - a pkg-config file ntl.pc to `$(PREFIX)/lib/pkgconfig`.

- `DEF_PREFIX=/default/installation/path`
  - as a short cut, you can set `DEF_PREFIX` so that `GMP_PREFIX` and `PREFIX` will default to that value
  - for example, if you are installing both GMP and NTL to `$HOME/.local`, just set `DEF_PREFIX=$HOME/.local`

- `SHARED=on`
  - this defaults to "off", but you should set it to "on" if you want to build NTL as a shared (dynamic) library (in addition to a static library)

For example, if you are installing GMP and NTL in `$HOME/.local`, invoke `configure` as

       % ./configure DEF_PREFIX=$HOME/.local

If you also want a shared library, invoke it as

       % ./configure DEF_PREFIX=$HOME/.local SHARED=on

Note that the order of options does not matter.

### Other configuration options

- See config.txt for a complete list of configuration options and more details about how to use them.
- Using these options, you can specify name of your compiler (the default is `CXX=g++`), special compilation flags, and many other details of the compilation process.

### Before installing NTL

- You can run

         % make check

  to make sure everything works. This can take a few minutes.

- The generated `makefile` also allows you to compile a program `foo.cpp` in the NTL `src` directory into the excutable `foo` by executing "`make foo`".

### After installing NTL

- You can copy `$(PREFIX)/include/NTL/USER_MAKEFILE.txt` to `makefile` in your current working directory. Then you can compile the program `foo.cpp` into the executable `foo` by executing "`make foo`".
  - The `makefile` will compile `foo.cpp` with all the right flags and compiler options to ensure a compilation that is consistent with NTL's build, and to ensure that all dependencies (header files and libraries) are located (at compile, link, and run time).
  - It's useful to look at this makefile to see what compiler flags are used and to read the comments in the file to see why they are used on your particular system.
  - Of course, you can use this `makefile` as a starting point for more complex projects.
- You can look at `$(PREFIX)/include/NTL/CONFIG_LOG.txt` for a summary of all the configuration options that were used in this build of NTL.
- You can peruse the documentation in `$(PREFIX)/doc`.
  - Open `$(PREFIX)/doc/tour.html` to get the main page of the documentation.
- You can use the pkg-config file `$(PREFIX)/lib/pkgconfig/ntl.pc` to integrate NTL into a build system such as Cmake/Meson.

### Using the GF2X library

- NTL provides good support for efficient computation on polynomials over GF(2).
- For even better performance, especially for polynomials of huge degree, you can configure NTL to use the GF2X library in place of its default implementation.
- See this page for details on how to do this.

### Multi-threading

- By default, NTL compiles in a thread safe manner (with configuration option `NTL_THREADS=on`) and many internal algorithms will exploit multiple threads if they are available (with configuration option `NTL_THREAD_BOOST=on`).
- See this example for more on exploiting multiple threads.
- Note that GMP and GF2X are thread safe.

### Exceptions

- By default, NTL treats errors in a very old-fashioned way: by printing an error message and aborting your program.
- However, you can override this behavior by configuration option `NTL_EXCEPTIONS=on`.
- This will make NTL throw an exception instead of aborting — see here for more details.
- It is not enabled by default because
  - most NTL clients probably don't need fancy exception handling, and
  - there is a small performance penalty for enabling exceptions.

### More on static and shared libraries

- By default, only a static library `libntl.a` is built and installed.
- The configuration option `SHARED=on` will also cause a shared (dynamic) library `libntla.so` to be built and installed.
- The shared library `libntla.so` is built and installed using `libtool`, which is a shell script that NTL builds at configuration time (this is the default which can be overridden by setting the variable `LIBTOOL` to point to a pre-built `libtool` script).
- In addition to `libntl.so`, `libtool` also generates and installs a file `libntl.la` that helps `libtool` track library dependencies.
- You can even choose to use `libtool` when building a static library with the option `ENABLE_LIBTOOL=on` (so that the file `libntl.la` is also built and installed) — this makes NTL fit better in an established "libtool ecosystem" and allows for more options when linking programs and other libraries against NTL.
- On Cygwin, for obscure reasons, you may have to use the option `LIBTOOL_LINK_FLAGS=-no-undefined`.