1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
|
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 <stdio.h> 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.
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 <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.
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.
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.
|