1Copyright 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc. 2Contributed by the Arenaire and Cacao projects, INRIA. 3 4This file is part of the GNU MPFR Library. 5 6The GNU MPFR Library is free software; you can redistribute it and/or modify 7it under the terms of the GNU Lesser General Public License as published by 8the Free Software Foundation; either version 3 of the License, or (at your 9option) any later version. 10 11The GNU MPFR Library is distributed in the hope that it will be useful, but 12WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 13or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 14License for more details. 15 16You should have received a copy of the GNU Lesser General Public License 17along with the GNU MPFR Library; see the file COPYING.LESSER. If not, see 18http://www.gnu.org/licenses/ or write to the Free Software Foundation, Inc., 1951 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. 20 21 22 23 Installing GNU MPFR 24 =================== 25 26Note: In case of problem, please read this INSTALL file carefully before 27reporting a bug, in particular Section "In case of problem" below. Some 28problems are due to bad configuration on the user side (not specific to 29MPFR). 30 310. You first need to install GMP. See <http://www.gnu.org/software/gmp/>. 32 MPFR requires GMP version 4.1 or later. 33 341. Extract the files from the archive. 35 362. It is strongly advised to apply the latest patches (if this has 37 not been done yet), e.g. 38 wget http://www.mpfr.org/mpfr-3.0.1/allpatches 39 patch -N -Z -p1 < allpatches 40 or 41 curl http://www.mpfr.org/mpfr-3.0.1/allpatches | patch -N -Z -p1 42 43 (Those instructions are for the GNU patch command, for example 44 /usr/bin/gpatch on Solaris.) 45 463. In the MPFR directory, to detect your system, type: 47 ./configure 48 possibly with options (see below, in particular if this step or 49 one of the following fails). 50 Note: paths provided in configure options must always be absolute 51 (relative paths are not supported). 52 534. To build the library, type: 54 make 55 56 [optional] if you want to tune MPFR for your specific architecture, see 57 the section "Tuning MPFR" below. Note that for most common architectures, 58 MPFR includes some default tuning parameters which should be near from 59 optimal. 60 615. To check the built library (runs the test files), type: 62 make check 63 646. To install it (default "/usr/local" | see "--prefix" option), type: 65 make install 66 67If you installed MPFR (header and library) in directories that are 68not searched by default by the compiler and/or linking tools, then, 69like with other libraries, you may need to set up some environment 70variables such as C_INCLUDE_PATH (to find the header mpfr.h), 71LIBRARY_PATH (to find the library), and if the shared library has 72been installed, LD_LIBRARY_PATH (before execution) or LD_RUN_PATH 73(before linking); this list is not exhaustive and some environment 74variables may be specific to your system. "make install" gives some 75instructions; please read them. You can also find more information 76in the manuals of your compiler and linker. The MPFR FAQ may also 77give some information. 78 79Remember that if you have several MPFR (or GMP) versions installed 80(e.g., one with the system, and one, newer, by you), you will not 81necessarily get a compilation/linking error if a wrong library is 82used (e.g., because LD_LIBRARY_PATH has not been set correctly). 83But unexpected results may occur. 84 85Under Mac OS X, if the shared library was not installed and you use 86Apple's linker (this is the default), you will also need to provide 87the -search_paths_first linker flag ("-Wl,-search_paths_first" when 88you link via gcc) to make sure that the right library is selected, 89as by default, Apple's linker selects a shared library preferably, 90even when it is farther in the library paths. We recall that if a 91wrong library is selected due to this behavior, unexpected results 92may occur. 93 94 95Building the documentation 96========================== 97 98To build the documentation in various formats, you may first need to 99install recent versions of some utilities such as texinfo. 100 101* Type "make info" to produce the documentation in the info format. 102 103* Type "make pdf" to produce the documentation in the PDF format. 104 105* Type "make dvi" to produce the documentation in the DVI format. 106 107* Type "make ps" to produce the documentation in the Postscript format. 108 109* Type "make html" to produce the documentation in the HTML format 110 (in several pages); if you want only one output HTML file, then 111 type "makeinfo --html --no-split mpfr.texi" instead. 112 113 114Building MPFR with internal GMP header files 115============================================ 116 117MPFR built with internal GMP header files is a bit faster, so you may want 118to build it with them. Just do this in step 1: 119 120 ./configure --with-gmp-build=GMPBUILD 121 122where GMPBUILD is the GMP build directory. The needed header files are: 123gmp-impl.h, longlong.h and all the necessary headers to use them. 124 125As gmp-impl.h and longlong.h are only in the GMP source directory, 126you first need to copy these files to the build directory if it is 127different (there may be other workarounds, such as setting $CPPFLAGS 128to search the GMP source directory). 129 130Warning: the library obtained in this way may use some internal GMP 131symbols, and thus dynamically linking your software with a different 132version of GMP might fail, even though it is declared as compatible 133by Libtool's versioning system. 134 135 136Tuning MPFR 137=========== 138 139For this, you need to build MPFR with a GMP build directory (see above). 140In the GMP build directory, you also need to go into the "tune" subdirectory 141and type "make speed". This will build the GMP speed library, which is used 142by the MPFR tuning mechanism. 143 144Then go back to the MPFR build directory, and type "make tune". This will 145build an optimized file "mparam.h" for your specific architecture. 146 147 148./configure options 149=================== 150 151--prefix=DIR installs MPFR headers and library in DIR/include and 152 DIR/lib respectively (the default is "/usr/local"). 153 154--with-gmp-include=DIR assumes that DIR contains gmp.h 155--with-gmp-lib=DIR assumes that DIR contains the GMP library 156--with-gmp=DIR assumes that DIR is where you have installed GMP. 157 same as --with-gmp-lib=DIR/lib 158 and --with-gmp-include=DIR/include 159 (use either --with-gmp alone or one or both of 160 --with-gmp-lib/--with-gmp-include) 161 Warning! Do not use these options if you have 162 CPPFLAGS and/or LDFLAGS containing a -I or -L 163 option with a directory that contains a GMP 164 header or library file, as these options just 165 add -I and -L options to CPPFLAGS and LDFLAGS 166 *after* the ones that are currently declared, 167 so that DIR will have a lower precedence. Also, 168 this may not work if DIR is a system directory. 169 170--with-gmp-build=DIR assumes that DIR contains the GMP build directory, 171 and enables the use of GMP internals (see above). 172 Warning! This option and the group of options 173 --with-gmp are mutually exclusive. 174 175--enable-assert build MPFR with assertions. 176 177--enable-thread-safe build MPFR as thread safe, using compiler-level 178 Thread Local Storage (TLS). Note: TLS support is 179 roughly tested by configure. If configure detects 180 that TLS does not work (because of the compiler, 181 linker or system libraries), it will output an 182 error message, telling you to build MPFR without 183 thread safe. For instance, though Mac OS X uses 184 GCC, it may not currently support GCC's __thread 185 storage class. 186 187Note: By default, the configure script tries to set CC/CFLAGS to GMP's 188ones (this feature needs GMP 4.3.0 or later, or the --with-gmp-build 189option). However this is not guaranteed to work as the configure script 190does some compiler tests earlier, and the change may be too late. Also, 191the values obtained from GMP may be incorrect if GMP has been built 192on a different machine. In such a case, the user may need to specify 193CC/CFLAGS as explained below. 194 195Run "./configure --help" to see the other options (autoconf default options). 196 197 198In case of problem 199================== 200 201First, look for any warning message in the configure output. 202 203Several documents may help you to solve the problem: 204 * this INSTALL file, in particular information given below; 205 * the FAQ (either the FAQ.html file distributed with MPFR, or the 206 on-line version <http://www.mpfr.org/faq.html>, which may be more 207 up-to-date); 208 * the MPFR web page for this version <http://www.mpfr.org/mpfr-3.0.1/>, 209 which lists bugs found in this version and provides some patches. 210 211If the "configure" fails, please check that the C compiler and its 212options are the same as those for the GMP build (specially the ABI). 213You can see the latter with the following command: 214 215 grep "^CC\|^CFLAGS" GMPBUILD/Makefile 216 217if the GMP build directory is available. Then type: 218 219 ./configure <configure options> CC=<C compiler> CFLAGS="<compiler options>" 220 221(quotes are needed when there are spaces or other special characters 222in the CC/CFLAGS value) and continue the install. On some platforms, 223you should provide further options to match those used by GMP, or set 224some environment variables. For instance, see the "Notes on AIX/PowerPC" 225section below. 226 227Warning! Do NOT use optimization options that can change the semantics 228of math operations, such as GCC's -ffast-math or Sun CC's -fast. 229Otherwise conversions from/to double's may be incorrect on infinities, 230NaN's and signed zeros. Since native FP arithmetic is used in a few 231places only, such options would not make MPFR faster anyway. 232 233On some platforms, try with "gmake" (GNU make) instead of "make". 234Problems have been reported with the Tru64 make. 235 236If the configure script reports that gmp.h version and libgmp version 237are different, or if the build was OK, but the tests failed to link 238with GMP or gave an error like 239 240 undefined reference to `__gmp_get_memory_functions' 241 242meaning that the GMP library was not found or a wrong GMP library was 243selected by the linker, then your library search paths are probably 244not correctly set (some paths are missing or they are specified in an 245incorrect order). 246 247Such problems commonly occur under some GNU/Linux machines, where the 248default header and library search paths may be inconsistent: GCC is 249configured to search /usr/local/include and /usr/local/lib by default, 250while the dynamic linker ignores /usr/local/lib. If you have a GMP 251version installed in /usr (provided by the OS vendor) and a new one 252installed in /usr/local, then the header of the new GMP version and 253the library of the old GMP version will be used! The best solution 254is to make sure that the dynamic linker configuration is consistent 255with GCC's behavior, for instance by having /usr/local/lib in 256/etc/ld.so.conf or in some file from /etc/ld.so.conf.d (as Debian 257did: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=395177). See 258also http://gcc.gnu.org/ml/gcc-help/2010-01/msg00171.html for more 259information. Alternatively you can use: 260 * environment variables. This may sometimes be necessary. If DIR 261 is the installation directory of GMP, add DIR/include to your 262 CPATH or C_INCLUDE_PATH (for compilers other than GCC, please 263 check the manual of your compiler), and add DIR/lib to your 264 LIBRARY_PATH and LD_LIBRARY_PATH (and/or LD_RUN_PATH); 265 * --with-gmp* configure options (described above), e.g. 266 --with-gmp=/opt/local (to use /opt/local/include for headers and 267 /opt/local/lib for libraries), but other software that uses GMP 268 and/or MPFR will need correct paths too, and environment variables 269 allow one to set such search paths in a global way. 270 Note about "--with-gmp=/usr/local". This option may appear to 271 solve the above inconsistency problem, but does not work as you 272 expect. Indeed it affects the library search path, in particular, 273 the one used by the dynamic linker (thus adding the missing 274 /usr/local/lib directory as wanted), but since /usr/local/include 275 is a "standard system include directory" for GCC, the include 276 search patch is not changed; this is often not a problem in this 277 particular case because usually, /usr/local/include is already 278 last in the include search patch, but this may fail under some 279 occasions and may trigger obscure errors. 280 281For instance, under Unix, where paths are separated by a colon: 282 283 * With POSIX sh-compatible shells (e.g. sh, ksh, bash, zsh): 284 export C_INCLUDE_PATH="/usr/local/include:/other/path/include" 285 export LIBRARY_PATH="/usr/local/lib:/other/path/lib" 286 export LD_LIBRARY_PATH="$LIBRARY_PATH" 287 288 * With csh or tcsh: 289 setenv C_INCLUDE_PATH "/usr/local/include:/other/path/include" 290 setenv LIBRARY_PATH "/usr/local/lib:/other/path/lib" 291 setenv LD_LIBRARY_PATH "$LIBRARY_PATH" 292 293If you can't solve your problem, you should contact us at <mpfr@loria.fr>, 294indicating the machine and operating system used (uname -a), the compiler 295and version used (gcc -v if you use gcc), the configure options used if 296any (including variables such as CC and CFLAGS), the version of GMP and 297MPFR used, and a description of the problem encountered. Please send us 298also the log of the "configure" (config.log). 299 300Note that even if you can build MPFR with a C++ compiler, you can't run 301the test suite: C and C++ are not the same language! You should use a C 302compiler instead. 303 304 305Notes on Mac OS X 306================= 307 308If you get an error of the form 309 310 ld: pointer in read-only segment not allowed in slidable image... 311 312this can mean that the link is done against a static (GMP) library. 313In such a case, you should configure MPFR with --disable-shared to 314disable the build of the shared library. 315 316 317Notes on FreeBSD 4.3 318==================== 319 320FreeBSD 4.3 is provided with an incorrect <float.h> header file, and 321MPFR tests related to long double's may fail. If you cannot upgrade 322the system, you can still use MPFR with FreeBSD 4.3, but you should 323not use conversions with the long double type. 324 325 326Notes on AIX/PowerPC 327==================== 328 329The following has been tested on AIX 5.3 (powerpc-ibm-aix5.3.0.0) with 330gcc 3.3.2 and GMP 4.2.1. 331 332If GMP was built with the 64-bit ABI, before building and testing MPFR, 333you should set the OBJECT_MODE environment variable to 64, e.g., with: 334 335 export OBJECT_MODE=64 336 337(in a sh-compatible shell). But you should also provide a correct CFLAGS 338value to the "configure" script: using --with-gmp-build is not sufficient 339due to the early compiler tests, as gcc will not compile any program if 340OBJECT_MODE is 64 and the -maix64 option is not provided. 341 342 343Notes on 32-bit Windows Applications (win32) 344============================================ 345 3461 - We advise to use MinGW (http://www.mingw.org/), which is simpler and 347 less demanding than Cygwin. Contrary to Cygwin, it also provides native 348 Windows code. The binaries compiled with Cygwin require a dynamic 349 library (cygwin.dll) to work; there is a Cygwin option -mno-cygwin to 350 build native code, but it may require some non-portable tricks. 351 3522 - If you just want to make a binary with gcc, there is nothing to do: 353 GMP, MPFR and the program compile exactly as under Linux. 354 But if you want to generate a library for MinGW from a Cygwin 355 environment, you may need the -mno-cygwin gcc option (otherwise 356 a typical error is _P_WAIT being undeclared). 357 3583 - If you want to make libraries to work under another Windows compiler 359 like Visual C / C++, you have two options. Since the unix-like *.a 360 library files are compatible with Windows *.lib files, you can simply 361 rename all *.a libraries to *.lib. The second option is to build 362 MPFR with the Microsoft Visual Studio compiler to produce Windows 363 libraries directly (Visual Studio build projects for MPFR are 364 available at http://fp.gladman.plus.com/computing/gmp4win.htm). 365 366 With gmp-4.1.3, the only remaining problem seems to be the "alloca" calls 367 in GMP. Configuring GMP and MPFR with --enable-alloca=malloc-reentrant 368 should work (if you build MPFR with GMP internal files). 369 370 Or you could add the library 371 "$MINGWIN$/lib/gcc-lib/mingw32/$VERSION$/libgcc.a" 372 to your project: it contains all the extra-functions needed by a program 373 compiled by gcc (division of 64-bit integer, bcopy, alloca...). 374 Of course, include it if and only if your compiler is not gcc. 375 3764 - On Windows32 / MinGW, if all the tests fail, try to run the test suite 377 with "make check EXEEXT=". 378 3795 - To avoid using the Microsoft runtime (which might not be conform to ISO C), 380 you can use the MinGW runtime package (which is an integral part of MinGW). 381 For example, with MinGW versions 3.15 and later you can get an 382 ISO-compliant printf() if you compile your application with either 383 '-ansi', '-posix' or '-D__USE_MINGW_ANSI_STDIO'. For example, you can 384 compile and test MPFR with CC="gcc -D__USE_MINGW_ANSI_STDIO". 385 386 For example under Win32, the following problem has been experienced with 387 MPFR 2.4.0 RC1 and the MSVC runtime (msvcrt.dll): 388 389 Error in mpfr_vsprintf (s, "%.*Zi, %R*e, %Lf%n", ...); 390 expected: "00000010610209857723, -1.2345678875e+07, 0.032258" 391 got: "00000010610209857723, -1.2345678875e+07, -0.000000" 392 FAIL: tsprintf.exe 393 394 This error is due to the MSVC runtime not supporting the L length modifier 395 for formatted output (e.g. printf with %Lf). You can check this with the 396 following program: 397 398 #include <stdio.h> 399 int main (void) 400 { 401 long double d = 1. / 31.; 402 printf ("%Lf\n", d); 403 return 0; 404 } 405 406 The expected output is 0.032258. 407 408 Note: The L modifier has been standard for a long time (it was added 409 in ISO C89). 410 411 412Notes on 64-bit Windows Applications (x64) 413========================================== 414 415[See the Notes on 32-bit Windows Applications, which might be relevant here, 416 in particular when running a 64-bit operating system] 417 418Cygwin and MinGW do not yet offer support for native Windows 64 builds but 419the 32-bit version of MPFR can be used to build 32-bit applications that 420will run on 64-bit Windows systems (see above). MPFR can be built as a native 42164-bit static or DLL library for Windows 64 using the Visual Studio build 422projects at http://fp.gladman.plus.com/computing/gmp4win.htm. 423