Debian Codegraph @

README

raw
1 This module wraps the MPFR library functions.
2
3 The MPFR library is a C library for multiple-precision floating-point
4 computations with exact rounding (also called correct rounding). It
5 is based on the GMP multiple-precision C library.
6
7 The main goal of MPFR is to provide a library for multiple-precision
8 floating-point computation which is both efficient and has a
9 well-defined semantics. It copies the good ideas from the
10 ANSI/IEEE-754 standard for double-precision floating-point
11 arithmetic (53-bit mantissa).
12
13 It also offers a wide range of trig, log, and other functions, and
14 constants.
15
16 MPFR, like GMP, is free. It is distributed under the
17 GNU Lesser General Public License (GNU Lesser GPL).
18
19 Because this module wraps the MPFR functions, it requires that both
20 the GMP C library and the MPFR C library have been installed.
21
22 For the GMP library see:
23 https://gmplib.org
24
25 For the MPFR library see:
26 https://www.mpfr.org
27
28 Minimum required version of gmp is gmp-4.2.0.
29 Minimum required version of mpfr is mpfr-3.0.0.
30 You'll get errors if you try to build Math::MPFR against an
31 insufficiently recent version of the mpfr library.
32 Some features of Math::MPFR require later versions of the gmp and mpfr
33 libraries. If the versions are not sufficiently recent, then those
34 features will not be available.
35
36 To build this module you need perl 5.6.0 or later. I'm not sure of all
37 the requirements to get it to build with earlier versions of perl, but
38 it's definite that the XS code relating to operator overloading will
39 not compile with perl versions prior to 5.6.
40
41 Build in the usual way:
42
43 perl Makefile.PL
44 make
45 make test
46 make install
47 make realclean (must be run before re-building.)
48
49 When building this module, the GMP and MPFR libraries will need to be
50 accessible. If those files are in a location where your compiler does
51 not find them by default, then instead of running 'perl Makefile.PL',
52 you'll need to run:
53
54 perl Makefile.pl INC="-I/path/to/gmp_includes -I/path/to/mpfr_includes"
55 LIBS="-L/path/to/mpfr_lib -lmpfr -L/path/to/gmp_lib -lgmp"
56
57 Other commandline args you may want to provide to 'perl Makefile.PL' are
58 D64=1 (for _Decimal64 support), D128=1 (for _Decimal128 support) and
59 F128=1 (for __float128 support).
60 See the Decimal64/128 and Float128 sections (below).
61 There are also some commandline args that provide some debugging of nvtoa() and doubletoa().
62 See the Debug section below.
63
64 ========
65 Checklib
66 ========
67
68 During the running of the Makefile.PL a check is run to ensure that the
69 gmp and mpfr libraries can be found when needed.
70 This check can be skipped by:
71 a) providing CHECK=0 as a Makefile.PL commmand line argument
72 or
73 b) by uncommenting the line (about line 19) that begins with:
74 #$checklib = 0;
75
76 ==================================
77 64-bit-int and long double support
78 ==================================
79
80 If your perl's Config reports that 'ivsize' is greater than or
81 equal to 8 && 'ivtype' is not 'long', then Math::MPFR will, by default,
82 be built with access to the Rmpfr_*_uj and Rmpfr_*_sj functions. Else,
83 access to those functions is, by default, denied.
84
85 Similarly, if your perl's Config reports that 'nvsize' is greater than
86 8 then Math::MPFR will be built with access to the Rmpfr_*_ld functions.
87
88 I am contactable by email at sisyphus at(@) cpan dot (.) org.
89
90 ===================================
91 Decimal64 and Decimal128 conversion
92 ===================================
93
94 The functions Rmpfr_set_DECIMAL64 and Rmpfr_get_DECIMAL64 allow
95 conversion between Math::Decimal64 (_Decimal64) and Math::MPFR (mpfr_t)
96 objects.
97 For this feature to be available you firstly need a compiler that has
98 the _Decimal64 data type.
99 You'll also need to have a recent version of the mpfr library that has
100 been built with _Decimal64 support (ie that was configured with
101 '--enable-decimal-float').
102
103 This should all be detected and enabled automatically whenever these
104 conditions are met.
105
106 To utilise mpfr's _Decimal64 functionality you also need to install
107 Math::Decimal64.
108
109 If you wish you can avoid _Decimal64 support by providing D64=0 as an
110 argument to the Makefile.PL - ie run 'perl Makefile.PL D64=0';
111 You can ensure _Decimal64 support by providing the argument D64=1.
112
113 Note that forcing 'D64=1' will not work unless the conditions
114 mentioned earlier in this section are met.
115
116 The above holds true also for the Math::Decimal128 and the _Decimal128
117 type. Just replace all occurrences of "64" with "128".
118
119 =========================================================
120 Conversion between Math::Float128 and Math::MPFR objects
121 =========================================================
122
123 If 'perl -V:nvtype' reports __float128, see also the section
124 'Conversion between __float128 NV and Math::MPFR objects', below.
125 This section deals only with conversion between Math::Float128 and
126 Math::MPFR objects - and if your nvtype is __float128 there's
127 probably nothing to be gained by calling on Math::Float128.
128
129 The functions Rmpfr_set_FLOAT128 and Rmpfr_get_FLOAT128 allow
130 conversion between Math::Float128 (__float128) and Math::MPFR (mpfr_t)
131 objects.
132 For this feature to be available you firstly need a compiler that has
133 the __float128 data type.
134 You'll also need to have a recent version (4.0.0 or later) of the mpfr
135 library that has been built with __float128 support (ie that was
136 configured with'--enable-float128').
137
138 This should all be detected and enabled automatically whenever these
139 conditions are met.
140
141 To utilise mpfr's __float128 functionality in this way you also need
142 to install Math::Float128.
143
144 If you wish you can avoid Math::Float128 support by providing F128=0
145 as an argument to the Makefile.PL - ie run 'perl Makefile.PL F128=0';
146 You can ensure Math::Float128 support by providing the argument F128=1.
147
148 You can aternatively override the automated procedure by
149 uncommenting one of a number of lines of code near the start of the
150 Makefile.PL. (The comments in the Makefile.PL are a clear statement
151 of what's required for this.)
152
153 Note that forcing inclusion of Math::Float128 support will not work
154 unless the conditions mentioned earlier in this section are met.
155
156 ==========================================================
157 Conversion between Math::LongDouble and Math::MPFR objects
158 ==========================================================
159
160 There are 2 functions provided for conversion between Math::LongDouble
161 and Math::MPFR objects:
162
163 Rmpfr_set_LD (assign the value of a Math::LongDouble object to a
164 Math::MPFR object)
165 Rmpfr_get_LD (assign the value of a Math::MPFR object to a
166 Math::Long Double object)
167
168 If your perl's nvtype is long double, just use Rmpfr_set_ld and
169 Rmpfr_get_ld instead.
170 Math::LongDouble provides 'long double' support for perls whose
171 nvtype is other than 'long double'.
172
173 =======================================================
174 Conversion between __float128 NV and Math::MPFR objects
175 =======================================================
176
177 To determine your nvtype, run 'perl -V:nvtype'.
178 As of perl-5.21.4 it is possible to build perl with an nvtype of
179 __float128. This is achieved by specifying -Dusequadmath as a
180 Configure arg .... but, it will not work for all architectures
181 and compilers.
182
183 If $Config{nvtype} specifies '__float128' && if your mpfr library
184 (need 4.0.0 or later) was built with --enable-float128 then you
185 can pass your __float128 NV values to and from Math::MPFR using
186 the Rmpfr_set_float128() and Rmpfr_get_float128() functions.
187 And the overloaded operations will also accept the __float128 NV
188 arguments as one would want.
189
190 This should all be detected and enabled automatically whenever these
191 conditions are met.
192 NOTE: Even if the mpfr library was not built with __float128 support
193 and the conditions are therefore not met, you can still pass
194 and receive __float128 values to/from Math::MPFR by instead
195 using the functions Rmpfr_get_NV and Rmpfr_set_NV - but that
196 happens only if your nvtype is __float128.
197
198 If you wish you can avoid __float128 support by providing F128=0 as
199 an argument to the Makefile.PL - ie run 'perl Makefile.PL F128=0';
200 You can ensure __float128 support by providing the argument F128=1.
201
202 Note that forcing inclusion of __float128 support will not work
203 unless the conditions mentioned earlier in this section are met.
204
205 =====
206 Debug
207 =====
208
209 If the Makefile.PL is given an argument that matches /NVTOA_DEBUG/i
210 then intermediate values in nvtoa() will be printed to STDERR.
211 In general, this will produce unwelcome clutter, but the option to
212 build Math::MPFR with -DNVTOA_DEBUG is there, if it's ever useful.
213
214 If the Makefile.PL is given an argument that matches /DTOA_ASSERT/i
215 then some assertion checks are run at various points in doubletoa().
216 If the assertion fails, then the program croaks with the relevant
217 diagnostic message.
218
219 When doubletoa() fails to determine the value of $nv, and falls
220 back to returning sprintf("%.16e", $nv), then the default
221 behaviour is to increase $Math::MPFR::doubletoa_fallback by 1.
222 If you wish to ignore such events, simply provide the Makefie.PL
223 with the argument FB=0 .
224 See the doubletoa() documentation in MPFR.pod.
225
226 ===============================
227 MS WINDOWS (Visual Studio 2019)
228 ===============================
229
230 I don't know how to build the gmp and mpfr libraries using Visual Studio
231 2019, so when building this module with Visual Studio 2019 I build
232 against gmp and mpfr libraries that were built using MinGW-w64.
233
234 Building with Visual Studio 2019 against *dynamic* gmp/mpfr libraries
235 that were built using a MinGW-w64 compiler is not recommended, as strange
236 results can then arise when calling mpfr functions that take a FILE*
237 argument.
238
239 If building with Visual Studio 2019 against static gmp/mpfr libs that were
240 built using a MinGW-w64 compiler I first make a copy of the gmp and mpfr
241 libraries (libgmp.a and libmpfr.a) along with copies of the following
242 MinGW-w64 library files:
243 libgcc.a
244 libgcc_s.a
245 libmingwex.a
246 libmingw32.a
247
248 For each of the 6 copied files, I leave the filename unchanged (though the
249 "lib" at the begining of the name is optional), and change the file
250 extension to ".lib".
251 In making those copies, I've left them in the same directory as the
252 original, but I assume (untested) that the copies could be moved to any
253 location of your choice.
254
255 Then build this module by cd'ing to the top level Math::MPFR source folder
256 and running:
257
258 perl Makefile.PL CHECK=0 INC="-IC:/path/to/gmp_header" LIBS="-LC:/path/to/libgcc -lgcc -LC:/path/to/libgcc_s -lgcc_s -LC:/path/to/standard_libs -lmingwex -lmingw32 -LC:/path/to/libgmp -lmpfr -lgmp"
259 nmake test
260 nmake install
261
262 NOTES
263 The given example "perl Makefile.PL ..." command assumes:
264 1) that both mpfr.h and gmp.h are in C:/path/to/gmp_header;
265 2) that libmingwex and libmingw32 libraries are in the same location;
266 3) that libmpfr.lib and libgmp.lib are in C:/path/to/libgmp.
267 Modify as necessary.
268