The gmp-mpfr-sys crate provides Rust FFI bindings to the following GNU arbitrary-precision libraries:
- GMP for integers and rational numbers,
- MPFR for floating-point numbers, and
- MPC for complex numbers.
The source of the three libraries is included in the package.
The gmp-mpfr-sys crate is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See the full text of the GNU LGPL and GNU GPL for details.
This crate contains three modules:
gmpprovides external FFI bindings to GMP.
mpfrprovides external FFI bindings to MPFR.
mpcprovides external FFI bindings to MPC.
If you want a high-level API, consider using Rug, a crate which provides integers and floating-point numbers with arbitrary precision and correct rounding:
Integeris a bignum integer with arbitrary precision,
Rationalis a bignum rational number with arbitrary precision,
Floatis a multi-precision floating-point number with correct rounding, and
Complexis a multi-precision complex number with correct rounding.
Since modules and enumerated types provide namespacing, most prefixes
in the C names are removed. However, when the prefix is not a whole
word it is not removed. For example
enum MPFR_RND_T becomes
mpfr::rnd_t::N. Also, the types
are not shortened to
The bindings do not cover undocumented or obsolete functions and macros.
[dependencies] gmp-mpfr-sys = "1.1"
If you are using the 2015 Rust edition, you also need to declare it by adding this to your crate root (usually lib.rs or main.rs):
extern crate gmp_mpfr_sys;
This crate required rustc version 1.13.0 or later.
If the C libraries have a major version bump with some deprecated functions removed, but no features are removed in the Rust bindings, then gmp-mpfr-sys will have a minor version bump rather than a major version bump. This allows more compatiblity across crates that use the Rust bindings but do not use the C libraries directly.
If on the other hand a dependent crate makes use of internal
implementation details, or includes a C library that directly uses the
header (.h) and library (.a) files built using C, it can be a good
idea to depend on version
"~1.1" instead of version
"1.1" in order
to ensure backwards compatibility at the C level as well.
The gmp-mpfr-sys crate has two optional features:
mpfr, enabled by default. Required to include the MPFR library.
mpc, enabled by default. Required to include the MPC library. This feature requires the
The GMP library is always included.
The two optional features are enabled by default; to use features selectively, you can add the dependency like this to Cargo.toml:
[dependencies.gmp-mpfr-sys] version = "1.1" default-features = false features = ["mpfr"]
Here only the
mpfr feature is selected.
The gmp-mpfr-sys crate passes some metadata to its dependents:
DEP_GMP_LIMB_BITScontains the number of bits per limb, which is 32 or 64.
DEP_GMP_OUT_DIRcontains the path of a directory that contains two subdirectories: the first subdirectory is named lib and contains the generated library (.a) files, and the second subdirectory is named include and contains the corresponding header (.h) files.
DEP_GMP_LIB_DIRcontains the path of the lib subdirectory of the
DEP_GMP_INCLUDE_DIRcontains the path of the include subdirectory of the
A dependent crate can use these environment variables in its build script.
To build on GNU/Linux, simply make sure you have
m4 installed on your system. For example on Fedora:
sudo dnf install diffutils gcc make m4
To build on macOS, you need the command-line developer tools. To install them, run the following command in a terminal:
You can build on Windows with the Rust GNU toolchain and an up-to-date MSYS2 installation. Some steps for a 64-bit environment are listed below. (32-bit: Changes for a 32-bit environment are written in brackets like this comment.)
To install MSYS2:
Install MSYS2 using the installer.
Launch the MSYS2 MinGW 64-bit terminal from the start menu. (32-bit: Launch the MSYS2 MinGW 32-bit terminal instead.)
Install the required tools.
pacman -S pacman-mirrors pacman -S diffutils make mingw-w64-x86_64-gcc
Then, to build a crate with a dependency on this crate:
Launch the MSYS MinGW 64-bit terminal from the start menu. (32-bit: Launch the MSYS2 MinGW 32-bit terminal instead.)
Change to the crate directory.
Build the crate using
Building the C libraries can take some time. In order to save compilation time, the built libraries are cached in the user’s cache directory as follows:
- on GNU/Linux: inside
- on macOS: inside
- on Windows: inside
To use a different directory, you can set the environment variable
GMP_MPFR_SYS_CACHE to the desired cache directory. Setting the
GMP_MPFR_SYS_CACHE variable to an empty string will disable caching.
Function and type bindings for the GMP library.
Function and type bindings for the MPC library.
Function and type bindings for the MPFR library.