xref: /netbsd-src/external/lgpl3/mpfr/dist/doc/README.dev (revision ec6772edaf0cdcb5f52a48f4aca5e33a8fb8ecfd)
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