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.