1 Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 Free Software Foundation, Inc.
2 Contributed by the AriC and Caramel projects, INRIA.
4 This file is part of the GNU MPFR Library.
6 The GNU MPFR Library is free software; you can redistribute it and/or modify
7 it under the terms of the GNU Lesser General Public License as published by
8 the Free Software Foundation; either version 3 of the License, or (at your
9 option) any later version.
11 The GNU MPFR Library is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
13 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
14 License for more details.
16 You should have received a copy of the GNU Lesser General Public License
17 along with the GNU MPFR Library; see the file COPYING.LESSER. If not, see
18 http://www.gnu.org/licenses/ or write to the Free Software Foundation, Inc.,
19 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
26 Note: In case of problem, please read this INSTALL file carefully before
27 reporting a bug, in particular Section "In case of problem" below. Some
28 problems are due to bad configuration on the user side (not specific to
31 0. You first need to install GMP. See <http://www.gnu.org/software/gmp/>.
32 MPFR requires GMP version 4.1 or later.
34 1. Extract the files from the archive.
36 2. It is strongly advised to apply the latest patches if this has
37 not been done yet and if patches are available. You can check
40 http://www.mpfr.org/mpfr-3.1.2/
42 which may have additional information. The patches can be applied
45 wget http://www.mpfr.org/mpfr-3.1.2/allpatches
46 patch -N -Z -p1 < allpatches
50 curl http://www.mpfr.org/mpfr-3.1.2/allpatches | patch -N -Z -p1
52 (Those instructions are for the GNU patch command, for example
53 /usr/bin/gpatch on Solaris.)
55 3. In the MPFR directory, to detect your system, type:
57 possibly with options (see below, in particular if this step or
58 one of the following fails). You should also check whether WARNING
59 lines have been output (such a problem may cause a failure in one
60 of the following steps).
61 Note: paths provided in configure options must always be absolute
62 (relative paths are not supported).
64 4. To build the library, type:
67 [optional] if you want to tune MPFR for your specific architecture, see
68 the section "Tuning MPFR" below. Note that for most common architectures,
69 MPFR includes some default tuning parameters which should be near from
72 5. To check the built library (runs the test files), type:
75 6. To install it (default "/usr/local" | see "--prefix" option), type:
78 If you installed MPFR (header and library) in directories that are
79 not searched by default by the compiler and/or linking tools, then,
80 like with other libraries, you may need to set up some environment
81 variables such as C_INCLUDE_PATH (to find the header mpfr.h),
82 LIBRARY_PATH (to find the library), and if the shared library has
83 been installed, LD_LIBRARY_PATH (before execution) or LD_RUN_PATH
84 (before linking); this list is not exhaustive and some environment
85 variables may be specific to your system. "make install" gives some
86 instructions; please read them. You can also find more information
87 in the manuals of your compiler and linker. The MPFR FAQ may also
88 give some information.
90 Remember that if you have several MPFR (or GMP) versions installed
91 (e.g., one with the system, and one, newer, by you), you will not
92 necessarily get a compilation/linking error if a wrong library is
93 used (e.g., because LD_LIBRARY_PATH has not been set correctly).
94 But unexpected results may occur.
96 Under Mac OS X, if the shared library was not installed and you use
97 Apple's linker (this is the default), you will also need to provide
98 the -search_paths_first linker flag ("-Wl,-search_paths_first" when
99 you link via gcc) to make sure that the right library is selected,
100 as by default, Apple's linker selects a shared library preferably,
101 even when it is farther in the library paths. We recall that if a
102 wrong library is selected due to this behavior, unexpected results
106 Building the documentation
107 ==========================
109 To build the documentation in various formats, you may first need to
110 install recent versions of some utilities such as texinfo.
112 * Type "make info" to produce the documentation in the info format.
114 * Type "make pdf" to produce the documentation in the PDF format.
116 * Type "make dvi" to produce the documentation in the DVI format.
118 * Type "make ps" to produce the documentation in the Postscript format.
120 * Type "make html" to produce the documentation in the HTML format
121 (in several pages); if you want only one output HTML file, then
122 type "makeinfo --html --no-split mpfr.texi" from the doc directory
126 Building MPFR with internal GMP header files
127 ============================================
129 MPFR built with internal GMP header files is a bit faster, so you may want
130 to build it with them. Just do this in step 1:
132 ./configure --with-gmp-build=GMPBUILD
134 where GMPBUILD is the GMP build directory. The needed header files are:
135 gmp-impl.h, longlong.h and all the necessary headers to use them, which
136 may be located either in the GMP source directory or in the GMP build
137 directory, in case they are different (MPFR takes care of that, as of
140 Warning: the library obtained in this way may use some internal GMP
141 symbols, and thus dynamically linking your software with a different
142 version of GMP might fail, even though it is declared as compatible
143 by Libtool's versioning system.
149 For this, you need to build MPFR with a GMP build directory (see above).
150 In the GMP build directory, you also need to go into the "tune" subdirectory
151 and type "make speed". This will build the GMP speed library, which is used
152 by the MPFR tuning mechanism.
154 Then go back to the MPFR build directory, go into the "tune" subdirectory and
155 type "make tune". This will build an optimized file "mparam.h" for your
156 specific architecture.
162 --prefix=DIR installs MPFR headers and library in DIR/include and
163 DIR/lib respectively (the default is "/usr/local").
165 --with-gmp-include=DIR assumes that DIR contains gmp.h
166 --with-gmp-lib=DIR assumes that DIR contains the GMP library
167 --with-gmp=DIR assumes that DIR is where you have installed GMP.
168 same as --with-gmp-lib=DIR/lib
169 and --with-gmp-include=DIR/include
170 (use either --with-gmp alone or one or both of
171 --with-gmp-lib/--with-gmp-include)
172 Warning! Do not use these options if you have
173 CPPFLAGS and/or LDFLAGS containing a -I or -L
174 option with a directory that contains a GMP
175 header or library file, as these options just
176 add -I and -L options to CPPFLAGS and LDFLAGS
177 *after* the ones that are currently declared,
178 so that DIR will have a lower precedence. Also,
179 this may not work if DIR is a system directory
180 (typically /usr or /usr/local); see below.
182 --with-gmp-build=DIR assumes that DIR contains the GMP build directory,
183 and enables the use of GMP internals (see above).
184 Warning! This option and the group of options
185 --with-gmp are mutually exclusive.
187 --enable-assert build MPFR with assertions.
189 --enable-thread-safe build MPFR as thread safe, using compiler-level
190 Thread Local Storage (TLS). Note: TLS support is
191 roughly tested by configure. If configure detects
192 that TLS does not work (because of the compiler,
193 linker or system libraries), it will output an
194 error message, telling you to build MPFR without
195 thread safe. For instance, though Mac OS X uses
196 GCC, it may not currently support GCC's __thread
199 --disable-thread-safe build MPFR without TLS. By default, TLS support
200 is detected automatically, and MPFR is built as
201 thread safe if supported. However this detection
202 is only a heuristic: TLS can be detected as
203 supported while its support is incomplete or
204 buggy (MPFR tests may fail). In such a case,
205 this option is useful.
207 --enable-gmp-internals allows the MPFR build to use GMP's undocumented
208 functions (not from the public API). Note that
209 library versioning is not guaranteed to work if
210 this option is used. Thus it must not be used in
211 binary distributions.
213 Note: By default, the configure script tries to set CC/CFLAGS to GMP's
214 ones (this feature needs GMP 4.3.0 or later, or the --with-gmp-build
215 option). However this is not guaranteed to work as the configure script
216 does some compiler tests earlier, and the change may be too late. Also,
217 the values obtained from GMP may be incorrect if GMP has been built
218 on a different machine. In such a case, the user may need to specify
219 CC/CFLAGS as explained below.
221 Run "./configure --help" to see the other options (autoconf default options).
224 If 'gmp.h' and 'libgmp' do not match
225 ====================================
227 Under some circumstances, the configure script may output a message
230 'gmp.h' and 'libgmp' seem to have different versions or
231 we cannot run a program linked with GMP (if you cannot
232 see the version numbers above). [...]
234 Even though the configure script does not fail in such a case, this
235 message most often indicates a real error, which needs to be avoided.
238 * The wanted GMP library does not have the same ABI as the one chosen
239 to build MPFR. The consequences may be:
241 - A different GMP library (with the correct ABI) has been found,
242 but does not have the same version as 'gmp.h'.
244 - No other GMP libraries have been found (in this case, no version
245 numbers should be printed above the warning message).
247 This is incorrect and one of the following steps (make, make check)
248 will probably fail. GMP (actually gmp.h) now provides CC and CFLAGS
249 information to select the correct ABI, so that this problem should
250 no longer occur; but if GMP was provided by a binary package, such
251 information may not be valid. See the
253 checking for CC and CFLAGS in gmp.h...
255 line in the configure output (about the 11th line) and the following
256 few ones for more information. You may need to reinstall GMP or to
257 provide your own CC and/or CFLAGS. See also the remaining of this
260 * A configure option like --with-gmp or --with-gmp-include was used
261 with a system include directory, e.g. one of the following:
264 --with-gmp=/usr/local
265 --with-gmp-include=/usr/include
266 --with-gmp-include=/usr/local/include
268 GCC (and possibly other compilers) will ignore such a directive for
269 include directories (but this rule is not applied for the library
270 itself!). This means that the library search paths will be reordered
271 as declared, but the specified include directory will still be near
272 the end of the include search paths (thus with a low precedence).
273 This is not a problem if only one GMP version is installed, but
274 otherwise, a wrong gmp.h may be chosen, so that the versions of
275 gmp.h and libgmp may not match. The suggestions are the following:
277 - If you want to use the GMP version under /usr, then you should
278 uninstall all the other GMP versions (header and library files)
279 that may be seen in the search paths, in particular those under
282 - If you want to use the GMP version under /usr/local, then you
283 should uninstall all the other GMP versions (header and library
284 files) that may be seen in the search paths, but *NOT* the one
285 under /usr (the version under /usr is provided by the OS vendor,
286 and changing/removing anything related to it may break your
287 system, and /usr should have a lower precedence than /usr/local
290 To find where GMP versions have been installed:
292 $ locate libgmp (if you have a locate database)
294 and if the compiler is GCC:
296 $ gcc -print-file-name=libgmp.so (under most systems)
297 $ gcc -print-file-name=libgmp.dylib (under Mac OS X)
299 and if this does not work, you may try:
301 $ gcc -print-search-dirs
303 * An official GCC version was used under Debian GNU/Linux. Problems
304 may come from the fact that Debian chose a different convention
305 for library search paths concerning 32-bit and 64-bit libraries.
306 A possible problem can be, for instance:
308 [Debian's GCC, correct library path]
309 $ gcc -print-file-name=libgmp.so
310 /home/vlefevre/gmp/athlon64/lib/../lib/libgmp.so
312 [Official GCC, incorrect library path]
313 $ gcc-4.3.1 -print-file-name=libgmp.so
314 /usr/lib/../lib64/libgmp.so
316 The solution: use a GCC provided by Debian or add symbolic links
317 such as lib64 -> lib (on 64-bit machines) for your library paths.
319 * The problem may also be temporary and only due to the fact that
320 libtool could not be used at this time. This is unlikely, though.
326 First, look for any warning message in the configure output.
328 Several documents may help you to solve the problem:
329 * this INSTALL file, in particular information given below;
330 * the FAQ (either the FAQ.html file distributed with MPFR, or the
331 on-line version <http://www.mpfr.org/faq.html>, which may be more
333 * the MPFR web page for this version <http://www.mpfr.org/mpfr-3.1.2/>,
334 which lists bugs found in this version and provides some patches.
336 If the "configure" fails, please check that the C compiler and its
337 options are the same as those for the GMP build (specially the ABI).
338 You can see the latter with the following command:
340 grep "^CC\|^CFLAGS" GMPBUILD/Makefile
342 if the GMP build directory is available. Then type:
344 ./configure <configure options> CC=<C compiler> CFLAGS="<compiler options>"
346 (quotes are needed when there are spaces or other special characters
347 in the CC/CFLAGS value) and continue the install. On some platforms,
348 you should provide further options to match those used by GMP, or set
349 some environment variables. For instance, see the "Notes on AIX/PowerPC"
352 Warning! Do NOT use optimization options that can change the semantics
353 of math operations, such as GCC's -ffast-math or Sun CC's -fast.
354 Otherwise conversions from/to double's may be incorrect on infinities,
355 NaN's and signed zeros. Since native FP arithmetic is used in a few
356 places only, such options would not make MPFR faster anyway.
358 If some "make check" tests fail, you can try the --disable-thread-safe
359 configure option (see the configure options above): it has been reported
360 that some platforms have buggy TLS support. Before trying this option,
361 you may want to check in the configure output whether MPFR was built
362 with TLS support; if yes, you will have a line:
363 checking for TLS support... yes
364 Alternatively "grep MPFR_USE_THREAD_SAFE config.log" will show that
365 MPFR_USE_THREAD_SAFE is defined to 1. If it is "no" (or the variable
366 is not defined), the --disable-thread-safe option would be useless.
368 Some tests failure may be due to other compiler bugs, in particular
369 in optimization code. You can try to build MPFR without compiler
370 optimizations by giving -O0 (letter O, digit 0) in CFLAGS. If the
371 MPFR tests no longer fail, this was probably due to a compiler bug,
372 though we cannot exclude a bug in MPFR. You may want to contact us
373 (see below), possibly after looking at:
374 http://www.loria.fr/~zimmerma/software/compilerbugs.html
376 On some platforms, try with "gmake" (GNU make) instead of "make".
377 Problems have been reported with the Tru64 make.
379 If the configure script reports that gmp.h version and libgmp version
380 are different, or if the build was OK, but the tests failed to link
381 with GMP or gave an error like
383 undefined reference to `__gmp_get_memory_functions'
385 meaning that the GMP library was not found or a wrong GMP library was
386 selected by the linker, then your library search paths are probably
387 not correctly set (some paths are missing or they are specified in an
390 Such problems commonly occur under some GNU/Linux machines, where the
391 default header and library search paths may be inconsistent: GCC is
392 configured to search /usr/local/include and /usr/local/lib by default,
393 while the dynamic linker ignores /usr/local/lib. If you have a GMP
394 version installed in /usr (provided by the OS vendor) and a new one
395 installed in /usr/local, then the header of the new GMP version and
396 the library of the old GMP version will be used! The best solution
397 is to make sure that the dynamic linker configuration is consistent
398 with GCC's behavior, for instance by having /usr/local/lib in
399 /etc/ld.so.conf or in some file from /etc/ld.so.conf.d (as Debian
400 did: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=395177). See
401 also http://gcc.gnu.org/ml/gcc-help/2010-01/msg00171.html for more
402 information. Alternatively you can use:
403 * environment variables. This may sometimes be necessary. If DIR
404 is the installation directory of GMP, add DIR/include to your
405 CPATH or C_INCLUDE_PATH (for compilers other than GCC, please
406 check the manual of your compiler), and add DIR/lib to your
407 LIBRARY_PATH and LD_LIBRARY_PATH (and/or LD_RUN_PATH);
408 * --with-gmp* configure options (described above), e.g.
409 --with-gmp=/opt/local (to use /opt/local/include for headers and
410 /opt/local/lib for libraries), but other software that uses GMP
411 and/or MPFR will need correct paths too, and environment variables
412 allow one to set such search paths in a global way.
413 Note about "--with-gmp=/usr/local". This option may appear to
414 solve the above inconsistency problem, but does not work as you
415 expect. Indeed it affects the library search path, in particular,
416 the one used by the dynamic linker (thus adding the missing
417 /usr/local/lib directory as wanted), but since /usr/local/include
418 is a "standard system include directory" for GCC, the include
419 search patch is not changed; this is often not a problem in this
420 particular case because usually, /usr/local/include is already
421 last in the include search patch, but this may fail under some
422 occasions and may trigger obscure errors.
424 For instance, under Unix, where paths are separated by a colon:
426 * With POSIX sh-compatible shells (e.g. sh, ksh, bash, zsh):
427 export C_INCLUDE_PATH="/usr/local/include:/other/path/include"
428 export LIBRARY_PATH="/usr/local/lib:/other/path/lib"
429 export LD_LIBRARY_PATH="$LIBRARY_PATH"
432 setenv C_INCLUDE_PATH "/usr/local/include:/other/path/include"
433 setenv LIBRARY_PATH "/usr/local/lib:/other/path/lib"
434 setenv LD_LIBRARY_PATH "$LIBRARY_PATH"
436 If you can't solve your problem, you should contact us via the MPFR
437 mailing-list <mpfr@inria.fr>, indicating the machine and operating system
438 used (uname -a), the compiler and version used (gcc -v if you use gcc),
439 the configure options used if any (including variables such as CC and
440 CFLAGS), the version of GMP and MPFR used, and a description of the
441 problem encountered. Please send us also the log of the "configure"
444 Note that even if you can build MPFR with a C++ compiler, you can't run
445 the test suite: C and C++ are not the same language! You should use a C
452 On 64-bit computers, it may happen that the default ABI (Application Binary
453 Interface) chosen by MPFR does not correspond to the default one chosen by
456 In particular, this kind of message may indicate the problem:
457 /usr/bin/ld: skipping incompatible mpfr/src/.libs/libmpfr.a when searching for -lmpfr
459 In fact, since MPFR relies on GMP, it uses the same ABI as GMP.
460 To be sure that your program compiles and links correctly, use the same
461 compiler flags as MPFR does (look for CFLAGS in config.log).
463 You might also recompile GMP with a different ABI, with for example
470 If you get an error of the form
472 ld: pointer in read-only segment not allowed in slidable image...
474 this can mean that the link is done against a static (GMP) library.
475 In such a case, you should configure MPFR with --disable-shared to
476 disable the build of the shared library.
482 FreeBSD 4.3 is provided with an incorrect <float.h> header file, and
483 MPFR tests related to long double's may fail. If you cannot upgrade
484 the system, you can still use MPFR with FreeBSD 4.3, but you should
485 not use conversions with the long double type.
491 The following has been tested on AIX 5.3 (powerpc-ibm-aix5.3.0.0) with
492 gcc 3.3.2 and GMP 4.2.1.
494 If GMP was built with the 64-bit ABI, before building and testing MPFR,
495 you should set the OBJECT_MODE environment variable to 64, e.g., with:
497 export OBJECT_MODE=64
499 (in a sh-compatible shell). But you should also provide a correct CFLAGS
500 value to the "configure" script: using --with-gmp-build is not sufficient
501 due to the early compiler tests, as gcc will not compile any program if
502 OBJECT_MODE is 64 and the -maix64 option is not provided.
505 MPFR for use with 32-bit Windows Applications (win32)
506 =====================================================
508 There are several ways of building MPFR on Windows, the most appropriate
509 approach depending on how you intend to use the resulting libraries.
514 1 - We advise to use MinGW (http://www.mingw.org/), which is simpler and
515 less demanding than Cygwin. Contrary to Cygwin, it also provides native
518 2 - If you just want to make a binary with gcc, there is nothing to do:
519 GMP, MPFR and the program compile exactly as under Linux.
520 But if you want to generate a library for MinGW from a Cygwin
521 environment, you may need the -mno-cygwin gcc option (otherwise
522 a typical error is _P_WAIT being undeclared).
524 3 - If you want to make libraries work under another Windows compiler
525 like Visual C / C++, since the unix-like *.a library files are compatible
526 with Windows *.lib files, you can simply rename all *.a libraries to *.lib.
528 With gmp-4.1.3, the only remaining problem seems to be the "alloca" calls
529 in GMP. Configuring GMP and MPFR with --enable-alloca=malloc-reentrant
530 should work (if you build MPFR with GMP internal files).
532 Or you could add the library
533 "$MINGWIN$/lib/gcc-lib/mingw32/$VERSION$/libgcc.a"
534 to your project: it contains all the extra-functions needed by a program
535 compiled by gcc (division of 64-bit integer, bcopy, alloca...).
536 Of course, include it if and only if your compiler is not gcc.
538 4 - On Windows32 / MinGW, if all the tests fail, try to run the test suite
539 with "make check EXEEXT=".
541 5 - To avoid using the Microsoft runtime (which might not be conform to ISO C),
542 you can use the MinGW runtime package (which is an integral part of MinGW).
543 For example, with MinGW versions 3.15 and later you can get an
544 ISO-compliant printf() if you compile your application with either
545 '-ansi', '-posix' or '-D__USE_MINGW_ANSI_STDIO'. For example, you can
546 compile and test MPFR with CC="gcc -D__USE_MINGW_ANSI_STDIO".
548 For example under Win32, the following problem has been experienced with
549 MPFR 2.4.0 RC1 and the MSVC runtime (msvcrt.dll):
551 Error in mpfr_vsprintf (s, "%.*Zi, %R*e, %Lf%n", ...);
552 expected: "00000010610209857723, -1.2345678875e+07, 0.032258"
553 got: "00000010610209857723, -1.2345678875e+07, -0.000000"
556 This error is due to the MSVC runtime not supporting the L length modifier
557 for formatted output (e.g. printf with %Lf). You can check this with the
563 long double d = 1. / 31.;
568 The expected output is 0.032258.
570 Note: The L modifier has been standard for a long time (it was added
573 Note 2: this now works correctly with Visual C++ 2008 and 2010
574 (tested on Microsoft (R) 32-bit C/C++ Optimizing Compiler Version
575 15.00.21022.08 for 80x86, Microsoft (R) C/C++ Optimizing Compiler
576 Version 15.00.21022.08 for x64, Microsoft (R) 32-bit C/C++ Optimizing
577 Compiler Version 16.00.30319.01 for 80x86, Microsoft (R) C/C++ Optimizing
578 Compiler Version 16.00.30319.01 for x64).
583 This build should be similar to that for MinGW except that the resulting
584 library depends on the Cygwin DLL and cannot therefore be used with
585 Visual Studio as with MinGW. Indeed, the binaries compiled with Cygwin
586 require a dynamic library (cygwin.dll) to work; there is a Cygwin option
587 -mno-cygwin to build native code, but it may require some non-portable tricks.
589 In case of failure, you may need to pass LDFLAGS='-shared-libgcc' at the
590 end of the configure line due to a bug in GCC. Otherwise, if threading
591 support is not needed, you can configure MPFR with --disable-thread-safe.
593 c. Using Visual C++ 2008/2010
594 =============================
596 Win32 versions of the MPFR library can be built using Microsoft Visual
597 C++ 2008 or 2010 using the build projects available here:
599 http://gladman.plushost.co.uk/oldsite/computing/gmp4win.php
601 These build projects contain both win32 and x64 builds but the latter
602 will give errors if your version of Visual C++ lacks the 64-bit
603 compiler and tools. The 32-bit build projects should however work
604 on Visual C++ 2008, Visual C++ Express 2008 (SP1), Visual C++ 2010
605 and Visual C++ Express 2010.
607 MPFR for use with 64-bit Windows Applications (x64)
608 ===================================================
610 There are two ways of building MPFR for use with 64-bit Windows
616 The MinGW64 version of the GCC compiler is now available here:
618 http://sourceforge.net/projects/mingw-w64/
620 It can build both GMP and MPFR for 64-bit Windows applications.
622 b. Using Visual C++ 2008/2010
623 =============================
625 x64 versions of the MPFR library can be built using Microsoft Visual
626 C++ 2008 or 2010 using the build projects available here:
628 http://gladman.plushost.co.uk/oldsite/computing/gmp4win.php
630 These build projects contain both win32 and x64 builds but the latter
631 can only be built if your version of Visual C++ contains the 64-bit
632 compiler and tools. On Visual C++ 2008, the 64-bit tools are an
633 option during installation so if you don't have them you will need
634 to start the Visual Studio installer and add them to your IDE
635 configuration. On Visual C++ 2010 they are installed by default.
637 As delivered, Visual C++ Express 2008 SP1 cannot build x64 projects
638 but the Windows SDK can be added to it to allow this. The IDE then
639 needs to be configured as described here:
641 http://msdn.microsoft.com/en-us/library/9yb4317s(VS.80).aspx
645 Visual C++ Express 2010 requires the Windows 7 SDK to be installed
646 in order to build x64 projects. This SDK is available here:
648 http://tinyurl.com/25zz8r6
650 In this case, once this SDK has been installed, Visual C++ Express 2010
651 will build x64 projects without further changes.