Crate gmp_mpfr_sys [−] [src]
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.
If you want a high-level API, consider using Rug, a crate which provides big integer and floating-point numbers. Its main features are
- bignum integers with arbitrary precision,
- bignum rational numbers with arbitrary precision,
- multi-precision floating-point numbers with correct rounding, and
- multi-precision complex numbers 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.1"
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 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.
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.1"
default-features = false
features = ["mpfr"]
Here only the mpfr
feature is selected.
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
To build on GNU/Linux, simply make sure you have diffutils
, gcc
,
make
and m4
installed on your system. For example on Fedora:
sudo dnf install diffutils gcc make m4
Building on macOS
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.
Building on Windows
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
(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 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
.
Modules
gmp |
Function and type bindings for the GMP library. |
mpc |
Function and type bindings for the MPC library. |
mpfr |
Function and type bindings for the MPFR library. |
Macros
mpfr_round_nearest_away |