path: root/README.dev

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.

===========================================================================

To make a release (for the MPFR team):

  0) 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).
  1) Check the version and update the date in mpfr.texi.
     Update the libtool version too (see Makefile.am).
  2) Update the NEWS file.
     Update the FAQ.html file with update-faq (and check it).
  3) Update the ChangeLog file. [To be completed]
  4) Generate the release version with "make dist".
  5) Test the release version on different machines, 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
     and in various locales (LC_ALL=tr_TR in particular, if installed).
  6) If there are no problems, add a tag. [To be completed]
  7) Update the version with the update-version script to indicate the
     next version.

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).

   =====================================================================

Quoted from <http://www.gnu.org/software/gcc/codingconventions.html>:

  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 <stdlib.h> defines NULL,
do not use NULL with #include <stdlib.h> 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 <stdio.h> 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.

   ====================================================================

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, ...

===========================================================================

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.

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 */
  MPFR_RET (mpfr_check_range (rop, inexact, rnd));  /* Check range and quit */
}


===========================================================================

If you plan to add a new threshold in MPFR which could be tune, 
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.