Crate gmp_mpfr_sys
source ·Expand description
§Rust low-level bindings for GMP, MPFR and MPC
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.
§Basic features
This crate contains three modules:
gmp
provides external FFI bindings to GMP.mpfr
provides external FFI bindings to MPFR.mpc
provides external FFI bindings to MPC.
The versions provided by this crate release are GMP version 6.3.0, MPFR version 4.2.1, and MPC version 1.3.1.
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:
Integer
is a bignum integer with arbitrary precision.Rational
is a bignum rational number with arbitrary precision.Float
is a multi-precision floating-point number with correct rounding.Complex
is a multi-precision complex number with correct rounding.
§Name prefixes
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
.
§Types
Unlike in the C libraries, the types gmp::mpz_t
, gmp::mpq_t
,
gmp::mpf_t
, gmp::randstate_t
, mpfr::mpfr_t
and
mpc::mpc_t
are defined directly as structs, not as single-element
arrays.
§Undocumented or obsolete functions
The bindings do not cover undocumented or obsolete functions and macros.
§Using gmp-mpfr-sys
The gmp-mpfr-sys crate is available on crates.io. To use gmp-mpfr-sys in your crate, add it as a dependency inside Cargo.toml:
[dependencies]
gmp-mpfr-sys = "1.6"
This crate requires rustc version 1.65.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.6"
instead of version "1.6"
in order
to ensure backwards compatibility at the C level as well.
§Optional features
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 thempfr
feature.
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.6"
default-features = false
features = ["mpfr"]
Here only the mpfr
feature is selected.
§Experimental optional features
It is not considered a breaking change if experimental features are removed. The removal of experimental features would however require a minor version bump.
Experimental features may also not work on all platforms.
There are three experimental features:
use-system-libs
, disabled by default. Using this feature, the system libraries for GMP, and MPFR and MPC if enabled, will be used instead of building them from source. The major versions of the system libraries must be equal to those provided by the crate, and the minor versions of the system libraries must be greater or equal to those provided by the crate. There are no restriction on the patch version.force-cross
, disabled by default. Without this feature, the build will fail if cross compilation is detected, because cross compilation is not tested or supported and can lead to silent failures that are hard to debug, especially if this crate is an indirect dependency. As an exception, cross compiling from x86_64 to i686 does not need this feature. (Compiling on MinGW does not have this exception because MinGW does not support cross compilation from 64-bit to 32-bit.)c-no-tests
, disabled by default. Using this feature will skip testing the C libraries. This is not advised; the risk that the GMP sources are miscompiled is unfortunately quite high. And if they indeed are miscompiled, the tests are very likely to trigger the compiler-introduced bug.
§Metadata
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 theDEP_GMP_OUT_DIR
directory.DEP_GMP_INCLUDE_DIR
contains the path of the include subdirectory of theDEP_GMP_OUT_DIR
directory.
A dependent crate can use these environment variables in its build script.
§Building on GNU/Linux
Warning: The build system does not support building in paths that contain spaces.
To build on GNU/Linux, simply make sure you have diffutils
, gcc
,
m4
and make
installed on your system. For example on Fedora:
sudo dnf install diffutils gcc m4 make
Note that you can use Clang instead of GCC by installing clang
and setting the
environment variable CC=clang
before building the crate.
§Building on macOS
Warning: The build system does not support building in paths that contain spaces.
To build on macOS, you need the command-line developer tools. To install them, run the following command in a terminal:
xcode-select --install
§Building on Windows
Warning: The build system does not support building in paths that contain spaces.
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 m4 make mingw-w64-x86_64-gcc
(32-bit: Install
mingw-w64-i686-gcc
instead ofmingw-w64-x86_64-gcc
.)
Then, to build a crate with a dependency on this crate:
-
Launch the MSYS2 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
.
Note that you can use Clang instead of GCC by installing
mingw-w64-x86_64-clang
(32-bit: mingw-w64-i686-clang
) and setting the
environment variable CC=clang
before building the crate.
§Cross compilation
While some cross compilation is possible, it is not tested automatically, and may not work. Merge requests that improve cross compilation are accepted.
The experimental feature force-cross
must be enabled for cross
compilation. There is one case which is allowed even without the
feature: when the only difference between host and target is that the
host is x86_64 and the target is i686.
§Caching the built C libraries
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
$XDG_CACHE_HOME/gmp-mpfr-sys
or$HOME/.cache/gmp-mpfr-sys
- on macOS: inside
$HOME/Library/Caches/gmp-mpfr-sys
- on Windows: inside
{FOLDERID_LocalAppData}\gmp-mpfr-sys
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 or to a single
underscore ("_"
) will disable caching.
Modules§
- This module is a place-holder for documentation; do not use it in code.
- Function and type bindings for the GMP library.
- Function and type bindings for the MPC library.
- Function and type bindings for the MPFR library.
Macros§
- See:
MPFR_DECL_INIT