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