The gmp-mpfr-sys crate provides Rust FFI bindings for:
The source of the three libraries is included in the package.
This 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 provides a low-level interface to GMP, MPFR and MPC in three modules. The documentation of the three modules contains links for each function, constant and type into the respective documentation of GMP, MPFR and MPC libraries. The three modules of this crate are:
gmp provides external FFI bindings to GMP.mpfr provides external FFI bindings to MPFR.mpc provides external FFI bindings to MPC.If you want a high-level API, consider using the rug crate,
which provides big integer and floating-point numbers. Its main
features are:
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 mp_set_memory_functions()
becomes gmp::set_memory_functions(), but mpz_init() becomes
gmp::mpz_init() not gmp::z_init(), and MPFR_RNDN in
enum MPFR_RND_T becomes mpfr::rnd_t::RNDN not mpfr::rnd_t::N.
Also, the types mpfr::mpfr_t and mpc::mpc_t are not shortened to
mpfr::t or mpc::t.
Unlike in the C libraries, the types gmp::mpz_t, gmp::mpq_t,
gmp::mpf_t, gmp::rand_state_t, mpfr::mpfr_t and mpc::mpc_t are
defined directly as structs, not as single-element arrays.
The bindings do not cover undocumented or obsolete functions and macros.
This crate required rustc version 1.13.0 or later.
To use gmp-mpfr-sys in your crate, add extern crate gmp_mpfr_sys;
to the crate root and add gmp-mpfr-sys as a dependency in
Cargo.toml:
toml
[dependencies]
gmp-mpfr-sys = "1.1.0"
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 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.0" instead of
version "1.1.0" in order to ensure backwards compatibility at the C
level as well.
The gmp-mpfr-sys crate passes some metadata to its dependents:
DEP_GMP_LIMB_BITS contains the number of bits per limb, which is
32 or 64.DEP_GMP_OUT_DIR contains 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_DIR contains the path of the lib subdirectory of
the DEP_GMP_OUT_DIR directory.DEP_GMP_INCLUDE_DIR contains the path of the include
subdirectory of the DEP_GMP_OUT_DIR directory.A dependent crate can use these environment variables in its build script.
The gmp-mpfr-sys crate has two optional features mpfr and mpc to
include the MPFR and MPC libraries respectively. The GMP library is
always included. The optional features are enabled by default; to
disable them add this to Cargo.toml:
toml
[dependencies.gmp-mpfr-sys]
version = "1.1.0"
default-features = false
To use features selectively, you can add this to Cargo.toml:
```toml [dependencies.gmp-mpfr-sys] version = "1.1.0" default-features = false
features = ["mpfr"] ```
Note that the the mpc feature depends on, and will enable, the
mpfr feature.
To build on GNU/Linux, simply make sure you have diffutils, gcc,
make and m4 installed on your system. For example on Fedora:
sh
sudo dnf install diffutils gcc make m4
To build on macOS, you need the command-line developer tools. An easy
way to install them is to start building the crate using
cargo build. If the tools are not installed yet, a popup should
appear which should help you install them.
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.
sh
pacman -S pacman-mirrors
pacman -S diffutils make mingw-w64-x86_64-gcc
(32-bit: Install mingw-w64-i686-gcc instead of
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 cargo.