Building, testing and installing¶
Quick start¶
Building FLINT requires:
GMP, at least version 6.2.1 (https://gmplib.org/)
MPFR, at least version 4.1.0 (https://mpfr.org/)
Either of the following build systems: * GNU Make together with GNU Autotools (Recommended) * CMake (Only supported for Windows users)
If building from a release on a typical Linux or Unix-like system (see below for instructions using CMake), FLINT can be configured, built and installed as follows:
./configure
make -j N
make install
where N is the number of jobs number allowed to run parallel. Typically, the
fastest way to build is to let N be the number of threads your CPU plus one,
which can be obtained in Bash through $(expr $(nproc) + 1).
If building from scratch, that is, without a configure script, then configure
needs to be generated first. For this GNU Autotools needs to be installed in
order to run
./bootstrap.sh
After this is done, configure should be generated and user can proceed with
configuring, building and installing FLINT.
By default, FLINT only builds a shared library, but a static library can be
built by pushing --enable-static to configure.
We also recommend that you check that the library works as it should through
make check, or make -j N check for a parallel check, before installing.
For a complete list of build settings, type
./configure --help
An example of a custom configuration command would be
./configure \
--enable-assert \
--enable-avx2 \
--with-gmp-include=/home/user1/builds/includes/ \
--with-gmp-lib=/home/user1/builds/lib/ \
--with-mpfr=/usr \
--prefix=/home/user1/installations/ \
CC=clang \
CFLAGS="-Wall -O3 -march=alderlake"
Library and install paths¶
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.
If GMP and MPFR are not installed in the default search path of your compiler
(e.g. /usr/include/ and /usr/lib/), you must specify where they are by
passing their location to configure --with-gmp=ABSOLUTE_PATH for GMP and
--with-mpfr=ABSOLUTE_PATH for MPFR.
Note that the FLINT build system can handle GMP and MPFR as installed at some
location and as source builds (built from source but not installed). Though, to
run the FLINT tests, GMP and MPFR needs to be properly installed.
Testing FLINT¶
The full FLINT test suite can be run using
make check
or in parallel on a multicore system using
make -j check
Here, make -j N check is typically the fastest way to build when N
equals to the number of threads your system’s CPU has plus one, that is,
make -j $(expr $(nproc) + 1) check typically is the fastest way to check
FLINT.
Number of test iterations¶
The number of test iterations can be changed with the
FLINT_TEST_MULTIPLIER environment variable. For example, the
following will only run 10% of the default iterations:
export FLINT_TEST_MULTIPLIER=0.1
make check
Conversely, FLINT_TEST_MULTIPLIER=10 will stress test FLINT
by performing 10x the default number of iterations.
Testing single modules¶
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:
make check MOD=ulong_extras
make -j N check MOD="fft fmpz_mat"
Testing single functions¶
Testing a single function is also possible, although one cannot utilize make
all the way through for this. For example, if you would like to test the
function fmpz_add and fmpz_sub in the module fmpz, you run
# Build all tests
make tests
# Run the test executable for `fmpz' with `fmpz_add' and `fmpz_sub' as inputs
./build/fmpz/test/main fmpz_add fmpz_sub
Test coverage¶
To obtain coverage statistics for the FLINT test suite, assuming
that gcov and lcov are installed, configure
FLINT with --enable-coverage. Then run:
make -j N check
make coverage_html
This will place a coverage report in build/coverage.
Static or dynamic library only¶
By default FLINT only builds a shared libraries by default. If you need to build
a static library, you can pass --enable-static to configure. With this,
--disable-shared can be passed as well to disable the build of a shared
library, which will reduce the building time.
AVX2 instructions¶
On x86-64 machines with AVX2 support, compiling FLINT with the --enable-avx2
option can improve performance substantially, notably by enabling
the small-prime FFT. Currently this option is not enabled by default.
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 --disable-reentrant option
to configure, though note that this is the default. The reentrant mode is
selected by passing the option --enable-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 specifying the build system triplet to configure via
--build=arch-vendor-os.
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.
CMake build for Windows users¶
For Windows users, we also provide a way to install FLINT using CMake. Note, however, that FLINT’s CMake script only exists to provide Windows users a way to install FLINT. For UNIX-type systems, please use Autotools along with GNU Make instead, as described at the top of this page.
If you wish to install FLINT with CMake on Windows, simply type:
mkdir build && cd build
cmake .. -DBUILD_SHARED_LIBS=ON
cmake --build . --target install
Uninstalling FLINT¶
To uninstall FLINT with GNU make, type:
make uninstall
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, MPFR and pthreads with the
options -lflint -lmpfr -lgmp -lpthread.
To clean up the local build files, use:
make clean
make distclean
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.
Linking and running code¶
Here is an example program to get started using FLINT:
#include "flint/flint.h"
#include "flint/arb.h"
int main()
{
arb_t x;
arb_init(x);
arb_const_pi(x, 50 * 3.33);
arb_printn(x, 50, 0); flint_printf("\n");
flint_printf("Computed with FLINT-%s\n", flint_version);
arb_clear(x);
}
Compile it with:
gcc test.c -lflint
You may also have to pass the flags -lmpfr and -lgmp to the compiler.
If the FLINT header and library files are not in a standard location
such as /usr/local, you may also have to provide flags such as:
-I/path/to/flint -L/path/to/flint
Finally, to run the program, make sure that the linker
can find libflint. If it is installed in a
nonstandard location, you can for example add this path to the
LD_LIBRARY_PATH environment variable.
The output of the example program should be something like the following:
[3.1415926535897932384626433832795028841971693993751 +/- 4.43e-50]
Computed with flint-3.0.0