Configuring and building

Configuring Flint

There are three ways to build Flint. One way is through a standard set of CMake files provided in the distribution. A second way is with a custom build system based on a configuration script and Makefiles also provided in the distribution. A third way using MSVC solution files is documented in a section further down.

The easiest way to use FLINT is to build a shared library. Simply download the FLINT tarball and untar it on your system.

FLINT requires either MPIR (version 2.6.0 or later) or GMP (version 5.1.1 or later). If MPIR is used, MPIR must be built with the --enable-gmpcompat option. FLINT also requires MPFR 3.0.0 or later and a pthread implementation.

Some of the input/output tests require fork and pipe, however these are disabled on Windows when a posix implementation is not provided.

If it happens that GMP/MPIR and MPFR are not in a standard location on your system (e.g. not in /usr/include/ and /usr/lib/), you need to tell the configure script where they are with the options --with-gmp=/path/to/gmp or --with-mpir=/path/to/mpir and --with-mpfr=/path/to/mpfr, e.g.

./configure --with-gmp=/home/user1/local --with-mpfr=/home/user1/local

FLINT can also build against a source build of GMP/MPIR and MPFR. Though programs using FLINT may require GMP/MPIR and MPFR to be installed (via make install if built from sources).

Note that FLINT builds static and shared libraries by default, except on platforms where this is not supported. If you do not require either a shared or static library then you may pass --disable-static or --disable-shared to configure. This can substantially speed up the build.

If you intend to install the FLINT library and header files, you can specify where they should be placed by passing --prefix=path to configure, where path is the directory under which the lib and include directories exist into which you wish to place the FLINT files when it is installed.

TLS, reentrancy and single mode

FLINT uses thread local storage by default (--enable-tls). However, if reentrancy is required on systems that do not support this, one can pass --disable-tls and mutexes will be used instead (requires POSIX). As most modern systems support thread local storage, it is not recommended to build FLINT without TLS.

There are two modes in which FLINT may installed: the default single mode, which is faster, but makes use of thread local storage for its memory manager and to handle threading, and a slower but less complicated reentrant mode. The later is useful when debugging a program where tracing allocations is important.

If you wish to select the single mode, pass the --single option to configure, though note that this is the default. The reentrant mode is selected by passing the option --reentrant to configure.

ABI and architecture support

On some systems, e.g. Sparc and some Macs, more than one ABI is available. FLINT chooses the ABI based on the CPU type available, however its default choice can be overridden by passing either ABI=64 or ABI=32 to configure.

To build on MinGW64 it is necessary to pass ABI=64 to configure, as FLINT is otherwise unable to distinguish it from MinGW32.

In some cases, it is necessary to override the CPU/OS defaults. This can be done by passing --build=cpu-os to configure.

The available choices for CPU include x86_64, x86, ia64, sparc, sparc64, ppc, ppc64. Other CPU types are unrecognised and FLINT will build with generic code on those machines.

The choices for OS include Linux, MINGW32, MINGW64, CYGWIN32, CYGWIN64, Darwin, FreeBSD, SunOS and numerous other operating systems.

It is also possible to override the default CC, AR and CFLAGS used by FLINT by passing CC=full_path_to_compiler, etc., to FLINT’s configure.

C++ wrapper

If you wish to enable the test functions for the FLINT C++ wrapper flintxx you must pass --enable-cxx to configure.

The C++ wrapper is always available, but tests will only run if this option is selected. It is disabled by default (--disable-cxx) because some C++ compilers internally segfault when compiling the tests, or exhaust memory due to the complexity of the C++ code.

Building, testing, installing and using FLINT

Once FLINT is configured, in the main directory of the FLINT directory tree simply type:

make
make check

GNU make or CMake is required to build FLINT. For GNU make, this is simply make on Linux, Darwin, MinGW and Cygwin systems. However, on some unixes the command is gmake. For CMake, this is cmake, which which may need to be installed with your package manager.

If you wish to install FLINT with GNU make, simply type:

make install

If you wish to install FLINT with CMake, simply type:

mkdir build && cd build
cmake .. -DBUILD_SHARED_LIBS=ON
cmake --build . --target install

Now to use FLINT, simply include the appropriate header files for the FLINT modules you wish to use in your C program. Then compile your program, linking against the FLINT library, GMP/MPIR, MPFR and pthreads with the options -lflint -lmpfr -lgmp -lpthread.

To uninstall FLINT with GNU make, type:

make uninstall

Note that you may have to set LD_LIBRARY_PATH or equivalent for your system to let the linker know where to find these libraries. Please refer to your system documentation for how to do this.

If you have any difficulties with conflicts with system headers on your machine, you can do the following in your code:

#undef ulong
#define ulong ulongxx
#include <stdio.h>
// other system headers
#undef ulong
#define ulong mp_limb_t

This prevents FLINT’s definition of ulong interfering with your system headers.

The FLINT custom make system responds to the standard commands

make
make library
make check
make clean
make distclean
make install

If your system supports parallel builds, FLINT will build in parallel, e.g:

make -j4 check

On some systems, parallel builds appear to be available but buggy.

Testing a single module or file

If you wish to simply check a single module of FLINT you can pass the option MOD=modname to make check. You can also pass a list of module names in inverted commas, e.g:

make check MOD=ulong_extras
make check MOD="fft fmpz_mat"

To specify an individual test(s) for any module you can add it (or comma separated test list) after chosen module name followed by the colon, e.g.:

make check MOD=ulong_extras:clog,factor,is_prime
make check MOD="fft fmpz_mat:add_sub,charpoly fq_vec:add"

Assertion checking

FLINT has an assert system. If you want a debug build you can pass --enable-assert to configure. However, this will slow FLINT considerably, so asserts should not be enabled (--disable-assert, the default) for deployment.

Exceptions

When FLINT encounters a problem, mostly illegal input, it currently aborts. There is an experimental interface for generating proper exceptions flint_throw, but this is currently rarely used and experimental - you should expect this to change.

At the end, all of FLINT’s exceptions call abort() to terminate the program. Using flint_set_abort(void (*abort_func)(void)), the user can install a function that will be called instead. Similar to the exceptions, this should be regarded as experimental.

Building FLINT2 with Microsoft Visual Studio using solution files

Brian Gladman has kindly provided the build scripts for building Flint with Microsoft Visual Studio.

Building FLINT2 with Microsoft Visual Studio requires Visual Studio 2015 Community (or higher version) and:

Obtain FLINT2 by cloning it using GIT from Brian Gladman’s repository:

git@github.com:BrianGladman/flint.git

FLINT2 depends on the MPIR, MPFR and PTHREADS libraries that have to be installed and built using Visual Studio before FLINT2 can be built. The application directories are assumed to be in the same root directory with the names and layouts:

mpir
   lib
   dll
mpfr
   lib
   dll
pthreads
   lib
   dll
flint
   build.vc
   lib
   dll

Here the lib and dll sub-directories for each application hold the static and dynamic link library outputs which will be used when Flint is built. They each contain up to four sub-directories for the normal configurations for building on Windows:

Win32\Release

Win32\Debug

x64\Release

x642\Debug

To build FLINT2 for a particular configuration requires that each of the three libraries on which FLINT2 depends must have been previously built for the same configuration.

Opening the solution file flint\build.vc\flint.sln provides the following build projects:

flint_config - a Python program for creating the Visual Studio build files

build_tests - a Python program for building the FLINT2 tests (after they have been created)

run_tests - a Python program for running the FLINT2 tests (after they have been built)

The first step in building FLINT2 is to generate the Visual Studio build files for the version of Visual Studio being used. This is done by running the Python application flint_config.py, either from within Visual Studio or on the command line. It is run with a single input parameter which is the last two digits of the Visual Studio version selected for building FLINT2 (the default is 19 if no input is given).

This creates a build directory in the Flint root directory, for example:

flint\build.vs19

that contains the file flint.sln which can now be loaded into Visual Studio and used to build the FLINT2 library.

Once the FLINT2 library has been built, the FLINT2 tests can now be built and run by returning to the Visual Studio solution:

flint\build.vc\flint.sln

and running the build_tests and run_tests Python applications.

After building FLINT2, the libraries and the header files that you need to use FLINT2 are placed in the directories:

  • lib\<Win32|x64>\<Debug|Release>
  • dll\<Win32|x64>\<Debug|Release>

depending on the version(s) that have been built.