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.50 (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). If for some reason, this doesn't work, there's still the old way: run the "prepare" script to generate these files; as the "prepare" script also runs "configure", you must give the options that will be passed to "configure", for instance: ./prepare --with-gmp=/path/to/gmp Give "--help" if you don't know (./prepare --help). Then, you can use the configure script as usual. Read the INSTALL file for more information. If you use GNU tools, you can give "-dev" as the first option to the "prepare" script to get better dependency tracking. 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 developed. If nightly snapshots are built, the date in the yyyymmdd format must be added to the version number, for instance: "2.0.1-20020319". =========================================================================== 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): 0) Make sure that the 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 default thresholds on different architectures with "make tune" and put them in mparam_h.in (make sure to use the latest release of GMP). 2) Check the version and change the suffix to "rc1", "rc2", etc. for the release candidates; remove the suffix for the final release. Update the libtool version too (see Makefile.am). Update the date in mpfr.texi. 3) Update the NEWS file. Update the FAQ.html file with update-faq (and check it). 4) Update the ChangeLog file with "TZ=UTC svn log -rHEAD:0 -v". 5) Generate the release version with "make dist". 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 the --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, with and without GMP built as a shared library, with and without srcdir equal to objdir (../mpfr/configure --srcdir=/users/spaces/pelissip/mpfr/), 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 --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. Test with both "make check" and the worst cases. Try also with gcc's -fno-common option. 7) For the release itself (not the release candidates), if there are no problems, 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). 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_STDINT_H: Define if 'intmax_t' is supported (ISO C99). 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. + 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 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. ===================================================================== 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). ==================================================================== 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. 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 ==================================================================== 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 (maker); ; 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 (maker); ; ==================================================================== 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. =========================================================================== 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_BASE: Base of the outputs (default: 10). MPFR_LOG_PREC: # of digits of the outputs (default: 0, ie. maximum). MPFR_LOG_LEVEL: Max recursive level (default: 7). MPFR_LOG_INPUT: Log the inputs MPFR_LOG_OUTPUT: Log the outputs 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`. ==================================================================== 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")); +++ MPFR_LOG_BEGIN(x) Add this macro at the beginning of a function. Example: int dodo (mpfr_t x, mpfr_t op, int cnt, mp_rnd_t rnd) { [decl] MPFR_LOG_BEGIN (("op[%#R]=%R rnd=%s", op, op, RND2STR(rnd))); +++ MPFR_LOG_END(x) Add this macro at the end of a function. Example: MPFR_LOG_END (("x[%#R]=%R i=%d", x, 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[%#R]=%R rnd=%d", op, op"), ("x[%#R]=%R inexact=%d", x, 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 registers a glibc printf extension %R to display a mpfr_t. %#R 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 Controler 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, mp_rnd_t rnd) { [Declare all used variables] int inexact; mp_prec_t prec; MPFR_ZIV_DECL (loop); MPFR_SAVE_EXPO_DECL (expo); /* Log it if requested */ MPFR_LOG_BEGIN (("op[%#R]=%R rnd=%d", op, op, rnd), ("rop[%#R]=%R inexact=%d", rop, 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 controler */ for (;;) /* Infinite loop */ { [Compute an estimation of the function and] [ an estimation 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 Controler */ 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 */ } =========================================================================== 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 */ mp_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 tune are 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.