1Copyright 2002-2023 Free Software Foundation, Inc. 2Contributed by the AriC and Caramba 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 18https://www.gnu.org/licenses/ or write to the Free Software Foundation, Inc., 1951 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. 20 21 22Notes for the MPFR developers and Git users 23=========================================== 24 25To compile the source code obtained from the repository or after applying 26some special patches, you need some additional GNU development utilities: 27aclocal, autoheader, automake, autoconf 2.60 (at least), and libtoolize. 28The AX_PTHREAD macro from autoconf-archive[*] is now included in the MPFR 29repository (m4/ax_pthread.m4). 30[*] https://www.gnu.org/software/autoconf-archive/ax_pthread.html 31 32As some files like "configure" are not part of the Git repository, you 33first need to run "autoreconf -i" (or ./autogen.sh, which could be used 34later to update the config files). Then you can run ./configure in the 35usual way (see the INSTALL file, but note that there are no patches to 36apply, and the URLs are not valid since the corresponding version has 37not been released yet). 38 39To generate mpfr.info, you need texinfo version 4.2 (or higher). 40 41=========================================================================== 42 43The VERSION file contains the number of the next release version, i.e. 44the version currently being developed. A suffix can be attached for the 45development versions (in general, "-dev") or pre-release versions (e.g. 46"-rc1"). It must be updated with the update-version script. Examples: 47 48 tools/update-version 3 1 0 dev 49 tools/update-version 3 1 0 rc1 50 tools/update-version 3 1 0 51 52The "-dev" suffix means that additional tests may be done or required 53for development. For instance, the data files from the tests/data 54directory are required; such files are not included in tarballs as 55they can be large. 56 57If nightly snapshots are built, the date in the yyyymmdd format and/or 58some Git information (for more accurate information) must be added to 59the version as a suffix, for instance: "2.3.0-20070621". 60 61Patches can be tracked by adding a chunk of the form 62 63--- PATCHES~ Tue Nov 6 19:59:33 2001 64+++ PATCHES Tue Nov 6 19:59:42 2001 65@@ -1,0 +1 @@ 66+<your-id-here> 67 68to the patch file[*]. After such patches have been applied, the file 69src/get_patches.c providing the mpfr_get_patches() function will be 70rebuilt by "make". MPFR distributors can still modify the version 71suffix from the applied patches according to their version naming 72scheme; for instance, for their own patches, MPFR developers do: 73 74 tools/update-version 3 1 0 p1 - 75 76[*] This idea comes from Thomas Roessler, who implemented it in Mutt. 77 78For patches from MPFR developers, e.g. for MPFR 3.1.0: 791. Unarchive the tarball: a directory mpfr-3.1.0 is created. 802. Go into this directory (cd mpfr-3.1.0). 813. Apply the current patches with "patch -N -Z -p1 < /path/to/allpatches". 824. Reset the PATCHES file with "true >| PATCHES". 835. Rename mpfr-3.1.0 as mpfr-3.1.0-a and duplicate it as mpfr-3.1.0-b 84 without changing the timestamps (e.g. with cp -a). 856. In mpfr-3.1.0-b, apply the patch obtained with "git diff", e.g. 86 patch --no-backup-if-mismatch -p0 < /path/to/new_patch 87 If an autotools file has been modified, run "autoreconf" and remove 88 the autom4te.cache directory. 897. In mpfr-3.1.0-b, update the version information: 90 tools/update-version 3 1 0 p<n> - 91 where <n> is the patch number. 928. In mpfr-3.1.0-b, update PATCHES file: echo >> PATCHES <patch_name> 939. Make the patch: TZ=UTC0 diff -Naurd mpfr-3.1.0-a mpfr-3.1.0-b 94 95The tools/build-patch script can be used to ease the process. 96 97Note: if autotools files are modified, the corresponding changes in the 98distributed files depending on them must be included in the patch, and 99the timestamps of such autotools files should be reset so that they do 100not change when the patch is applied with the -Z option. Otherwise the 101autotools would be needed to build MPFR (unless maintainer mode is 102disabled). 103 104Patches are put under the www directory of the misc.git repository for 105the MPFR website. 106 107=========================================================================== 108 109When submitting patches, unified diffs (option -u) are recommended, 110as they are more readable. You can also use the option -d to generate 111a smaller set of changes. See diff(1) for more information. 112 113=========================================================================== 114 115Copyright Notices: For easier maintainability, make sure that the 116copyright notices match the regexp "Copyright.* yyyy Free Software" 117where yyyy is the year of the latest modification in the branch 118(and nothing else should match it). 119 120The latest rules for GNU software can be found here: 121 122 https://www.gnu.org/prep/maintain/maintain.html#Copyright-Notices 123 124=========================================================================== 125 126To make a release (for the MPFR team): 127 128 *** Please read this section entirely before making any release. *** 129 130 0) For a non-patchlevel release, before creating a branch from master 131 (or more often), some operations should be done in master: 132 * update the doc/texinfo.tex file from a recent version, and check 133 whether this yields unwanted changes in the MPFR manual generated 134 in the main formats (HTML, info, PDF); 135 * make sure that the src/mpfr-longlong.h file (from GMP's longlong.h) 136 is up-to-date (updates could also be done in patchlevel releases, 137 but with care); 138 * among the checks below, those that are most likely to notice issues, 139 as it is easy to forget something; 140 * in particular, check that the abi-compliance-checker output, 141 the "API Compatibility" section of the manual (mpfr.texi), and 142 the NEWS file are consistent; 143 * update the libtool version (see src/Makefile.am) and the DLL version 144 (see configure.ac) if need be, though this should have been done as 145 soon as the ABI changed in the master branch; 146 * update the ChangeLog (see below) in the master branch, in order to 147 minimize the future diffs. 148 If everything is OK, create the branch (below designated <branch>). 149 Switch to the branch and create an annotated tag <branch>-root on HEAD: 150 "New <branch> branch from master." 151 This tag should be placed on the parent of the first commit specific to 152 the branch; it could also be added later; its id should be the same as 153 the one output by "git merge-base master <branch>". 154 In the master branch, update the version with the update-version 155 script to indicate the next version (use the "dev" suffix). 156 Note: Not everything can be done in master before creating the branch, 157 as this step may be done much time before the release candidate, with 158 the goal of a feature freeze. 159 160 1) Check the version and change the suffix to "rc1", "rc2", etc. with 161 tools/update-version for the release candidates; remove the suffix 162 for the final release. 163 If not done yet, update the libtool version (see src/Makefile.am) 164 and the DLL version (see configure.ac). 165 Update the README file if need be: the list of the distributed files 166 and the URL of the README.dev file (use the right branch). 167 Check these versions with tools/ck-version-info (this check will also 168 be done automatically by "make dist" / "make distcheck"). 169 Update the date in doc/mpfr.texi. 170 171 2) Generate the tuning parameters on different architectures and 172 put them in src/mparam_h.in. For each architecture: 173 174 a) download the latest release of GMP on gmplib.org 175 b) build GMP with --disable-shared in, say, "/path/to/gmp-x.y.z". 176 There is no need in tuning GMP, since most users will build MPFR 177 with a vanilla GMP installation, i.e., with the default GMP tuning; 178 however, you need to go into /path/to/gmp-x.y.z/tune and type 179 "make speed" (the MPFR tuning is using the resulting speed library) 180 c) configure MPFR with 181 --disable-shared --with-gmp-build=/path/to/gmp-x.y.z 182 d) go into the "tune" directory and run "make tune" 183 e) put the resulting mparam.h file into mparam_h.in (please include 184 the version of GMP and the compiler used) 185 186 You can produce time graphs to check the thresholds are correct (and 187 compare to the corresponding mpf functions) with mbench. For example 188 (-x1 corresponds to add, -x2 to sub, -x3 to mul, ...): 189 190 $ cd mpfr/tools/mbench 191 $ make mpfr-gfx GMP=... MPFR=... 192 $ ./mpfr-gfx -b16 -e320 -s16 -f2 -x3 # compares mpfr_mul and mpf_mul 193 # from 16 to 320 bits with increment 194 # of 16 bits 195 $ gnuplot -persist plot.gnuplot 196 197 Another example, comparing mpfr_mul and mpf_mul from 2 to 1000000 bits, 198 with ratio 1.1 between two sizes, 10 random values, and 10 smoothness 199 checks: 200 201 $ ./mpfr-gfx -b2 -e1000000 -r1.1 -f10 -x3 -m10 202 $ gnuplot -persist plot.gnuplot 203 204 Check the coverage of each source file by the test suite is at least 90% 205 (or clearly justify any value under this threshold), and publish (for 206 example in NEWS) the global coverage of this release. The individual 207 coverage of each source file might also be published on the release web 208 page. There is a specific mparam.h file to improve coverage; it should 209 be tested by configuring MPFR with -DMPFR_TUNE_COVERAGE. 210 211 Also test with -DMPFR_COV_CHECK, which allows one to check the coverage 212 of some combinations of variable values (as defined in the MPFR source 213 and test suite). 214 215 3) Update the NEWS file, in particular say if the release is binary 216 and/or API compatible (or not) with previous releases. 217 Also update the "API Compatibility" section in the manual (mpfr.texi). 218 Cherry-pick these changes in the master branch. 219 Check with abi-compliance-checker (ABI Compliance Checker)[a] against 220 the previous MPFR release (built with no configure options, except 221 --prefix) that no changes have been missed. The build-multi script 222 in the misc.git repository[b] may be useful to prepare data for 223 abi-compliance-checker (for the version to be released, a temporary 224 tarball thus needs to be generated, e.g. with "make dist"). 225 Example of use for the 4.1.1 release candidate: 226 $ make distcheck 227 $ mkdir ~/tmp/abicc 228 $ /path/to/build-multi ~/tmp/abicc \ 229 /path/to/mpfr-4.1.0.tar.xz mpfr-4.1.1-rc1.tar.xz 230 $ cd ~/tmp/abicc 231 $ abi-compliance-checker -lib mpfr -old 4.1.0.xml -new 4.1.1-rc1.xml 232 Note that abi-compliance-checker can check only the symbols, types 233 and constants; it cannot detect just a change in the behavior, thus 234 may miss some incompatibilities. 235 Update the FAQ.html file with update-faq (and check it) in the doc 236 directory. 237 [a] https://lvc.github.io/abi-compliance-checker/ 238 [b] https://gitlab.inria.fr/mpfr/misc/-/blob/master/build-multi 239 240 4) Update the ChangeLog file with "make update-changelog" in UTF-8 locales. 241 This should at least be done last, in order to be complete before the 242 generation of the tarball. 243 Note: First, make sure that all the pending commits have been done. 244 Push the changes with "git push". 245 246 5) Create an annotated tag whose name corresponds to the content of 247 the VERSION file: 248 $ tag=$(cat VERSION) 249 $ git tag -m "GNU MPFR $tag tag." $tag 250 and push it: 251 $ git push origin $tag 252 Note: in case of error, see the git-tag(1) man page. 253 254 6) Export the tree identified by this tag in order to get a tarball: 255 $ ./tools/export-release $(cat VERSION) /path/to/some/dir 256 A mpfr-$tag subdirectory will be created there; each file or directory 257 has a timestamp corresponding to its last change. 258 From this directory, generate the tarballs with: 259 $ ./autogen.sh 260 $ ./configure 261 $ make distcheck 262 If need be, after "./autogen.sh", replace config.guess and config.sub 263 by their latest version (see URLs in these files), e.g. if they are 264 known to solve issues. But note that they may not have been fully 265 tested. 266 267 7) Test the release version on different machines, with --enable-assert 268 set to "yes", "no" (default), "none" and "full" respectively, with 269 and without -DMPFR_DISABLE_IEEE_FLOATS in $CFLAGS, with and without gmp 270 internal files (--enable-gmp-internals), with and without GMP built as 271 a shared library, with objdir equal to and different from srcdir (e.g. 272 ../mpfr-source/configure after making mpfr-source read-only), with 273 and without --enable-logging. 274 275 Try different temporary allocation methods: GMP's --disable-alloca 276 configure option (or compile GMP with --enable-alloca=debug and MPFR 277 with --with-gmp-build to be able to get the memory leak errors); and 278 -DMPFR_ALLOCA_MAX=0. 279 280 Try different gcc versions with different options: with and without 281 "-std=c99 -O3 -D_XOPEN_SOURCE=500", with and without "-ansi" (which 282 allows to turn off features that are incompatible with ISO C90), 283 with and without [-ansi] -pedantic-errors (which has the effect to 284 disable extensions, such as long long when used together with -ansi), 285 with and without -std=c11, with and without --enable-thread-safe, in 286 various FPU precisions (double, double extended and single) if the 287 platform supports that (e.g. under Linux/x86, with GCC and its -mpc64 288 option to simulate the FreeBSD / NetBSD 6- behavior, where by default, 289 the x87 FPU is configured to round on 53 bits), and in various locales 290 (LC_ALL=tr_TR in particular, if installed). 291 On x86, test with -m96bit-long-double and -m128bit-long-double. 292 Try also with gcc's -fno-common option. 293 Check also with "-Wformat=2", but without logging support (in order 294 to avoid too many spurious warnings). 295 Check with "-UHAVE_BIG_ENDIAN -UHAVE_LITTLE_ENDIAN" to simulate 296 platforms where the endianness is unknown (or can't be specified 297 without AC_CONFIG_HEADERS). 298 Check also without the mpz_t pool (-DMPFR_POOL_NENTRIES=0). 299 Check the generic code, e.g. with -DMPFR_GENERIC_ABI in $CFLAGS 300 (useful because most tests are written for low precision) and with 301 mpfr_cv_c_long_double_format=unknown (as a variable assignment). 302 Check with -DMPFR_GROUP_STATIC_SIZE=0 to detect memory leaks that would 303 occur in medium precision or more if a MPFR_GROUP_CLEAR were forgotten. 304 305 Check that make and make check pass with a C++ compiler, for example: 306 ./configure CC=g++ (MPFR 2.3.2 did not). 307 Also test --enable-gmp-internals with it. 308 309 Try different compilers, e.g., icc, opencc (x86_64 machines), 310 tcc <https://bellard.org/tcc/>, llvm-gcc, clang. 311 312 On 64-bit PowerPC, test against GMP built with the different ABI's: 313 32, mode32 and mode64 (in particular mode32, where long's have 314 32 bits and limbs have 64 bits [long long]). 315 316 Test with -DMPFR_TESTS_FPE_DIV -DMPFR_ERRDIVZERO 317 -DMPFR_DISABLE_IEEE_FLOATS in order 318 to detect whether tests can fail due to a FP division by 0 (yielding 319 either FE_DIVBYZERO, e.g. from 1.0 / 0.0 to generate an infinity, or 320 FE_INVALID, e.g. from 0.0 / 0.0 to generate a NaN) on platforms where 321 such an operation fails (e.g. trap). On platforms that do not support 322 IEEE 754, such an operation yields an undefined behavior. 323 If _MPFR_IEEE_FLOATS is defined to 1 (by the configure script), some 324 divisions by 0 are avoided in the MPFR library. 325 The -DMPFR_DISABLE_IEEE_FLOATS option sets _MPFR_IEEE_FLOATS to 0, 326 allowing one to detect more issues, for platforms without IEEE floats. 327 328 Test with -D_MPFR_PREC_FORMAT=2 when the "int" type is smaller 329 than the "long" type. 330 331 Test with mini-gmp. 332 333 Test with valgrind by setting the environment variable: 334 LOG_COMPILER="valgrind -q --error-exitcode=1 --leak-check=full" 335 See below for more information about valgrind. 336 337 Test with "clang -fsanitize=undefined" (available as of Clang 3.3), 338 e.g.: ./configure CC=clang CFLAGS='-fsanitize=undefined' 339 The -fno-sanitize-recover option can give more visibility by making 340 the corresponding tests fail (useful for automated tests). However, 341 clang unconditionally regards the floating-point division by zero 342 as an error with "-fsanitize=undefined"; this is detected by a 343 configure test, which sets MPFR_ERRDIVZERO to disable the tests 344 involving a floating-point division by zero. Alternatively, on systems 345 supporting IEC 60559 / IEEE 754 division by zero, one can also provide 346 the -fno-sanitize=float-cast-overflow,float-divide-by-zero option 347 *after* the -fsanitize=undefined one. 348 349 GCC 4.9 also supports "-fsanitize=undefined", but it just gives 350 diagnostic messages at run time, not a failure; GCC 5 supports 351 -fno-sanitize-recover like clang. 352 353 Test with GCC's AddressSanitizer (-fsanitize=address). Optimizations 354 should not be enabled, otherwise they can make some errors disappear. 355 One also needs to unset LD_PRELOAD or use -static-libasan to avoid 356 failures. But the -static-libasan solution does not work with MPFR, 357 as it yields the following error: 358 Your application is linked against incompatible ASan runtimes. 359 360 Test with i686-w64-mingw32 under Wine (see below). 361 362 Test with both "make check" and the worst cases. 363 364 Check various warnings, in particular for obsolescent features. 365 With GCC: "-Wall -Wold-style-declaration -Wold-style-definition 366 -Wmissing-parameter-type -Wmissing-prototypes -Wmissing-declarations 367 -Wmissing-field-initializers". The -Wint-in-bool-context option 368 could be added once available. These warnings can easily be checked 369 in automatic tests by adding "-Werror". Add -Wno-error=... options 370 when needed (but except in some cases, it may be better to improve 371 the MPFR code; in particular, the -Wno-error=unused-function option 372 should no longer be necessary, thanks to conditional compilation or 373 MPFR_MAYBE_UNUSED). 374 375 Check whether some functions could be declared as pure, const, etc. 376 with GCC, using -Wsuggest-attribute=... options. 377 378 Check that there are no abnormal regressions in the timings (both for 379 100, 1000, 10000 digits, https://www.mpfr.org/mpfr-current/timings.html, 380 and for small precision, using the mbench program, see tools/mbench). 381 382 Test the library interface compatibility by running the test suite 383 compiled against an old library version and dynamically linked with 384 the new library version: for instance, build the shared library of 385 old and new MPFR versions with the same configure options, and from 386 the build directory of the old version, do something like: 387 (cd src/.libs && \ 388 ln -nsf ../../../mpfr-new/src/.libs/libmpfr.so.1.* libmpfr.so.1) 389 then "make check". 390 391 Also test with different environment variables set 392 (GMP_CHECK_RANDOMIZE, MPFR_CHECK_LIBC_PRINTF, MPFR_CHECK_LARGEMEM, 393 MPFR_CHECK_EXPENSIVE, MPFR_SUSPICIOUS_OVERFLOW, MPFR_CHECK_LOCALES, 394 MPFR_CHECK_BADCASES). 395 Note: a non-default GMP_CHECK_RANDOMIZE value allows one to make sure 396 that a test against a hard-coded result does not depend on it. 397 398 Check there is no branch misprediction due to wrong MPFR_LIKELY or 399 MPFR_UNLIKELY statements. For that test, configure with 400 --enable-debug-prediction, run "timings-mpfr 100", and check that 401 the output contains no WARNING. 402 403 For various platforms and compilers, check that: 404 * [make check-gmp-symbols] 405 MPFR does not use GMP internal symbols (unless --with-gmp-build 406 or --enable-gmp-internals has been used); 407 * [make check-exported-symbols] 408 MPFR does not define symbols with a GMP reserved prefix. 409 But note that these rules are not really portable: they may do 410 nothing or might even incorrectly fail on some platforms. 411 412 8) For the release itself (not the release candidates), update the 413 version with the update-version script in the Git repository to 414 indicate the next patchlevel version (use the "dev" suffix). 415 Increase the 2nd number of the libtool version (see src/Makefile.am) 416 for the next patchlevel version. 417 418 9) * For the release itself (not the release candidates): 419 Create a web page for the MPFR release and add the documentation 420 (for mpfr.html, use "makeinfo --html --no-split mpfr.texi" from 421 the doc directory). Make sure that both the .dvi and .ps files 422 have an a4 papersize (see technical information later about the 423 MPFR manual). 424 Upload the tarballs and the signatures to the MPFR web server 425 (via the misc.git repository). 426 Prepare the files for the GNU FTP site with the gnu-sigdir script 427 of the misc.git repository and upload them. 428 Update the mpfr-current symbolic link and the history page. 429 Update the old current page to point to the new release; see 430 examples for 3.0.1 (latest version of the branch) and 3.1.0 431 (which is not the latest version of the branch). 432 Run the tools/announce-text script to do some checking and get 433 the announce text. Edit this text if need be. 434 Announce the release in the mpfr-announce, mpfr, gmp-discuss, gcc 435 and info-gnu[1] mailing-lists. 436 In case of a new patchlevel release, add a link from the web page 437 of the previous release. 438 439 * For the release candidates: 440 Upload the tarballs and the signatures to the MPFR web server 441 (via the misc.git repository). 442 Run the tools/announce-text script to do some checking and get 443 the announce text. Edit this text if need be. 444 Announce the RC in the mpfr-announce, mpfr, gmp-discuss, gcc and 445 platform-testers[2] mailing-lists. 446 A minimal web page for the MPFR release can be created right now 447 (see Git history such as [3] for examples), as the manual already 448 contains the new URLs. 449 450 [1] https://www.gnu.org/prep/maintain/html_node/Announcements.html 451 [2] See https://lists.gnu.org/mailman/listinfo/platform-testers and 452 https://lists.gnu.org/archive/html/platform-testers/2011-09/msg00000.html 453 [3] commit a04e43bb98b916c354f15d7e88b2934f84d0a6ab of misc.git 454 i.e. https://gitlab.inria.fr/mpfr/misc/-/commit/a04e43bb 455 456Note: Mail sent to the mpfr-announce list should also be sent to 457the mpfr list, and the Reply-To should be set to the mpfr list. 458 459For major or minor releases (but not patchlevels), a new branch may be 460created first to allow new features to be committed to master. 461 462To add tcc support with libtool 2.4.2 or below, do the following before 463running "make distcheck": 464$ patch m4/libtool.m4 libtool-tcc-wl.patch 465$ autoreconf 466 467And for libtool 2.4.3 to 2.4.6, the following is needed: 468$ patch m4/libtool.m4 libtool-tcc-rpath.patch 469$ autoreconf 470 471=========================================================================== 472 473Here is a non-exhaustive list of macros used for building and checking MPFR. 474Most of them are automatically set up by the configure script and its options. 475 476List of macros used for building MPFR (also used for checking): 477 478+ HAVE_CONFIG_H: Define if we have to include 'config.h' first. 479+ MPFR_HAVE_GMP_IMPL: Define if we have the gmp internal files. 480 ('gmp-impl.h', 'gmp-maparam.h', ...). 481+ MPFR_USE_MINI_GMP: Define to use mini-gmp. 482 483+ HAVE_ALLOCA: Define if alloca() works. 484+ HAVE_ALLOCA_H: Define if the function alloca() is in alloca.h. 485+ HAVE_LOCALE_H: Define if <locale.h> is available. 486+ HAVE_LONG_LONG: Define if the system supports 'long long'. 487 488+ HAVE_STDARG: Define if the system supports 'stdarg.h'. 489 Otherwise it is assumed it is 'vararg.h'. 490 491+ HAVE_INTTYPES_H: Define if <inttypes.h> is available (ISO C99). 492+ HAVE_STDINT_H: Define if <stdint.h> is available (ISO C99). 493+ MPFR_HAVE_INTMAX_MAX: Define if the INTMAX_MAX macro works correctly 494 (if 'intmax_t' is supported). 495 496+ MPFR_HAVE_C11_LOCK: Define if C11 threads are supported. 497+ HAVE_PTHREAD: Define if pthread is available. 498 499Format of long double. 500+ HAVE_LDOUBLE_IS_DOUBLE: IEEE double. 501+ HAVE_LDOUBLE_IEEE_EXT_BIG: IEEE extended, big endian. 502+ HAVE_LDOUBLE_IEEE_EXT_LITTLE: IEEE extended, little endian. 503+ HAVE_LDOUBLE_IEEE_QUAD_BIG: IEEE quad, big endian. 504+ HAVE_LDOUBLE_IEEE_QUAD_LITTLE: IEEE quad, little endian. 505+ HAVE_LDOUBLE_MAYBE_DOUBLE_DOUBLE: Double-double (a.k.a. IBM). 506 507+ MPFR_DISABLE_IEEE_FLOATS: 508 Related to the native floating-point types (e.g. 509 for conversion functions), use the generic code 510 instead of IEEE 754 specific one. 511 Note: This is mainly for developers in order to 512 check the generic code, as machines without IEEE 513 floating-point types are very uncommon nowadays. 514+ MPFR_WANT_ASSERT: Assertion level. See src/mpfr-impl.h for details. 515+ MPFR_EXP_CHECK: Define if we want to check the exp field. 516 517+ _MPFR_PREC_FORMAT: Used to define the mpfr_prec_t type. 518+ _MPFR_EXP_FORMAT: Used to define the mpfr_exp_t type. 519 Note: these two macros are for internal use, 520 testing and experimented users only; they must 521 not be changed when the MPFR library is to be 522 installed in a system directory. 523 524+ IEEE_DBL_MANT_DIG: Number of bits in the significand (mantissa) of a 525 double (default: 53). 526+ MPFR_LDBL_MANT_DIG: Number of bits in the significand (mantissa) of a 527 long double (generally based on the standard macro 528 LDBL_MANT_DIG). Note: be careful with formats such 529 as double-double (a.k.a. IBM long double). 530 531+ MPFR_USE_LOGGING: Define to enable logging (this needs GCC, and this 532 is not available with mini-gmp, since mpfr_fprintf 533 cannot be defined with mini-gmp). 534 535+ MPFR_WANT_DECIMAL_FLOATS: 536 Define to build conversion functions from/to 537 decimal floats. At most one of the following 538 three macros can be defined. 539+ DECIMAL_BID_FORMAT: BID encoding detected or assumed. 540+ DECIMAL_DPD_FORMAT: DPD encoding detected or assumed. 541+ DECIMAL_GENERIC_CODE: Use generic code for decimal floats. 542 543+ MPFR_WANT_FLOAT128: Define to build conversion functions from/to 544 binary128 floats (_Float128 or __float128). 545 546+ MPFR_ALLOCA_MAX: Maximum size for the use of alloca() by temporary 547 allocations (default: 16384); if set to 0, alloca() 548 will not be used, and not even referenced. 549 This macro is not used when MPFR is built with 550 the GMP build directory (--with-gmp-build). 551 552+ MPFR_USE_THREAD_SAFE: Define to build MPFR as thread safe (TLS). 553+ MPFR_USE_C11_THREAD_SAFE: 554 Define to implement TLS in the C11 way. 555 556+ MPFR_WANT_SHARED_CACHE: 557 Define to have caches shared by all threads. 558+ MPFR_THREAD_LOCK_METHOD: 559 When MPFR_WANT_SHARED_CACHE is defined, this macro 560 gives the thread locking method (string). 561 562+ MPFR_HAVE_NORETURN: Define if the _Noreturn function specifier is 563 supported. 564+ MPFR_HAVE_BUILTIN_UNREACHABLE: 565 Define if the __builtin_unreachable GCC built-in is 566 supported. 567 568+ MPFR_GENERIC_ABI: Define to disable code that is tied to a specific 569 ABI (e.g. GMP_NUMB_BITS value). 570 Note: Currently it is also used to disable code 571 specific to low precision, i.e. to use only generic 572 code. This is useful because most tests are written 573 for low precision, meaning that without this macro, 574 the generic code would not sufficiently be tested. 575 576+ MPFR_WANT_PROVEN_CODE: 577 Define to enable formally proven code (used only 578 under some conditions, see below). 579 580List of macros used for checking MPFR: 581 582+ MPFR_HAVE_FESETROUND: Define if the function fesetround() is available 583 (and in header <fenv.h>). 584+ MPFR_FPU_PREC: Allows to test MPFR on x86 processors when the 585 x87 FPU rounding precision has been changed (see 586 tests/tests.c for its usage). 587+ HAVE_SUBNORM_DBL: Define if the double type fully supports subnormals. 588+ HAVE_SUBNORM_FLT: Define if the float type fully supports subnormals. 589+ HAVE_SIGNEDZ: Define if signed zeros are supported. 590+ HAVE_SYS_TIME_H: Define if the header sys/time.h is usable. 591+ HAVE_GETTIMEOFDAY: Define if the function gettimeofday() is available. 592+ HAVE_SETLOCALE: Define if the function setlocale() is available. 593+ MPFR_ERRDIVZERO: Define if the floating-point division by 0 fails 594 in the MPFR library (e.g., because a SIGFPE signal 595 is generated, or because it is regarded as undefined 596 behavior by a sanitizer). This disables the tests 597 involving such operations. 598 Note: Tests related to NaN and infinities must not 599 rely on native FP division by 0, whether this macro 600 is defined or not. 601+ MPFR_TESTS_FPE_DIV: Define to check whether there has been a FP 602 exception FE_DIVBYZERO or FE_INVALID, which 603 probably comes from 1.0 / 0.0 or 0.0 / 0.0 to 604 generate an infinity or a NaN. This is normally 605 used together with MPFR_ERRDIVZERO, in order to 606 check that all divisions by 0 have been protected 607 in the tests (so that tests can pass on platforms 608 where the floating-point division by 0 fails). 609+ MPFR_TESTS_FPE_TRAP: Define to trap the FE_DIVBYZERO and FE_INVALID 610 exceptions; MPFR_TESTS_FPE_DIV needs to be defined 611 too, and MPFR_ERRDIVZERO should be defined as well 612 to avoid spurious traps (see above). 613+ MPFR_TESTS_TIMEOUT: Define to enable timeout in the tests. Its value 614 specifies the default timeout (in seconds), or 0 615 for no timeout by default. When defined, this 616 value can be overridden at run time (e.g., with 617 "make check" or when executing an individual test) 618 with the MPFR_TESTS_TIMEOUT environment variable. 619+ MPFR_TESTS_ABORT: Define to replace exit(1) by abort(), thus with a 620 core dump. 621+ MPFR_COV_CHECK: Define to enable value coverage checking (must not 622 be used in production). This macro is for the MPFR 623 developers, in order to improve the test suite. 624 625=========================================================================== 626 627Environment variables that affect the tests: 628 629+ GMP_CHECK_RANDOMIZE: Seed for the random functions, except for 0 or 1, 630 in which case a random (time based) seed is used. 631 By default, a fixed seed is used. Only developers 632 and testers should change the seed. 633 634+ MPFR_CHECK_LARGEMEM: Define to enable tests that take a lot of memory. 635 636+ MPFR_CHECK_EXPENSIVE: Define to enable tests that take a lot of time. 637 Warning! The --enable-assert=full option should 638 not be used, otherwise this can take much too 639 long. While checking assertions (--enable-assert) 640 may be useful with MPFR_CHECK_EXPENSIVE, the 641 --enable-assert=full is not necessary with it. 642 643+ MPFR_CHECK_LIBC_PRINTF: 644 Define to enable comparisons with the printf 645 function of the C library. These comparisons are 646 disabled by default as failures could be due to 647 the C library itself on some machines, and they 648 do not affect MPFR. 649 650+ MPFR_CHECK_LOCALES: Fail in case a locale cannot be set. Developers 651 can set this variable on their machines to make 652 sure that needed locales are properly installed 653 and tested. 654 655+ MPFR_CHECK_BADCASES: Fail if function bad_cases generates too many 656 cases for which f(f^{-1}(x)) ≠ x, due to a poor 657 choice of the parameters. 658 659+ MPFR_DEBUG_BADCASES: For debugging (see tests.c, function bad_cases). 660 661+ MPFR_SUSPICIOUS_OVERFLOW: 662 Define to check suspicious overflow in the generic 663 tests (tgeneric.c). For developers and testers. 664 665+ MPFR_TESTS_MEMORY_LIMIT: 666 The memory limit for the tests (default is 667 2^22 = 4 MB). Set to 0 for unlimited. 668 669+ MPFR_TESTS_TIMEOUT: When timeout in the tests is enabled, this 670 overrides the value of the macro. 671 672+ MPFR_TGENERIC_STAT: For the generic tests, output the number of normal 673 cases and the total. 674 675=========================================================================== 676 677Before testing any macro (such as HAVE_STDINT_H) in a .c file, one needs: 678 679#ifdef HAVE_CONFIG_H 680# include "config.h" 681#endif 682 683except if mpfr-impl.h (for the library) or mpfr-test.h (for the tests) is 684included first, because these header files already have the above code. 685 686=========================================================================== 687 688The GNU Coding standards can be read at: 689 https://www.gnu.org/prep/standards/ 690 691ISO C Names and corresponding headers: 692 http://www.schweikhardt.net/identifiers.html 693 694The C language: 695 https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf (C99) 696 https://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf 697 https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf (C11 draft) 698 https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3054.pdf (C2x draft) 699 http://home.datacomm.ch/t_wolf/tw/c/c9x_changes.html 700 701About undefined behavior: 702 https://blog.regehr.org/archives/213 703 https://blog.regehr.org/archives/226 704 https://blog.regehr.org/archives/232 705 https://blog.regehr.org/archives/1520 706 https://blog.llvm.org/posts/2011-05-13-what-every-c-programmer-should-know/ 707 708Type punning, strict aliasing, and optimization: 709 https://blog.regehr.org/archives/959 710 711To allow MPFR to be built on some buggy compiler, try to follow 712these rules: 713 714 ===================================================================== 715 716Don't write: 717 mp_limb_t l; 718 [...] 719 if (l) do_action (); 720But: 721 mp_limb_t l; 722 [...] 723 if (l != 0) do_action (); 724 725since mp_limb_t may be "unsigned long long", and some buggy compiler 726produce illegal codes with the first form. 727 728 ===================================================================== 729 730Try to avoid "LONG_MIN/1" since it produces a SIGNAL on (old) FreeBsd. 731Don't forget that LONG_MIN/-1 is not representable (specially 732with code like MPFR_EXP_MIN/n). 733 734 ===================================================================== 735 736Don't use "near" and "far" as variable names since they are "Keywords" 737for some C compiler (Old DOS compiler). Also don't use "pm", which is used 738by the C compiler 'sharp' to design variables that should be stored in the 739flash memory. Don't use "new", which is reserved in C++. 740 741Check C++ reserved keywords, e.g. from 742 743 https://en.cppreference.com/w/cpp/keyword 744 745or more generally: 746 747 https://www.google.com/search?q=%22C%2B%2B%22+reserved+keywords 748 749Quoted from <https://www.gnu.org/software/gcc/codingconventions.html>: 750 751 Avoid the use of identifiers or idioms that would prevent code 752 compiling with a C++ compiler. Identifiers such as new or class, 753 that are reserved words in C++, should not be used as variables 754 or field names. Explicit casts should be used to convert between 755 void* and other pointer types. 756 757When a string literal ("...") is followed by a macro name, there 758must be white space between them, otherwise this is parsed as a 759user-defined string literal in C++11: 760 761 https://en.cppreference.com/w/cpp/language/user_literal 762 https://stackoverflow.com/a/6402166/3782797 763 764In at least mpfr.h, use the underscore version of the attribute names 765(e.g. "__sentinel__" instead of "sentinel"), otherwise user code could 766fail to compile with GCC when it defines macros such as "sentinel" 767(before the #include's or via the -D command-line option). See 768 769 https://gcc.gnu.org/onlinedocs/gcc/Attribute-Syntax.html 770 771 ===================================================================== 772 773Setting errno is safe to signal some error information (as in the 774formatted output functions), but errno must not be read (unless we 775have just modified it) as this may yield undefined behavior in some 776corner cases out of our control (ISO C99 / C11, 7.14.1.1p5, also 777mentioned in J.2). 778 779 ===================================================================== 780 781C-Reduce may be useful to try to identify whether a bug comes from the 782compiler. 783 784 ===================================================================== 785 786About type conversions: 787 788To do type punning (i.e. store a value of some type and reinterpret 789it as another type), use a union. This is valid in ISO C99 and above 790(in C99, see 6.5#7 and Note 82 of 6.5.2.3#3 for the clarification), 791but not in C++. So, users of a C++ compilers should make sure that 792their compiler supports type punning via a union. If some problem is 793reported, we should address it either by making the code compatible 794or by adding a configure test to reject the compiler. 795 796Some references: 797* https://en.wikipedia.org/wiki/Type_punning#Use_of_union 798* https://stackoverflow.com/questions/346622/opinions-on-type-punning-in-c 799 "Opinions on type-punning in C++?" 800 801Do not do conversions between function pointers and other kinds of 802pointers (including to void *). This yields undefined behavior and 803may not work in practice. Example: 804 805 https://stackoverflow.com/questions/5579835/c-function-pointer-casting-to-void-pointer 806 807Adding a level of indirection is OK, as suggested there, and on: 808 809 https://stackoverflow.com/questions/36645660/why-cant-i-cast-a-function-pointer-to-void 810 811To convert an unsigned integer u to the corresponding signed integer with 812the two's complement rule (i.e. modular arithmetic) but in a portable way, 813write e.g. for long: 814 815 u > LONG_MAX ? -1 - (long) ~u : (long) u 816 817(at least GCC and Clang optimize this expression to identity). This is 818provided by the ULONG2LONG() macro (defined in mpfr-impl.h). 819 820 ===================================================================== 821 822For floating-point constants, do not use the non-standard and useless 823suffix "D". It seems to mean "double" for GCC[*], but for instance, 824ICC 15 regards 1.0D as 0 (though ICC claims compatibility with GCC) 825and for tcc 0.9.27, this is an error. The standard suffixes from TS 18661-2 826are: 827 828 f l F L df dd dl DF DD DL 829 830Moreover, avoid native floating-point if possible. Be careful that GCC 831does not conform to the C standard by default. References: 832 https://gcc.gnu.org/bugzilla/show_bug.cgi?id=323 833 https://gcc.gnu.org/bugzilla/show_bug.cgi?id=85957 834 835[*] https://stackoverflow.com/questions/4331200/what-do-f-and-d-mean-at-the-end-of-numeric-literals 836 837 ===================================================================== 838 839In MPFR, _Float128 may be defined as __float128 if the latter is provided 840by the compiler, but not the former. In such a case, do not assume that 841_Float128 and long double are necessarily different types (as required by 842the WG14 N2579 draft "IEC 60559 interchange and extended types"). 843 844 ===================================================================== 845 846For string suffix selection, do not write expressions of the form 847string + integer, such as 848 849 "foo" + i 850 851because Clang emits a warning 852 853 adding 'int' to a string does not append to the string [-Wstring-plus-int] 854 855Instead, one may write 856 857 &"foo"[i] or (char *) "foo" + i 858 859(the first form is the one suggested by Clang, the second one is more 860immediate to understand). 861 862=========================================================================== 863 864Avoid variable names "l", "I" and "O", which look like "1" and "0" with 865some fonts. 866 867=========================================================================== 868 869For identifiers defined in MPFR, do not use the GMP namespaces 870(gmp_..., GMP_...). 871 872=========================================================================== 873 874You are allowed to use the mpn and mpz classes of GMP functions (types 875and functions starting with "mpn_" and "mpz_"). However, except for some 876conversion functions where they may be needed, 877 * the mpq class and GMP's formatted output and input functions (i.e., 878 printf and scanf style) can only be used in an alternative method 879 by testing MPFR_USE_MINI_GMP (and only if there is a real benefit), 880 since they are not available in mini-gmp; 881 * the mpf class must not be used at all. 882 883=========================================================================== 884 885The headers <limits.h>, <stdio.h>, <stdlib.h> and <string.h> are always 886included in mpfr-impl.h; thus you need not (and should not) include them 887in usual source and test files. 888 889=========================================================================== 890 891For files that need intmax_t or similar, use: 892 893#if HAVE_INTTYPES_H 894# include <inttypes.h> 895#endif 896#if HAVE_STDINT_H 897# include <stdint.h> 898#endif 899 900Note that even though the ISO C99 standard requires that <inttypes.h> 901include <stdint.h>, in practice this is not true on all platforms, 902such as OSF/1 (Tru64) 5.1. This is consistent with autoconf, which 903has used this form since 2004-01-26 (in headers.m4). 904 905References: 906 https://git.savannah.gnu.org/gitweb/?p=autoconf.git;a=commitdiff;h=62ac9bbfebe879581dabeed78c6ac66b907dd51d 907 https://sympa.inria.fr/sympa/arc/mpfr/2010-08/msg00015.html 908 909=========================================================================== 910 911Use locale-dependent functions when the result needs to depend on the 912locales, e.g. the decimal-point character in mpfr_out_str. 913 914Conversely, do not use locale-dependent functions when the result must 915not depend on the locales. In particular, the alphanumeric characters 916used in number strings (as created by mpfr_get_str) must be those of 917the required characters from the basic character set (see ISO C99 918standard Section 5.2.1 "Character sets"). 919 920Note that in Turkish locales on some systems: 921 * the uppercase version of "i" is "İ" (an "I" with a dot above); 922 * the lowercase version of "I" is "ı" (a dotless "i"). 923These characters are available in ISO-8859-9, thus as "char" in the 924tr_TR.iso88599 locale. However, in UTF-8, they are not available as 925(8-bit) "char"; thus toupper('i') gives 'i' and tolower('I') gives 'I'. 926So, when writing code and testing, these two encodings need to be 927considered, as they can give different behaviors. 928 929=========================================================================== 930 931If you have to mix TMP_DECL and MPFR_SAVE_EXPO_DECL in the declaring 932section of your function, please declare MPFR_SAVE_EXPO_DECL before 933TMP_DECL, since TMP_DECL may be replace by nothing: 934 935Instead of: Usually preprocessed as: 936 unsigned long t unsigned long t; 937 TMP_DECL (marker); ; 938 MPFR_SAVE_EXPO_DECL (expo); mpfr_save_expo_t expo; 939use: 940 unsigned long t unsigned long t; 941 MPFR_SAVE_EXPO_DECL (expo); mpfr_save_expo_t expo; 942 TMP_DECL (marker); ; 943 944=========================================================================== 945 946Memory allocation 947----------------- 948 949Do not use TMP_DECL / TMP_ALLOC, ... but MPFR_TMP_DECL, MPFR_TMP_ALLOC, ... 950 951In the tests, use only tests_allocate, tests_reallocate and tests_free 952(there may be some rare exceptions, such as in tabort_defalloc*.c). 953 954Avoid code that would yield unnecessary reallocations, which can be very 955expensive. In particular, for code that is based on the mpz layer of GMP, 956do not use mpz_init, but mpz_init2 with the estimated maximum size; it is 957better to overestimate this size a bit than underestimating it. 958 959=========================================================================== 960 961Do not use C99-only features, such as empty macro arguments or C++-style 962comments. 963 964=========================================================================== 965 966When testing a "boolean" macro M (i.e. which is normally either equal 967to 1 or undefined), do not use #if M, but #ifdef M or #if defined(M). 968With icc, the form #if M triggers a warning ("remark #193: zero used 969for undefined preprocessing identifier"). 970 971=========================================================================== 972 973If you want to use the logging of MPFR, you need to enable it: 974 make distclean 975 ./configure --enable-logging 976 make 977Then link your program with this new build of MPFR. 978 979The logging feature needs GCC to build MPFR, and it is not available 980with mini-gmp, since mpfr_fprintf cannot be defined with mini-gmp. 981 982Warning! The logging code for functions sometimes output an "inexact" 983value, but in case of exception, this value may be meaningless. In 984fact, the output value is the value of some variable; please check 985the source code of the function to understand its real meaning. 986 987You can control what is logged using the environment variables: 988 989MPFR_LOG_FILE: Name of the LOG file (default: mpfr.log). 990MPFR_LOG_FLUSH: When this variable is set, flush the log stream after 991 each log output (useful to get the latest logs in case 992 of crash, but this makes logging slower). 993MPFR_LOG_PREC: Number of digits of the output (set the internal variable 994 mpfr_log_prec, default: 6). 995MPFR_LOG_LEVEL: Max recursive level (default: 7). 996 997MPFR_LOG_INPUT: Log the input 998MPFR_LOG_OUTPUT: Log the output 999MPFR_LOG_TIME: Log the time spent inside the function. 1000MPFR_LOG_INTERNAL: Log the intermediary variables if any. 1001MPFR_LOG_MSG: Log the messages sent by MPFR if any. 1002MPFR_LOG_ZIV: Log what the Ziv Loops do. 1003MPFR_LOG_STAT: Log how many times Ziv failed. 1004MPFR_LOG_ALL: Log everything 1005 1006Define them. Run your program, and view `mpfr.log`. 1007 1008For example, just define MPFR_LOG_ALL, run you program, and view `mpfr.log`. 1009 1010Note: The running time may be much longer. If logging is used on the 1011test suite with a default timeout, it may be necessary to increase the 1012timeout time by setting the environment variable MPFR_TESTS_TIMEOUT 1013to the new timeout value in seconds (or 0 to disable the timeout). 1014 1015=========================================================================== 1016 1017This feature is available only for gcc >= 3.0 and glibc >= 2.0. 1018To achieve this, these macros have been added: 1019 1020+++ MPFR_LOG_VAR(y) 1021 Log a MPFR variable if requested (INTERNAL). 1022 Example: 1023 mpfr_t y; 1024 MPFR_LOG_VAR (y); 1025 1026+++ MPFR_LOG_MSG(x) 1027 Log another message (a warning for example) 1028Example: 1029 MPFR_LOG_MSG (("WARNING: Unchecked code\n", 0)); 1030The 0 is here a dummy value, because there must be at least an argument 1031after the format string. 1032 1033+++ MPFR_LOG_BEGIN(x) 1034 Add this macro at the beginning of a function. 1035Example: 1036 int dodo (mpfr_t x, mpfr_t op, int cnt, mpfr_rnd_t rnd) { 1037 [decl] 1038 MPFR_LOG_BEGIN (("op[%Pu]=%.*Rg rnd=%s", 1039 mpfr_get_prec(op), mpfr_log_prec, op, RND2STR(rnd))); 1040 1041+++ MPFR_LOG_END(x) 1042 Add this macro at the end of a function. 1043Example: 1044 MPFR_LOG_END (("x[%Pu]=%.*Rg i=%d", mpfr_get_prec (x), mpfr_log_prec, x, i)); 1045 return i; 1046} 1047 1048+++ MPFR_LOG_FUNC (begin,end) 1049 Add this macro at the beginning of a function. It does 1050the same job as MPFR_LOG_BEGIN and MPFR_LOG_END but it is smatter 1051since it intercepts the return itself to put the end statement. 1052Example 1053 MPFR_LOG_FUNC ( 1054 ("op[%Pu]=%.*Rg rnd=%d", op, mpfr_get_prec (op), mpfr_log_prec, op), 1055 ("x[%Pu]=%.*Rg inexact=%d", mpfr_get_prec (x), mpfr_log_prec, x, i)); 1056 1057 1058The double brackets "((" and "))" are needed since MPFR must still 1059compile with non GNU compiler, so Macros with variable # of args 1060are not allowed. 1061 1062It uses the extension of the mpfr_printf function: %Rf to display a mpfr_t. 1063%Ru is used to display the precision of a mpfr_t. 1064It uses some extended attributes of GCC (constructor, etc.) to achieve 1065its goals too. 1066 1067=========================================================================== 1068 1069ZivLoop Controller 1070 1071Ziv strategy is quite used in MPFR. In order to factorize the code, you 1072could use these macros: 1073 1074+++ MPFR_ZIV_DECL(_x) 1075 Declare a ZivLoop controller 1076 1077+++ MPFR_ZIV_INIT(_x, _prec) 1078 Init a ZivLoop controller according to the initial value of _prec. 1079 1080+++ MPFR_ZIV_NEXT(_x, _prec) 1081 Increase the precision _prec according to the ZivLoop controller. 1082 1083+++ MPFR_ZIV_FREE(_x) 1084 Free the ZivLoop controller. 1085 1086=========================================================================== 1087 1088If you plan to add a new function, you could follow this schema: 1089 1090int 1091mpfr_toto (mpfr_ptr rop, mpfr_srcptr op, mpfr_rnd_t rnd) 1092{ 1093 [Declare all used variables] 1094 int inexact; 1095 mpfr_prec_t prec; 1096 MPFR_ZIV_DECL (loop); 1097 MPFR_SAVE_EXPO_DECL (expo); 1098 1099 /* Log it if requested */ 1100 MPFR_LOG_BEGIN 1101 (("op[%Pu]=%.*Rg rnd=%d", mpfr_get_prec (op), mpfr_log_prec, op, rnd), 1102 ("rop[%Pu]=%.*Rg inexact=%d", 1103 mpfr_get_prec (rop), mpfr_log_prec, rop, inexact)); 1104 1105 /* First deal with particular cases */ 1106 if (MPFR_UNLIKELY (MPFR_IS_SINGULAR (op))) 1107 { 1108 if (MPFR_IS_NAN (op)) 1109 { 1110 MPFR_SET_NAN (rop); 1111 MPFR_RET_NAN; 1112 } 1113 else if (MPFR_IS_INF (op)) 1114 { 1115 [Code to deal with Infinity] 1116 } 1117 else 1118 { 1119 MPFR_ASSERTD (MPFR_IS_ZERO (op)); 1120 [Code to deal with Zero] 1121 } 1122 } 1123 [Other particular case: For example, op<0 or op == 1] 1124 1125 [Compute the first estimation of the used precision `prec`] 1126 [Initialize the intermediate variables using mpfr_init2] 1127 MPFR_SAVE_EXPO_MARK (expo); /* Maximal range for exponent */ 1128 1129 MPFR_ZIV_INIT (loop, prec); /* Initialize the ZivLoop controller */ 1130 for (;;) /* Infinite loop */ 1131 { 1132 [Compute an estimation of the function and] 1133 [an estimate of the error.] 1134 if (MPFR_CAN_ROUND (...)) /* If we can round, quit the loop */ 1135 break; 1136 MPFR_ZIV_NEXT (loop, prec); /* Increase used precision */ 1137 [Use `mpfr_set_prec` to resize all needed intermediate variables] 1138 } 1139 MPFR_ZIV_FREE (loop); /* Free the ZivLoop Controller */ 1140 1141 inexact = mpfr_set (rop, temp, rnd); /* Set rop to the computed value */ 1142 [Clear all intermediate variables] 1143 1144 MPFR_SAVE_EXPO_FREE (expo); /* Restore exponent range */ 1145 return mpfr_check_range (rop, inexact, rnd); /* Check range and quit */ 1146} 1147 1148Make sure that Ziv loops cannot increase the precision forever because of 1149internal exception. Otherwise one gets either a segmentation fault (with 1150limited stack size) or an assertion failure (with unlimited stack size, 1151e.g. with "make check"). 1152 1153Do not use code with side effects inside MPFR_ASSERTD or MPFR_ASSERTN, 1154as assertion checking can be disabled. If a variable is set only to test 1155it in an MPFR_ASSERTD expression, the MPFR_DBGRES macro should be used 1156with the assignment as its argument, e.g. 1157 int inex; 1158 MPFR_DBGRES (inex = mpfr_set (y, x, rnd)); 1159 MPFR_ASSERTD (inex == 0); 1160 1161Exception handling (overflow/underflow in particular): 1162 * Warning: To detect exceptions and/or possible error loss due to 1163 internal exceptions, testing whether some variable is singular with 1164 MPFR_IS_SINGULAR is generally not sufficient! Indeed, in case of 1165 overflow (resp. underflow), the value may be rounded (in absolute 1166 value) to the largest finite number (resp. to the smallest non-zero 1167 number, possible even in round-to-nearest mode). 1168 * The MPFR_BLOCK* macros can be useful, e.g. 1169 { 1170 MPFR_BLOCK_DECL (flags); 1171 /* ... */ 1172 MPFR_BLOCK (flags, /* expression or statements */) 1173 /* ... */ 1174 if (MPFR_OVERFLOW (flags)) 1175 { /* case of overflow in expression or statements */ } 1176 /* ... */ 1177 } 1178 See mpfr-impl.h (search for MPFR_BLOCK) for more information. 1179 1180=========================================================================== 1181 1182If you plan to add a new threshold in MPFR which could be tuned, 1183you should add its default value in the file `mparam_h.in'. When the 1184script configure finishes, it creates the file `mparam.h' from `mparam_h.in'. 1185 1186Then you needs to modify the program `tuneup.c' to allow it to compute 1187the new threshold. If it is a classical threshold (not complex), you could 1188use this method (example of mpfr_exp): 1189 1190/* Define the threshold as a variable instead of a constant */ 1191mpfr_prec_t mpfr_exp_threshold; 1192#undef MPFR_EXP_THRESHOLD 1193#define MPFR_EXP_THRESHOLD mpfr_exp_threshold 1194/* Include the test function to threshold directly in the test 1195 program. It will override the mpfr_exp coming from libmpfr.a */ 1196#include "exp.c" 1197/* Define the speed function related to mpfr_exp */ 1198static double speed_mpfr_exp (struct speed_params *s) { 1199 SPEED_MPFR_FUNC (mpfr_exp); 1200} 1201 1202Then in the function `all', you will have to call the tune function, 1203and write the new THRESHOLD in the file `mparam.h': 1204 1205 /* Tune mpfr_exp */ 1206 if (verbose) 1207 printf ("Tuning mpfr_exp...\n"); 1208 tune_simple_func (&mpfr_exp_threshold, speed_mpfr_exp); 1209 fprintf (f, "#define MPFR_EXP_THRESHOLD %lu\n", 1210 (unsigned long) mpfr_exp_threshold); 1211 1212More complex tuning is possible but needs special attention. 1213 1214=========================================================================== 1215 1216MPFR uses many macros, thus finding where an error occurs exactly may 1217be difficult when it is in some macro expansion. For GCC users, a new 1218experimental -ftrack-macro-expansion option has been added in GCC 4.7. 1219"It allows the compiler to emit diagnostic about the current macro 1220expansion stack when a compilation error occurs in a macro expansion." 1221<https://gcc.gnu.org/gcc-4.7/changes.html> 1222 1223=========================================================================== 1224 1225Bit Twiddling Hacks - Sean Eron Anderson maintain a list of tricks to get 1226efficient code on <https://graphics.stanford.edu/~seander/bithacks.html>. 1227WARNING: some of those tricks may not take into account possible overflows, 1228and may not be portable. 1229 1230=========================================================================== 1231 1232MPFR manual (mpfr.texi): 1233 * Use "significand", not "mantissa". 1234 * Use "decimal-point character" (as in ISO C) when the meaning is 1235 the corresponding character ("." or ",", depending on the locale), 1236 not "decimal point", "decimal separator", "fractional point", or 1237 "radix point" (the latter is fine with a mathematical meaning). 1238 This is just the name of this character (as originally defined 1239 for base 10) and does not imply a number written in decimal. 1240 Note: POSIX uses the term "radix character". 1241 * Use "@minus{}" for the minus character, not "-". 1242 * Warning! Texinfo is not like TeX. Whitespace is preserved in the 1243 info file. So, do not use additional space for .texi indentation. 1244 This also means that you need to care about the typography. Please 1245 read Section "Inserting Space" in the Texinfo manual. 1246 * Follow the English typography (no space before punctuation marks, 1247 double space after a period, etc.), not the French one. 1248 1249The MPFR manual in DVI/PS/PDF formats should have an a4 papersize, as 1250declared in mpfr.texi (@afourpaper command). The DVI file format (.dvi) 1251traditionally does not contain papersize information, which has two 1252consequences: 1253 * When viewing a .dvi file, one gets the papersize from global settings, 1254 which may differ from the papersize declared in the mpfr.texi file. 1255 In particular, a4 text on letter paper can be truncated, depending on 1256 the margins. 1257 * Since the .ps file is built from the .dvi file and makeinfo does not 1258 provide the papersize information to the dvips command, the .ps file 1259 can get a wrong papersize, depending on the settings on the machine 1260 where this file is generated. Papersize information should be checked 1261 before distributing the .ps file. 1262Nowadays, .dvi files can contain papersize information via "specials", 1263and texinfo.tex has been updated to include such information. However, 1264the interpretation of such data is based on a common agreement between 1265drivers rather on a standard. In short, the papersize issues should no 1266longer appear, but this should be checked manually. The bug report: 1267https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=874632 1268 1269=========================================================================== 1270 1271Running "make" outputs a lot of information, and warnings are not very 1272visible. The following tool "eet" allows a copy of warning messages to 1273be output to a different window (e.g. xterm or zenity): 1274 1275 https://www.vinc17.net/unix/#eet 1276 1277Direct link to the tarball: https://www.vinc17.net/unix/eet.tar.xz 1278 1279=========================================================================== 1280 1281Be careful when avoiding "'var' may be used uninitialized in this function" 1282warnings from gcc. Initializing such variables to a dummy value has several 1283drawbacks: 1284 * this may prevent other tools (that do static or dynamic analysis) from 1285 detecting bugs; 1286 * this makes code maintenance more difficult (e.g. when modifying the 1287 code, one may more easily forget a real initialization); 1288 * this makes the compiler add useless code (though this should not be 1289 significant). 1290 1291The INITIALIZED macro can be used to avoid such warnings with gcc, e.g. 1292 1293 int INITIALIZED(i); 1294 1295It uses the "int i = i;" pseudo-initialization trick, disabled with other 1296compilers as this is undefined behavior. See: 1297 1298 https://gcc.gnu.org/bugzilla/show_bug.cgi?id=36296 1299 1300If a dummy initialization must be added, use preferably an "invalid" value 1301(e.g. NULL for pointers, or a value that can be checked with MPFR_ASSERTN 1302before using it) that could make the program abort instead of returning an 1303incorrect value in case of a bug in MPFR. 1304 1305=========================================================================== 1306 1307Avoid mixing signed and unsigned integer types, as this can lead signed 1308types to be automatically converted into unsigned types (usual arithmetic 1309conversions). If such a signed type contains a negative value, the result 1310may be incorrect on some platforms. With MPFR 2.x, this problem could 1311arise with mpfr_exp_t, which is signed, and mpfr_prec_t (mp_prec_t), 1312which was unsigned (it is now signed), meaning that in general, a cast 1313of a mpfr_prec_t to a mpfr_exp_t was needed. 1314 1315Note that such bugs are difficult to detect because they may depend on 1316the platform (e.g., on LP64, 32-bit unsigned int + 64-bit long will give 1317a signed type, but on ILP32, 32-bit int + 32-bit unsigned long will give 1318an unsigned type, which may not be what is expected), but also on the 1319input values. So, do not rely on tests very much. However, if a test 1320works on 32 bits but fails on 64 bits in the extended exponent range 1321(or conversely), the cause may be related to the integer types (e.g. a 1322signness problem or an integer overflow due to different type sizes). 1323 1324For instance, in MPFR, such issues were fixed in r1992 and r5588. 1325 1326An example that will fail with 32-bit int and long: 1327 1328 long long umd(void) 1329 { 1330 long a = 1; 1331 unsigned int b = 2; 1332 return a - b; 1333 } 1334 1335When creating a new variable that will always contain non-negative values, 1336it is generally better to define it as a signed type if it may be used in 1337an arithmetic expression. The exceptions are when the value is seen as an 1338array of bits (e.g. for limbs) and to temporarily avoid integer overflow. 1339 1340=========================================================================== 1341 1342To use features related to types larger than type long, "mpfr-intmax.h" 1343must be included before "mpfr-impl.h". 1344 1345The intmax_t and uintmax_t types can be used only if _MPFR_H_HAVE_INTMAX_T 1346is defined. In this case, the printf / gmp_printf length specifier "j" can 1347be used only when NPRINTF_J is not defined. 1348 1349For internal use, mpfr-intmax.h also unconditionally defines mpfr_intmax_t, 1350mpfr_uintmax_t, MPFR_UINTMAX_MAX, MPFR_INTMAX_MAX, MPFR_INTMAX_MIN and 1351the corresponding length specifier MPFR_INTMAX_FSPEC. 1352 1353Warning! mpfr_intmax_t may be smaller than intmax_t if NPRINTF_J is defined. 1354 1355=========================================================================== 1356 1357Use mpfr_prec_t and mpfr_rnd_t instead of the old types mp_prec_t and 1358mp_rnd_t. Similarly, use mpfr_exp_t instead of GMP's mp_exp_t type 1359(unless you really want mp_exp_t, e.g. for conversions with mpf; but 1360you must not assume that mpfr_exp_t and mp_exp_t are identical). 1361 1362=========================================================================== 1363 1364How to specify (for reading) the minimum exponent or the maximum exponent 1365in the MPFR source depends on the context. 1366 13671. The most portable form is mpfr_get_emin() and mpfr_get_emax(). In 1368 the MPFR source, this is equivalent to __gmpfr_emin and __gmpfr_emax 1369 respectively (macros are defined in mpfr-impl.h; the only difference 1370 is that the macros do not evaluate to a lvalue). 1371 13722. If the exponent range has been extended, you can use the constants 1373 MPFR_EMIN_MIN and MPFR_EMAX_MAX instead. This will be faster if TLS 1374 is enabled. It also avoids a bug on some Linux/Sparc machines with 1375 some GCC versions and TLS, but this shouldn't be the primary concern, 1376 as this might be the other way round on some other machines. This is 1377 the most common context. 1378 13793. If you want the minimum and maximum possible exponent values supported 1380 by MPFR, use MPFR_EMIN_MIN and MPFR_EMAX_MAX respectively. 1381 13824. If you want the minimum and maximum values supported by the mpfr_exp_t 1383 type (i.e. the limits of this type), use MPFR_EXP_MIN and MPFR_EXP_MAX 1384 respectively. This may be useful for intermediate computations on the 1385 exponents. 1386 1387More on exponent handling: 1388 1389* The mpfr_exp_t type has at least 32 bits since it must contain the 1390 default exponent range. 1391 1392* The range of valid exponents is defined so that if a and b are two 1393 valid exponents (i.e. between MPFR_EMIN_MIN and MPFR_EMAX_MAX), then 1394 ± a ± b ± 1 fits in a mpfr_exp_t. 1395 1396* The unsigned type corresponding to mpfr_exp_t is mpfr_uexp_t. It may be 1397 useful if the considered values are non-negative and don't necessarily 1398 fit in mpfr_exp_t. To convert a non-negative mpfr_exp_t to mpfr_uexp_t, 1399 you should use the MPFR_UEXP macro, which is defined as: 1400 #define MPFR_UEXP(X) (MPFR_ASSERTD ((X) >= 0), (mpfr_uexp_t) (X)) 1401 1402* If a mpfr_exp_t appears in arithmetic expressions together with ISO C90 1403 types int and/or long, computations must be done with the largest type, 1404 which is provided by mpfr_eexp_t. 1405 1406* If a mpfr_exp_t needs to be converted from or to a MPFR number, the 1407 mpfr_set_exp_t or mpfr_get_exp_t macro should be used. 1408 1409* If a mpfr_exp_t needs to be converted into a character string with a 1410 formatted output function (fprintf, printf, sprintf), the mpfr_eexp_t 1411 type should be used, together with the MPFR_EXP_FSPEC specifier, e.g. 1412 1413 printf ("%" MPFR_EXP_FSPEC "d", (mpfr_eexp_t) exponent); 1414 1415For implementation details, see the mpfr.h and mpfr-impl.h files. 1416 1417=========================================================================== 1418 1419Be careful that the ternary value (a.k.a. "inexact") is not guaranteed 1420to be -1, 0, or 1, in general (for some functions, the exact value may 1421contain other information, such as midpoint cases with MPFR_EVEN_INEX), 1422and the exact behavior may change in the future. So, it is not correct 1423to multiply ternary values returned by arbitrary functions as this may 1424overflow. 1425 1426To work with ternary values, mpfr-impl.h provides the following macros: 1427 1428#define SIGN(I) ((I) < 0 ? -1 : (I) > 0) 1429#define SAME_SIGN(I1,I2) (SIGN (I1) == SIGN (I2)) 1430 1431=========================================================================== 1432 1433Because of a bug in the Mac OS X 10.5 linker, avoid tentative definitions 1434(C99, 6.9.2). Depending on the context, use either a simple declaration 1435(with the "extern" storage-class specifier) or an external definition. 1436This is also cleaner. 1437 1438=========================================================================== 1439 1440In case of detected internal error, do not use printf() and exit(). 1441Use assertions (MPFR_ASSERTN) instead. 1442 1443=========================================================================== 1444 1445The only compiler known to support _Decimal64 and _Decimal128 is GCC. 1446In code related to these types, when the decimal encoding can be BID, 1447do not use any conversion between binary and decimal types, otherwise 1448GCC will generate from 2 to 3 MB of code (depending on the GCC version) 1449in the MPFR shared library when the encoding is BID: 1450 https://gcc.gnu.org/bugzilla/show_bug.cgi?id=96173 1451 https://gforge.inria.fr/tracker/index.php?func=detail&aid=21849&group_id=136&atid=619 1452 1453=========================================================================== 1454 1455When using GNU extensions (based on the value of the __GNUC_* macros), check 1456whether they work with ICC. The following paper can give useful information: 1457"Intel® Compilers for Linux*: Compatibility with GNU Compilers" at 1458<https://software.intel.com/articles/intel-compilers-for-linux-compatibility-with-gnu-compilers>. 1459 1460To detect compilers, see 1461 1462 https://sourceforge.net/p/predef/wiki/Compilers/ 1463 1464=========================================================================== 1465 1466Note about the formally proven code (src/*_extracted.c): 1467 1468The code has been proven with types of fixed width (due to a limitation 1469of the F*/KreMLin proof system). Thus this code may be used only under 1470some conditions, so that MPFR enables it only under such conditions via 1471a #if, e.g. in add1sp.c: 1472 1473#if defined(MPFR_WANT_PROVEN_CODE) && GMP_NUMB_BITS == 64 && \ 1474 UINT_MAX == 0xffffffff && MPFR_PREC_BITS == 64 && \ 1475 _MPFR_PREC_FORMAT == 3 && _MPFR_EXP_FORMAT == _MPFR_PREC_FORMAT 1476 1477which implies that the #define's in add1sp1_extracted.c 1478 1479#define int64_t long 1480#define uint32_t unsigned int 1481#define uint64_t mp_limb_t 1482 1483are correct. 1484 1485Be careful with any attempt to reuse the code in a more general context, 1486e.g. by removing these #define's and just assuming that the prototypes 1487match the ABI. There is another implicit requirement: uint64_t must be 1488at least as large as unsigned int. Otherwise the code may become incorrect 1489due to integer promotions. The issue of integer promotions about intN_t vs 1490int has been mentioned in 1491 1492 https://gcc.gnu.org/pipermail/gcc/2021-November/237726.html 1493 1494=========================================================================== 1495 1496For configure tests, use AC_LINK_IFELSE rather than AC_COMPILE_IFELSE, 1497which is broken by design. The reason is that some errors just produce 1498a warning (which is not a bug from the compiler: in ISO C terminology, 1499this corresponds to a diagnostic, and the compilation is allowed to 1500succeed), and this is unfixable in a portable way. 1501 1502=========================================================================== 1503 1504Shell portability 1505----------------- 1506 1507Shell commands (in /bin/sh scripts, in Makefile and autotools related 1508files...) need to be valid in POSIX shells, but also in Bourne shells 1509(for instance, /bin/sh under Solaris is a Bourne shell). 1510 1511In particular: 1512 1513* Do not use $(...) but `...` (backticks). 1514 1515* Be careful that quote nesting with backticks such as "`cmd "$foo"`" 1516 is not portable: 1517 1518 https://unix.stackexchange.com/q/387246/74516 1519 ("quotes inside backticks inside quotes in ksh") 1520 1521 But the external quotes are not needed when assigning to a variable: 1522 1523 out=`cmd "$foo"` 1524 1525 Otherwise one can write "`cmd \"$foo\"`". 1526 1527=========================================================================== 1528 1529About the test suite 1530-------------------- 1531 1532When adding a test file for a new function (say mpfr_func), you can use 1533the following prototype tfunc.c (to put in the directory 'tests'). 1534This file performs random tests for values of x between -5 and 5, with 1535a precision varying from 2 to 100. 1536 1537You can add your own tests to this basic file. When adding the expected 1538result, do NOT use the one obtained from the MPFR function! Otherwise, 1539if this function is buggy, the test will be wrong and the function will 1540remain buggy. For random tests, avoid mpfr_urandomb as its values are 1541not truly random due to how it is specified (if the exponent is less 1542than 0, some of the trailing bits will necessarily be 0). 1543 1544Do not forget to add 'tfunc' in the variable check_PROGRAMS 1545of the tests/Makefile.am file. 1546 1547/* Test file for mpfr_func. 1548 1549Copyright 2023 Free Software Foundation, Inc. 1550Contributed by the AriC and Caramba projects, INRIA. 1551 1552This file is part of the GNU MPFR Library. 1553 1554The GNU MPFR Library is free software; you can redistribute it and/or modify 1555it under the terms of the GNU Lesser General Public License as published by 1556the Free Software Foundation; either version 3 of the License, or (at your 1557option) any later version. 1558 1559The GNU MPFR Library is distributed in the hope that it will be useful, but 1560WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 1561or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 1562License for more details. 1563 1564You should have received a copy of the GNU Lesser General Public License 1565along with the GNU MPFR Library; see the file COPYING.LESSER. If not, see 1566https://www.gnu.org/licenses/ or write to the Free Software Foundation, Inc., 156751 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. */ 1568 1569#include "mpfr-test.h" 1570 1571#define TEST_FUNCTION mpfr_func 1572#define TEST_RANDOM_EMIN -5 1573#define TEST_RANDOM_EMAX 5 1574#include "tgeneric.c" 1575 1576int 1577main (int argc, char *argv[]) 1578{ 1579 tests_start_mpfr (); 1580 1581 test_generic (2, 100, 100); 1582 1583 tests_end_mpfr (); 1584 return 0; 1585} 1586 1587 --------------------------------------------------------------------- 1588 1589Here is how the test suite works since the full Automake 1.13 support 1590(merge of the vl-am113 branch in r8821). 1591 1592The tests_start_mpfr function, which should be called at the beginning 1593of each test program (unless nothing is tested and main() just contains 1594"return 77;"), starts by calling the test_version function, whose goal 1595is to do various header/library version checks of GMP and MPFR. In case 1596of mismatch between a header and a library, an error message is output 1597("make check" will redirect it to a log file). Then there are 3 cases: 1598 15991. An error in the MPFR version check is a fatal error: test_version() 1600 exits with an error (exit status = 1). The reason is that a different 1601 MPFR library (somewhere in some library search path) would probably 1602 be tested, so that the results of the test would be meaningless. 1603 16042. An error in the GMP version check is a non-fatal error: if there are 1605 no errors in MPFR version check, test_version() returns with value 1. 1606 However, the tversion test program will regard this as a fatal error 1607 (thus "make check" will fail). The probable reason of the mismatch is 1608 that the GMP library has been upgraded while the MPFR test suite has 1609 not been rebuilt; otherwise there is probably something wrong in the 1610 GMP installation. 1611 16123. Otherwise test_version() returns with value 0 (everything is fine). 1613 1614Note: The tests_start_mpfr function does a setbuf on stdout to disable 1615buffering. As a consequence, no operations on stdout (such as printf) 1616must be done before this function is called. 1617 1618With Automake 1.13+, the tests are run in parallel if a -j make option 1619is used. In case of failure, information can be found in the log file 1620of each failed test program and in the global tests/test-suite.log file 1621(which is output automatically if the VERBOSE environment variable is 1622set to 1). If no tests fail, then the tests/tversion.log file is output 1623after the "testsuite summary"; it contains various useful information 1624about the MPFR build. 1625 1626To use a wrapper to run the tests, such as valgrind or wine, define 1627LOG_COMPILER, e.g.: 1628 LOG_COMPILER="valgrind -q --error-exitcode=1 --leak-check=full" make check 1629 LOG_COMPILER=wine make check 1630 1631More information about the parallel test harness: 1632https://www.gnu.org/software/automake/manual/automake.html#Parallel-Test-Harness 1633 1634 --------------------------------------------------------------------- 1635 1636In the tests, do not use `mpfr_set_d` (except when testing it), as the 1637result will depend on the floating-point arithmetic of the system; 1638this has shown many problems in the past and problems may still occur 1639with new systems. Use `mpfr_set_si` or `mpfr_set_str` instead. 1640 1641To check the result of some function, use mpfr_equal_p rather than 1642mpfr_cmp, as mpfr_cmp will return 0 (equality) if the result is NaN. 1643 1644Do not use functions that need optional features (except in a context 1645where such features are required). For instance, the mpfr_printf-like 1646functions need <stdarg.h> (HAVE_STDARG defined), thus should not be 1647used, except for testing them. 1648 1649For temporary result files created by test programs, choose a unique 1650filename to avoid conflicts in parallel tests. To ensure that, the 1651filename should start with the name of the test program (for instance, 1652"tfprintf_out.txt" for tfprintf.c). Add the filename to CLEANFILES in 1653the tests/Makefile.am file. 1654 1655In case of failure of a test, freeing the memory explicitly before exiting 1656is not necessary. We do this in case of success just to be able to detect 1657memory leaks in MPFR. 1658 1659Also, try to make sure that the tests run against previous MPFR versions, 1660possibly by disabling some tests with code like 1661 1662 #if MPFR_VERSION >= MPFR_VERSION_NUM(2,3,0) 1663 1664It is possible to check out the tests from a branch, e.g. master, with 1665 1666 git checkout master -- tests/ 1667 1668But to avoid the update of tests/Makefile.am with new tests, which 1669would probably fail as these new tests are typically written for new 1670MPFR functions, the following may be better: 1671 1672 git checkout master -- 'tests/*.c' 'tests/*.h' 1673 1674Note that (as seen with "git status") since the corresponding changes are 1675put in the index and there is no intent to commit, you should also do 1676 1677 git restore --staged tests 1678 1679 --------------------------------------------------------------------- 1680 1681Test function-like macros associated with functions 1682 * for side effects in argument evaluation (arguments must always be 1683 evaluated once); 1684 * for support of types that would be eligible to implicit type conversion 1685 with the function. Be careful: C and C++ have different rules. 1686 1687Support "gcc -Werror=c++-compat" and g++, possibly with -DMPFR_USE_NO_MACRO 1688in CFLAGS. The following was added to mpfr-test.h: 1689 1690#if defined (__cplusplus) 1691#define VOIDP_CAST(X) (X) 1692#else 1693#define VOIDP_CAST(X) ((void *) (X)) 1694#if defined (__GNUC__) 1695#define IGNORE_CPP_COMPAT 1696#endif 1697#endif 1698 1699For instance, in tcopysign.c, since mpfr_copysign is implemented both as 1700a function and as a function-like macro: 1701 1702 int a = 0, b = 0, c = 0; 1703[...] 1704#ifdef IGNORE_CPP_COMPAT 1705#pragma GCC diagnostic push 1706#pragma GCC diagnostic ignored "-Wc++-compat" 1707#endif 1708 mpfr_copysign ((a++, VOIDP_CAST(z)), 1709 (b++, VOIDP_CAST(p)), 1710 (c++, VOIDP_CAST(y)), rnd_mode); 1711#ifdef IGNORE_CPP_COMPAT 1712#pragma GCC diagnostic pop 1713#endif 1714 MPFR_ASSERTN (a == 1); 1715 MPFR_ASSERTN (b == 1); 1716 MPFR_ASSERTN (c == 1); 1717 1718 --------------------------------------------------------------------- 1719 1720To check the coverage of the test suite, you can use gcov. 1721To get accurate information, do not enable optimizations. 1722 1723 ./configure CFLAGS="--coverage" 1724 make clean 1725 make check 1726 find . -name '*.c' -exec gcov '{}' ';' | grep "lines executed" | sort 1727 1728For each source file, there is a .c.gcov file which contains much more 1729information. 1730 1731Another solution is to run the script 'coverage' within the 'tools' directory. 1732 1733 --------------------------------------------------------------------- 1734 1735To run the MPFR test suite under valgrind, you may need to do several 1736things. 1737 1738First, as the running time is much longer than usual, you should not use 1739the --enable-tests-timeout configure option, or set the timeout value to 1740a large value; this can be done at run time, e.g. with 1741 1742 export MPFR_TESTS_TIMEOUT=0 1743 1744to disable the timeout, so that you do not need to rebuild MPFR for 1745this purpose. 1746 1747Then just set the LOG_COMPILER environment variable to something like 1748 1749 valgrind -q --error-exitcode=1 --leak-check=full 1750 1751before running "make check", or type directly: 1752 1753 LOG_COMPILER="valgrind -q --error-exitcode=1 --leak-check=full" make check 1754 1755NOTE: with the new tests/Makefile.am file, the following is obsolete; 1756but it might still be useful under some occasions, e.g. if all the 1757valgrind output needs to be sent to a single file. 1758 1759Before running valgrind, you should run "make check" a first time so 1760that everything is compiled out of valgrind. 1761 1762Then you need the --trace-children=yes valgrind option (a possible 1763exception is when you run an individual test that has been built 1764statically). The reason is that libtool generates wrapper scripts 1765to link the tests against the right libraries. The drawback is that 1766you will get valgrind output for all the processes, including the 1767shell commands from the wrapper scripts (the --trace-children-skip 1768valgrind option will not allow you to filter every unwanted process). 1769But you can filter the output with: 1770 1771 sed -n '/= Command: [^ ]*\/\.libs\/lt-/,/= ERROR SUMMARY:/p' 1772 1773For readability, you should redirect the valgrind output to a file. 1774You can use --log-file, but due to --trace-children=yes, you need 1775the %p format specifier in the filename argument to generate a file 1776for each child; however, many files will be generated, and it may be 1777better to use the following method to get a single file: 1778 1779 valgrind --trace-children=yes --log-fd=3 make check 3> vg.out 1780 1781then 1782 1783 sed -n '/= Command: [^ ]*\/\.libs\/lt-/,/= ERROR SUMMARY:/p' vg.out 1784 1785to get only the valgrind output corresponding to the MPFR tests. 1786 1787Or if your shell supports it, you can use a process substitution 1788to filter the valgrind output directly to a file, e.g. with bash 1789or zsh: 1790 1791 valgrind --trace-children=yes --log-fd=3 make check 3> >(sed -n \ 1792 '/= Command: [^ ]*\/\.libs\/lt-/,/= ERROR SUMMARY:/p' > vg.out) 1793 1794if you do not mind about the buffering delays. 1795 1796 --------------------------------------------------------------------- 1797 1798NOTE: with "AM_LDFLAGS = -no-install" in tests/Makefile.am, the following 1799is obsolete, as libtool no longer generates wrapper scripts; but it is left 1800here in case negative effects of "AM_LDFLAGS = -no-install" are seen or for 1801users with a special setup. 1802 1803To debug some test program, e.g. tadd, with gdb, you cannot run "gdb tadd" 1804since libtool has generated a wrapper script to link the program against 1805the correct MPFR library. Instead, run: 1806 1807 libtool --mode=execute gdb tadd 1808 1809Alternatively, something like 1810 1811 LD_PRELOAD=../src/.libs/libmpfr.so gdb .libs/tadd 1812 1813may also work (example for GNU/Linux). 1814 1815Note: for test programs not listed in Makefile.am (check_PROGRAMS), 1816libtool is not used (a static link against MPFR is done via LOADLIBES 1817in Makefile.am), so that gdb should be used in the conventional way. 1818You can use the following wrapper script to have a command that works 1819with both: 1820 1821------------------------------------------------------------ 1822#!/bin/sh 1823 1824unset cmd 1825case $1 in 1826 -*) ;; 1827 ?*) test "x$(head -c 2 "$1")" = 'x#!' && \ 1828 grep -q "^# Generated by libtool" "$1" && \ 1829 cmd="libtool --mode=execute" ;; 1830esac 1831 1832exec $cmd gdb "$@" 1833------------------------------------------------------------ 1834 1835and 1836 1837 alias gdb='/path/to/the/wrapper/script' 1838 1839=========================================================================== 1840 1841To cross-compile MPFR for i686-w64-mingw32 and test it under Wine: 1842 18430. Install wine (at least the 32-bit version). 1844 18451. Build and install GMP. 1846 1847In the GMP source directory: 1848$ ./configure --host=i686-w64-mingw32 --disable-shared --prefix=... 1849$ make 1850$ make check LOG_COMPILER=wine 1851$ make install 1852 1853Note: With MinGW earlier than v8.0.0, the -D__USE_MINGW_ANSI_STDIO option 1854may be necessary in order to get an ISO-conforming printf as mentioned in 1855MPFR's INSTALL file. 1856 18572. Build and check MPFR. 1858 1859In the MPFR source directory: 1860$ ./configure --host=i686-w64-mingw32 --disable-shared --with-gmp=... 1861$ make 1862$ make check LOG_COMPILER=wine 1863 1864Note: Due to bugs in autoconf[1] and dash[2], the configure script 1865may create files with a binary filename or have any other arbitrary 1866behavior if /bin/sh is dash. The cause is that it tries to execute 1867a MS Windows executable, which is interpreted as a shell script by 1868dash (thus with random, meaningless commands). 1869 1870[1] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=850329 1871[2] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=816313 1872 1873=========================================================================== 1874 1875After a MPFR build, the list of GMP symbols used by this particular MPFR 1876build can be obtained as follows: 1877 1878 nm -u src/.libs/libmpfr.so | sed -n 's/^ *U \(__gmp.*\)/\1/p' 1879 1880at least under Linux, the library name and the "nm" behavior being 1881non-portable (adding the POSIX "-P" option may help, but there are 1882still differences between platforms). 1883 1884Note that this list may depend on various parameters, such as the 1885architecture and the compilation options. 1886 1887GMP internal symbols used by MPFR can be detected with the following 1888shell command (just replace /path/to/gmp.h by the actual pathname): 1889 1890nm -u src/.libs/libmpfr.so | sed -n 's/^ *U \(__gmp.*\)/\1/p' | \ 1891while read s 1892do 1893 case $s in 1894 __gmpn_*) regex="__MPN(${s#__gmpn_})" ;; 1895 *) regex="$s" ;; 1896 esac 1897 grep -q "^#define .* ${regex}$" /path/to/gmp.h || echo "Internal: $s" 1898done 1899 1900A similar check can be done with "make check-gmp-symbols". 1901 1902One can also check that MPFR does not define exported symbols with a 1903prefix outside "mpfr_" and "__gmpfr_" by using "nm -g" and filtering 1904at least the "U" lines. But this can only be a manual check to avoid 1905false positives. Checking that a GMP reserved prefix is not used can 1906be done automatically, as with "make check-exported-symbols". 1907 1908=========================================================================== 1909 1910To update the FAQ, checkout the misc directory of the repository root. 1911Modify the faq.xhtml file and run 1912 1913 xsltproc --nodtdattr faq-web.xsl faq.xhtml > www/faq.html 1914 1915Check with "git diff" that this change has been done correctly (in case 1916of incorrect installation of XML tools), validate the files with 1917 1918 xmllint --noout --loaddtd --valid faq.xhtml www/faq.html 1919 1920and if everything is OK (no error messages), commit both files. 1921 1922Update the FAQ.html file with update-faq in the doc directory of the 1923MPFR master and supported release branches. 1924 1925=========================================================================== 1926 1927Spelling: 1928 * Some suggestions: https://gcc.gnu.org/codingconventions.html#Spelling 1929 * Check with "codespell" (done by mpfrlint). 1930 1931=========================================================================== 1932 1933Git: 1934 * When creating a branch, add an associated <branch>-root tag on the 1935 root commit (i.e. just before the first commit in the new branch). 1936 This can be useful for commands like "git diff <branch>-root" to get 1937 the commits done in the branch since its creation, and such tags are 1938 used in tests/Makefile.am for output_info (Git information output by 1939 "make check"). 1940