version 1.1.1.3, 2000/12/01 05:44:45 |
version 1.1.1.4, 2003/08/25 16:06:02 |
|
|
This is gmp.info, produced by makeinfo version 4.0 from gmp.texi. |
This is gmp.info, produced by makeinfo version 4.2 from gmp.texi. |
|
|
|
This manual describes how to install and use the GNU multiple precision |
|
arithmetic library, version 4.1.2. |
|
|
|
Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, |
|
2001, 2002 Free Software Foundation, Inc. |
|
|
|
Permission is granted to copy, distribute and/or modify this |
|
document under the terms of the GNU Free Documentation License, Version |
|
1.1 or any later version published by the Free Software Foundation; |
|
with no Invariant Sections, with the Front-Cover Texts being "A GNU |
|
Manual", and with the Back-Cover Texts being "You have freedom to copy |
|
and modify this GNU Manual, like GNU software". A copy of the license |
|
is included in *Note GNU Free Documentation License::. |
INFO-DIR-SECTION GNU libraries |
INFO-DIR-SECTION GNU libraries |
START-INFO-DIR-ENTRY |
START-INFO-DIR-ENTRY |
* gmp: (gmp). GNU Multiple Precision Arithmetic Library. |
* gmp: (gmp). GNU Multiple Precision Arithmetic Library. |
END-INFO-DIR-ENTRY |
END-INFO-DIR-ENTRY |
|
|
This file documents GNU MP, a library for arbitrary-precision |
|
arithmetic. |
|
|
|
Copyright (C) 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 |
|
Free Software Foundation, Inc. |
|
|
|
Permission is granted to make and distribute verbatim copies of this |
|
manual provided the copyright notice and this permission notice are |
|
preserved on all copies. |
|
|
|
Permission is granted to copy and distribute modified versions of |
|
this manual under the conditions for verbatim copying, provided that |
|
the entire resulting derived work is distributed under the terms of a |
|
permission notice identical to this one. |
|
|
|
Permission is granted to copy and distribute translations of this |
|
manual into another language, under the above conditions for modified |
|
versions, except that this permission notice may be stated in a |
|
translation approved by the Foundation. |
|
|
|
|
|
File: gmp.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir) |
File: gmp.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir) |
|
|
GNU MP |
GNU MP |
****** |
****** |
|
|
This manual documents how to install and use the GNU multiple |
This manual describes how to install and use the GNU multiple precision |
precision arithmetic library, version 3.1.1. |
arithmetic library, version 4.1.2. |
|
|
|
Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, |
|
2001, 2002 Free Software Foundation, Inc. |
|
|
|
Permission is granted to copy, distribute and/or modify this |
|
document under the terms of the GNU Free Documentation License, Version |
|
1.1 or any later version published by the Free Software Foundation; |
|
with no Invariant Sections, with the Front-Cover Texts being "A GNU |
|
Manual", and with the Back-Cover Texts being "You have freedom to copy |
|
and modify this GNU Manual, like GNU software". A copy of the license |
|
is included in *Note GNU Free Documentation License::. |
|
|
* Menu: |
* Menu: |
|
|
* Copying:: GMP Copying Conditions (LGPL). |
* Copying:: GMP Copying Conditions (LGPL). |
* Introduction to GMP:: Brief introduction to GNU MP. |
* Introduction to GMP:: Brief introduction to GNU MP. |
* Installing GMP:: How to configure and compile the GMP library. |
* Installing GMP:: How to configure and compile the GMP library. |
* GMP Basics:: What every GMP user should now. |
* GMP Basics:: What every GMP user should know. |
* Reporting Bugs:: How to usefully report bugs. |
* Reporting Bugs:: How to usefully report bugs. |
* Integer Functions:: Functions for arithmetic on signed integers. |
* Integer Functions:: Functions for arithmetic on signed integers. |
* Rational Number Functions:: Functions for arithmetic on rational numbers. |
* Rational Number Functions:: Functions for arithmetic on rational numbers. |
* Floating-point Functions:: Functions for arithmetic on floats. |
* Floating-point Functions:: Functions for arithmetic on floats. |
* Low-level Functions:: Fast functions for natural numbers. |
* Low-level Functions:: Fast functions for natural numbers. |
* Random Number Functions:: Functions for generating random numbers. |
* Random Number Functions:: Functions for generating random numbers. |
|
* Formatted Output:: `printf' style output. |
|
* Formatted Input:: `scanf' style input. |
|
* C++ Class Interface:: Class wrappers around GMP types. |
* BSD Compatible Functions:: All functions found in BSD MP. |
* BSD Compatible Functions:: All functions found in BSD MP. |
* Custom Allocation:: How to customize the internal allocation. |
* Custom Allocation:: How to customize the internal allocation. |
|
* Language Bindings:: Using GMP from other languages. |
|
* Algorithms:: What happens behind the scenes. |
|
* Internals:: How values are represented behind the scenes. |
|
|
* Contributors:: Who brings your this library? |
* Contributors:: Who brings your this library? |
* References:: Some useful papers and books to read. |
* References:: Some useful papers and books to read. |
|
* GNU Free Documentation License:: |
* Concept Index:: |
* Concept Index:: |
* Function Index:: |
* Function Index:: |
|
|
Line 86 know that what they have is not what we distributed, s |
|
Line 97 know that what they have is not what we distributed, s |
|
problems introduced by others will not reflect on our reputation. |
problems introduced by others will not reflect on our reputation. |
|
|
The precise conditions of the license for the GNU MP library are |
The precise conditions of the license for the GNU MP library are |
found in the Lesser General Public License that accompany the source |
found in the Lesser General Public License version 2.1 that accompanies |
code. |
the source code, see `COPYING.LIB'. Certain demonstration programs are |
|
provided under the terms of the plain General Public License version 2, |
|
see `COPYING'. |
|
|
|
|
File: gmp.info, Node: Introduction to GMP, Next: Installing GMP, Prev: Copying, Up: Top |
File: gmp.info, Node: Introduction to GMP, Next: Installing GMP, Prev: Copying, Up: Top |
Line 114 many different CPUs, and by a general emphasis on spee |
|
Line 127 many different CPUs, and by a general emphasis on spee |
|
simplicity or elegance). |
simplicity or elegance). |
|
|
There is carefully optimized assembly code for these CPUs: ARM, DEC |
There is carefully optimized assembly code for these CPUs: ARM, DEC |
Alpha 21064, 21164, and 21264, AMD 29000, AMD K6 and Athlon, Hitachi |
Alpha 21064, 21164, and 21264, AMD 29000, AMD K6, K6-2 and Athlon, |
SuperH and SH-2, HPPA 1.0, 1.1 and 2.0, Intel Pentium, Pentium |
Hitachi SuperH and SH-2, HPPA 1.0, 1.1 and 2.0, Intel Pentium, Pentium |
Pro/Pentium II, generic x86, Intel i960, Motorola MC68000, MC68020, |
Pro/II/III, Pentium 4, generic x86, Intel IA-64, i960, Motorola |
MC88100, and MC88110, Motorola/IBM PowerPC 32 and 64, National NS32000, |
MC68000, MC68020, MC88100, and MC88110, Motorola/IBM PowerPC 32 and 64, |
IBM POWER, MIPS R3000, R4000, SPARCv7, SuperSPARC, generic SPARCv8, |
National NS32000, IBM POWER, MIPS R3000, R4000, SPARCv7, SuperSPARC, |
UltraSPARC, DEC VAX, and Zilog Z8000. Some optimizations also for |
generic SPARCv8, UltraSPARC, DEC VAX, and Zilog Z8000. Some |
Clipper, IBM ROMP (RT), and Pyramid AP/XP. |
optimizations also for Cray vector systems, Clipper, IBM ROMP (RT), and |
|
Pyramid AP/XP. |
|
|
There is a mailing list for GMP users. To join it, send a mail to |
There are two public mailing lists of interest. One for general |
<gmp-request@swox.com> with the word `subscribe' in the message *body* |
questions and discussions about usage of the GMP library and one for |
(not in the subject line). |
discussions about development of GMP. There's more information about |
|
the mailing lists at `http://swox.com/mailman/listinfo/'. These lists |
|
are *not* for bug reports. |
|
|
For up-to-date information on GMP, please see the GMP Home Pages at |
The proper place for bug reports is <bug-gmp@gnu.org>. See *Note |
`http://www.swox.com/gmp/'. |
Reporting Bugs:: for info about reporting bugs. |
|
|
|
For up-to-date information on GMP, please see the GMP web pages at |
|
|
|
`http://swox.com/gmp/' |
|
|
|
The latest version of the library is available at |
|
|
|
`ftp://ftp.gnu.org/gnu/gmp' |
|
|
|
Many sites around the world mirror `ftp.gnu.org', please use a mirror |
|
near you, see `http://www.gnu.org/order/ftp.html' for a full list. |
|
|
How to use this Manual |
How to use this Manual |
====================== |
====================== |
|
|
Everyone should read *Note GMP Basics::. If you need to install the |
Everyone should read *Note GMP Basics::. If you need to install the |
library yourself, you need to read *Note Installing GMP::, too. |
library yourself, then read *Note Installing GMP::. If you have a |
|
system with multiple ABIs, then read *Note ABI and ISA::, for the |
|
compiler options that must be used on applications. |
|
|
The rest of the manual can be used for later reference, although it |
The rest of the manual can be used for later reference, although it |
is probably a good idea to glance through it. |
is probably a good idea to glance through it. |
Line 144 File: gmp.info, Node: Installing GMP, Next: GMP Basi |
|
Line 173 File: gmp.info, Node: Installing GMP, Next: GMP Basi |
|
Installing GMP |
Installing GMP |
************** |
************** |
|
|
GMP has an autoconf/automake/libtool based configuration system. On a |
GMP has an autoconf/automake/libtool based configuration system. On |
Unix-like system a basic build can be done with |
a Unix-like system a basic build can be done with |
|
|
./configure |
./configure |
make |
make |
Line 158 And you can install (under `/usr/local' by default) wi |
|
Line 187 And you can install (under `/usr/local' by default) wi |
|
|
|
make install |
make install |
|
|
If you experience problems, please report them to <bug-gmp@gnu.org>. |
If you experience problems, please report them to <bug-gmp@gnu.org>. |
(*Note Reporting Bugs::, for information on what to include in useful |
See *Note Reporting Bugs::, for information on what to include in |
bug reports.) |
useful bug reports. |
|
|
* Menu: |
* Menu: |
|
|
Line 176 File: gmp.info, Node: Build Options, Next: ABI and I |
|
Line 205 File: gmp.info, Node: Build Options, Next: ABI and I |
|
Build Options |
Build Options |
============= |
============= |
|
|
All the usual autoconf configure options are available, run `./configure |
All the usual autoconf configure options are available, run |
--help' for a summary. |
`./configure --help' for a summary. The file `INSTALL.autoconf' has |
|
some generic installation information too. |
|
|
Non-Unix Systems |
Non-Unix Systems |
`configure' needs various Unix-like tools installed. On an MS-DOS |
`configure' requires various Unix-like tools. On an MS-DOS system |
system cygwin or djgpp should work. It might be possible to build |
DJGPP can be used, and on MS Windows Cygwin or MINGW can be used, |
without the help of `configure', certainly all the code is there, |
|
but unfortunately you'll be on your own. |
|
|
|
Object Directory |
`http://www.cygnus.com/cygwin' |
To compile in a separate object directory, `cd' to that directory, |
`http://www.delorie.com/djgpp' |
|
`http://www.mingw.org' |
|
|
|
Microsoft also publishes an Interix "Services for Unix" which can |
|
be used to build GMP on Windows (with a normal `./configure'), but |
|
it's not free software. |
|
|
|
The `macos' directory contains an unsupported port to MacOS 9 on |
|
Power Macintosh, see `macos/README'. Note that MacOS X "Darwin" |
|
should use the normal Unix-style `./configure'. |
|
|
|
It might be possible to build without the help of `configure', |
|
certainly all the code is there, but unfortunately you'll be on |
|
your own. |
|
|
|
Build Directory |
|
To compile in a separate build directory, `cd' to that directory, |
and prefix the configure command with the path to the GMP source |
and prefix the configure command with the path to the GMP source |
directory. For example `../src/gmp/configure'. Not all `make' |
directory. For example |
programs have the necessary features (`VPATH') to support this. |
|
In particular, SunOS and Slowaris `make' have bugs that make them |
|
unable to build from a separate object directory. Use GNU `make' |
|
instead. |
|
|
|
|
cd /my/build/dir |
|
/my/sources/gmp-4.1.2/configure |
|
|
|
Not all `make' programs have the necessary features (`VPATH') to |
|
support this. In particular, SunOS and Slowaris `make' have bugs |
|
that make them unable to build in a separate directory. Use GNU |
|
`make' instead. |
|
|
`--disable-shared', `--disable-static' |
`--disable-shared', `--disable-static' |
By default both shared and static libraries are built (where |
By default both shared and static libraries are built (where |
possible), but one or other can be disabled. Shared libraries are |
possible), but one or other can be disabled. Shared libraries |
very slightly slower, having a small cost on each function call, |
result in smaller executables and permit code sharing between |
but result in smaller executables and permit code sharing between |
separate running processes, but on some CPUs are slightly slower, |
separate running processes. |
having a small cost on each function call. |
|
|
`--target=CPU-VENDOR-OS' |
Native Compilation, `--build=CPU-VENDOR-OS' |
The build target can be specified in the usual way, for either |
For normal native compilation, the system can be specified with |
native or cross compilation. |
`--build'. By default `./configure' uses the output from running |
|
`./config.guess'. On some systems `./config.guess' can determine |
|
the exact CPU type, on others it will be necessary to give it |
|
explicitly. For example, |
|
|
If `--target' isn't given, `./configure' builds for the host |
./configure --build=ultrasparc-sun-solaris2.7 |
system as determined by `./config.guess'. On some systems this |
|
can't distinguish between different CPUs in a family, and you |
|
should check the guess. Running `./config.guess' on the target |
|
system will also show the relevant `VENDOR-OS', if you don't |
|
already know what it should be. |
|
|
|
|
In all cases the `OS' part is important, since it controls how |
|
libtool generates shared libraries. Running `./config.guess' is |
|
the simplest way to see what it should be, if you don't know |
|
already. |
|
|
|
Cross Compilation, `--host=CPU-VENDOR-OS' |
|
When cross-compiling, the system used for compiling is given by |
|
`--build' and the system where the library will run is given by |
|
`--host'. For example when using a FreeBSD Athlon system to build |
|
GNU/Linux m68k binaries, |
|
|
|
./configure --build=athlon-pc-freebsd3.5 --host=m68k-mac-linux-gnu |
|
|
|
Compiler tools are sought first with the host system type as a |
|
prefix. For example `m68k-mac-linux-gnu-ranlib' is tried, then |
|
plain `ranlib'. This makes it possible for a set of |
|
cross-compiling tools to co-exist with native tools. The prefix |
|
is the argument to `--host', and this can be an alias, such as |
|
`m68k-linux'. But note that tools don't have to be setup this |
|
way, it's enough to just have a `PATH' with a suitable |
|
cross-compiling `cc' etc. |
|
|
|
Compiling for a different CPU in the same family as the build |
|
system is a form of cross-compilation, though very possibly this |
|
would merely be special options on a native compiler. In any case |
|
`./configure' avoids depending on being able to run code on the |
|
build system, which is important when creating binaries for a |
|
newer CPU since they very possibly won't run on the build system. |
|
|
|
In all cases the compiler must be able to produce an executable |
|
(of whatever format) from a standard C `main'. Although only |
|
object files will go to make up `libgmp', `./configure' uses |
|
linking tests for various purposes, such as determining what |
|
functions are available on the host system. |
|
|
|
Currently a warning is given unless an explicit `--build' is used |
|
when cross-compiling, because it may not be possible to correctly |
|
guess the build system type if the `PATH' has only a |
|
cross-compiling `cc'. |
|
|
|
Note that the `--target' option is not appropriate for GMP. It's |
|
for use when building compiler tools, with `--host' being where |
|
they will run, and `--target' what they'll produce code for. |
|
Ordinary programs or libraries like GMP are only interested in the |
|
`--host' part, being where they'll run. (Some past versions of |
|
GMP used `--target' incorrectly.) |
|
|
|
CPU types |
In general, if you want a library that runs as fast as possible, |
In general, if you want a library that runs as fast as possible, |
you should configure GMP for the exact CPU type your system uses. |
you should configure GMP for the exact CPU type your system uses. |
However, this may mean the binaries won't run on older members of |
However, this may mean the binaries won't run on older members of |
Line 219 Object Directory |
|
Line 313 Object Directory |
|
The best idea is always to build GMP for the exact machine type |
The best idea is always to build GMP for the exact machine type |
you intend to run it on. |
you intend to run it on. |
|
|
The following CPU targets have specific assembly code support. See |
The following CPUs have specific support. See `configure.in' for |
`configure.in' for which `mpn' subdirectories get used by each. |
details of what code and compiler options they select. |
|
|
* Alpha: `alpha', `alphaev5', `alphaev6' |
* Alpha: alpha, alphaev5, alphaev56, alphapca56, alphapca57, |
|
alphaev6, alphaev67, alphaev68 |
|
|
* Hitachi: `sh', `sh2' |
* Cray: c90, j90, t90, sv1 |
|
|
* HPPA: `hppa1.0', `hppa1.1', `hppa2.0', `hppa2.0w' |
* HPPA: hppa1.0, hppa1.1, hppa2.0, hppa2.0n, hppa2.0w |
|
|
* MIPS: `mips', `mips3', |
* MIPS: mips, mips3, mips64 |
|
|
* Motorola: `m68000', `m68k', `m88k', `m88110' |
* Motorola: m68k, m68000, m68010, m68020, m68030, m68040, |
|
m68060, m68302, m68360, m88k, m88110 |
|
|
* POWER: `power1', `power2', `power2sc', `powerpc', `powerpc64' |
* POWER: power, power1, power2, power2sc |
|
|
* SPARC: `sparc', `sparcv8', `microsparc', `supersparc', |
* PowerPC: powerpc, powerpc64, powerpc401, powerpc403, |
`sparcv9', `ultrasparc', `sparc64' |
powerpc405, powerpc505, powerpc601, powerpc602, powerpc603, |
|
powerpc603e, powerpc604, powerpc604e, powerpc620, powerpc630, |
|
powerpc740, powerpc7400, powerpc7450, powerpc750, powerpc801, |
|
powerpc821, powerpc823, powerpc860, |
|
|
* 80x86 family: `i386', `i486', `i586', `pentium', `pentiummmx', |
* SPARC: sparc, sparcv8, microsparc, supersparc, sparcv9, |
`pentiumpro', `pentium2', `pentium3', `k6', `k62', `k63', |
ultrasparc, ultrasparc2, ultrasparc2i, ultrasparc3, sparc64 |
`athlon' |
|
|
|
* Other: `a29k', `arm', `clipper', `i960', `ns32k', `pyramid', |
* 80x86 family: i386, i486, i586, pentium, pentiummmx, |
`vax', `z8k' |
pentiumpro, pentium2, pentium3, pentium4, k6, k62, k63, athlon |
|
|
CPUs not listed use generic C code. If some of the assembly code |
* Other: a29k, arm, clipper, i960, ns32k, pyramid, sh, sh2, vax, |
causes problems, the generic C code can be selected with CPU |
z8k |
`none'. |
|
|
|
|
CPUs not listed will use generic C code. |
|
|
|
Generic C Build |
|
If some of the assembly code causes problems, or if otherwise |
|
desired, the generic C code can be selected with CPU `none'. For |
|
example, |
|
|
|
./configure --host=none-unknown-freebsd3.5 |
|
|
|
Note that this will run quite slowly, but it should be portable |
|
and should at least make it possible to get something running if |
|
all else fails. |
|
|
|
`ABI' |
|
On some systems GMP supports multiple ABIs (application binary |
|
interfaces), meaning data type sizes and calling conventions. By |
|
default GMP chooses the best ABI available, but a particular ABI |
|
can be selected. For example |
|
|
|
./configure --host=mips64-sgi-irix6 ABI=n32 |
|
|
|
See *Note ABI and ISA::, for the available choices on relevant |
|
CPUs, and what applications need to do. |
|
|
`CC', `CFLAGS' |
`CC', `CFLAGS' |
The C compiler used is chosen from among some likely candidates, |
By default the C compiler used is chosen from among some likely |
with GCC normally preferred if it's present. The usual |
candidates, with `gcc' normally preferred if it's present. The |
`CC=whatever' can be passed to `./configure' to choose something |
usual `CC=whatever' can be passed to `./configure' to choose |
different. |
something different. |
|
|
For some configurations specific compiler flags are set based on |
For some systems, default compiler flags are set based on the CPU |
the target CPU and compiler, see `CFLAGS' in the generated |
and compiler. The usual `CFLAGS="-whatever"' can be passed to |
`Makefile's. The usual `CFLAGS="-whatever"' can be passed to |
|
`./configure' to use something different or to set good flags for |
`./configure' to use something different or to set good flags for |
systems GMP doesn't otherwise know. |
systems GMP doesn't otherwise know. |
|
|
Note that if `CC' is set then `CFLAGS' must also be set. This |
The `CC' and `CFLAGS' used are printed during `./configure', and |
applies even if `CC' is merely one of the choices GMP would make |
can be found in each generated `Makefile'. This is the easiest way |
itself. This may change in a future release. |
to check the defaults when considering changing or adding |
|
something. |
|
|
`--disable-alloca' |
Note that when `CC' and `CFLAGS' are specified on a system |
By default, GMP allocates temporary workspace using `alloca' if |
supporting multiple ABIs it's important to give an explicit |
that function is available, or `malloc' if not. If you're working |
`ABI=whatever', since GMP can't determine the ABI just from the |
with large numbers and `alloca' overflows the available stack |
flags and won't be able to select the correct assembler code. |
space, you can build with `--disable-alloca' to use `malloc' |
|
instead. `malloc' will probably be slightly slower than `alloca'. |
|
|
|
When not using `alloca', it's actually the allocation function |
If just `CC' is selected then normal default `CFLAGS' for that |
selected with `mp_set_memory_functions' that's used, this being |
compiler will be used (if GMP recognises it). For example |
`malloc' by default. *Note Custom Allocation::. |
`CC=gcc' can be used to force the use of GCC, with default flags |
|
(and default ABI). |
|
|
Depending on your system, the only indication of stack overflow |
`CPPFLAGS' |
might be a segmentation violation. It might be possible to |
Any flags like `-D' defines or `-I' includes required by the |
increase available stack space with `limit', `ulimit' or |
preprocessor should be set in `CPPFLAGS' rather than `CFLAGS'. |
`setrlimit', or under DJGPP with `stubedit' or `_stklen'. |
Compiling is done with both `CPPFLAGS' and `CFLAGS', but |
|
preprocessing uses just `CPPFLAGS'. This distinction is because |
|
most preprocessors won't accept all the flags the compiler does. |
|
Preprocessing is done separately in some configure tests, and in |
|
the `ansi2knr' support for K&R compilers. |
|
|
`--enable-fft' |
C++ Support, `--enable-cxx' |
By default multiplications are done using Karatsuba and 3-way |
C++ support in GMP can be enabled with `--enable-cxx', in which |
Toom-Cook algorithms, but a Fermat FFT can be enabled, for use on |
case a C++ compiler will be required. As a convenience |
large to very large operands. Currently the FFT is recommended |
`--enable-cxx=detect' can be used to enable C++ support only if a |
only for knowledgeable users who check the algorithm thresholds |
compiler can be found. The C++ support consists of a library |
for their CPU. |
`libgmpxx.la' and header file `gmpxx.h'. |
|
|
`--enable-mpbsd' |
A separate `libgmpxx.la' has been adopted rather than having C++ |
The Berkeley MP compatibility library (`libmp.a') and header file |
objects within `libgmp.la' in order to ensure dynamic linked C |
|
programs aren't bloated by a dependency on the C++ standard |
|
library, and to avoid any chance that the C++ compiler could be |
|
required when linking plain C programs. |
|
|
|
`libgmpxx.la' will use certain internals from `libgmp.la' and can |
|
only be expected to work with `libgmp.la' from the same GMP |
|
version. Future changes to the relevant internals will be |
|
accompanied by renaming, so a mismatch will cause unresolved |
|
symbols rather than perhaps mysterious misbehaviour. |
|
|
|
In general `libgmpxx.la' will be usable only with the C++ compiler |
|
that built it, since name mangling and runtime support are usually |
|
incompatible between different compilers. |
|
|
|
`CXX', `CXXFLAGS' |
|
When C++ support is enabled, the C++ compiler and its flags can be |
|
set with variables `CXX' and `CXXFLAGS' in the usual way. The |
|
default for `CXX' is the first compiler that works from a list of |
|
likely candidates, with `g++' normally preferred when available. |
|
The default for `CXXFLAGS' is to try `CFLAGS', `CFLAGS' without |
|
`-g', then for `g++' either `-g -O2' or `-O2', or for other |
|
compilers `-g' or nothing. Trying `CFLAGS' this way is convenient |
|
when using `gcc' and `g++' together, since the flags for `gcc' will |
|
usually suit `g++'. |
|
|
|
It's important that the C and C++ compilers match, meaning their |
|
startup and runtime support routines are compatible and that they |
|
generate code in the same ABI (if there's a choice of ABIs on the |
|
system). `./configure' isn't currently able to check these things |
|
very well itself, so for that reason `--disable-cxx' is the |
|
default, to avoid a build failure due to a compiler mismatch. |
|
Perhaps this will change in the future. |
|
|
|
Incidentally, it's normally not good enough to set `CXX' to the |
|
same as `CC'. Although `gcc' for instance recognises `foo.cc' as |
|
C++ code, only `g++' will invoke the linker the right way when |
|
building an executable or shared library from object files. |
|
|
|
Temporary Memory, `--enable-alloca=<choice>' |
|
GMP allocates temporary workspace using one of the following three |
|
methods, which can be selected with for instance |
|
`--enable-alloca=malloc-reentrant'. |
|
|
|
* `alloca' - C library or compiler builtin. |
|
|
|
* `malloc-reentrant' - the heap, in a re-entrant fashion. |
|
|
|
* `malloc-notreentrant' - the heap, with global variables. |
|
|
|
For convenience, the following choices are also available. |
|
`--disable-alloca' is the same as `--enable-alloca=no'. |
|
|
|
* `yes' - a synonym for `alloca'. |
|
|
|
* `no' - a synonym for `malloc-reentrant'. |
|
|
|
* `reentrant' - `alloca' if available, otherwise |
|
`malloc-reentrant'. This is the default. |
|
|
|
* `notreentrant' - `alloca' if available, otherwise |
|
`malloc-notreentrant'. |
|
|
|
`alloca' is reentrant and fast, and is recommended, but when |
|
working with large numbers it can overflow the available stack |
|
space, in which case one of the two malloc methods will need to be |
|
used. Alternately it might be possible to increase available |
|
stack with `limit', `ulimit' or `setrlimit', or under DJGPP with |
|
`stubedit' or `_stklen'. Note that depending on the system the |
|
only indication of stack overflow might be a segmentation |
|
violation. |
|
|
|
`malloc-reentrant' is, as the name suggests, reentrant and thread |
|
safe, but `malloc-notreentrant' is faster and should be used if |
|
reentrancy is not required. |
|
|
|
The two malloc methods in fact use the memory allocation functions |
|
selected by `mp_set_memory_functions', these being `malloc' and |
|
friends by default. *Note Custom Allocation::. |
|
|
|
An additional choice `--enable-alloca=debug' is available, to help |
|
when debugging memory related problems (*note Debugging::). |
|
|
|
FFT Multiplication, `--disable-fft' |
|
By default multiplications are done using Karatsuba, 3-way |
|
Toom-Cook, and Fermat FFT. The FFT is only used on large to very |
|
large operands and can be disabled to save code size if desired. |
|
|
|
Berkeley MP, `--enable-mpbsd' |
|
The Berkeley MP compatibility library (`libmp') and header file |
(`mp.h') are built and installed only if `--enable-mpbsd' is used. |
(`mp.h') are built and installed only if `--enable-mpbsd' is used. |
*Note BSD Compatible Functions::. |
*Note BSD Compatible Functions::. |
|
|
|
MPFR, `--enable-mpfr' |
|
The optional MPFR functions are built and installed only if |
|
`--enable-mpfr' is used. These are in a separate library |
|
`libmpfr.a' and are documented separately too (*note Introduction |
|
to MPFR: (mpfr)Introduction to MPFR.). |
|
|
|
Assertion Checking, `--enable-assert' |
|
This option enables some consistency checking within the library. |
|
This can be of use while debugging, *note Debugging::. |
|
|
|
Execution Profiling, `--enable-profiling=prof/gprof' |
|
Profiling support can be enabled either for `prof' or `gprof'. |
|
This adds `-p' or `-pg' respectively to `CFLAGS', and for some |
|
systems adds corresponding `mcount' calls to the assembler code. |
|
*Note Profiling::. |
|
|
`MPN_PATH' |
`MPN_PATH' |
Various assembler versions of mpn subroutines are provided, and, |
Various assembler versions of each mpn subroutines are provided. |
for a given CPU target, a search is made though a path to choose a |
For a given CPU, a search is made though a path to choose a |
version of each. For example `sparcv8' has path `"sparc32/v8 |
version of each. For example `sparcv8' has |
sparc32 generic"', which means it looks first for v8 code, falls |
|
back on plain sparc32, and finally falls back on generic C. |
|
Knowledgeable users with special requirements can specify a path |
|
with `MPN_PATH="dir list"'. This will normally be unnecessary |
|
because all sensible paths should be available under one or other |
|
CPU target. |
|
|
|
Demonstration Programs |
MPN_PATH="sparc32/v8 sparc32 generic" |
The `demos' subdirectory has some sample programs using GMP. These |
|
aren't built or installed, but there's a `Makefile' with rules for |
|
them. For instance, `make pexpr' and then `./pexpr 68^975+10'. |
|
|
|
|
which means look first for v8 code, then plain sparc32 (which is |
|
v7), and finally fall back on generic C. Knowledgeable users with |
|
special requirements can specify a different path. Normally this |
|
is completely unnecessary. |
|
|
Documentation |
Documentation |
The document you're now reading is `gmp.texi'. The usual automake |
The document you're now reading is `gmp.texi'. The usual automake |
targets are available to make `gmp.ps' and/or `gmp.dvi'. Some |
targets are available to make PostScript `gmp.ps' and/or DVI |
supplementary notes can be found in the `doc' subdirectory. |
`gmp.dvi'. |
|
|
|
HTML can be produced with `makeinfo --html', see *Note Generating |
|
HTML: (texinfo)makeinfo html. Or alternately `texi2html', see |
|
*Note Texinfo to HTML: (texi2html)Top. |
|
|
|
PDF can be produced with `texi2dvi --pdf' (*note PDF: (texinfo)PDF |
|
Output.) or with `pdftex'. |
|
|
|
Some supplementary notes can be found in the `doc' subdirectory. |
|
|
|
|
File: gmp.info, Node: ABI and ISA, Next: Notes for Package Builds, Prev: Build Options, Up: Installing GMP |
File: gmp.info, Node: ABI and ISA, Next: Notes for Package Builds, Prev: Build Options, Up: Installing GMP |
|
|
Line 326 the instructions and registers a CPU has available. |
|
Line 560 the instructions and registers a CPU has available. |
|
|
|
Some 64-bit ISA CPUs have both a 64-bit ABI and a 32-bit ABI |
Some 64-bit ISA CPUs have both a 64-bit ABI and a 32-bit ABI |
defined, the latter for compatibility with older CPUs in the family. |
defined, the latter for compatibility with older CPUs in the family. |
GMP chooses the best ABI available for a given target system, and this |
GMP supports some CPUs like this in both ABIs. In fact within GMP |
generally gives significantly greater speed. |
`ABI' means a combination of chip ABI, plus how GMP chooses to use it. |
|
For example in some 32-bit ABIs, GMP may support a limb as either a |
|
32-bit `long' or a 64-bit `long long'. |
|
|
The burden is on application programs and cooperating libraries to |
By default GMP chooses the best ABI available for a given system, |
ensure they match the ABI chosen by GMP. Fortunately this presents a |
and this generally gives significantly greater speed. But an ABI can |
difficulty only on a few systems, and if you have one of them then the |
be chosen explicitly to make GMP compatible with other libraries, or |
performance gains are enough to make it worth the trouble. |
particular application requirements. For example, |
|
|
Some of what's described in this section may change in future |
./configure ABI=32 |
releases of GMP. |
|
|
|
HPPA 2.0 |
In all cases it's vital that all object code used in a given program |
CPU target `hppa2.0' uses the hppa2.0n 32-bit ABI, but either a |
is compiled for the same ABI. |
32-bit or 64-bit limb. |
|
|
|
A 64-bit limb is available on HP-UX 10 or up when using `c89'. No |
Usually a limb is implemented as a `long'. When a `long long' limb |
`gcc' support is planned for 64-bit operations in this ABI. |
is used this is encoded in the generated `gmp.h'. This is convenient |
Applications must be compiled with the same options as GMP, which |
for applications, but it does mean that `gmp.h' will vary, and can't be |
means |
just copied around. `gmp.h' remains compiler independent though, since |
|
all compilers for a particular ABI will be expected to use the same |
|
limb type. |
|
|
c89 +DA2.0 +e -D_LONG_LONG_LIMB |
Currently no attempt is made to follow whatever conventions a system |
|
has for installing library or header files built for a particular ABI. |
|
This will probably only matter when installing multiple builds of GMP, |
|
and it might be as simple as configuring with a special `libdir', or it |
|
might require more than that. Note that builds for different ABIs need |
|
to done separately, with a fresh `./configure' and `make' each. |
|
|
A 32-bit limb is used in other cases, and no special compiler |
|
options are needed. |
|
|
|
CPU target `hppa2.0w' uses the hppa2.0w 64-bit ABI, which is |
HPPA 2.0 (`hppa2.0*') |
available on HP-UX 11 or up when using `c89'. `gcc' support for |
|
this is in progress. Applications must be compiled for the same |
|
ABI, which means |
|
|
|
c89 +DD64 |
`ABI=2.0w' |
|
The 2.0w ABI uses 64-bit limbs and pointers and is available |
|
on HP-UX 11 or up when using `cc'. `gcc' support for this is |
|
in progress. Applications must be compiled with |
|
|
MIPS 3 and 4 under IRIX 6 |
cc +DD64 |
Targets `mips*-*-irix6*' use the n32 ABI and a 64-bit limb. |
|
Applications must be compiled for the same ABI, which means either |
|
|
|
gcc -mabi=n32 |
`ABI=2.0n' |
cc -n32 |
The 2.0n ABI means the 32-bit HPPA 1.0 ABI but with a 64-bit |
|
limb using `long long'. This is available on HP-UX 10 or up |
|
when using `cc'. No `gcc' support is planned for this. |
|
Applications must be compiled with |
|
|
PowerPC 64 |
cc +DA2.0 +e |
CPU target `powerpc64' uses either the 32-bit ABI or the AIX |
|
64-bit ABI. The latter is used on targets `powerpc64-*-aix*' and |
|
applications must be compiled using either |
|
|
|
gcc -maix64 |
`ABI=1.0' |
xlc -q64 |
HPPA 2.0 CPUs can run all HPPA 1.0 and 1.1 code in the 32-bit |
|
HPPA 1.0 ABI. No special compiler options are needed for |
|
applications. |
|
|
On other systems the 32-bit ABI is used, but with 64-bit limbs |
All three ABIs are available for CPUs `hppa2.0w' and `hppa2.0', but |
provided by `long long' in `gcc'. Applications must be compiled |
for CPU `hppa2.0n' only 2.0n or 1.0 are allowed. |
using |
|
|
|
gcc -D_LONG_LONG_LIMB |
|
|
|
Sparc V9 |
MIPS under IRIX 6 (`mips*-*-irix[6789]') |
On a sparc v9 CPU, either the v8plus 32-bit ABI or v9 64-bit ABI |
IRIX 6 supports the n32 and 64 ABIs and always has a 64-bit MIPS 3 |
is used. Targets `ultrasparc*-*-solaris2.[7-9]', |
or better CPU. In both these ABIs GMP uses a 64-bit limb. A new |
`sparcv9-*-solaris2.[7-9]' and `sparc64-*-linux*' use the v9 ABI, |
enough `gcc' is required (2.95 for instance). |
if the compiler supports it. Other targets use the v8plus ABI |
|
(but with as much of the v9 ISA as possible in the circumstances). |
|
Note that Solaris prior to 2.7 doesn't save all registers |
|
properly, and hence uses the v8plus ABI. |
|
|
|
For the v8plus ABI, applications can be compiled with either |
`ABI=n32' |
|
The n32 ABI is 32-bit pointers and integers, but with a |
|
64-bit limb using a `long long'. Applications must be |
|
compiled with |
|
|
gcc -mv8plus |
gcc -mabi=n32 |
cc -xarch=v8plus |
cc -n32 |
|
|
For the v9 ABI, applications must be compiled with either |
`ABI=64' |
|
The 64-bit ABI is 64-bit pointers and integers. Applications |
|
must be compiled with |
|
|
gcc -m64 -mptr64 -Wa,-xarch=v9 -mcpu=v9 |
gcc -mabi=64 |
cc -xarch=v9 |
cc -64 |
|
|
Don't be confused by the names of these options, they're called |
Note that MIPS GNU/Linux, as of kernel version 2.2, doesn't have |
`arch' but they effectively control the ABI. |
the necessary support for n32 or 64 and so only gets a 32-bit limb |
|
and the MIPS 2 code. |
|
|
|
|
|
PowerPC 64 (`powerpc64', `powerpc620', `powerpc630') |
|
|
|
`ABI=aix64' |
|
The AIX 64 ABI uses 64-bit limbs and pointers and is |
|
available on systems `*-*-aix*'. Applications must be |
|
compiled (and linked) with |
|
|
|
gcc -maix64 |
|
xlc -q64 |
|
|
|
`ABI=32' |
|
This is the basic 32-bit PowerPC ABI. No special compiler |
|
options are needed for applications. |
|
|
|
|
|
Sparc V9 (`sparcv9' and `ultrasparc*') |
|
|
|
`ABI=64' |
|
The 64-bit V9 ABI is available on Solaris 2.7 and up and |
|
GNU/Linux. GCC 2.95 or up, or Sun `cc' is required. |
|
Applications must be compiled with |
|
|
|
gcc -m64 -mptr64 -Wa,-xarch=v9 -mcpu=v9 |
|
cc -xarch=v9 |
|
|
|
`ABI=32' |
|
On Solaris 2.6 and earlier, and on Solaris 2.7 with the |
|
kernel in 32-bit mode, only the plain V8 32-bit ABI can be |
|
used, since the kernel doesn't save all registers. GMP still |
|
uses as much of the V9 ISA as it can in these circumstances. |
|
No special compiler options are required for applications, |
|
though using something like the following requesting V9 code |
|
within the V8 ABI is recommended. |
|
|
|
gcc -mv8plus |
|
cc -xarch=v8plus |
|
|
|
`gcc' 2.8 and earlier only supports `-mv8' though. |
|
|
|
Don't be confused by the names of these sparc `-m' and `-x' |
|
options, they're called `arch' but they effectively control the |
|
ABI. |
|
|
|
On Solaris 2.7 with the kernel in 32-bit-mode, a normal native |
|
build will reject `ABI=64' because the resulting executables won't |
|
run. `ABI=64' can still be built if desired by making it look |
|
like a cross-compile, for example |
|
|
|
./configure --build=none --host=sparcv9-sun-solaris2.7 ABI=64 |
|
|
|
|
File: gmp.info, Node: Notes for Package Builds, Next: Notes for Particular Systems, Prev: ABI and ISA, Up: Installing GMP |
File: gmp.info, Node: Notes for Package Builds, Next: Notes for Particular Systems, Prev: ABI and ISA, Up: Installing GMP |
|
|
Line 411 Notes for Package Builds |
|
Line 701 Notes for Package Builds |
|
distribution. |
distribution. |
|
|
Libtool is used to build the library and `-version-info' is set |
Libtool is used to build the library and `-version-info' is set |
appropriately, having started from `3:0:0' in GMP 3.0. The GMP 3 series |
appropriately, having started from `3:0:0' in GMP 3.0. The GMP 4 series |
will be upwardly binary compatible in each release, but may be adding |
will be upwardly binary compatible in each release and will be upwardly |
additional function interfaces. On systems where libtool versioning is |
binary compatible with all of the GMP 3 series. Additional function |
not fully checked by the loader, an auxiliary mechanism may be needed |
interfaces may be added in each release, so on systems where libtool |
to express that a dynamic linked application depends on a new enough |
versioning is not fully checked by the loader an auxiliary mechanism |
minor version of GMP. |
may be needed to express that a dynamic linked application depends on a |
|
new enough GMP. |
|
|
|
An auxiliary mechanism may also be needed to express that |
|
`libgmpxx.la' (from `--enable-cxx', *note Build Options::) requires |
|
`libgmp.la' from the same GMP version, since this is not done by the |
|
libtool versioning, nor otherwise. A mismatch will result in |
|
unresolved symbols from the linker, or perhaps the loader. |
|
|
|
Using `DESTDIR' or a `prefix' override with `make install' and a |
|
shared `libgmpxx' may run into a libtool relinking problem, see *Note |
|
Known Build Problems::. |
|
|
When building a package for a CPU family, care should be taken to use |
When building a package for a CPU family, care should be taken to use |
`--target' to choose the least common denominator among the CPUs which |
`--host' (or `--build') to choose the least common denominator among |
might use the package. For example this might necessitate `i386' for |
the CPUs which might use the package. For example this might |
x86s, or plain `sparc' (meaning V7) for SPARCs. |
necessitate `i386' for x86s, or plain `sparc' (meaning V7) for SPARCs. |
|
|
Users who care about speed will want GMP built for their exact CPU |
Users who care about speed will want GMP built for their exact CPU |
type, to make use of the available optimizations. Providing a way to |
type, to make use of the available optimizations. Providing a way to |
suitably rebuild a package may be useful. This could be as simple as |
suitably rebuild a package may be useful. This could be as simple as |
making it possible for a user to omit `--target' in a build so |
making it possible for a user to omit `--build' (and `--host') so |
`./config.guess' will detect the CPU. But a way to manually specify a |
`./config.guess' will detect the CPU. But a way to manually specify a |
`--target' will be wanted for systems where `./config.guess' is inexact. |
`--build' will be wanted for systems where `./config.guess' is inexact. |
|
|
|
Note that `gmp.h' is a generated file, and will be architecture and |
|
ABI dependent. |
|
|
|
|
File: gmp.info, Node: Notes for Particular Systems, Next: Known Build Problems, Prev: Notes for Package Builds, Up: Installing GMP |
File: gmp.info, Node: Notes for Particular Systems, Next: Known Build Problems, Prev: Notes for Package Builds, Up: Installing GMP |
|
|
Notes for Particular Systems |
Notes for Particular Systems |
============================ |
============================ |
|
|
AIX 4.3 |
AIX 3 and 4 |
Targets `*-*-aix4.[3-9]*' have shared libraries disabled since |
On systems `*-*-aix[34]*' shared libraries are disabled by |
they seem to fail on AIX 4.3. |
default, since some versions of the native `ar' fail on the |
|
convenience libraries used. A shared build can be attempted with |
|
|
|
./configure --enable-shared --disable-static |
|
|
|
Note that the `--disable-static' is necessary because in a shared |
|
build libtool makes `libgmp.a' a symlink to `libgmp.so', |
|
apparently for the benefit of old versions of `ld' which only |
|
recognise `.a', but unfortunately this is done even if a fully |
|
functional `ld' is available. |
|
|
|
ARM |
|
On systems `arm*-*-*', versions of GCC up to and including 2.95.3 |
|
have a bug in unsigned division, giving wrong results for some |
|
operands. GMP `./configure' will demand GCC 2.95.4 or later. |
|
|
|
Compaq C++ |
|
Compaq C++ on OSF 5.1 has two flavours of `iostream', a standard |
|
one and an old pre-standard one (see `man iostream_intro'). GMP |
|
can only use the standard one, which unfortunately is not the |
|
default but must be selected by defining `__USE_STD_IOSTREAM'. |
|
Configure with for instance |
|
|
|
./configure --enable-cxx CPPFLAGS=-D__USE_STD_IOSTREAM |
|
|
|
Microsoft Windows |
|
On systems `*-*-cygwin*', `*-*-mingw*' and `*-*-pw32*' by default |
|
GMP builds only a static library, but a DLL can be built instead |
|
using |
|
|
|
./configure --disable-static --enable-shared |
|
|
|
Static and DLL libraries can't both be built, since certain export |
|
directives in `gmp.h' must be different. `--enable-cxx' cannot be |
|
used when building a DLL, since libtool doesn't currently support |
|
C++ DLLs. This might change in the future. |
|
|
|
Microsoft C |
|
A MINGW DLL build of GMP can be used with Microsoft C. Libtool |
|
doesn't install `.lib' and `.exp' files, but they can be created |
|
with the following commands, where `/my/inst/dir' is the install |
|
directory (with a `lib' subdirectory). |
|
|
|
lib /machine:IX86 /def:_libs/libgmp-3.dll-def |
|
cp libgmp-3.lib /my/inst/dir/lib |
|
cp _libs/libgmp-3.dll-exp /my/inst/dir/lib/libgmp-3.exp |
|
|
|
MINGW uses `msvcrt.dll' for I/O, so applications wanting to use |
|
the GMP I/O routines must be compiled with `cl /MD' to do the |
|
same. If one of the other I/O choices provided by MS C is desired |
|
then the suggestion is to use the GMP string functions and confine |
|
I/O to the application. |
|
|
|
Motorola 68k CPU Types |
|
`m68k' is taken to mean 68000. `m68020' or higher will give a |
|
performance boost on applicable CPUs. `m68360' can be used for |
|
CPU32 series chips. `m68302' can be used for "Dragonball" series |
|
chips, though this is merely a synonym for `m68000'. |
|
|
OpenBSD 2.6 |
OpenBSD 2.6 |
`m4' in this release of OpenBSD has a bug in `eval' that makes it |
`m4' in this release of OpenBSD has a bug in `eval' that makes it |
unsuitable for `.asm' file processing. `./configure' will detect |
unsuitable for `.asm' file processing. `./configure' will detect |
the problem and either abort or choose another m4 in the `PATH'. |
the problem and either abort or choose another m4 in the `PATH'. |
The bug is fixed in OpenBSD 2.7, so either upgrade or use GNU m4. |
The bug is fixed in OpenBSD 2.7, so either upgrade or use GNU m4. |
|
|
Sparc V8 |
Power CPU Types |
Using CPU target `sparcv8' or `supersparc' on relevant systems will |
In GMP, CPU types `power*' and `powerpc*' will each use |
give a significant performance increase over the V7 code. |
instructions not available on the other, so it's important to |
|
choose the right one for the CPU that will be used. Currently GMP |
|
has no assembler code support for using just the common |
|
instruction subset. To get executables that run on both, the |
|
current suggestion is to use the generic C code (CPU `none'), |
|
possibly with appropriate compiler options (like `-mcpu=common' for |
|
`gcc'). CPU `rs6000' (which is not a CPU but a family of |
|
workstations) is accepted by `config.sub', but is currently |
|
equivalent to `none'. |
|
|
|
Sparc CPU Types |
|
`sparcv8' or `supersparc' on relevant systems will give a |
|
significant performance increase over the V7 code. |
|
|
|
Sparc App Regs |
|
The GMP assembler code for both 32-bit and 64-bit Sparc clobbers |
|
the "application registers" `g2', `g3' and `g4', the same way that |
|
the GCC default `-mapp-regs' does (*note SPARC Options: (gcc)SPARC |
|
Options.). |
|
|
|
This makes that code unsuitable for use with the special V9 |
|
`-mcmodel=embmedany' (which uses `g4' as a data segment pointer), |
|
and for applications wanting to use those registers for special |
|
purposes. In these cases the only suggestion currently is to |
|
build GMP with CPU `none' to avoid the assembler code. |
|
|
SunOS 4 |
SunOS 4 |
`/usr/bin/m4' lacks various features needed to process `.asm' |
`/usr/bin/m4' lacks various features needed to process `.asm' |
files, and instead `./configure' will automatically use |
files, and instead `./configure' will automatically use |
`/usr/5bin/m4', which we believe is always available (if not then |
`/usr/5bin/m4', which we believe is always available (if not then |
use GNU m4). |
use GNU m4). |
|
|
x86 Pentium and PentiumPro |
x86 CPU Types |
The Intel Pentium P5 code is good for its intended P5, but quite |
`i386' selects generic code which will run reasonably well on all |
slow when run on Intel P6 class chips (PPro, P-II, P-III). `i386' |
x86 chips. |
is a better choice if you're making binaries that must run on both. |
|
|
|
x86 MMX and old GAS |
`i586', `pentium' or `pentiummmx' code is good for the intended P5 |
Old versions of GAS don't support MMX instructions, in particular |
Pentium chips, but quite slow when run on Intel P6 class chips |
version 1.92.3 that comes with FreeBSD 2.2.8 doesn't (and |
(PPro, P-II, P-III). `i386' is a better choice when making |
unfortunately there's no newer assembler for that system). |
binaries that must run on both. |
|
|
If the target CPU has MMX code but the assembler doesn't support |
`pentium4' and an SSE2 capable assembler are important for best |
|
results on Pentium 4. The specific code is for instance roughly a |
|
2x to 3x speedup over the generic `i386' code. |
|
|
|
x86 MMX and SSE2 Code |
|
If the CPU selected has MMX code but the assembler doesn't support |
it, a warning is given and non-MMX code is used instead. This |
it, a warning is given and non-MMX code is used instead. This |
will be an inferior build, since the MMX code that's present is |
will be an inferior build, since the MMX code that's present is |
there because it's faster than the corresponding plain integer |
there because it's faster than the corresponding plain integer |
code. |
code. The same applies to SSE2. |
|
|
x86 GCC 2.95.2 `-march=pentiumpro' |
Old versions of `gas' don't support MMX instructions, in particular |
GCC 2.95.2 miscompiles `mpz/powm.c' when `-march=pentiumpro' is |
version 1.92.3 that comes with FreeBSD 2.2.8 doesn't (and |
used, so that option is omitted from the `CFLAGS' chosen for |
unfortunately there's no newer assembler for that system). |
relevant CPUs. The problem is believed to be fixed in GCC 2.96. |
|
|
|
|
Solaris 2.6 and 2.7 `as' generate incorrect object code for |
|
register to register `movq' instructions, and so can't be used for |
|
MMX code. Install a recent `gas' if MMX code is wanted on these |
|
systems. |
|
|
|
|
File: gmp.info, Node: Known Build Problems, Prev: Notes for Particular Systems, Up: Installing GMP |
File: gmp.info, Node: Known Build Problems, Prev: Notes for Particular Systems, Up: Installing GMP |
|
|
Known Build Problems |
Known Build Problems |
==================== |
==================== |
|
|
You might find more up-to-date information at |
You might find more up-to-date information at `http://swox.com/gmp/'. |
`http://www.swox.com/gmp/'. |
|
|
|
Generic C on a 64-bit system |
Compiler link options |
When making a generic C build using `--target=none' on a 64-bit |
The version of libtool currently in use rather aggressively strips |
system (meaning where `unsigned long' is 64 bits), |
compiler options when linking a shared library. This will |
`BITS_PER_MP_LIMB', `BITS_PER_LONGINT' and `BYTES_PER_MP_LIMB' in |
hopefully be relaxed in the future, but for now if this is a |
`mpn/generic/gmp-mparam.h' need to be changed to 64 and 8. This |
problem the suggestion is to create a little script to hide them, |
will hopefully be automated in a future version of GMP. |
and for instance configure with |
|
|
|
./configure CC=gcc-with-my-options |
|
|
|
DJGPP |
|
The DJGPP port of `bash' 2.03 is unable to run the `configure' |
|
script, it exits silently, having died writing a preamble to |
|
`config.log'. Use `bash' 2.04 or higher. |
|
|
|
`make all' was found to run out of memory during the final |
|
`libgmp.la' link on one system tested, despite having 64Mb |
|
available. A separate `make libgmp.la' helped, perhaps recursing |
|
into the various subdirectories uses up memory. |
|
|
|
`DESTDIR' and shared `libgmpxx' |
|
`make install DESTDIR=/my/staging/area', or the same with a |
|
`prefix' override, to install to a temporary directory is not |
|
fully supported by current versions of libtool when building a |
|
shared version of a library which depends on another being built |
|
at the same time, like `libgmpxx' and `libgmp'. |
|
|
|
The problem is that `libgmpxx' is relinked at the install stage to |
|
ensure that if the system puts a hard-coded path to `libgmp' within |
|
`libgmpxx' then that path will be correct. Naturally the linker is |
|
directed to look only at the final location, not the staging area, |
|
so if `libgmp' is not already in that final location then the link |
|
will fail. |
|
|
|
A workaround for this on SVR4 style systems, such as GNU/Linux, |
|
where paths are not hard-coded, is to include the staging area in |
|
the linker's search using `LD_LIBRARY_PATH'. For example with |
|
`--prefix=/usr' but installing under `/my/staging/area', |
|
|
|
LD_LIBRARY_PATH=/my/staging/area/usr/lib \ |
|
make install DESTDIR=/my/staging/area |
|
|
|
GNU binutils `strip' prior to 2.12 |
|
`strip' from GNU binutils 2.11 and earlier should not be used on |
|
the static libraries `libgmp.a' and `libmp.a' since it will |
|
discard all but the last of multiple archive members with the same |
|
name, like the three versions of `init.o' in `libgmp.a'. Binutils |
|
2.12 or higher can be used successfully. |
|
|
|
The shared libraries `libgmp.so' and `libmp.so' are not affected by |
|
this and any version of `strip' can be used on them. |
|
|
|
`make' syntax error |
|
On certain versions of SCO OpenServer 5 and IRIX 6.5 the native |
|
`make' is unable to handle the long dependencies list for |
|
`libgmp.la'. The symptom is a "syntax error" on the following |
|
line of the top-level `Makefile'. |
|
|
|
libgmp.la: $(libgmp_la_OBJECTS) $(libgmp_la_DEPENDENCIES) |
|
|
|
Either use GNU Make, or as a workaround remove |
|
`$(libgmp_la_DEPENDENCIES)' from that line (which will make the |
|
initial build work, but if any recompiling is done `libgmp.la' |
|
might not be rebuilt). |
|
|
|
MacOS X and GCC |
|
Libtool currently only knows how to create shared libraries on |
|
MacOS X using the native `cc' (which is a modified GCC), not a |
|
plain GCC. A static-only build should work though |
|
(`--disable-shared'). |
|
|
|
Also, libtool currently cannot build C++ shared libraries on MacOS |
|
X, so if `--enable-cxx' is desired then `--disable-shared' must be |
|
used. Hopefully this will be fixed in the future. |
|
|
NeXT prior to 3.3 |
NeXT prior to 3.3 |
The system compiler on old versions of NeXT was a massacred and |
The system compiler on old versions of NeXT was a massacred and |
old GCC, even if it called itself `cc'. This compiler cannot be |
old GCC, even if it called itself `cc'. This compiler cannot be |
used to build GMP, you need to get a real GCC, and install that |
used to build GMP, you need to get a real GCC, and install that. |
before you compile GMP. (NeXT may have fixed this in release 3.3 |
(NeXT may have fixed this in release 3.3 of their system.) |
of their system.) |
|
|
|
POWER and PowerPC |
POWER and PowerPC |
Bugs in GCC 2.7.2 (and 2.6.3) mean it can't be used to compile GMP |
Bugs in GCC 2.7.2 (and 2.6.3) mean it can't be used to compile GMP |
Line 509 Sequent Symmetry |
|
Line 967 Sequent Symmetry |
|
Use the GNU assembler instead of the system assembler, since the |
Use the GNU assembler instead of the system assembler, since the |
latter has serious bugs. |
latter has serious bugs. |
|
|
Stripped Libraries |
Solaris 2.6 |
GNU binutils `strip' should not be used on the static libraries |
The system `sed' prints an error "Output line too long" when |
`libgmp.a' and `libmp.a', neither directly nor via `make |
libtool builds `libgmp.la'. This doesn't seem to cause any |
install-strip'. It can be used on the shared libraries |
obvious ill effects, but GNU `sed' is recommended, to avoid any |
`libgmp.so' and `libmp.so' though. |
doubt. |
|
|
Currently (binutils 2.10.0), `strip' extracts archives into a |
Sparc Solaris 2.7 with gcc 2.95.2 in ABI=32 |
single directory, but GMP contains multiple object files of the |
A shared library build of GMP seems to fail in this combination, |
same name (eg. three versions of `init.o'), and they overwrite |
it builds but then fails the tests, apparently due to some |
each other, leaving only the one that happens to be last. |
incorrect data relocations within `gmp_randinit_lc_2exp_size'. |
|
The exact cause is unknown, `--disable-shared' is recommended. |
|
|
If stripped static libraries are wanted, the suggested workaround |
Windows DLL test programs |
is to build normally, strip the separate object files, and do |
When creating a DLL version of `libgmp', libtool creates wrapper |
another `make all' to rebuild. Alternately `CFLAGS' with `-g' |
scripts like `t-mul' for programs that would normally be |
omitted can always be used if it's just debugging which is |
`t-mul.exe', in order to setup the right library paths etc. This |
unwanted. |
works fine, but the absence of `t-mul.exe' etc causes `make' to |
|
think they need recompiling every time, which is an annoyance when |
|
re-running a `make check'. |
|
|
SunOS 4 Native Tools |
|
The setting for `GSYM_PREFIX' in `config.m4' may be incorrectly |
|
determined when using the native `grep', leading at link-time to |
|
undefined symbols like `___gmpn_add_n'. To fix this, after running |
|
`./configure', change the relevant line in `config.m4' to |
|
`define(<GSYM_PREFIX>, <_>)'. |
|
|
|
The `ranlib' command will need to be run manually when building a |
|
static library with the native `ar'. After `make', run `ranlib |
|
.libs/libgmp.a', and when using `--enable-mpbsd' run `ranlib |
|
.libs/libmp.a' too. |
|
|
|
`version.c' compilation |
|
The current `./configure' relies on certain features of `sed' that |
|
some old systems don't have. One symptom is `VERSION' not being |
|
set correctly in the generated `config.h', leading to `version.c' |
|
failing to compile. Irix 5.3, MIPS RISC/OS and Ultrix 4.4 are |
|
believed to be affected. GNU `sed' is recommended, though it |
|
might be possible to build by editing `config.h' manually instead. |
|
|
|
VAX running Ultrix |
|
You need to build and install the GNU assembler before you compile |
|
GMP. The VAX assembly in GMP uses an instruction (`jsobgtr') that |
|
cannot be assembled by the Ultrix assembler. |
|
|
|
|
|
File: gmp.info, Node: GMP Basics, Next: Reporting Bugs, Prev: Installing GMP, Up: Top |
File: gmp.info, Node: GMP Basics, Next: Reporting Bugs, Prev: Installing GMP, Up: Top |
|
|
GMP Basics |
GMP Basics |
********** |
********** |
|
|
All declarations needed to use GMP are collected in the include file |
|
`gmp.h'. It is designed to work with both C and C++ compilers. |
|
|
|
*Using functions, macros, data types, etc. not documented in this |
*Using functions, macros, data types, etc. not documented in this |
manual is strongly discouraged. If you do so your application is |
manual is strongly discouraged. If you do so your application is |
guaranteed to be incompatible with future versions of GMP.* |
guaranteed to be incompatible with future versions of GMP.* |
|
|
* Menu: |
* Menu: |
|
|
* Nomenclature and Types:: Which data types are there? |
* Headers and Libraries:: |
* Function Classes:: How the functions are organized. |
* Nomenclature and Types:: |
* GMP Variable Conventions:: Some rules and hints about variables. |
* Function Classes:: |
* GMP and Reentrancy:: What about reentrancy? |
* Variable Conventions:: |
* Useful Macros and Constants:: Convenient helpers. |
* Parameter Conventions:: |
* Compatibility with older versions:: Compatibility issues. |
* Memory Management:: |
* Getting the Latest Version of GMP:: How to get the software. |
* Reentrancy:: |
|
* Useful Macros and Constants:: |
|
* Compatibility with older versions:: |
|
* Demonstration Programs:: |
|
* Efficiency:: |
|
* Debugging:: |
|
* Profiling:: |
|
* Autoconf:: |
|
* Emacs:: |
|
|
|
|
File: gmp.info, Node: Nomenclature and Types, Next: Function Classes, Prev: GMP Basics, Up: GMP Basics |
File: gmp.info, Node: Headers and Libraries, Next: Nomenclature and Types, Prev: GMP Basics, Up: GMP Basics |
|
|
|
Headers and Libraries |
|
===================== |
|
|
|
All declarations needed to use GMP are collected in the include file |
|
`gmp.h'. It is designed to work with both C and C++ compilers. |
|
|
|
#include <gmp.h> |
|
|
|
Note however that prototypes for GMP functions with `FILE *' |
|
parameters are only provided if `<stdio.h>' is included too. |
|
|
|
#include <stdio.h> |
|
#include <gmp.h> |
|
|
|
Likewise `<stdarg.h>' (or `<varargs.h>') is required for prototypes |
|
with `va_list' parameters, such as `gmp_vprintf'. And `<obstack.h>' |
|
for prototypes with `struct obstack' parameters, such as |
|
`gmp_obstack_printf', when available. |
|
|
|
All programs using GMP must link against the `libgmp' library. On a |
|
typical Unix-like system this can be done with `-lgmp', for example |
|
|
|
gcc myprogram.c -lgmp |
|
|
|
GMP C++ functions are in a separate `libgmpxx' library. This is |
|
built and installed if C++ support has been enabled (*note Build |
|
Options::). For example, |
|
|
|
g++ mycxxprog.cc -lgmpxx -lgmp |
|
|
|
GMP is built using Libtool and an application can use that to link |
|
if desired, *note Shared library support for GNU: (libtool)Top. |
|
|
|
If GMP has been installed to a non-standard location then it may be |
|
necessary to use `-I' and `-L' compiler options to point to the right |
|
directories, and some sort of run-time path for a shared library. |
|
Consult your compiler documentation, for instance *Note Introduction: |
|
(gcc)Top. |
|
|
|
|
|
File: gmp.info, Node: Nomenclature and Types, Next: Function Classes, Prev: Headers and Libraries, Up: GMP Basics |
|
|
Nomenclature and Types |
Nomenclature and Types |
====================== |
====================== |
|
|
Line 600 mantissa with a limited precision exponent. The C dat |
|
Line 1083 mantissa with a limited precision exponent. The C dat |
|
objects is `mpf_t'. |
objects is `mpf_t'. |
|
|
A "limb" means the part of a multi-precision number that fits in a |
A "limb" means the part of a multi-precision number that fits in a |
single word. (We chose this word because a limb of the human body is |
single machine word. (We chose this word because a limb of the human |
analogous to a digit, only larger, and containing several digits.) |
body is analogous to a digit, only larger, and containing several |
Normally a limb contains 32 or 64 bits. The C data type for a limb is |
digits.) Normally a limb is 32 or 64 bits. The C data type for a limb |
`mp_limb_t'. |
is `mp_limb_t'. |
|
|
|
|
File: gmp.info, Node: Function Classes, Next: GMP Variable Conventions, Prev: Nomenclature and Types, Up: GMP Basics |
File: gmp.info, Node: Function Classes, Next: Variable Conventions, Prev: Nomenclature and Types, Up: GMP Basics |
|
|
Function Classes |
Function Classes |
================ |
================ |
Line 614 Function Classes |
|
Line 1097 Function Classes |
|
There are six classes of functions in the GMP library: |
There are six classes of functions in the GMP library: |
|
|
1. Functions for signed integer arithmetic, with names beginning with |
1. Functions for signed integer arithmetic, with names beginning with |
`mpz_'. The associated type is `mpz_t'. There are about 100 |
`mpz_'. The associated type is `mpz_t'. There are about 150 |
functions in this class. |
functions in this class. |
|
|
2. Functions for rational number arithmetic, with names beginning with |
2. Functions for rational number arithmetic, with names beginning with |
`mpq_'. The associated type is `mpq_t'. There are about 20 |
`mpq_'. The associated type is `mpq_t'. There are about 40 |
functions in this class, but the functions in the previous class |
functions in this class, but the integer functions can be used for |
can be used for performing arithmetic on the numerator and |
arithmetic on the numerator and denominator separately. |
denominator separately. |
|
|
|
3. Functions for floating-point arithmetic, with names beginning with |
3. Functions for floating-point arithmetic, with names beginning with |
`mpf_'. The associated type is `mpf_t'. There are about 50 |
`mpf_'. The associated type is `mpf_t'. There are about 60 |
functions is this class. |
functions is this class. |
|
|
4. Functions compatible with Berkeley GMP, such as `itom', `madd', and |
4. Functions compatible with Berkeley MP, such as `itom', `madd', and |
`mult'. The associated type is `MINT'. |
`mult'. The associated type is `MINT'. |
|
|
5. Fast low-level functions that operate on natural numbers. These |
5. Fast low-level functions that operate on natural numbers. These |
are used by the functions in the preceding groups, and you can |
are used by the functions in the preceding groups, and you can |
also call them directly from very time-critical user programs. |
also call them directly from very time-critical user programs. |
These functions' names begin with `mpn_'. There are about 30 |
These functions' names begin with `mpn_'. The associated type is |
(hard-to-use) functions in this class. |
array of `mp_limb_t'. There are about 30 (hard-to-use) functions |
|
in this class. |
|
|
The associated type is array of `mp_limb_t'. |
|
|
|
6. Miscellaneous functions. Functions for setting up custom |
6. Miscellaneous functions. Functions for setting up custom |
allocation and functions for generating random numbers. |
allocation and functions for generating random numbers. |
|
|
|
|
File: gmp.info, Node: GMP Variable Conventions, Next: GMP and Reentrancy, Prev: Function Classes, Up: GMP Basics |
File: gmp.info, Node: Variable Conventions, Next: Parameter Conventions, Prev: Function Classes, Up: GMP Basics |
|
|
GMP Variable Conventions |
Variable Conventions |
======================== |
==================== |
|
|
As a general rule, all GMP functions expect output arguments before |
GMP functions generally have output arguments before input |
input arguments. This notation is based on an analogy with the |
arguments. This notation is by analogy with the assignment operator. |
assignment operator. (The BSD MP compatibility functions disobey this |
The BSD MP compatibility functions are exceptions, having the output |
rule, having the output argument(s) last.) |
arguments last. |
|
|
GMP lets you use the same variable for both input and output in one |
GMP lets you use the same variable for both input and output in one |
call. For example, the main function for integer multiplication, |
call. For example, the main function for integer multiplication, |
Line 665 functions for that purpose. Which function to use dep |
|
Line 1146 functions for that purpose. Which function to use dep |
|
of variable. See the chapters on integer functions, rational number |
of variable. See the chapters on integer functions, rational number |
functions, and floating-point functions for details. |
functions, and floating-point functions for details. |
|
|
A variable should only be initialized once, or at least cleared out |
A variable should only be initialized once, or at least cleared |
between each initialization. After a variable has been initialized, it |
between each initialization. After a variable has been initialized, it |
may be assigned to any number of times. |
may be assigned to any number of times. |
|
|
For efficiency reasons, avoid initializing and clearing out a GMP |
For efficiency reasons, avoid excessive initializing and clearing. |
variable in a loop. Instead, initialize it before entering the loop, |
In general, initialize near the start of a function and clear near the |
and clear it out after the loop has exited. |
end. For example, |
|
|
GMP variables are small, containing only a couple of sizes, and |
|
pointers to allocated data. Once you have initialized a GMP variable, |
|
you don't need to worry about space allocation. All functions in GMP |
|
automatically allocate additional space when a variable does not |
|
already have enough. They do not, however, reduce the space when a |
|
smaller value is stored. Most of the time this policy is best, since |
|
it avoids frequent re-allocation. |
|
|
|
When a variable of type `mpz_t' is used as a function parameter, it's |
|
effectively a call-by-reference, meaning anything the function does to |
|
it will be be done to the original in the caller. When a function is |
|
going to return an `mpz_t' result, it should provide a separate |
|
parameter or parameters that it sets, like the GMP library functions |
|
do. A `return' of an `mpz_t' doesn't return the object, only a pointer |
|
to it, and this is almost certainly not what you want. All this |
|
applies to `mpq_t' and `mpf_t' too. |
|
|
|
Here's an example function accepting an `mpz_t' parameter, doing a |
|
certain calculation, and returning a result. |
|
|
|
void |
void |
myfunction (mpz_t result, mpz_t param, unsigned long n) |
foo (void) |
{ |
{ |
unsigned long i; |
mpz_t n; |
|
int i; |
mpz_mul_ui (result, param, n); |
mpz_init (n); |
for (i = 1; i < n; i++) |
for (i = 1; i < 100; i++) |
mpz_add_ui (result, result, i*7); |
{ |
|
mpz_mul (n, ...); |
|
mpz_fdiv_q (n, ...); |
|
... |
|
} |
|
mpz_clear (n); |
} |
} |
|
|
int |
|
main (void) |
|
{ |
|
mpz_t r, n; |
|
mpz_init (r); |
|
mpz_init_set_str (n, "123456", 0); |
|
|
|
myfunction (r, n, 20L); |
|
mpz_out_str (stdout, 10, r); printf ("\n"); |
|
|
|
return 0; |
|
} |
|
|
|
This example will work if `result' and `param' are the same |
|
variable, just like the library functions. But sometimes this is |
|
tricky to arrange, and an application might not want to bother for its |
|
own subroutines. |
|
|
|
`mpz_t' is actually implemented as a one-element array of a certain |
|
structure type. This is why using it to declare a variable gives an |
|
object with the fields GMP needs, but then using it as a parameter |
|
passes a pointer to the object. Note that the actual contents of an |
|
`mpz_t' are for internal use only and you should not access them |
|
directly if you want your code to be compatible with future GMP |
|
releases. |
|
|
|
|
|
File: gmp.info, Node: GMP and Reentrancy, Next: Useful Macros and Constants, Prev: GMP Variable Conventions, Up: GMP Basics |
|
|
|
GMP and Reentrancy |
|
================== |
|
|
|
The GMP code is reentrant and thread-safe, with some exceptions: |
|
|
|
* The function `mpf_set_default_prec' saves the selected precision in |
|
a global variable. |
|
|
|
* The function `mp_set_memory_functions' uses several global |
|
variables for storing the selected memory allocation functions. |
|
|
|
* If the memory allocation functions set by a call to |
|
`mp_set_memory_functions' (or `malloc' and friends by default) are |
|
not reentrant, GMP will not be reentrant either. |
|
|
|
* The old random number functions (`mpz_random', etc) use a random |
|
number generator from the C library, usually `mrand48' or |
|
`random'. These routines are not reentrant, since they rely on |
|
global state. (However the newer random number functions that |
|
accept a `gmp_randstate_t' parameter are reentrant.) |
|
|
|
* If `alloca' is not available, or GMP is configured with |
|
`--disable-alloca', the library is not reentrant, due to the |
|
current implementation of `stack-alloc.c'. In the generated |
|
`config.h', `USE_STACK_ALLOC' set to 1 will mean not reentrant. |
|
|
|
|
|
File: gmp.info, Node: Useful Macros and Constants, Next: Compatibility with older versions, Prev: GMP and Reentrancy, Up: GMP Basics |
|
|
|
Useful Macros and Constants |
|
=========================== |
|
|
|
- Global Constant: const int mp_bits_per_limb |
|
The number of bits per limb. |
|
|
|
- Macro: __GNU_MP_VERSION |
|
- Macro: __GNU_MP_VERSION_MINOR |
|
- Macro: __GNU_MP_VERSION_PATCHLEVEL |
|
The major and minor GMP version, and patch level, respectively, as |
|
integers. For GMP i.j, these numbers will be i, j, and 0, |
|
respectively. For GMP i.j.k, these numbers will be i, j, and k, |
|
respectively. |
|
|
|
|
|
File: gmp.info, Node: Compatibility with older versions, Next: Getting the Latest Version of GMP, Prev: Useful Macros and Constants, Up: GMP Basics |
|
|
|
Compatibility with older versions |
|
================================= |
|
|
|
This version of GMP is upwardly binary compatible with versions 3.0 |
|
and 3.0.1, and upwardly compatible at the source level with versions |
|
2.0, 2.0.1, and 2.0.2, with the following exceptions. |
|
|
|
* `mpn_gcd' had its source arguments swapped as of GMP 3.0 for |
|
consistency with other `mpn' functions. |
|
|
|
* `mpf_get_prec' counted precision slightly differently in GMP 3.0 |
|
and 3.0.1, but in 3.1 has reverted to the 2.0.x style. |
|
|
|
|
|
There are a number of compatibility issues between GMP 1 and GMP 2 |
|
that of course also apply when porting applications from GMP 1 to GMP |
|
3. Please see the GMP 2 manual for details. |
|
|
|
|
|
File: gmp.info, Node: Getting the Latest Version of GMP, Prev: Compatibility with older versions, Up: GMP Basics |
|
|
|
Getting the Latest Version of GMP |
|
================================= |
|
|
|
The latest version of the GMP library is available at |
|
`ftp://ftp.gnu.org/pub/gnu/gmp'. Many sites around the world mirror |
|
`ftp.gnu.org'; please use a mirror site near you, see |
|
`http://www.gnu.org/order/ftp.html'. |
|
|
|
|
|
File: gmp.info, Node: Reporting Bugs, Next: Integer Functions, Prev: GMP Basics, Up: Top |
|
|
|
Reporting Bugs |
|
************** |
|
|
|
If you think you have found a bug in the GMP library, please |
|
investigate it and report it. We have made this library available to |
|
you, and it is not too much to ask you to report the bugs you find. |
|
Before you report a bug, you may want to check |
|
`http://www.swox.com/gmp/' for patches for this release. |
|
|
|
Please include the following in any report, |
|
|
|
* The GMP version number, and if pre-packaged or patched then say so. |
|
|
|
* A test program that makes it possible for us to reproduce the bug. |
|
Include instructions on how to run the program. |
|
|
|
* A description of what is wrong. If the results are incorrect, in |
|
what way. If you get a crash, say so. |
|
|
|
* If you get a crash, include a stack backtrace from the debugger if |
|
it's informative (`where' in `gdb', or `$C' in `adb'). |
|
|
|
* *Please do not send core dumps, executables or `strace's.* |
|
|
|
* The configuration options you used when building GMP, if any. |
|
|
|
* The name of the compiler and its version. For `gcc', get the |
|
version with `gcc -v', otherwise perhaps `what `which cc`', or |
|
similar. |
|
|
|
* The output from running `uname -a'. |
|
|
|
* The output from running `./config.guess'. |
|
|
|
* If the bug is related to `configure', then the contents of |
|
`config.log'. |
|
|
|
* If the bug is related to an `asm' file not assembling, then the |
|
contents of `config.m4'. |
|
|
|
It is not uncommon that an observed problem is actually due to a bug |
|
in the compiler; the GMP code tends to explore interesting corners in |
|
compilers. |
|
|
|
If your bug report is good, we will do our best to help you get a |
|
corrected version of the library; if the bug report is poor, we won't |
|
do anything about it (except maybe ask you to send a better report). |
|
|
|
Send your report to: <bug-gmp@gnu.org>. |
|
|
|
If you think something in this manual is unclear, or downright |
|
incorrect, or if the language needs to be improved, please send a note |
|
to the same address. |
|
|
|
|
|
File: gmp.info, Node: Integer Functions, Next: Rational Number Functions, Prev: Reporting Bugs, Up: Top |
|
|
|
Integer Functions |
|
***************** |
|
|
|
This chapter describes the GMP functions for performing integer |
|
arithmetic. These functions start with the prefix `mpz_'. |
|
|
|
GMP integers are stored in objects of type `mpz_t'. |
|
|
|
* Menu: |
|
|
|
* Initializing Integers:: |
|
* Assigning Integers:: |
|
* Simultaneous Integer Init & Assign:: |
|
* Converting Integers:: |
|
* Integer Arithmetic:: |
|
* Integer Division:: |
|
* Integer Exponentiation:: |
|
* Integer Roots:: |
|
* Number Theoretic Functions:: |
|
* Integer Comparisons:: |
|
* Integer Logic and Bit Fiddling:: |
|
* I/O of Integers:: |
|
* Integer Random Numbers:: |
|
* Miscellaneous Integer Functions:: |
|
|
|
|
|
File: gmp.info, Node: Initializing Integers, Next: Assigning Integers, Prev: Integer Functions, Up: Integer Functions |
|
|
|
Initialization Functions |
|
======================== |
|
|
|
The functions for integer arithmetic assume that all integer objects |
|
are initialized. You do that by calling the function `mpz_init'. |
|
|
|
- Function: void mpz_init (mpz_t INTEGER) |
|
Initialize INTEGER with limb space and set the initial numeric |
|
value to 0. Each variable should normally only be initialized |
|
once, or at least cleared out (using `mpz_clear') between each |
|
initialization. |
|
|
|
Here is an example of using `mpz_init': |
|
|
|
{ |
|
mpz_t integ; |
|
mpz_init (integ); |
|
... |
|
mpz_add (integ, ...); |
|
... |
|
mpz_sub (integ, ...); |
|
|
|
/* Unless the program is about to exit, do ... */ |
|
mpz_clear (integ); |
|
} |
|
|
|
As you can see, you can store new values any number of times, once an |
|
object is initialized. |
|
|
|
- Function: void mpz_clear (mpz_t INTEGER) |
|
Free the limb space occupied by INTEGER. Make sure to call this |
|
function for all `mpz_t' variables when you are done with them. |
|
|
|
- Function: void * _mpz_realloc (mpz_t INTEGER, mp_size_t NEW_ALLOC) |
|
Change the limb space allocation to NEW_ALLOC limbs. This |
|
function is not normally called from user code, but it can be used |
|
to give memory back to the heap, or to increase the space of a |
|
variable to avoid repeated automatic re-allocation. |
|
|
|
- Function: void mpz_array_init (mpz_t INTEGER_ARRAY[], size_t |
|
ARRAY_SIZE, mp_size_t FIXED_NUM_BITS) |
|
Allocate *fixed* limb space for all ARRAY_SIZE integers in |
|
INTEGER_ARRAY. The fixed allocation for each integer in the array |
|
is enough to store FIXED_NUM_BITS. If the fixed space will be |
|
insufficient for storing the result of a subsequent calculation, |
|
the result is unpredictable. |
|
|
|
This function is useful for decreasing the working set for some |
|
algorithms that use large integer arrays. |
|
|
|
There is no way to de-allocate the storage allocated by this |
|
function. Don't call `mpz_clear'! |
|
|
|
|
|
File: gmp.info, Node: Assigning Integers, Next: Simultaneous Integer Init & Assign, Prev: Initializing Integers, Up: Integer Functions |
|
|
|
Assignment Functions |
|
==================== |
|
|
|
These functions assign new values to already initialized integers |
|
(*note Initializing Integers::). |
|
|
|
- Function: void mpz_set (mpz_t ROP, mpz_t OP) |
|
- Function: void mpz_set_ui (mpz_t ROP, unsigned long int OP) |
|
- Function: void mpz_set_si (mpz_t ROP, signed long int OP) |
|
- Function: void mpz_set_d (mpz_t ROP, double OP) |
|
- Function: void mpz_set_q (mpz_t ROP, mpq_t OP) |
|
- Function: void mpz_set_f (mpz_t ROP, mpf_t OP) |
|
Set the value of ROP from OP. |
|
|
|
- Function: int mpz_set_str (mpz_t ROP, char *STR, int BASE) |
|
Set the value of ROP from STR, a '\0'-terminated C string in base |
|
BASE. White space is allowed in the string, and is simply |
|
ignored. The base may vary from 2 to 36. If BASE is 0, the |
|
actual base is determined from the leading characters: if the |
|
first two characters are `0x' or `0X', hexadecimal is assumed, |
|
otherwise if the first character is `0', octal is assumed, |
|
otherwise decimal is assumed. |
|
|
|
This function returns 0 if the entire string up to the '\0' is a |
|
valid number in base BASE. Otherwise it returns -1. |
|
|
|
[It turns out that it is not entirely true that this function |
|
ignores white-space. It does ignore it between digits, but not |
|
after a minus sign or within or after "0x". We are considering |
|
changing the definition of this function, making it fail when |
|
there is any white-space in the input, since that makes a lot of |
|
sense. Please tell us your opinion about this change. Do you |
|
really want it to accept "3 14" as meaning 314 as it does now?] |
|
|
|
- Function: void mpz_swap (mpz_t ROP1, mpz_t ROP2) |
|
Swap the values ROP1 and ROP2 efficiently. |
|
|
|
|
|
File: gmp.info, Node: Simultaneous Integer Init & Assign, Next: Converting Integers, Prev: Assigning Integers, Up: Integer Functions |
|
|
|
Combined Initialization and Assignment Functions |
|
================================================ |
|
|
|
For convenience, GMP provides a parallel series of |
|
initialize-and-set functions which initialize the output and then store |
|
the value there. These functions' names have the form `mpz_init_set...' |
|
|
|
Here is an example of using one: |
|
|
|
{ |
|
mpz_t pie; |
|
mpz_init_set_str (pie, "3141592653589793238462643383279502884", 10); |
|
... |
|
mpz_sub (pie, ...); |
|
... |
|
mpz_clear (pie); |
|
} |
|
|
|
Once the integer has been initialized by any of the `mpz_init_set...' |
|
functions, it can be used as the source or destination operand for the |
|
ordinary integer functions. Don't use an initialize-and-set function |
|
on a variable already initialized! |
|
|
|
- Function: void mpz_init_set (mpz_t ROP, mpz_t OP) |
|
- Function: void mpz_init_set_ui (mpz_t ROP, unsigned long int OP) |
|
- Function: void mpz_init_set_si (mpz_t ROP, signed long int OP) |
|
- Function: void mpz_init_set_d (mpz_t ROP, double OP) |
|
Initialize ROP with limb space and set the initial numeric value |
|
from OP. |
|
|
|
- Function: int mpz_init_set_str (mpz_t ROP, char *STR, int BASE) |
|
Initialize ROP and set its value like `mpz_set_str' (see its |
|
documentation above for details). |
|
|
|
If the string is a correct base BASE number, the function returns |
|
0; if an error occurs it returns -1. ROP is initialized even if |
|
an error occurs. (I.e., you have to call `mpz_clear' for it.) |
|
|
|
|
|
File: gmp.info, Node: Converting Integers, Next: Integer Arithmetic, Prev: Simultaneous Integer Init & Assign, Up: Integer Functions |
|
|
|
Conversion Functions |
|
==================== |
|
|
|
This section describes functions for converting GMP integers to |
|
standard C types. Functions for converting _to_ GMP integers are |
|
described in *Note Assigning Integers:: and *Note I/O of Integers::. |
|
|
|
- Function: mp_limb_t mpz_getlimbn (mpz_t OP, mp_size_t N) |
|
Return limb #N from OP. This function allows for very efficient |
|
decomposition of a number in its limbs. |
|
|
|
The function `mpz_size' can be used to determine the useful range |
|
for N. |
|
|
|
- Function: unsigned long int mpz_get_ui (mpz_t OP) |
|
Return the least significant part from OP. This function combined |
|
with |
|
`mpz_tdiv_q_2exp(..., OP, CHAR_BIT*sizeof(unsigned long int))' can |
|
be used to decompose an integer into unsigned longs. |
|
|
|
- Function: signed long int mpz_get_si (mpz_t OP) |
|
If OP fits into a `signed long int' return the value of OP. |
|
Otherwise return the least significant part of OP, with the same |
|
sign as OP. |
|
|
|
If OP is too large to fit in a `signed long int', the returned |
|
result is probably not very useful. To find out if the value will |
|
fit, use the function `mpz_fits_slong_p'. |
|
|
|
- Function: double mpz_get_d (mpz_t OP) |
|
Convert OP to a double. |
|
|
|
- Function: char * mpz_get_str (char *STR, int BASE, mpz_t OP) |
|
Convert OP to a string of digits in base BASE. The base may vary |
|
from 2 to 36. |
|
|
|
If STR is `NULL', space for the result string is allocated using |
|
the default allocation function. |
|
|
|
If STR is not `NULL', it should point to a block of storage enough |
|
large for the result. To find out the right amount of space to |
|
provide for STR, use `mpz_sizeinbase (OP, BASE) + 2'. The two |
|
extra bytes are for a possible minus sign, and for the terminating |
|
null character. |
|
|
|
A pointer to the result string is returned. This pointer will |
|
will either equal STR, or if that is `NULL', will point to the |
|
allocated storage. |
|
|
|
|
|
File: gmp.info, Node: Integer Arithmetic, Next: Integer Division, Prev: Converting Integers, Up: Integer Functions |
|
|
|
Arithmetic Functions |
|
==================== |
|
|
|
- Function: void mpz_add (mpz_t ROP, mpz_t OP1, mpz_t OP2) |
|
- Function: void mpz_add_ui (mpz_t ROP, mpz_t OP1, unsigned long int |
|
OP2) |
|
Set ROP to OP1 + OP2. |
|
|
|
- Function: void mpz_sub (mpz_t ROP, mpz_t OP1, mpz_t OP2) |
|
- Function: void mpz_sub_ui (mpz_t ROP, mpz_t OP1, unsigned long int |
|
OP2) |
|
Set ROP to OP1 - OP2. |
|
|
|
- Function: void mpz_mul (mpz_t ROP, mpz_t OP1, mpz_t OP2) |
|
- Function: void mpz_mul_si (mpz_t ROP, mpz_t OP1, long int OP2) |
|
- Function: void mpz_mul_ui (mpz_t ROP, mpz_t OP1, unsigned long int |
|
OP2) |
|
Set ROP to OP1 times OP2. |
|
|
|
- Function: void mpz_addmul_ui (mpz_t ROP, mpz_t OP1, unsigned long |
|
int OP2) |
|
Add OP1 times OP2 to ROP. |
|
|
|
- Function: void mpz_mul_2exp (mpz_t ROP, mpz_t OP1, unsigned long int |
|
OP2) |
|
Set ROP to OP1 times 2 raised to OP2. This operation can also be |
|
defined as a left shift, OP2 steps. |
|
|
|
- Function: void mpz_neg (mpz_t ROP, mpz_t OP) |
|
Set ROP to -OP. |
|
|
|
- Function: void mpz_abs (mpz_t ROP, mpz_t OP) |
|
Set ROP to the absolute value of OP. |
|
|
|