GNU Info
(gmp.info)Build Options
Build Options
=============
All the usual autoconf configure options are available, run
`./configure --help' for a summary. The file `INSTALL.autoconf' has
some generic installation information too.
Non-Unix Systems
`configure' requires various Unix-like tools. On an MS-DOS system
Cygwin, DJGPP or MINGW can be used. See
`http://www.cygnus.com/cygwin'
`http://www.delorie.com/djgpp'
`http://www.mingw.org'
The `macos' directory contains an unsupported port to MacOS 9 on
Power Macintosh. Note that MacOS X "Darwin" can use the normal
`./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
directory. For example
cd /my/build/dir
/my/sources/gmp-4.0.1/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'
By default both shared and static libraries are built (where
possible), but one or other can be disabled. Shared libraries
result in smaller executables and permit code sharing between
separate running processes, but on some CPUs are slightly slower,
having a small cost on each function call.
Native Compilation, `--build=CPU-VENDOR-OS'
For normal native compilation, the system can be specified with
`--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,
./configure --build=ultrasparc-sun-solaris2.7
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 checked for,
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 with 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.
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,
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
the family, and might run slower on other members, older or newer.
The best idea is always to build GMP for the exact machine type
you intend to run it on.
The following CPUs have specific support. See `configure.in' for
details of what code and compiler options they select.
* Alpha: alpha, alphaev5, alphaev56, alphapca56, alphaev6,
alphaev67
* Cray: c90, j90, t90, sv1
* HPPA: hppa1.0, hppa1.1, hppa2.0, hppa2.0n, hppa2.0w
* MIPS: mips, mips3, mips64
* Motorola: m68k, m68000, m68010, m68020, m68030, m68040,
m68060, m68302, m68360, m88k, m88110
* POWER: power, power1, power2, power2sc, powerpc, powerpc64
* SPARC: sparc, sparcv8, microsparc, supersparc, sparcv9,
ultrasparc, sparc64
* 80x86 family: i386, i486, i586, pentium, pentiummmx,
pentiumpro, pentium2, pentium3, pentium4, k6, k62, k63, athlon
* Other: a29k, arm, clipper, i960, ns32k, pyramid, sh, sh2, vax,
z8k
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 --build=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 --build=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'
By default the C compiler used is chosen from among some likely
candidates, with `gcc' normally preferred if it's present. The
usual `CC=whatever' can be passed to `./configure' to choose
something different.
For some systems, default compiler flags are set based on the CPU
and compiler. The usual `CFLAGS="-whatever"' can be passed to
`./configure' to use something different or to set good flags for
systems GMP doesn't otherwise know.
The `CC' and `CFLAGS' used are printed during `./configure', and
can be found in each generated `Makefile'. This is the easiest way
to check the defaults when considering changing or adding
something.
Note that when `CC' and `CFLAGS' are specified on a system
supporting multiple ABIs it's important to give an explicit
`ABI=whatever', since GMP can't determine the ABI just from the
flags and won't be able to select the correct assembler code.
If just `CC' is selected then normal default `CFLAGS' for that
compiler will be used (if GMP recognises it). For example
`CC=gcc' can be used to force the use of GCC, with default flags
(and default ABI).
`CPPFLAGS'
Any flags like `-D' defines or `-I' includes required by the
preprocessor should be set in `CPPFLAGS' rather than `CFLAGS'.
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.
C++ Support, `--enable-cxx'
C++ support in GMP can be enabled with `--enable-cxx', in which
case a C++ compiler will be required. As a convenience
`--enable-cxx=detect' can be used to enable C++ support only if a
compiler can be found. The C++ support consists of a library
`libgmpxx.la' and header file `gmpxx.h'.
A separate `libgmpxx.la' has been adopted rather than having C++
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.
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.).
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'
Various assembler versions of mpn subroutines are provided, and,
for a given CPU, a search is made though a path to choose a
version of each. For example `sparcv8' has path `sparc32/v8
sparc32 generic', which means it looks first for v8 code, then
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.
Demonstration Programs
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
./pexpr 68^975+10
Documentation
The document you're now reading is `gmp.texi'. The usual automake
targets are available to make PostScript `gmp.ps' and/or DVI
`gmp.dvi'.
HTML can be produced with `makeinfo --html', see Note: Generating
HTML. Or alternately `texi2html', see
Note: Texinfo to HTML.
PDF can be produced with `texi2dvi --pdf' (Note: PDF.
) or with `pdftex'.
Some supplementary notes can be found in the `doc' subdirectory.
automatically generated by info2www version 1.2.2.9