flint3-sys

FLINT bindings for the Rust programming language, using bindgen.

Since the FLINT API evolves quickly, this crate always compiles FLINT from source and never attempts to use a system library.

Versioning

This crate follows FLINT's versioning, except for the patch version, which may increase faster.

Optional Features

• gmp-mpfr-sys: Enables a dependency on the gmp-mpfr-sys crate and builds FLINT against GMP and MPFR libraries compiled by it. If this feature is not enabled, there is a system dependency on GMP and MPFR.

• force-bindgen: Adds bindgen as a build dependency and regenerates the bindings. Useful for maintenance (see below).

Metadata

This crate passes the following metadata to its dependents:

• DEP_FLINT_LIB_DIR: Path to the directory containing libflint.a.
• DEP_FLINT_INCLUDE_DIR: Path to the directory containing FLINT headers, such as DEP_FLINT_INCLUDE_DIR/flint/flint.h.

This is useful for crates that need to compile a C library depending on FLINT. See the Cargo book for more details.

Licensing

This crate is distributed under the MIT license.
Note that FLINT itself is licensed under the LGPLv3.

Architecture

Creating a *-sys crate involves several design decisions, as outlined by Kornel.

Build from Source?

While FLINT is available via many package managers, using the system library can introduce issues due to FLINT's unstable API.

Using pkg-config to link against a system-installed FLINT is straightforward, but building against it requires running bindgen on the system headers. This:

• Is slower (since bindgen is not multithreaded),
• Results in unpredictable APIs,
• May miss AVX2 optimizations, which are often not enabled in precompiled packages.

For these reasons, this crate builds FLINT from source.

For FLINT's dependencies (GMP and MPFR), you may choose to compile them from source (using the gmp-mpfr-sys feature) or rely on the system libraries. Compiling from source typically yields better performance.
Note: flint3-sys does not expose any part of the GMP or MPFR APIs.

bindgen in build.rs?

There are two approaches:

1. Run bindgen upstream and ship the generated bindings.
2. Run bindgen in the build script.

By default, the first option is used as it's much faster. However, it may lead to desynchronization: the headers used to generate the bindings are not necessarily the ones you'll have after building FLINT. Parts of FLINT's headers are generated by its ./configure script, so constants like FLINT_HAVE_FFT_SMALL might not match.

To regenerate bindings manually, enable the force-bindgen feature.

Maintenance

To update the bundled version of FLINT:

1. Update the ./flint submodule.
2. Run KEEP_BINDGEN_OUTPUT=1 cargo build -F force-bindgen to regenerate ./bindgen/flint.rs and ./bindgen/extern.c.
3. Test thoroughly.
4. Commit the changes.