Copyright 2002-2017 Free Software Foundation, Inc. Contributed by the AriC and Caramba projects, INRIA. This file is part of the GNU MPFR Library. The GNU MPFR Library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. The GNU MPFR Library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with the GNU MPFR Library; see the file COPYING.LESSER. If not, see http://www.gnu.org/licenses/ or write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. Notes for the MPFR developers and Subversion users ================================================== To compile source code obtained from the Subversion repository, you need some GNU development utilities: aclocal, autoheader, automake, autoconf 2.60 (at least) and libtoolize. As some files like "configure" are not part of the Subversion repository, you first need to run "autoreconf -i"; if you have both autoconf 2.13 and 2.50 installed and use a wrapper, you may need to run "autoreconf" a second time (as with old Debian packages, due to a bug in the wrapper). Then you can run "configure" in the usual way (see the INSTALL file, but note that there are no patches to apply, and the URLs are not valid since the corresponding version has not been released yet). To generate mpfr.info, you need texinfo version 4.2 (or higher). =========================================================================== The VERSION file contains the number of the next release version, i.e. the version currently being developed. A suffix can be attached for the development versions (in general, "-dev") or pre-release versions (e.g. "-rc1"). It must be updated with the update-version script. If nightly snapshots are built, the date in the yyyymmdd format and/or the Subversion revision number (giving more accurate information) must be added to the version as a suffix, for instance: "2.3.0-20070621" or "2.3.0-dev-r4553". Patches can be tracked by adding a chunk of the form --- PATCHES~ Tue Nov 6 19:59:33 2001 +++ PATCHES Tue Nov 6 19:59:42 2001 @@ -1,0 +1 @@ + to the patch file[*]. After such patches have been applied, the file src/get_patches.c providing the mpfr_get_patches() function will be rebuilt by "make". MPFR distributors can still modify the version suffix from the applied patches according to their version naming scheme; for instance, for their own patches, MPFR developers do: tools/update-version 3 1 0 p1 - [*] This idea comes from Thomas Roessler, who implemented it in Mutt. For patches from MPFR developers, e.g. for MPFR 3.1.0: 1. Unarchive the tarball: a directory mpfr-3.1.0 is created. 2. Go into this directory (cd mpfr-3.1.0). 3. Apply the current patches with "patch -N -Z -p1 < /path/to/allpatches". 4. Reset the PATCHES file with "true >| PATCHES". 5. Rename mpfr-3.1.0 as mpfr-3.1.0-a and duplicate it as mpfr-3.1.0-b without changing the timestamps (e.g. with cp -a). 6. In mpfr-3.1.0-b, apply the patch obtained with "svn diff", e.g. patch --no-backup-if-mismatch -p0 < /path/to/new_patch 7. In mpfr-3.1.0-b, update the version information: tools/update-version 3 1 0 p - where is the patch number. 8. In mpfr-3.1.0-b, update PATCHES file: echo >> PATCHES 9. Make the patch: TZ=UTC diff -Naurd mpfr-3.1.0-a mpfr-3.1.0-b Note: if autotools files are modified, the corresponding changes in the distributed files depending on them must be included in the patch, and the timestamps of such autotools files should be reset so that they do not change when the patch is applied with the -Z option. Otherwise the autotools would be needed to build MPFR (unless maintainer mode is disabled). =========================================================================== When submitting patches, unified diffs (option -u) are recommended, as they are more readable. You can also use the option -d to generate a smaller set of changes. See diff(1) for more information. =========================================================================== Copyright Notices: For easier maintainability, make sure that the copyright notices match the regexp "Copyright.* yyyy Free Software" where yyyy is the year of the latest modification in the branch (and nothing else should match it). The latest rules for GNU software can be found here: http://www.gnu.org/prep/maintain/maintain.html#Copyright-Notices =========================================================================== To make a release (for the MPFR team): *** Please read this section entirely before making any release. *** 0) Make sure that the src/mpfr-longlong.h file (from GMP's longlong.h) and the libtool-related files (config.guess, etc.) are up-to-date. An "autoreconf -f -i" may be necessary. 1) Generate the tuning parameters on different architectures and put them in src/mparam_h.in. For each architecture: a) download the latest release of GMP on gmplib.org b) build GMP with --disable-shared in say /tmp/gmp-x.y.z There is no need in tuning GMP, since most users will build MPFR with a vanilla GMP installation, i.e., with the default GMP tuning; however you need to go into /tmp/gmp-x.y.z/tune and type "make speed" (the MPFR tuning is using the resulting speed library) c) configure MPFR with --disable-shared --with-gmp-build=/tmp/gmp-x.y.z d) go into the "tune" directory and run "make tune" e) put the resulting mparam.h file into mparam_h.in (please include the version of GMP and the compiler used) You can produce time graphs to check the thresholds are correct (and compare to the corresponding mpf functions) with mbench. For example: $ cd mpfr/tools/mbench $ make mpfr-gfx GMP=... MPFR=... $ ./mpfr-gfx -b16 -e320 -s16 -f2 -x3 # compares mpfr_mul and mpf_mul # from 16 to 320 bits with increment # of 16 bits $ gnuplot -persist plot.gnuplot Another example, comparing mpfr_mul and mpf_mul from 2 to 1000000 bits, with ratio 1.1 between two sizes, 10 random values, and 10 smoothness checks: $ ./mpfr-gfx -b2 -e1000000 -r1.1 -f10 -x3 -m10 $ gnuplot -persist plot.gnuplot Check the coverage of each source file by the test suite is at least 90% (or clearly justify any value under this threshold), and publish (for example in NEWS) the global coverage of this release. The individual coverage of each source file might also be published on the release web page. 2) Check the version and change the suffix to "rc1", "rc2", etc. with update-version for the release candidates; remove the suffix for the final release. Update the libtool version too (see src/Makefile.am). Update the date in doc/mpfr.texi. 3) Update the NEWS file, in particular say if the the release is binary and/or API compatible (or not) with previous releases. Also update the "API Compatibility" section in the manual (mpfr.texi). Update the FAQ.html file with update-faq (and check it) in the doc directory. 4) Update the ChangeLog file with "TZ=UTC svn log -rHEAD:0 -v" in UTF-8 locales, e.g. "LC_ALL=en_US.UTF8 TZ=UTC svn log -rHEAD:0 -v". 5) Make sure that any change has been committed (with "svn st"). Generate the release version with "make dist", but see below. 6) Test the release version on different machines, with and without --enable-assert (--enable-assert, though doing more checks, may hide bugs due to the fact that is always included) with and without GMP's --disable-alloca configure option (or compile GMP with --enable-alloca=debug and MPFR with --with-gmp-build to be able to get the memory leak errors), with and without -DXDEBUG in $CFLAGS, with and without gmp internal files (--enable-gmp-internals), with and without GMP built as a shared library, with objdir equal to and different from srcdir (e.g. ../mpfr-source/configure after making mpfr-source read-only), with and without --enable-logging. Try different gcc versions with different options: with and without "-std=c99 -O3 -D_XOPEN_SOURCE=500", with and without "-ansi" (which allows to turn off features that are incompatible with ISO C90), with and without [-ansi] -pedantic-errors (which has the effect to disable extensions, such as long long when used together with -ansi) with and without --enable-thread-safe, in various FPU precisions (double, double extended and single) if the platform supports that (e.g. under Linux/x86), and in various locales (LC_ALL=tr_TR in particular, if installed). On x86, test with -m96bit-long-double and -m128bit-long-double. Try also with gcc's -fno-common option. Check also with "-Wformat=2", but without logging support (in order to avoid too many spurious warnings). Check that make and make check pass with a C++ compiler, for example: ./configure CC=g++ (MPFR 2.3.2 did not). Also test --enable-gmp-internals with it. Try different compilers, e.g., icc, opencc (x86_64 machines), tcc , llvm-gcc, clang. On 64-bit PowerPC, test against GMP built with the different ABI's: 32, mode32 and mode64 (in particular mode32, where long's have 32 bits and limbs have 64 bits [long long]). Test with -DMPFR_TEST_DIVBYZERO=1 -DMPFR_ERRDIVZERO=1 in order to detect whether tests can fail due to a FP division by 0 on platforms where such an operation fails (e.g. trap). Test with -D_MPFR_PREC_FORMAT=2 when the "int" type is smaller than the "long" type. Test with valgrind: "valgrind --trace-children=yes make check" (after a first "make check" for the compilation). See below for more information about valgrind. Test with both "make check" and the worst cases. Check that there are no abnormal regressions in the timings (both for 100, 1000, 10000 digits, http://mpfr.org/mpfr-current/timings.html, and for small precision, using the mbench program, see mpfr/mbench). Test the library interface compatibility by running the test suite compiled against an old library version and dynamically linked with the new library version: for instance, build the shared library of old and new MPFR versions with the same configure options, and from the build directory of the old version, do something like: (cd src/.libs && \ ln -nsf ../../../mpfr-new/src/.libs/libmpfr.so.1.* libmpfr.so.1) then "make check". 7) For the release itself (not the release candidates), if no problems have been found, create a tag with: svn cp .../mpfr/branches/x.y .../mpfr/tags/x.y.z 8) Update the version with the update-version script to indicate the next version (use the "dev" suffix). 9) Create a web page for the MPFR release and add the documentation (for mpfr.html, use "makeinfo --html --no-split mpfr.texi" from the doc directory). Upload the tarballs and the signatures to the MPFR web server (via svn), to InriaForge and to the GNU FTP site. Update the mpfr-current symbolic link and the history page. Announce the release in the mpfr-announce, gmp-discuss and gcc mailing-lists, and on InriaForge. In case of a new patchlevel release, add a link from the web page of the previous release. For major or minor releases (but not patchlevels), a branch may be created first to allow new features to be committed to the trunk. =========================================================================== To check the coverage of the Test Suite, you can use GCOV. ./configure CFLAGS="-fprofile-arcs -ftest-coverage" make clean make check find . -name '*.c' -exec gcov '{}' ';' | grep "lines executed" | sort For each source file, there is a .c.gcov file which contains much more information. Another solution is to run the script 'coverage' from MPFR source directory. =========================================================================== List of the used macros for building MPFR: + HAVE_STRCASECMP: Define if the system supports 'strcasecmp' function. + HAVE_STRNCASECMP: Define if the system supports 'strncasecmp' function. + HAVE_CONFIG_H: Define if we have to include 'config.h' first. + MPFR_HAVE_GMP_IMPL: Define if we have the gmp internal files. ('gmp-impl.h', 'gmp-maparam.h', ...). + HAVE_ALLOCA_H: Define if the function 'alloca' is in alloca.h. + HAVE_LONG_LONG: Define if the system supports 'long long' + HAVE_STDARG: Define if the system supports 'stdarg.h'. Otherwise it is assumed it is 'vararg.h'. + HAVE_INTTYPES_H: Define if is available (ISO C99). + HAVE_STDINT_H: Define if is available (ISO C99). + MPFR_HAVE_INTMAX_MAX: Define if the INTMAX_MAX macro works correctly (if 'intmax_t' is supported). Define format of long double. + HAVE_LDOUBLE_IEEE_EXT_LITTLE: IEEE extended, little endian. + HAVE_LDOUBLE_IEEE_QUAD_BIG: IEEE quad, big endian. + XDEBUG: Use generic 'double' code instead of IEEE specific one. The IEEE code for double needs GMP internal files. + MPFR_WANT_ASSERT: Define if we want to turn on the assertions. + MPFR_EXP_CHECK: Define if we want to check the exp field. + MPFR_PREC_FORMAT: Define the internal format of prec field (For experimented users). + IEEE_DBL_MANT_DIG: Number of bits in the mantissa of a double. (Default: 53). + LDBL_MANT_DIG: Number of bits in the mantissa of a long double List of the used macros for checking MPFR: + MPFR_HAVE_FESETROUND: Define if the fesetround function is defined (and in header fenv.h). + HAVE_DENORMS: Define if subnormal (denormalized) floats work. + HAVE_SYS_TIME_H: Define if the header sys/time.h is usable. + HAVE_GETTIMEOFDAY: Define if the function gettimeofday is present. + MPFR_HAVE_TESTS_x86: Define if we are on x86. =========================================================================== The GNU Coding standards can be read at: http://www.gnu.org/prep/standards_toc.html ISO C Names and corresponding headers: http://www.schweikhardt.net/identifiers.html Language C: http://www.vmunix.com/~gabor/c/draft.html To allow MPFR to be built on some buggy compiler, try to follow theses rules: ===================================================================== Don't write: mp_limb_t l; [...] if (l) do_action (); But: mp_limb_t l; [...] if (l != 0) do_action (); since mp_limb_t may be "unsigned long long", and some buggy compiler produce illegal codes with the first form. ===================================================================== Don't use "near" and "far" as variable names since they are "Keywords" for some C compiler (Old DOS compiler). Also don't use "pm", which is used by the C compiler 'sharp' to design variables that should be stored in the flash memory. Don't use "new", which is reserved in C++. ===================================================================== Avoid variable names "l", "I" and "O", which look like "1" and "0" with some fonts. ===================================================================== For identifiers defined in MPFR, do not use the GMP namespaces (gmp_..., GMP_...). ===================================================================== Quoted from : Avoid the use of identifiers or idioms that would prevent code compiling with a C++ compiler. Identifiers such as new or class, that are reserved words in C++, should not be used as variables or field names. Explicit casts should be used to convert between void* and other pointer types. ===================================================================== Try to avoid "LONG_MIN/1" since it produces a SIGNAL on (old) FreeBsd. Don't forget that LONG_MIN/-1 is not representable (specially with code like MPFR_EXP_MIN/n). ===================================================================== Though the ISO C standard requires that defines NULL, do not use NULL with #include only, because this will not work with the native SunOS 4 C compiler, whose headers are not conform to the standard (even with C90); other problems may occur on this architecture. You can either include or use 0 (possibly casted to the target pointer type). ==================================================================== For files that need intmax_t or similar, use: #if HAVE_INTTYPES_H # include #endif #if HAVE_STDINT_H # include #endif Note that even though the ISO C99 standard requires that include , in practice this is not true on all platforms, such as OSF/1 (Tru64) 5.1. This is consistent with autoconf, which has used this form since 2004-01-26 (in headers.m4). References: http://git.savannah.gnu.org/gitweb/?p=autoconf.git;a=commitdiff;h=62ac9bbfebe879581dabeed78c6ac66b907dd51d https://sympa.inria.fr/sympa/arc/mpfr/2010-08/msg00015.html ==================================================================== Use locale-dependent functions when the result needs to depend on the locales, e.g. the fractional point in mpfr_out_str. Conversely, do not use locale-dependent functions when the result must not depend on the locales. In particular, the alphanumeric characters used in number strings (as created by mpfr_get_str) must be those of the required characters from the basic character set (see ISO C99 standard Section 5.2.1 "Character sets"). And tolower(letter) does not necessarily return the corresponding lowercase letter from these required characters. For instance, tolower('I') returns a dotless 'i' in Turkish locales. ==================================================================== In the tests, do not use `mpfr_set_d` (except when testing it), as the result will depend on the floating-point arithmetic of the system; this has shown many problems in the past and problems may still occur with new systems. Use `mpfr_set_si` or `mpfr_set_str` instead. To check the result of some function, use mpfr_equal_p rather than mpfr_cmp, as mpfr_cmp will return 0 (equality) if the result is NaN. Do not use functions that need optional features (except in a context where such features are required). For instance, the mpfr_printf-like functions need (HAVE_STDARG defined), thus should not be used, except for testing them. Also, make sure that the tests run against previous MPFR versions, possibly by disabling some tests with code like #if MPFR_VERSION >= MPFR_VERSION_NUM(2,3,0) Indeed one can now easily run the trunk tests in a branch by executing svn switch .../svn/mpfr/trunk/tests tests from the working copy. One can know when the tests directory has been switched, thanks to $ svn status S tests In case of failure, freeing the memory explicitly is not necessary. We do this in case of success just to be able to detect memory leaks in MPFR. ==================================================================== If you have to mix TMP_DECL and MPFR_SAVE_EXPO_DECL in the declaring section of your function, please declare MPFR_SAVE_EXPO_DECL before TMP_DECL, since TMP_DECL may be replace by nothing: Instead of: Usually preprocessed as: unsigned long t unsigned long t; TMP_DECL (marker); ; MPFR_SAVE_EXPO_DECL (expo); mpfr_save_expo_t expo; use: unsigned long t unsigned long t; MPFR_SAVE_EXPO_DECL (expo); mpfr_save_expo_t expo; TMP_DECL (marker); ; ==================================================================== Do not use TMP_DECL / TMP_ALLOC, ... but MPFR_TMP_DECL, MPFR_TMP_ALLOC, ... ==================================================================== Do not use C99-only features, such as empty macro arguments or C++-style comments. ==================================================================== When testing a "boolean" macro M (i.e. which is normally either equal to 1 or undefined), do not use #if M, but #ifdef M or #if defined(M). With icc, the form #if M triggers a warning ("remark #193: zero used for undefined preprocessing identifier"). =========================================================================== If wou want to use the logging of MPFR, you need to enable it: ./configure --enable-logging make clean make Then link your program with this new build of MPFR. Warning! The logging code for functions sometimes output an "inexact" value, but in case of exception, this value may be meaningless. In fact, the output value is the value of some variable; please check the source code of the function to understand its real meaning. You can control what is logged using the environment variables: MPFR_LOG_FILE: Name of the LOG file (default: mpfr.log). MPFR_LOG_PREC: # of digits of the output (set the internal variable mpfr_log_prec, default: 6). MPFR_LOG_LEVEL: Max recursive level (default: 7). MPFR_LOG_INPUT: Log the input MPFR_LOG_OUTPUT: Log the output MPFR_LOG_TIME: Log the time spent inside the function. MPFR_LOG_INTERNAL: Log the intermediary variables if any. MPFR_LOG_MSG: Log the messages sent by MPFR if any. MPFR_LOG_ZIV: Log what the Ziv Loops do. MPFR_LOG_STAT: Log how many times Ziv failed. MPFR_LOG_ALL: Log everything Define them. Run your program, and view `mpfr.log`. For example, just define MPFR_LOG_ALL, run you program, and view `mpfr.log`. Note: The running time may be much longer. If logging is used on the testsuite with a default timeout, it may be necessary to increase the timeout time by setting the environment variable MPFR_TESTS_TIMEOUT to the new timeout value in seconds (or 0 to disable the timeout). ==================================================================== This feature is available only for gcc >= 3.0 and glibc >= 2.0. To achieve this, theses macros have been added: +++ MPFR_LOG_VAR(y) Log a MPFR variable if requested (INTERNAL). Example: mpfr_t y; MPFR_LOG_VAR (y); +++ MPFR_LOG_MSG(x) Log another message (a warning for example) Example: MPFR_LOG_MSG (("WARNING: Unchecked code\n", 0)); The 0 is here a dummy value, because there must be at least an argument after the format string. +++ MPFR_LOG_BEGIN(x) Add this macro at the beginning of a function. Example: int dodo (mpfr_t x, mpfr_t op, int cnt, mpfr_rnd_t rnd) { [decl] MPFR_LOG_BEGIN (("op[%Pu]=%.*Rg rnd=%s", mpfr_get_prec(op), mpfr_log_prec, op, RND2STR(rnd))); +++ MPFR_LOG_END(x) Add this macro at the end of a function. Example: MPFR_LOG_END (("x[%Pu]=%.*Rg i=%d", mpfr_get_prec (x), mpfr_log_prec, x, i)); return i; } +++ MPFR_LOG_FUNC (begin,end) Add this macro at the beginning of a function. It does the same job as MPFR_LOG_BEGIN and MPFR_LOG_END but it is smatter since it intercepts the return itself to put the end statement. Example MPFR_LOG_FUNC ( ("op[%Pu]=%.*Rg rnd=%d", op, mpfr_get_prec (op), mpfr_log_prec, op), ("x[%Pu]=%.*Rg inexact=%d", mpfr_get_prec (x), mpfr_log_prec, x, i)); The double brackets "((" and "))" are needed since MPFR must still compile with non GNU compiler, so Macros with variable # of args are not allowed. It uses the extension of the mpfr_printf function: %Rf to display a mpfr_t. %Ru is used to display the precision of a mpfr_t. It uses some extended attributes of GCC (constructor, etc.) to achieve its goals too. =========================================================================== ZivLoop Controller Ziv strategy is quite used in MPFR. In order to factorize the code, you could use theses macros: +++ MPFR_ZIV_DECL(_x) Declare a ZivLoop controller +++ MPFR_ZIV_INIT(_x, _prec) Init a ZivLoop controller according to the initial value of _prec. +++ MPFR_ZIV_NEXT(_x, _prec) Increase the precision _prec according to the ZivLoop controller. +++ MPFR_ZIV_FREE(_x) Free the ZivLoop controller. =========================================================================== If you plan to add a new function, you could follow this schema: int mpfr_toto (mpfr_ptr rop, mpfr_srcptr op, mpfr_rnd_t rnd) { [Declare all used variables] int inexact; mpfr_prec_t prec; MPFR_ZIV_DECL (loop); MPFR_SAVE_EXPO_DECL (expo); /* Log it if requested */ MPFR_LOG_BEGIN (("op[%Pu]=%.*Rg rnd=%d", mpfr_get_prec (op), mpfr_log_prec, op, rnd), ("rop[%Pu]=%.*Rg inexact=%d", mpfr_get_prec (rop), mpfr_log_prec, rop, inexact)); /* First deal with particular cases */ if (MPFR_UNLIKELY (MPFR_IS_SINGULAR (op))) { if (MPFR_IS_NAN (op)) { MPFR_SET_NAN (rop); MPFR_RET_NAN; } else if (MPFR_IS_INF (op)) { [Code to deal with Infinity] } else { MPFR_ASSERTD (MPFR_IS_ZERO (op)); [Code to deal with Zero] } } [Other particular case: For example, op<0 or op == 1] [Compute the first estimation of the used precision `prec`] [Initialize the intermediate variables using mpfr_init2] MPFR_SAVE_EXPO_MARK (expo); /* Maximal range for exponent */ MPFR_ZIV_INIT (loop, prec); /* Initialize the ZivLoop controller */ for (;;) /* Infinite loop */ { [Compute an estimation of the function and] [an estimate of the error.] if (MPFR_CAN_ROUND (...)) /* If we can round, quit the loop */ break; MPFR_ZIV_NEXT (loop, prec); /* Increase used precision */ [Use `mpfr_set_prec` to resize all needed intermediate variables] } MPFR_ZIV_FREE (loop); /* Free the ZivLoop Controller */ inexact = mpfr_set (rop, temp, rnd); /* Set rop to the computed value */ [Clear all intermediate variables] MPFR_SAVE_EXPO_FREE (expo); /* Restore exponent range */ return mpfr_check_range (rop, inexact, rnd); /* Check range and quit */ } Make sure that Ziv loops cannot increase the precision forever because of internal exception. Otherwise one gets either a segmentation fault (with limited stack size) or an assertion failure (with unlimited stack size, e.g. with "make check"). Do not use code with side effects inside MPFR_ASSERTD or MPFR_ASSERTN, as assertion checking can be disabled. Exception handling (overflow/underflow in particular): * Warning: To detect exceptions and/or possible error loss due to internal exceptions, testing whether some variable is singular with MPFR_IS_SINGULAR is generally not sufficient! Indeed, in case of overflow (resp. underflow), the value may be rounded (in absolute value) to the largest finite number (resp. to the smallest non-zero number, possible even in round-to-nearest mode). * The MPFR_BLOCK* macros can be useful, e.g. { MPFR_BLOCK_DECL (flags); /* ... */ MPFR_BLOCK (flags, /* expression or statements */) /* ... */ if (MPFR_OVERFLOW (flags)) { /* case of overflow in expression or statements */ } /* ... */ } See mpfr-impl.h (search for MPFR_BLOCK) for more information. =========================================================================== If you plan to add a new threshold in MPFR which could be tuned, you should add its default value in the file `mparam_h.in'. When the script configure finishes, it creates the file `mparam.h' from `mparam_h.in'. Then you needs to modify the program `tuneup.c' to allow it to compute the new threshold. If it is a classical threshold (not complex), you could use this method (example of mpfr_exp): /* Define the threshold as a variable instead of a constant */ mpfr_prec_t mpfr_exp_threshold; #undef MPFR_EXP_THRESHOLD #define MPFR_EXP_THRESHOLD mpfr_exp_threshold /* Include the test function to threshold directly in the test program. It will overide the mpfr_exp coming from libmpfr.a */ #include "exp.c" /* Define the speed function related to mpfr_exp */ static double speed_mpfr_exp (struct speed_params *s) { SPEED_MPFR_FUNC (mpfr_exp); } Then in the function `all', you will have to call the tune function, and write the new THRESHOLD in the file `mparam.h': /* Tune mpfr_exp */ if (verbose) printf ("Tuning mpfr_exp...\n"); tune_simple_func (&mpfr_exp_threshold, speed_mpfr_exp); fprintf (f, "#define MPFR_EXP_THRESHOLD %lu\n", (unsigned long) mpfr_exp_threshold); More complex tuning is possible but needs special attention. =========================================================================== Bit Twiddling Hacks - Sean Eron Anderson maintain a list of tricks to get efficient code on . WARNING: some of those tricks may not take into account possible overflows, and may not be portable. =========================================================================== MPFR manual (mpfr.texi): * Use "significand", not "mantissa". * Use "@minus{}" for the minus character, not "-". * Warning! Texinfo is not like TeX. Whitespace is preserved in the info file. So, do not use additional space for .texi indentation. This also means that you need to care about the typography. Please read Section "Inserting Space" in the Texinfo manual. * Follow the English typography, not the French one! * Beware of the following texinfo bug: http://savannah.gnu.org/bugs/?33329 http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=583558 =========================================================================== Running "make" outputs a lot of information, and warnings are not very visible. The following tool "eet" allows a copy of warning messages to be output to a different window (e.g. xterm or zenity): http://www.vinc17.net/unix/#eet Direct link to the tarball: http://www.vinc17.net/unix/eet.tar.bz2 =========================================================================== Be careful when avoiding "'var' may be used uninitialized in this function" warnings from gcc. Initializing such variables to a dummy value has several drawbacks: * this may prevent other tools (that do static or dynamic analysis) from detecting bugs; * this makes code maintenance more difficult (e.g. when modifying the code, one may more easily forget a real initialization); * this makes the compiler add useless code (though this should not be significant). The INITIALIZED macro can be used to avoid such warnings with gcc, e.g. int INITIALIZED(i); It uses the "int i = i;" pseudo-initialization trick, disabled with other compilers as this is undefined behavior. See: http://gcc.gnu.org/bugzilla/show_bug.cgi?id=36296 If a dummy initialization must be added, use preferably an "invalid" value (e.g. NULL for pointers, or a value that can be checked with MPFR_ASSERTN before using it) that could make the program abort instead of returning an incorrect value in case of a bug in MPFR. =========================================================================== Avoid mixing signed and unsigned types, as this can lead signed types to be automatically converted into unsigned types (usual arithmetic conversions). If such a signed type contains a negative value, the result will probably be incorrect. With MPFR 2.x, this problem could arise with mpfr_exp_t, which is signed, and mpfr_prec_t (mp_prec_t), which was unsigned (it is now signed), meaning that in general, a cast of a mpfr_prec_t into a mpfr_exp_t was needed. Note that such bugs are difficult to detect because they may depend on the platform (e.g., on LP64, 32-bit unsigned int + 64-bit long is OK, but on ILP32, 32-bit int + 32-bit unsigned long is incorrect), but also on the input values. So, do not rely on tests very much. However, if a test works on 32 bits but fails on 64 bits in the extended exponent range (or conversely), the cause may be related to the integer types (e.g. a signness problem or an integer overflow due to different type sizes). =========================================================================== You can use the features related to intmax_t only if _MPFR_H_HAVE_INTMAX_T is defined. In such a case, do not use the macros UINTMAX_MAX, INTMAX_MAX and INTMAX_MIN directly (because they may make the compilation fail), but the MPFR versions: MPFR_UINTMAX_MAX, MPFR_INTMAX_MAX and MPFR_INTMAX_MIN. =========================================================================== Use mpfr_prec_t and mpfr_rnd_t instead of the old types mp_prec_t and mp_rnd_t. Similarly, use mpfr_exp_t instead of GMP's mp_exp_t type (unless you really want mp_exp_t, e.g. for conversions with mpf; but you should not assume that mpfr_exp_t and mp_exp_t are identical). =========================================================================== How to specify (for reading) the minimum exponent or the maximum exponent in the MPFR source depends on the context. 1. The most portable form is mpfr_get_emin() and mpfr_get_emax(). In the MPFR source, this is equivalent to __gmpfr_emin and __gmpfr_emax respectively (macros are defined in mpfr-impl.h; the only difference is that the macros do not evaluate to a lvalue). 2. If the exponent range has been extended, you can use the constants MPFR_EXT_EMIN and MPFR_EXT_EMAX instead. This will be faster if TLS is enabled. It also avoids a bug on some Linux/Sparc machines with some GCC versions and TLS, but this shouldn't be the primary concern, as this might be the other way round on some other machines. This is the most common context. Note: If you really want to specify the current minimum or maximum exponent, do not use MPFR_EMIN_MIN or MPFR_EMAX_MAX, even though they have the same value. This may prevent some form of testing in the future. 3. If you want the minimum and maximum possible exponent values supported by MPFR, use MPFR_EMIN_MIN and MPFR_EMAX_MAX respectively. 4. If you want the minimum and maximum values supported by the mpfr_exp_t type (i.e. the limits of this type), use MPFR_EXP_MIN and MPFR_EXP_MAX respectively. This may be useful for intermediate computations on the exponents. =========================================================================== Because of a bug in the Mac OS X 10.5 linker, avoid tentative definitions (C99, 6.9.2). Depending on the context, use either a simple declaration (with the "extern" storage-class specifier) or an external definition. This is also cleaner. =========================================================================== In case of detected internal error, do not use printf() and exit(). Use assertions (MPFR_ASSERTN) instead. =========================================================================== When adding a test file for a new function (say mpfr_func), you can use the following prototype tfunc.c (to put in the directory 'tests'). This file performs random tests for values of x between -5 and 5, with a precision varying from 2 to 100. You can add your own tests to this basic file. Do not forget to add 'tfunc' in the variable check_PROGRAMS of tests/Makefile.am /* Test file for mpfr_func. Copyright 2017 Free Software Foundation, Inc. Contributed by the AriC and Caramba projects, INRIA. This file is part of the GNU MPFR Library. The GNU MPFR Library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. The GNU MPFR Library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with the GNU MPFR Library; see the file COPYING.LESSER. If not, see http://www.gnu.org/licenses/ or write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. */ #include #include #include #include "mpfr-test.h" #define TEST_FUNCTION mpfr_func #define TEST_RANDOM_EMIN -5 #define TEST_RANDOM_EMAX 5 #include "tgeneric.c" int main (int argc, char *argv[]) { tests_start_mpfr (); test_generic (2, 100, 100); tests_end_mpfr (); return 0; } =========================================================================== NOTE: with "AM_LDFLAGS = -no-install" in tests/Makefile.am, the following is obsolete, as libtool no longer generates wrapper scripts; but it is left here in case negative effects of "AM_LDFLAGS = -no-install" are seen or for users with a special setup. To debug some test program, e.g. tadd, with gdb, you cannot run "gdb tadd" since libtool has generated a wrapper script to link the program against the correct MPFR library. Instead, run: libtool --mode=execute gdb tadd Alternatively, something like LD_PRELOAD=../src/.libs/libmpfr.so gdb .libs/tadd may also work (example for GNU/Linux). Note: for test programs not listed in Makefile.am (check_PROGRAMS), libtool is not used (a static link against MPFR is done via LOADLIBES in Makefile.am), so that gdb should be used in the conventional way. You can use the following wrapper script to have a command that works with both: ------------------------------------------------------------ #!/bin/sh unset cmd case $1 in -*) ;; ?*) test "x$(head -c 2 "$1")" = 'x#!' && \ grep -q "^# Generated by libtool" "$1" && \ cmd="libtool --mode=execute" ;; esac exec $cmd gdb "$@" ------------------------------------------------------------ and alias gdb='/path/to/the/wrapper/script' =========================================================================== For developers - Use of the svn:eol-style Subversion property The svn:eol-style Subversion property is traditionally set to "native" on text files, but this has drawbacks: * On systems where the end-of-line (EOL) sequence is not LF, the obtained files are different from those from the tarballs. This makes maintenance harder. * Some tools under Windows (such as makeinfo of MinGW/MSYS) don't support the MS-Windows EOL sequence CRLF, and the MPFR build fails. For these reasons, the svn:eol-style Subversion property should never be set to "native". =========================================================================== To run the MPFR test suite under valgrind, you may need to do several things. First, as the running time is much longer than usual, you should not use the --enable-tests-timeout configure option, or set the timeout value to a large value; this can be done at run time, e.g. with export MPFR_TESTS_TIMEOUT=0 to disable the timeout, so that you do not need to rebuild MPFR for this purpose. Then just set the VALGRIND environment variable to something like valgrind -q --error-exitcode=1 --leak-check=full before running "make check", or type directly: VALGRIND="valgrind -q --error-exitcode=1 --leak-check=full" make check NOTE: with the new tests/Makefile.am file, the following is obsolete; but it might still be useful under some occasions, e.g. if all the valgrind output needs to be sent to a single file. Before running valgrind, you should run "make check" a first time so that everything is compiled out of valgrind. Then you need the --trace-children=yes valgrind option (a possible exception is when you run an individual test that has been built statically). The reason is that libtool generates wrapper scripts to link the tests against the right libraries. The drawback is that you will get valgrind output for all the processes, including the shell commands from the wrapper scripts (the --trace-children-skip valgrind option will not allow you to filter every unwanted process). But you can filter the output with: sed -n '/= Command: [^ ]*\/\.libs\/lt-/,/= ERROR SUMMARY:/p' For readability, you should redirect the valgrind output to a file. You can use --log-file, but due to --trace-children=yes, you need the %p format specifier in the filename argument to generate a file for each child; however many files will be generated, and it may be better to use the following method to get a single file: valgrind --trace-children=yes --log-fd=3 make check 3> vg.out then sed -n '/= Command: [^ ]*\/\.libs\/lt-/,/= ERROR SUMMARY:/p' vg.out to get only the valgrind output corresponding to the MPFR tests. Or if your shell supports it, you can use a process substitution to filter the valgrind output directly to a file, e.g. with bash or zsh: valgrind --trace-children=yes --log-fd=3 make check 3> >(sed -n \ '/= Command: [^ ]*\/\.libs\/lt-/,/= ERROR SUMMARY:/p' > vg.out) if you do not mind about the buffering delays. =========================================================================== To update the FAQ, checkout the misc directory of the repository root. Modify the faq.xhtml file and run xsltproc --nodtdattr faq-web.xsl faq.xhtml > www/faq.html Check with "svn diff" that this change has been done correctly (in case of incorrect installation of XML tools), validate the files with xmllint --noout --loaddtd --valid faq.xhtml www/faq.html and if everything is OK (no error messages), commit both files. Update the FAQ.html file with update-faq in the doc directory of the MPFR trunk and supported branches.