Annotation of OpenXM_contrib/gmp/gmp.info-1, Revision 1.1.1.4
1.1.1.4 ! ohara 1: This is gmp.info, produced by makeinfo version 4.2 from gmp.texi.
1.1 maekawa 2:
1.1.1.4 ! ohara 3: This manual describes how to install and use the GNU multiple precision
! 4: arithmetic library, version 4.1.2.
! 5:
! 6: Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
! 7: 2001, 2002 Free Software Foundation, Inc.
! 8:
! 9: Permission is granted to copy, distribute and/or modify this
! 10: document under the terms of the GNU Free Documentation License, Version
! 11: 1.1 or any later version published by the Free Software Foundation;
! 12: with no Invariant Sections, with the Front-Cover Texts being "A GNU
! 13: Manual", and with the Back-Cover Texts being "You have freedom to copy
! 14: and modify this GNU Manual, like GNU software". A copy of the license
! 15: is included in *Note GNU Free Documentation License::.
1.1.1.2 maekawa 16: INFO-DIR-SECTION GNU libraries
1.1 maekawa 17: START-INFO-DIR-ENTRY
1.1.1.2 maekawa 18: * gmp: (gmp). GNU Multiple Precision Arithmetic Library.
1.1 maekawa 19: END-INFO-DIR-ENTRY
20:
21:
22: File: gmp.info, Node: Top, Next: Copying, Prev: (dir), Up: (dir)
23:
24: GNU MP
25: ******
26:
1.1.1.4 ! ohara 27: This manual describes how to install and use the GNU multiple precision
! 28: arithmetic library, version 4.1.2.
! 29:
! 30: Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
! 31: 2001, 2002 Free Software Foundation, Inc.
! 32:
! 33: Permission is granted to copy, distribute and/or modify this
! 34: document under the terms of the GNU Free Documentation License, Version
! 35: 1.1 or any later version published by the Free Software Foundation;
! 36: with no Invariant Sections, with the Front-Cover Texts being "A GNU
! 37: Manual", and with the Back-Cover Texts being "You have freedom to copy
! 38: and modify this GNU Manual, like GNU software". A copy of the license
! 39: is included in *Note GNU Free Documentation License::.
1.1 maekawa 40:
41: * Menu:
42:
1.1.1.2 maekawa 43: * Copying:: GMP Copying Conditions (LGPL).
44: * Introduction to GMP:: Brief introduction to GNU MP.
45: * Installing GMP:: How to configure and compile the GMP library.
1.1.1.4 ! ohara 46: * GMP Basics:: What every GMP user should know.
1.1.1.2 maekawa 47: * Reporting Bugs:: How to usefully report bugs.
48: * Integer Functions:: Functions for arithmetic on signed integers.
49: * Rational Number Functions:: Functions for arithmetic on rational numbers.
50: * Floating-point Functions:: Functions for arithmetic on floats.
51: * Low-level Functions:: Fast functions for natural numbers.
52: * Random Number Functions:: Functions for generating random numbers.
1.1.1.4 ! ohara 53: * Formatted Output:: `printf' style output.
! 54: * Formatted Input:: `scanf' style input.
! 55: * C++ Class Interface:: Class wrappers around GMP types.
1.1.1.2 maekawa 56: * BSD Compatible Functions:: All functions found in BSD MP.
57: * Custom Allocation:: How to customize the internal allocation.
1.1.1.4 ! ohara 58: * Language Bindings:: Using GMP from other languages.
! 59: * Algorithms:: What happens behind the scenes.
! 60: * Internals:: How values are represented behind the scenes.
1.1 maekawa 61:
1.1.1.2 maekawa 62: * Contributors:: Who brings your this library?
63: * References:: Some useful papers and books to read.
1.1.1.4 ! ohara 64: * GNU Free Documentation License::
1.1 maekawa 65: * Concept Index::
66: * Function Index::
67:
68:
1.1.1.2 maekawa 69: File: gmp.info, Node: Copying, Next: Introduction to GMP, Prev: Top, Up: Top
1.1 maekawa 70:
71: GNU MP Copying Conditions
72: *************************
73:
74: This library is "free"; this means that everyone is free to use it
75: and free to redistribute it on a free basis. The library is not in the
76: public domain; it is copyrighted and there are restrictions on its
77: distribution, but these restrictions are designed to permit everything
78: that a good cooperating citizen would want to do. What is not allowed
79: is to try to prevent others from further sharing any version of this
80: library that they might get from you.
81:
82: Specifically, we want to make sure that you have the right to give
83: away copies of the library, that you receive source code or else can
84: get it if you want it, that you can change this library or use pieces
85: of it in new free programs, and that you know you can do these things.
86:
87: To make sure that everyone has such rights, we have to forbid you to
88: deprive anyone else of these rights. For example, if you distribute
89: copies of the GNU MP library, you must give the recipients all the
90: rights that you have. You must make sure that they, too, receive or
91: can get the source code. And you must tell them their rights.
92:
93: Also, for our own protection, we must make certain that everyone
94: finds out that there is no warranty for the GNU MP library. If it is
95: modified by someone else and passed on, we want their recipients to
96: know that what they have is not what we distributed, so that any
97: problems introduced by others will not reflect on our reputation.
98:
99: The precise conditions of the license for the GNU MP library are
1.1.1.4 ! ohara 100: found in the Lesser General Public License version 2.1 that accompanies
! 101: the source code, see `COPYING.LIB'. Certain demonstration programs are
! 102: provided under the terms of the plain General Public License version 2,
! 103: see `COPYING'.
1.1 maekawa 104:
105:
1.1.1.2 maekawa 106: File: gmp.info, Node: Introduction to GMP, Next: Installing GMP, Prev: Copying, Up: Top
1.1 maekawa 107:
108: Introduction to GNU MP
109: **********************
110:
111: GNU MP is a portable library written in C for arbitrary precision
112: arithmetic on integers, rational numbers, and floating-point numbers.
113: It aims to provide the fastest possible arithmetic for all applications
114: that need higher precision than is directly supported by the basic C
115: types.
116:
117: Many applications use just a few hundred bits of precision; but some
1.1.1.2 maekawa 118: applications may need thousands or even millions of bits. GMP is
1.1 maekawa 119: designed to give good performance for both, by choosing algorithms
120: based on the sizes of the operands, and by carefully keeping the
121: overhead at a minimum.
122:
1.1.1.2 maekawa 123: The speed of GMP is achieved by using fullwords as the basic
1.1 maekawa 124: arithmetic type, by using sophisticated algorithms, by including
125: carefully optimized assembly code for the most common inner loops for
126: many different CPUs, and by a general emphasis on speed (as opposed to
127: simplicity or elegance).
128:
1.1.1.2 maekawa 129: There is carefully optimized assembly code for these CPUs: ARM, DEC
1.1.1.4 ! ohara 130: Alpha 21064, 21164, and 21264, AMD 29000, AMD K6, K6-2 and Athlon,
! 131: Hitachi SuperH and SH-2, HPPA 1.0, 1.1 and 2.0, Intel Pentium, Pentium
! 132: Pro/II/III, Pentium 4, generic x86, Intel IA-64, i960, Motorola
! 133: MC68000, MC68020, MC88100, and MC88110, Motorola/IBM PowerPC 32 and 64,
! 134: National NS32000, IBM POWER, MIPS R3000, R4000, SPARCv7, SuperSPARC,
! 135: generic SPARCv8, UltraSPARC, DEC VAX, and Zilog Z8000. Some
! 136: optimizations also for Cray vector systems, Clipper, IBM ROMP (RT), and
! 137: Pyramid AP/XP.
! 138:
! 139: There are two public mailing lists of interest. One for general
! 140: questions and discussions about usage of the GMP library and one for
! 141: discussions about development of GMP. There's more information about
! 142: the mailing lists at `http://swox.com/mailman/listinfo/'. These lists
! 143: are *not* for bug reports.
! 144:
! 145: The proper place for bug reports is <bug-gmp@gnu.org>. See *Note
! 146: Reporting Bugs:: for info about reporting bugs.
! 147:
! 148: For up-to-date information on GMP, please see the GMP web pages at
! 149:
! 150: `http://swox.com/gmp/'
! 151:
! 152: The latest version of the library is available at
1.1.1.2 maekawa 153:
1.1.1.4 ! ohara 154: `ftp://ftp.gnu.org/gnu/gmp'
! 155:
! 156: Many sites around the world mirror `ftp.gnu.org', please use a mirror
! 157: near you, see `http://www.gnu.org/order/ftp.html' for a full list.
1.1 maekawa 158:
159: How to use this Manual
160: ======================
161:
1.1.1.2 maekawa 162: Everyone should read *Note GMP Basics::. If you need to install the
1.1.1.4 ! ohara 163: library yourself, then read *Note Installing GMP::. If you have a
! 164: system with multiple ABIs, then read *Note ABI and ISA::, for the
! 165: compiler options that must be used on applications.
1.1 maekawa 166:
167: The rest of the manual can be used for later reference, although it
168: is probably a good idea to glance through it.
169:
170:
1.1.1.2 maekawa 171: File: gmp.info, Node: Installing GMP, Next: GMP Basics, Prev: Introduction to GMP, Up: Top
172:
173: Installing GMP
174: **************
175:
1.1.1.4 ! ohara 176: GMP has an autoconf/automake/libtool based configuration system. On
! 177: a Unix-like system a basic build can be done with
1.1.1.2 maekawa 178:
179: ./configure
180: make
1.1 maekawa 181:
1.1.1.2 maekawa 182: Some self-tests can be run with
1.1 maekawa 183:
1.1.1.2 maekawa 184: make check
185:
186: And you can install (under `/usr/local' by default) with
187:
188: make install
189:
1.1.1.4 ! ohara 190: If you experience problems, please report them to <bug-gmp@gnu.org>.
! 191: See *Note Reporting Bugs::, for information on what to include in
! 192: useful bug reports.
1.1.1.2 maekawa 193:
194: * Menu:
195:
196: * Build Options::
197: * ABI and ISA::
198: * Notes for Package Builds::
199: * Notes for Particular Systems::
200: * Known Build Problems::
201:
202:
203: File: gmp.info, Node: Build Options, Next: ABI and ISA, Prev: Installing GMP, Up: Installing GMP
204:
205: Build Options
206: =============
207:
1.1.1.4 ! ohara 208: All the usual autoconf configure options are available, run
! 209: `./configure --help' for a summary. The file `INSTALL.autoconf' has
! 210: some generic installation information too.
1.1.1.2 maekawa 211:
212: Non-Unix Systems
1.1.1.4 ! ohara 213: `configure' requires various Unix-like tools. On an MS-DOS system
! 214: DJGPP can be used, and on MS Windows Cygwin or MINGW can be used,
! 215:
! 216: `http://www.cygnus.com/cygwin'
! 217: `http://www.delorie.com/djgpp'
! 218: `http://www.mingw.org'
! 219:
! 220: Microsoft also publishes an Interix "Services for Unix" which can
! 221: be used to build GMP on Windows (with a normal `./configure'), but
! 222: it's not free software.
! 223:
! 224: The `macos' directory contains an unsupported port to MacOS 9 on
! 225: Power Macintosh, see `macos/README'. Note that MacOS X "Darwin"
! 226: should use the normal Unix-style `./configure'.
! 227:
! 228: It might be possible to build without the help of `configure',
! 229: certainly all the code is there, but unfortunately you'll be on
! 230: your own.
1.1.1.2 maekawa 231:
1.1.1.4 ! ohara 232: Build Directory
! 233: To compile in a separate build directory, `cd' to that directory,
1.1.1.2 maekawa 234: and prefix the configure command with the path to the GMP source
1.1.1.4 ! ohara 235: directory. For example
! 236:
! 237: cd /my/build/dir
! 238: /my/sources/gmp-4.1.2/configure
! 239:
! 240: Not all `make' programs have the necessary features (`VPATH') to
! 241: support this. In particular, SunOS and Slowaris `make' have bugs
! 242: that make them unable to build in a separate directory. Use GNU
! 243: `make' instead.
1.1.1.2 maekawa 244:
245: `--disable-shared', `--disable-static'
246: By default both shared and static libraries are built (where
1.1.1.4 ! ohara 247: possible), but one or other can be disabled. Shared libraries
! 248: result in smaller executables and permit code sharing between
! 249: separate running processes, but on some CPUs are slightly slower,
! 250: having a small cost on each function call.
! 251:
! 252: Native Compilation, `--build=CPU-VENDOR-OS'
! 253: For normal native compilation, the system can be specified with
! 254: `--build'. By default `./configure' uses the output from running
! 255: `./config.guess'. On some systems `./config.guess' can determine
! 256: the exact CPU type, on others it will be necessary to give it
! 257: explicitly. For example,
! 258:
! 259: ./configure --build=ultrasparc-sun-solaris2.7
! 260:
! 261: In all cases the `OS' part is important, since it controls how
! 262: libtool generates shared libraries. Running `./config.guess' is
! 263: the simplest way to see what it should be, if you don't know
! 264: already.
! 265:
! 266: Cross Compilation, `--host=CPU-VENDOR-OS'
! 267: When cross-compiling, the system used for compiling is given by
! 268: `--build' and the system where the library will run is given by
! 269: `--host'. For example when using a FreeBSD Athlon system to build
! 270: GNU/Linux m68k binaries,
! 271:
! 272: ./configure --build=athlon-pc-freebsd3.5 --host=m68k-mac-linux-gnu
! 273:
! 274: Compiler tools are sought first with the host system type as a
! 275: prefix. For example `m68k-mac-linux-gnu-ranlib' is tried, then
! 276: plain `ranlib'. This makes it possible for a set of
! 277: cross-compiling tools to co-exist with native tools. The prefix
! 278: is the argument to `--host', and this can be an alias, such as
! 279: `m68k-linux'. But note that tools don't have to be setup this
! 280: way, it's enough to just have a `PATH' with a suitable
! 281: cross-compiling `cc' etc.
! 282:
! 283: Compiling for a different CPU in the same family as the build
! 284: system is a form of cross-compilation, though very possibly this
! 285: would merely be special options on a native compiler. In any case
! 286: `./configure' avoids depending on being able to run code on the
! 287: build system, which is important when creating binaries for a
! 288: newer CPU since they very possibly won't run on the build system.
! 289:
! 290: In all cases the compiler must be able to produce an executable
! 291: (of whatever format) from a standard C `main'. Although only
! 292: object files will go to make up `libgmp', `./configure' uses
! 293: linking tests for various purposes, such as determining what
! 294: functions are available on the host system.
! 295:
! 296: Currently a warning is given unless an explicit `--build' is used
! 297: when cross-compiling, because it may not be possible to correctly
! 298: guess the build system type if the `PATH' has only a
! 299: cross-compiling `cc'.
! 300:
! 301: Note that the `--target' option is not appropriate for GMP. It's
! 302: for use when building compiler tools, with `--host' being where
! 303: they will run, and `--target' what they'll produce code for.
! 304: Ordinary programs or libraries like GMP are only interested in the
! 305: `--host' part, being where they'll run. (Some past versions of
! 306: GMP used `--target' incorrectly.)
1.1 maekawa 307:
1.1.1.4 ! ohara 308: CPU types
1.1 maekawa 309: In general, if you want a library that runs as fast as possible,
1.1.1.2 maekawa 310: you should configure GMP for the exact CPU type your system uses.
311: However, this may mean the binaries won't run on older members of
312: the family, and might run slower on other members, older or newer.
313: The best idea is always to build GMP for the exact machine type
314: you intend to run it on.
315:
1.1.1.4 ! ohara 316: The following CPUs have specific support. See `configure.in' for
! 317: details of what code and compiler options they select.
! 318:
! 319: * Alpha: alpha, alphaev5, alphaev56, alphapca56, alphapca57,
! 320: alphaev6, alphaev67, alphaev68
! 321:
! 322: * Cray: c90, j90, t90, sv1
! 323:
! 324: * HPPA: hppa1.0, hppa1.1, hppa2.0, hppa2.0n, hppa2.0w
! 325:
! 326: * MIPS: mips, mips3, mips64
! 327:
! 328: * Motorola: m68k, m68000, m68010, m68020, m68030, m68040,
! 329: m68060, m68302, m68360, m88k, m88110
1.1.1.2 maekawa 330:
1.1.1.4 ! ohara 331: * POWER: power, power1, power2, power2sc
1.1.1.2 maekawa 332:
1.1.1.4 ! ohara 333: * PowerPC: powerpc, powerpc64, powerpc401, powerpc403,
! 334: powerpc405, powerpc505, powerpc601, powerpc602, powerpc603,
! 335: powerpc603e, powerpc604, powerpc604e, powerpc620, powerpc630,
! 336: powerpc740, powerpc7400, powerpc7450, powerpc750, powerpc801,
! 337: powerpc821, powerpc823, powerpc860,
1.1.1.2 maekawa 338:
1.1.1.4 ! ohara 339: * SPARC: sparc, sparcv8, microsparc, supersparc, sparcv9,
! 340: ultrasparc, ultrasparc2, ultrasparc2i, ultrasparc3, sparc64
1.1.1.2 maekawa 341:
1.1.1.4 ! ohara 342: * 80x86 family: i386, i486, i586, pentium, pentiummmx,
! 343: pentiumpro, pentium2, pentium3, pentium4, k6, k62, k63, athlon
1.1.1.2 maekawa 344:
1.1.1.4 ! ohara 345: * Other: a29k, arm, clipper, i960, ns32k, pyramid, sh, sh2, vax,
! 346: z8k
1.1 maekawa 347:
1.1.1.4 ! ohara 348: CPUs not listed will use generic C code.
1.1.1.2 maekawa 349:
1.1.1.4 ! ohara 350: Generic C Build
! 351: If some of the assembly code causes problems, or if otherwise
! 352: desired, the generic C code can be selected with CPU `none'. For
! 353: example,
1.1.1.2 maekawa 354:
1.1.1.4 ! ohara 355: ./configure --host=none-unknown-freebsd3.5
1.1.1.2 maekawa 356:
1.1.1.4 ! ohara 357: Note that this will run quite slowly, but it should be portable
! 358: and should at least make it possible to get something running if
! 359: all else fails.
1.1.1.2 maekawa 360:
1.1.1.4 ! ohara 361: `ABI'
! 362: On some systems GMP supports multiple ABIs (application binary
! 363: interfaces), meaning data type sizes and calling conventions. By
! 364: default GMP chooses the best ABI available, but a particular ABI
! 365: can be selected. For example
! 366:
! 367: ./configure --host=mips64-sgi-irix6 ABI=n32
! 368:
! 369: See *Note ABI and ISA::, for the available choices on relevant
! 370: CPUs, and what applications need to do.
1.1.1.2 maekawa 371:
372: `CC', `CFLAGS'
1.1.1.4 ! ohara 373: By default the C compiler used is chosen from among some likely
! 374: candidates, with `gcc' normally preferred if it's present. The
! 375: usual `CC=whatever' can be passed to `./configure' to choose
! 376: something different.
! 377:
! 378: For some systems, default compiler flags are set based on the CPU
! 379: and compiler. The usual `CFLAGS="-whatever"' can be passed to
1.1.1.3 maekawa 380: `./configure' to use something different or to set good flags for
381: systems GMP doesn't otherwise know.
382:
1.1.1.4 ! ohara 383: The `CC' and `CFLAGS' used are printed during `./configure', and
! 384: can be found in each generated `Makefile'. This is the easiest way
! 385: to check the defaults when considering changing or adding
! 386: something.
! 387:
! 388: Note that when `CC' and `CFLAGS' are specified on a system
! 389: supporting multiple ABIs it's important to give an explicit
! 390: `ABI=whatever', since GMP can't determine the ABI just from the
! 391: flags and won't be able to select the correct assembler code.
! 392:
! 393: If just `CC' is selected then normal default `CFLAGS' for that
! 394: compiler will be used (if GMP recognises it). For example
! 395: `CC=gcc' can be used to force the use of GCC, with default flags
! 396: (and default ABI).
! 397:
! 398: `CPPFLAGS'
! 399: Any flags like `-D' defines or `-I' includes required by the
! 400: preprocessor should be set in `CPPFLAGS' rather than `CFLAGS'.
! 401: Compiling is done with both `CPPFLAGS' and `CFLAGS', but
! 402: preprocessing uses just `CPPFLAGS'. This distinction is because
! 403: most preprocessors won't accept all the flags the compiler does.
! 404: Preprocessing is done separately in some configure tests, and in
! 405: the `ansi2knr' support for K&R compilers.
! 406:
! 407: C++ Support, `--enable-cxx'
! 408: C++ support in GMP can be enabled with `--enable-cxx', in which
! 409: case a C++ compiler will be required. As a convenience
! 410: `--enable-cxx=detect' can be used to enable C++ support only if a
! 411: compiler can be found. The C++ support consists of a library
! 412: `libgmpxx.la' and header file `gmpxx.h'.
! 413:
! 414: A separate `libgmpxx.la' has been adopted rather than having C++
! 415: objects within `libgmp.la' in order to ensure dynamic linked C
! 416: programs aren't bloated by a dependency on the C++ standard
! 417: library, and to avoid any chance that the C++ compiler could be
! 418: required when linking plain C programs.
! 419:
! 420: `libgmpxx.la' will use certain internals from `libgmp.la' and can
! 421: only be expected to work with `libgmp.la' from the same GMP
! 422: version. Future changes to the relevant internals will be
! 423: accompanied by renaming, so a mismatch will cause unresolved
! 424: symbols rather than perhaps mysterious misbehaviour.
! 425:
! 426: In general `libgmpxx.la' will be usable only with the C++ compiler
! 427: that built it, since name mangling and runtime support are usually
! 428: incompatible between different compilers.
! 429:
! 430: `CXX', `CXXFLAGS'
! 431: When C++ support is enabled, the C++ compiler and its flags can be
! 432: set with variables `CXX' and `CXXFLAGS' in the usual way. The
! 433: default for `CXX' is the first compiler that works from a list of
! 434: likely candidates, with `g++' normally preferred when available.
! 435: The default for `CXXFLAGS' is to try `CFLAGS', `CFLAGS' without
! 436: `-g', then for `g++' either `-g -O2' or `-O2', or for other
! 437: compilers `-g' or nothing. Trying `CFLAGS' this way is convenient
! 438: when using `gcc' and `g++' together, since the flags for `gcc' will
! 439: usually suit `g++'.
! 440:
! 441: It's important that the C and C++ compilers match, meaning their
! 442: startup and runtime support routines are compatible and that they
! 443: generate code in the same ABI (if there's a choice of ABIs on the
! 444: system). `./configure' isn't currently able to check these things
! 445: very well itself, so for that reason `--disable-cxx' is the
! 446: default, to avoid a build failure due to a compiler mismatch.
! 447: Perhaps this will change in the future.
! 448:
! 449: Incidentally, it's normally not good enough to set `CXX' to the
! 450: same as `CC'. Although `gcc' for instance recognises `foo.cc' as
! 451: C++ code, only `g++' will invoke the linker the right way when
! 452: building an executable or shared library from object files.
! 453:
! 454: Temporary Memory, `--enable-alloca=<choice>'
! 455: GMP allocates temporary workspace using one of the following three
! 456: methods, which can be selected with for instance
! 457: `--enable-alloca=malloc-reentrant'.
! 458:
! 459: * `alloca' - C library or compiler builtin.
! 460:
! 461: * `malloc-reentrant' - the heap, in a re-entrant fashion.
! 462:
! 463: * `malloc-notreentrant' - the heap, with global variables.
! 464:
! 465: For convenience, the following choices are also available.
! 466: `--disable-alloca' is the same as `--enable-alloca=no'.
! 467:
! 468: * `yes' - a synonym for `alloca'.
! 469:
! 470: * `no' - a synonym for `malloc-reentrant'.
! 471:
! 472: * `reentrant' - `alloca' if available, otherwise
! 473: `malloc-reentrant'. This is the default.
! 474:
! 475: * `notreentrant' - `alloca' if available, otherwise
! 476: `malloc-notreentrant'.
! 477:
! 478: `alloca' is reentrant and fast, and is recommended, but when
! 479: working with large numbers it can overflow the available stack
! 480: space, in which case one of the two malloc methods will need to be
! 481: used. Alternately it might be possible to increase available
! 482: stack with `limit', `ulimit' or `setrlimit', or under DJGPP with
! 483: `stubedit' or `_stklen'. Note that depending on the system the
! 484: only indication of stack overflow might be a segmentation
! 485: violation.
! 486:
! 487: `malloc-reentrant' is, as the name suggests, reentrant and thread
! 488: safe, but `malloc-notreentrant' is faster and should be used if
! 489: reentrancy is not required.
! 490:
! 491: The two malloc methods in fact use the memory allocation functions
! 492: selected by `mp_set_memory_functions', these being `malloc' and
! 493: friends by default. *Note Custom Allocation::.
! 494:
! 495: An additional choice `--enable-alloca=debug' is available, to help
! 496: when debugging memory related problems (*note Debugging::).
! 497:
! 498: FFT Multiplication, `--disable-fft'
! 499: By default multiplications are done using Karatsuba, 3-way
! 500: Toom-Cook, and Fermat FFT. The FFT is only used on large to very
! 501: large operands and can be disabled to save code size if desired.
1.1.1.2 maekawa 502:
1.1.1.4 ! ohara 503: Berkeley MP, `--enable-mpbsd'
! 504: The Berkeley MP compatibility library (`libmp') and header file
1.1.1.2 maekawa 505: (`mp.h') are built and installed only if `--enable-mpbsd' is used.
506: *Note BSD Compatible Functions::.
507:
1.1.1.4 ! ohara 508: MPFR, `--enable-mpfr'
! 509: The optional MPFR functions are built and installed only if
! 510: `--enable-mpfr' is used. These are in a separate library
! 511: `libmpfr.a' and are documented separately too (*note Introduction
! 512: to MPFR: (mpfr)Introduction to MPFR.).
! 513:
! 514: Assertion Checking, `--enable-assert'
! 515: This option enables some consistency checking within the library.
! 516: This can be of use while debugging, *note Debugging::.
! 517:
! 518: Execution Profiling, `--enable-profiling=prof/gprof'
! 519: Profiling support can be enabled either for `prof' or `gprof'.
! 520: This adds `-p' or `-pg' respectively to `CFLAGS', and for some
! 521: systems adds corresponding `mcount' calls to the assembler code.
! 522: *Note Profiling::.
! 523:
1.1.1.2 maekawa 524: `MPN_PATH'
1.1.1.4 ! ohara 525: Various assembler versions of each mpn subroutines are provided.
! 526: For a given CPU, a search is made though a path to choose a
! 527: version of each. For example `sparcv8' has
! 528:
! 529: MPN_PATH="sparc32/v8 sparc32 generic"
! 530:
! 531: which means look first for v8 code, then plain sparc32 (which is
! 532: v7), and finally fall back on generic C. Knowledgeable users with
! 533: special requirements can specify a different path. Normally this
! 534: is completely unnecessary.
1.1.1.2 maekawa 535:
536: Documentation
537: The document you're now reading is `gmp.texi'. The usual automake
1.1.1.4 ! ohara 538: targets are available to make PostScript `gmp.ps' and/or DVI
! 539: `gmp.dvi'.
! 540:
! 541: HTML can be produced with `makeinfo --html', see *Note Generating
! 542: HTML: (texinfo)makeinfo html. Or alternately `texi2html', see
! 543: *Note Texinfo to HTML: (texi2html)Top.
! 544:
! 545: PDF can be produced with `texi2dvi --pdf' (*note PDF: (texinfo)PDF
! 546: Output.) or with `pdftex'.
! 547:
! 548: Some supplementary notes can be found in the `doc' subdirectory.
1.1.1.2 maekawa 549:
550:
551: File: gmp.info, Node: ABI and ISA, Next: Notes for Package Builds, Prev: Build Options, Up: Installing GMP
1.1 maekawa 552:
1.1.1.2 maekawa 553: ABI and ISA
554: ===========
1.1 maekawa 555:
1.1.1.2 maekawa 556: ABI (Application Binary Interface) refers to the calling conventions
557: between functions, meaning what registers are used and what sizes the
558: various C data types are. ISA (Instruction Set Architecture) refers to
559: the instructions and registers a CPU has available.
1.1 maekawa 560:
1.1.1.2 maekawa 561: Some 64-bit ISA CPUs have both a 64-bit ABI and a 32-bit ABI
562: defined, the latter for compatibility with older CPUs in the family.
1.1.1.4 ! ohara 563: GMP supports some CPUs like this in both ABIs. In fact within GMP
! 564: `ABI' means a combination of chip ABI, plus how GMP chooses to use it.
! 565: For example in some 32-bit ABIs, GMP may support a limb as either a
! 566: 32-bit `long' or a 64-bit `long long'.
1.1 maekawa 567:
1.1.1.4 ! ohara 568: By default GMP chooses the best ABI available for a given system,
! 569: and this generally gives significantly greater speed. But an ABI can
! 570: be chosen explicitly to make GMP compatible with other libraries, or
! 571: particular application requirements. For example,
1.1 maekawa 572:
1.1.1.4 ! ohara 573: ./configure ABI=32
1.1 maekawa 574:
1.1.1.4 ! ohara 575: In all cases it's vital that all object code used in a given program
! 576: is compiled for the same ABI.
1.1 maekawa 577:
1.1.1.4 ! ohara 578: Usually a limb is implemented as a `long'. When a `long long' limb
! 579: is used this is encoded in the generated `gmp.h'. This is convenient
! 580: for applications, but it does mean that `gmp.h' will vary, and can't be
! 581: just copied around. `gmp.h' remains compiler independent though, since
! 582: all compilers for a particular ABI will be expected to use the same
! 583: limb type.
1.1 maekawa 584:
1.1.1.4 ! ohara 585: Currently no attempt is made to follow whatever conventions a system
! 586: has for installing library or header files built for a particular ABI.
! 587: This will probably only matter when installing multiple builds of GMP,
! 588: and it might be as simple as configuring with a special `libdir', or it
! 589: might require more than that. Note that builds for different ABIs need
! 590: to done separately, with a fresh `./configure' and `make' each.
1.1 maekawa 591:
592:
1.1.1.4 ! ohara 593: HPPA 2.0 (`hppa2.0*')
1.1 maekawa 594:
1.1.1.4 ! ohara 595: `ABI=2.0w'
! 596: The 2.0w ABI uses 64-bit limbs and pointers and is available
! 597: on HP-UX 11 or up when using `cc'. `gcc' support for this is
! 598: in progress. Applications must be compiled with
1.1 maekawa 599:
1.1.1.4 ! ohara 600: cc +DD64
1.1 maekawa 601:
1.1.1.4 ! ohara 602: `ABI=2.0n'
! 603: The 2.0n ABI means the 32-bit HPPA 1.0 ABI but with a 64-bit
! 604: limb using `long long'. This is available on HP-UX 10 or up
! 605: when using `cc'. No `gcc' support is planned for this.
! 606: Applications must be compiled with
1.1 maekawa 607:
1.1.1.4 ! ohara 608: cc +DA2.0 +e
1.1 maekawa 609:
1.1.1.4 ! ohara 610: `ABI=1.0'
! 611: HPPA 2.0 CPUs can run all HPPA 1.0 and 1.1 code in the 32-bit
! 612: HPPA 1.0 ABI. No special compiler options are needed for
! 613: applications.
! 614:
! 615: All three ABIs are available for CPUs `hppa2.0w' and `hppa2.0', but
! 616: for CPU `hppa2.0n' only 2.0n or 1.0 are allowed.
! 617:
! 618:
! 619: MIPS under IRIX 6 (`mips*-*-irix[6789]')
! 620: IRIX 6 supports the n32 and 64 ABIs and always has a 64-bit MIPS 3
! 621: or better CPU. In both these ABIs GMP uses a 64-bit limb. A new
! 622: enough `gcc' is required (2.95 for instance).
! 623:
! 624: `ABI=n32'
! 625: The n32 ABI is 32-bit pointers and integers, but with a
! 626: 64-bit limb using a `long long'. Applications must be
! 627: compiled with
! 628:
! 629: gcc -mabi=n32
! 630: cc -n32
! 631:
! 632: `ABI=64'
! 633: The 64-bit ABI is 64-bit pointers and integers. Applications
! 634: must be compiled with
! 635:
! 636: gcc -mabi=64
! 637: cc -64
! 638:
! 639: Note that MIPS GNU/Linux, as of kernel version 2.2, doesn't have
! 640: the necessary support for n32 or 64 and so only gets a 32-bit limb
! 641: and the MIPS 2 code.
1.1 maekawa 642:
643:
1.1.1.4 ! ohara 644: PowerPC 64 (`powerpc64', `powerpc620', `powerpc630')
1.1 maekawa 645:
1.1.1.4 ! ohara 646: `ABI=aix64'
! 647: The AIX 64 ABI uses 64-bit limbs and pointers and is
! 648: available on systems `*-*-aix*'. Applications must be
! 649: compiled (and linked) with
1.1 maekawa 650:
1.1.1.4 ! ohara 651: gcc -maix64
! 652: xlc -q64
1.1 maekawa 653:
1.1.1.4 ! ohara 654: `ABI=32'
! 655: This is the basic 32-bit PowerPC ABI. No special compiler
! 656: options are needed for applications.
1.1.1.2 maekawa 657:
658:
1.1.1.4 ! ohara 659: Sparc V9 (`sparcv9' and `ultrasparc*')
1.1.1.2 maekawa 660:
1.1.1.4 ! ohara 661: `ABI=64'
! 662: The 64-bit V9 ABI is available on Solaris 2.7 and up and
! 663: GNU/Linux. GCC 2.95 or up, or Sun `cc' is required.
! 664: Applications must be compiled with
! 665:
! 666: gcc -m64 -mptr64 -Wa,-xarch=v9 -mcpu=v9
! 667: cc -xarch=v9
! 668:
! 669: `ABI=32'
! 670: On Solaris 2.6 and earlier, and on Solaris 2.7 with the
! 671: kernel in 32-bit mode, only the plain V8 32-bit ABI can be
! 672: used, since the kernel doesn't save all registers. GMP still
! 673: uses as much of the V9 ISA as it can in these circumstances.
! 674: No special compiler options are required for applications,
! 675: though using something like the following requesting V9 code
! 676: within the V8 ABI is recommended.
! 677:
! 678: gcc -mv8plus
! 679: cc -xarch=v8plus
! 680:
! 681: `gcc' 2.8 and earlier only supports `-mv8' though.
! 682:
! 683: Don't be confused by the names of these sparc `-m' and `-x'
! 684: options, they're called `arch' but they effectively control the
! 685: ABI.
! 686:
! 687: On Solaris 2.7 with the kernel in 32-bit-mode, a normal native
! 688: build will reject `ABI=64' because the resulting executables won't
! 689: run. `ABI=64' can still be built if desired by making it look
! 690: like a cross-compile, for example
! 691:
! 692: ./configure --build=none --host=sparcv9-sun-solaris2.7 ABI=64
1.1.1.2 maekawa 693:
694:
695: File: gmp.info, Node: Notes for Package Builds, Next: Notes for Particular Systems, Prev: ABI and ISA, Up: Installing GMP
696:
697: Notes for Package Builds
698: ========================
699:
700: GMP should present no great difficulties for packaging in a binary
701: distribution.
702:
703: Libtool is used to build the library and `-version-info' is set
1.1.1.4 ! ohara 704: appropriately, having started from `3:0:0' in GMP 3.0. The GMP 4 series
! 705: will be upwardly binary compatible in each release and will be upwardly
! 706: binary compatible with all of the GMP 3 series. Additional function
! 707: interfaces may be added in each release, so on systems where libtool
! 708: versioning is not fully checked by the loader an auxiliary mechanism
! 709: may be needed to express that a dynamic linked application depends on a
! 710: new enough GMP.
! 711:
! 712: An auxiliary mechanism may also be needed to express that
! 713: `libgmpxx.la' (from `--enable-cxx', *note Build Options::) requires
! 714: `libgmp.la' from the same GMP version, since this is not done by the
! 715: libtool versioning, nor otherwise. A mismatch will result in
! 716: unresolved symbols from the linker, or perhaps the loader.
! 717:
! 718: Using `DESTDIR' or a `prefix' override with `make install' and a
! 719: shared `libgmpxx' may run into a libtool relinking problem, see *Note
! 720: Known Build Problems::.
1.1.1.2 maekawa 721:
722: When building a package for a CPU family, care should be taken to use
1.1.1.4 ! ohara 723: `--host' (or `--build') to choose the least common denominator among
! 724: the CPUs which might use the package. For example this might
! 725: necessitate `i386' for x86s, or plain `sparc' (meaning V7) for SPARCs.
1.1.1.2 maekawa 726:
727: Users who care about speed will want GMP built for their exact CPU
728: type, to make use of the available optimizations. Providing a way to
729: suitably rebuild a package may be useful. This could be as simple as
1.1.1.4 ! ohara 730: making it possible for a user to omit `--build' (and `--host') so
1.1.1.2 maekawa 731: `./config.guess' will detect the CPU. But a way to manually specify a
1.1.1.4 ! ohara 732: `--build' will be wanted for systems where `./config.guess' is inexact.
! 733:
! 734: Note that `gmp.h' is a generated file, and will be architecture and
! 735: ABI dependent.
1.1.1.2 maekawa 736:
737:
738: File: gmp.info, Node: Notes for Particular Systems, Next: Known Build Problems, Prev: Notes for Package Builds, Up: Installing GMP
739:
740: Notes for Particular Systems
741: ============================
742:
1.1.1.4 ! ohara 743: AIX 3 and 4
! 744: On systems `*-*-aix[34]*' shared libraries are disabled by
! 745: default, since some versions of the native `ar' fail on the
! 746: convenience libraries used. A shared build can be attempted with
! 747:
! 748: ./configure --enable-shared --disable-static
! 749:
! 750: Note that the `--disable-static' is necessary because in a shared
! 751: build libtool makes `libgmp.a' a symlink to `libgmp.so',
! 752: apparently for the benefit of old versions of `ld' which only
! 753: recognise `.a', but unfortunately this is done even if a fully
! 754: functional `ld' is available.
! 755:
! 756: ARM
! 757: On systems `arm*-*-*', versions of GCC up to and including 2.95.3
! 758: have a bug in unsigned division, giving wrong results for some
! 759: operands. GMP `./configure' will demand GCC 2.95.4 or later.
! 760:
! 761: Compaq C++
! 762: Compaq C++ on OSF 5.1 has two flavours of `iostream', a standard
! 763: one and an old pre-standard one (see `man iostream_intro'). GMP
! 764: can only use the standard one, which unfortunately is not the
! 765: default but must be selected by defining `__USE_STD_IOSTREAM'.
! 766: Configure with for instance
! 767:
! 768: ./configure --enable-cxx CPPFLAGS=-D__USE_STD_IOSTREAM
! 769:
! 770: Microsoft Windows
! 771: On systems `*-*-cygwin*', `*-*-mingw*' and `*-*-pw32*' by default
! 772: GMP builds only a static library, but a DLL can be built instead
! 773: using
! 774:
! 775: ./configure --disable-static --enable-shared
! 776:
! 777: Static and DLL libraries can't both be built, since certain export
! 778: directives in `gmp.h' must be different. `--enable-cxx' cannot be
! 779: used when building a DLL, since libtool doesn't currently support
! 780: C++ DLLs. This might change in the future.
! 781:
! 782: Microsoft C
! 783: A MINGW DLL build of GMP can be used with Microsoft C. Libtool
! 784: doesn't install `.lib' and `.exp' files, but they can be created
! 785: with the following commands, where `/my/inst/dir' is the install
! 786: directory (with a `lib' subdirectory).
! 787:
! 788: lib /machine:IX86 /def:_libs/libgmp-3.dll-def
! 789: cp libgmp-3.lib /my/inst/dir/lib
! 790: cp _libs/libgmp-3.dll-exp /my/inst/dir/lib/libgmp-3.exp
! 791:
! 792: MINGW uses `msvcrt.dll' for I/O, so applications wanting to use
! 793: the GMP I/O routines must be compiled with `cl /MD' to do the
! 794: same. If one of the other I/O choices provided by MS C is desired
! 795: then the suggestion is to use the GMP string functions and confine
! 796: I/O to the application.
! 797:
! 798: Motorola 68k CPU Types
! 799: `m68k' is taken to mean 68000. `m68020' or higher will give a
! 800: performance boost on applicable CPUs. `m68360' can be used for
! 801: CPU32 series chips. `m68302' can be used for "Dragonball" series
! 802: chips, though this is merely a synonym for `m68000'.
1.1.1.2 maekawa 803:
804: OpenBSD 2.6
805: `m4' in this release of OpenBSD has a bug in `eval' that makes it
806: unsuitable for `.asm' file processing. `./configure' will detect
807: the problem and either abort or choose another m4 in the `PATH'.
808: The bug is fixed in OpenBSD 2.7, so either upgrade or use GNU m4.
809:
1.1.1.4 ! ohara 810: Power CPU Types
! 811: In GMP, CPU types `power*' and `powerpc*' will each use
! 812: instructions not available on the other, so it's important to
! 813: choose the right one for the CPU that will be used. Currently GMP
! 814: has no assembler code support for using just the common
! 815: instruction subset. To get executables that run on both, the
! 816: current suggestion is to use the generic C code (CPU `none'),
! 817: possibly with appropriate compiler options (like `-mcpu=common' for
! 818: `gcc'). CPU `rs6000' (which is not a CPU but a family of
! 819: workstations) is accepted by `config.sub', but is currently
! 820: equivalent to `none'.
! 821:
! 822: Sparc CPU Types
! 823: `sparcv8' or `supersparc' on relevant systems will give a
! 824: significant performance increase over the V7 code.
! 825:
! 826: Sparc App Regs
! 827: The GMP assembler code for both 32-bit and 64-bit Sparc clobbers
! 828: the "application registers" `g2', `g3' and `g4', the same way that
! 829: the GCC default `-mapp-regs' does (*note SPARC Options: (gcc)SPARC
! 830: Options.).
! 831:
! 832: This makes that code unsuitable for use with the special V9
! 833: `-mcmodel=embmedany' (which uses `g4' as a data segment pointer),
! 834: and for applications wanting to use those registers for special
! 835: purposes. In these cases the only suggestion currently is to
! 836: build GMP with CPU `none' to avoid the assembler code.
1.1.1.2 maekawa 837:
838: SunOS 4
839: `/usr/bin/m4' lacks various features needed to process `.asm'
840: files, and instead `./configure' will automatically use
841: `/usr/5bin/m4', which we believe is always available (if not then
842: use GNU m4).
843:
1.1.1.4 ! ohara 844: x86 CPU Types
! 845: `i386' selects generic code which will run reasonably well on all
! 846: x86 chips.
! 847:
! 848: `i586', `pentium' or `pentiummmx' code is good for the intended P5
! 849: Pentium chips, but quite slow when run on Intel P6 class chips
! 850: (PPro, P-II, P-III). `i386' is a better choice when making
! 851: binaries that must run on both.
! 852:
! 853: `pentium4' and an SSE2 capable assembler are important for best
! 854: results on Pentium 4. The specific code is for instance roughly a
! 855: 2x to 3x speedup over the generic `i386' code.
1.1.1.2 maekawa 856:
1.1.1.4 ! ohara 857: x86 MMX and SSE2 Code
! 858: If the CPU selected has MMX code but the assembler doesn't support
1.1.1.2 maekawa 859: it, a warning is given and non-MMX code is used instead. This
860: will be an inferior build, since the MMX code that's present is
861: there because it's faster than the corresponding plain integer
1.1.1.4 ! ohara 862: code. The same applies to SSE2.
! 863:
! 864: Old versions of `gas' don't support MMX instructions, in particular
! 865: version 1.92.3 that comes with FreeBSD 2.2.8 doesn't (and
! 866: unfortunately there's no newer assembler for that system).
1.1.1.2 maekawa 867:
1.1.1.4 ! ohara 868: Solaris 2.6 and 2.7 `as' generate incorrect object code for
! 869: register to register `movq' instructions, and so can't be used for
! 870: MMX code. Install a recent `gas' if MMX code is wanted on these
! 871: systems.
1.1.1.2 maekawa 872:
873:
874: File: gmp.info, Node: Known Build Problems, Prev: Notes for Particular Systems, Up: Installing GMP
1.1 maekawa 875:
876: Known Build Problems
877: ====================
878:
1.1.1.4 ! ohara 879: You might find more up-to-date information at `http://swox.com/gmp/'.
1.1.1.2 maekawa 880:
1.1.1.4 ! ohara 881: Compiler link options
! 882: The version of libtool currently in use rather aggressively strips
! 883: compiler options when linking a shared library. This will
! 884: hopefully be relaxed in the future, but for now if this is a
! 885: problem the suggestion is to create a little script to hide them,
! 886: and for instance configure with
! 887:
! 888: ./configure CC=gcc-with-my-options
! 889:
! 890: DJGPP
! 891: The DJGPP port of `bash' 2.03 is unable to run the `configure'
! 892: script, it exits silently, having died writing a preamble to
! 893: `config.log'. Use `bash' 2.04 or higher.
! 894:
! 895: `make all' was found to run out of memory during the final
! 896: `libgmp.la' link on one system tested, despite having 64Mb
! 897: available. A separate `make libgmp.la' helped, perhaps recursing
! 898: into the various subdirectories uses up memory.
! 899:
! 900: `DESTDIR' and shared `libgmpxx'
! 901: `make install DESTDIR=/my/staging/area', or the same with a
! 902: `prefix' override, to install to a temporary directory is not
! 903: fully supported by current versions of libtool when building a
! 904: shared version of a library which depends on another being built
! 905: at the same time, like `libgmpxx' and `libgmp'.
! 906:
! 907: The problem is that `libgmpxx' is relinked at the install stage to
! 908: ensure that if the system puts a hard-coded path to `libgmp' within
! 909: `libgmpxx' then that path will be correct. Naturally the linker is
! 910: directed to look only at the final location, not the staging area,
! 911: so if `libgmp' is not already in that final location then the link
! 912: will fail.
! 913:
! 914: A workaround for this on SVR4 style systems, such as GNU/Linux,
! 915: where paths are not hard-coded, is to include the staging area in
! 916: the linker's search using `LD_LIBRARY_PATH'. For example with
! 917: `--prefix=/usr' but installing under `/my/staging/area',
! 918:
! 919: LD_LIBRARY_PATH=/my/staging/area/usr/lib \
! 920: make install DESTDIR=/my/staging/area
! 921:
! 922: GNU binutils `strip' prior to 2.12
! 923: `strip' from GNU binutils 2.11 and earlier should not be used on
! 924: the static libraries `libgmp.a' and `libmp.a' since it will
! 925: discard all but the last of multiple archive members with the same
! 926: name, like the three versions of `init.o' in `libgmp.a'. Binutils
! 927: 2.12 or higher can be used successfully.
! 928:
! 929: The shared libraries `libgmp.so' and `libmp.so' are not affected by
! 930: this and any version of `strip' can be used on them.
! 931:
! 932: `make' syntax error
! 933: On certain versions of SCO OpenServer 5 and IRIX 6.5 the native
! 934: `make' is unable to handle the long dependencies list for
! 935: `libgmp.la'. The symptom is a "syntax error" on the following
! 936: line of the top-level `Makefile'.
! 937:
! 938: libgmp.la: $(libgmp_la_OBJECTS) $(libgmp_la_DEPENDENCIES)
! 939:
! 940: Either use GNU Make, or as a workaround remove
! 941: `$(libgmp_la_DEPENDENCIES)' from that line (which will make the
! 942: initial build work, but if any recompiling is done `libgmp.la'
! 943: might not be rebuilt).
! 944:
! 945: MacOS X and GCC
! 946: Libtool currently only knows how to create shared libraries on
! 947: MacOS X using the native `cc' (which is a modified GCC), not a
! 948: plain GCC. A static-only build should work though
! 949: (`--disable-shared').
! 950:
! 951: Also, libtool currently cannot build C++ shared libraries on MacOS
! 952: X, so if `--enable-cxx' is desired then `--disable-shared' must be
! 953: used. Hopefully this will be fixed in the future.
1.1.1.2 maekawa 954:
955: NeXT prior to 3.3
956: The system compiler on old versions of NeXT was a massacred and
957: old GCC, even if it called itself `cc'. This compiler cannot be
1.1.1.4 ! ohara 958: used to build GMP, you need to get a real GCC, and install that.
! 959: (NeXT may have fixed this in release 3.3 of their system.)
1.1.1.2 maekawa 960:
961: POWER and PowerPC
962: Bugs in GCC 2.7.2 (and 2.6.3) mean it can't be used to compile GMP
963: on POWER or PowerPC. If you want to use GCC for these machines,
964: get GCC 2.7.2.1 (or later).
965:
966: Sequent Symmetry
967: Use the GNU assembler instead of the system assembler, since the
968: latter has serious bugs.
969:
1.1.1.4 ! ohara 970: Solaris 2.6
! 971: The system `sed' prints an error "Output line too long" when
! 972: libtool builds `libgmp.la'. This doesn't seem to cause any
! 973: obvious ill effects, but GNU `sed' is recommended, to avoid any
! 974: doubt.
! 975:
! 976: Sparc Solaris 2.7 with gcc 2.95.2 in ABI=32
! 977: A shared library build of GMP seems to fail in this combination,
! 978: it builds but then fails the tests, apparently due to some
! 979: incorrect data relocations within `gmp_randinit_lc_2exp_size'.
! 980: The exact cause is unknown, `--disable-shared' is recommended.
! 981:
! 982: Windows DLL test programs
! 983: When creating a DLL version of `libgmp', libtool creates wrapper
! 984: scripts like `t-mul' for programs that would normally be
! 985: `t-mul.exe', in order to setup the right library paths etc. This
! 986: works fine, but the absence of `t-mul.exe' etc causes `make' to
! 987: think they need recompiling every time, which is an annoyance when
! 988: re-running a `make check'.
1.1 maekawa 989:
990:
1.1.1.2 maekawa 991: File: gmp.info, Node: GMP Basics, Next: Reporting Bugs, Prev: Installing GMP, Up: Top
1.1 maekawa 992:
1.1.1.2 maekawa 993: GMP Basics
994: **********
1.1 maekawa 995:
1.1.1.2 maekawa 996: *Using functions, macros, data types, etc. not documented in this
997: manual is strongly discouraged. If you do so your application is
998: guaranteed to be incompatible with future versions of GMP.*
999:
1000: * Menu:
1001:
1.1.1.4 ! ohara 1002: * Headers and Libraries::
! 1003: * Nomenclature and Types::
! 1004: * Function Classes::
! 1005: * Variable Conventions::
! 1006: * Parameter Conventions::
! 1007: * Memory Management::
! 1008: * Reentrancy::
! 1009: * Useful Macros and Constants::
! 1010: * Compatibility with older versions::
! 1011: * Demonstration Programs::
! 1012: * Efficiency::
! 1013: * Debugging::
! 1014: * Profiling::
! 1015: * Autoconf::
! 1016: * Emacs::
1.1.1.2 maekawa 1017:
1018:
1.1.1.4 ! ohara 1019: File: gmp.info, Node: Headers and Libraries, Next: Nomenclature and Types, Prev: GMP Basics, Up: GMP Basics
! 1020:
! 1021: Headers and Libraries
! 1022: =====================
! 1023:
! 1024: All declarations needed to use GMP are collected in the include file
! 1025: `gmp.h'. It is designed to work with both C and C++ compilers.
! 1026:
! 1027: #include <gmp.h>
! 1028:
! 1029: Note however that prototypes for GMP functions with `FILE *'
! 1030: parameters are only provided if `<stdio.h>' is included too.
! 1031:
! 1032: #include <stdio.h>
! 1033: #include <gmp.h>
! 1034:
! 1035: Likewise `<stdarg.h>' (or `<varargs.h>') is required for prototypes
! 1036: with `va_list' parameters, such as `gmp_vprintf'. And `<obstack.h>'
! 1037: for prototypes with `struct obstack' parameters, such as
! 1038: `gmp_obstack_printf', when available.
! 1039:
! 1040: All programs using GMP must link against the `libgmp' library. On a
! 1041: typical Unix-like system this can be done with `-lgmp', for example
! 1042:
! 1043: gcc myprogram.c -lgmp
! 1044:
! 1045: GMP C++ functions are in a separate `libgmpxx' library. This is
! 1046: built and installed if C++ support has been enabled (*note Build
! 1047: Options::). For example,
! 1048:
! 1049: g++ mycxxprog.cc -lgmpxx -lgmp
! 1050:
! 1051: GMP is built using Libtool and an application can use that to link
! 1052: if desired, *note Shared library support for GNU: (libtool)Top.
! 1053:
! 1054: If GMP has been installed to a non-standard location then it may be
! 1055: necessary to use `-I' and `-L' compiler options to point to the right
! 1056: directories, and some sort of run-time path for a shared library.
! 1057: Consult your compiler documentation, for instance *Note Introduction:
! 1058: (gcc)Top.
! 1059:
! 1060:
! 1061: File: gmp.info, Node: Nomenclature and Types, Next: Function Classes, Prev: Headers and Libraries, Up: GMP Basics
1.1.1.2 maekawa 1062:
1.1 maekawa 1063: Nomenclature and Types
1064: ======================
1065:
1066: In this manual, "integer" usually means a multiple precision integer, as
1.1.1.2 maekawa 1067: defined by the GMP library. The C data type for such integers is
1.1 maekawa 1068: `mpz_t'. Here are some examples of how to declare such integers:
1069:
1070: mpz_t sum;
1071:
1072: struct foo { mpz_t x, y; };
1073:
1074: mpz_t vec[20];
1075:
1076: "Rational number" means a multiple precision fraction. The C data type
1077: for these fractions is `mpq_t'. For example:
1078:
1079: mpq_t quotient;
1080:
1081: "Floating point number" or "Float" for short, is an arbitrary precision
1.1.1.2 maekawa 1082: mantissa with a limited precision exponent. The C data type for such
1.1 maekawa 1083: objects is `mpf_t'.
1084:
1085: A "limb" means the part of a multi-precision number that fits in a
1.1.1.4 ! ohara 1086: single machine word. (We chose this word because a limb of the human
! 1087: body is analogous to a digit, only larger, and containing several
! 1088: digits.) Normally a limb is 32 or 64 bits. The C data type for a limb
! 1089: is `mp_limb_t'.
1.1 maekawa 1090:
1.1.1.2 maekawa 1091:
1.1.1.4 ! ohara 1092: File: gmp.info, Node: Function Classes, Next: Variable Conventions, Prev: Nomenclature and Types, Up: GMP Basics
1.1.1.2 maekawa 1093:
1.1 maekawa 1094: Function Classes
1095: ================
1096:
1.1.1.2 maekawa 1097: There are six classes of functions in the GMP library:
1.1 maekawa 1098:
1099: 1. Functions for signed integer arithmetic, with names beginning with
1.1.1.4 ! ohara 1100: `mpz_'. The associated type is `mpz_t'. There are about 150
1.1 maekawa 1101: functions in this class.
1102:
1103: 2. Functions for rational number arithmetic, with names beginning with
1.1.1.4 ! ohara 1104: `mpq_'. The associated type is `mpq_t'. There are about 40
! 1105: functions in this class, but the integer functions can be used for
! 1106: arithmetic on the numerator and denominator separately.
1.1 maekawa 1107:
1108: 3. Functions for floating-point arithmetic, with names beginning with
1.1.1.4 ! ohara 1109: `mpf_'. The associated type is `mpf_t'. There are about 60
1.1 maekawa 1110: functions is this class.
1111:
1.1.1.4 ! ohara 1112: 4. Functions compatible with Berkeley MP, such as `itom', `madd', and
1.1 maekawa 1113: `mult'. The associated type is `MINT'.
1114:
1115: 5. Fast low-level functions that operate on natural numbers. These
1116: are used by the functions in the preceding groups, and you can
1117: also call them directly from very time-critical user programs.
1.1.1.4 ! ohara 1118: These functions' names begin with `mpn_'. The associated type is
! 1119: array of `mp_limb_t'. There are about 30 (hard-to-use) functions
! 1120: in this class.
1.1 maekawa 1121:
1122: 6. Miscellaneous functions. Functions for setting up custom
1.1.1.2 maekawa 1123: allocation and functions for generating random numbers.
1124:
1125:
1.1.1.4 ! ohara 1126: File: gmp.info, Node: Variable Conventions, Next: Parameter Conventions, Prev: Function Classes, Up: GMP Basics
1.1 maekawa 1127:
1.1.1.4 ! ohara 1128: Variable Conventions
! 1129: ====================
1.1 maekawa 1130:
1.1.1.4 ! ohara 1131: GMP functions generally have output arguments before input
! 1132: arguments. This notation is by analogy with the assignment operator.
! 1133: The BSD MP compatibility functions are exceptions, having the output
! 1134: arguments last.
1.1 maekawa 1135:
1.1.1.2 maekawa 1136: GMP lets you use the same variable for both input and output in one
1137: call. For example, the main function for integer multiplication,
1138: `mpz_mul', can be used to square `x' and put the result back in `x' with
1.1 maekawa 1139:
1.1.1.2 maekawa 1140: mpz_mul (x, x, x);
1141:
1142: Before you can assign to a GMP variable, you need to initialize it
1.1 maekawa 1143: by calling one of the special initialization functions. When you're
1144: done with a variable, you need to clear it out, using one of the
1145: functions for that purpose. Which function to use depends on the type
1146: of variable. See the chapters on integer functions, rational number
1147: functions, and floating-point functions for details.
1148:
1.1.1.4 ! ohara 1149: A variable should only be initialized once, or at least cleared
1.1 maekawa 1150: between each initialization. After a variable has been initialized, it
1151: may be assigned to any number of times.
1152:
1.1.1.4 ! ohara 1153: For efficiency reasons, avoid excessive initializing and clearing.
! 1154: In general, initialize near the start of a function and clear near the
! 1155: end. For example,
1.1.1.2 maekawa 1156:
1157: void
1.1.1.4 ! ohara 1158: foo (void)
1.1.1.2 maekawa 1159: {
1.1.1.4 ! ohara 1160: mpz_t n;
! 1161: int i;
! 1162: mpz_init (n);
! 1163: for (i = 1; i < 100; i++)
! 1164: {
! 1165: mpz_mul (n, ...);
! 1166: mpz_fdiv_q (n, ...);
! 1167: ...
! 1168: }
! 1169: mpz_clear (n);
1.1.1.2 maekawa 1170: }
1.1 maekawa 1171:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to gmp.info-1 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gmp