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
|
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.51
from cln.texi on 2 Febuary 1998 -->
<TITLE>CLN, a Class Library for Numbers - 11 Using the library</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="cln_1.html">first</A>, <A HREF="cln_10.html">previous</A>, <A HREF="cln_12.html">next</A>, <A HREF="cln_13.html">last</A> section, <A HREF="cln_toc.html">table of contents</A>.
<P><HR><P>
<H1><A NAME="SEC61" HREF="cln_toc.html#TOC61">11 Using the library</A></H1>
<P>
For the following discussion, we will assume that you have installed
the CLN source in <CODE>$CLN_DIR</CODE> and built it in <CODE>$CLN_TARGETDIR</CODE>.
For example, for me it's <CODE>CLN_DIR="$HOME/cln"</CODE> and
<CODE>CLN_TARGETDIR="$HOME/cln/linuxelf"</CODE>. You might define these as
environment variables, or directly substitute the appropriate values.
</P>
<H2><A NAME="SEC62" HREF="cln_toc.html#TOC62">11.1 Compiler options</A></H2>
<P>
Until you have installed CLN in a public place, the following options are
needed:
</P>
<P>
When you compile CLN application code, add the flags
<PRE>
-I$CLN_DIR/include -I$CLN_TARGETDIR/include
</PRE>
<P>
to the C++ compiler's command line (<CODE>make</CODE> variable CFLAGS or CXXFLAGS).
When you link CLN application code to form an executable, add the flags
<PRE>
$CLN_TARGETDIR/src/libcln.a
</PRE>
<P>
to the C/C++ compiler's command line (<CODE>make</CODE> variable LIBS).
</P>
<P>
If you did a <CODE>make install</CODE>, the include files are installed in a
public directory (normally <CODE>/usr/local/include</CODE>), hence you don't
need special flags for compiling. The library has been installed to a
public directory as well (normally <CODE>/usr/local/lib</CODE>), hence when
linking a CLN application it is sufficient to give the flag <CODE>-lcln</CODE>.
</P>
<H2><A NAME="SEC63" HREF="cln_toc.html#TOC63">11.2 Include files</A></H2>
<P>
Here is a summary of the include files and their contents.
</P>
<DL COMPACT>
<DT><CODE><cl_object.h></CODE>
<DD>
General definitions, reference counting, garbage collection.
<DT><CODE><cl_number.h></CODE>
<DD>
The ordinary number classes.
<DT><CODE><cl_real.h></CODE>
<DD>
Functions for class cl_R, the real numbers.
<DT><CODE><cl_float.h></CODE>
<DD>
Functions for class cl_F, the floats.
<DT><CODE><cl_sfloat.h></CODE>
<DD>
Functions for class cl_SF, the short-floats.
<DT><CODE><cl_ffloat.h></CODE>
<DD>
Functions for class cl_FF, the single-floats.
<DT><CODE><cl_dfloat.h></CODE>
<DD>
Functions for class cl_DF, the double-floats.
<DT><CODE><cl_lfloat.h></CODE>
<DD>
Functions for class cl_LF, the long-floats.
<DT><CODE><cl_rational.h></CODE>
<DD>
Functions for class cl_RA, the rational numbers.
<DT><CODE><cl_integer.h></CODE>
<DD>
Functions for class cl_I, the integers.
<DT><CODE><cl_complex.h></CODE>
<DD>
Functions for class cl_N, the complex numbers.
<DT><CODE><cl_random.h></CODE>
<DD>
Random number generators.
<DT><CODE><cl_malloc.h></CODE>
<DD>
<CODE>cl_malloc_hook</CODE>, <CODE>cl_free_hook</CODE>.
<DT><CODE><cl_abort.h></CODE>
<DD>
<CODE>cl_abort</CODE>.
<DT><CODE><cl_io.h></CODE>
<DD>
Input/Output.
<DT><CODE><cl_input.h></CODE>
<DD>
Flags for customizing input operations.
<DT><CODE><cl_output.h></CODE>
<DD>
Flags for customizing output operations.
<DT><CODE><cl_condition.h></CODE>
<DD>
Conditions/exceptions.
<DT><CODE><cl_string.h></CODE>
<DD>
Strings.
<DT><CODE><cl_symbol.h></CODE>
<DD>
Symbols.
<DT><CODE><cl_proplist.h></CODE>
<DD>
Property lists.
<DT><CODE><cl_ring.h></CODE>
<DD>
General rings.
<DT><CODE><cl_numtheory.h></CODE>
<DD>
Number threory functions.
<DT><CODE><cl_modinteger.h></CODE>
<DD>
Modular integers.
<DT><CODE><cl_V.h></CODE>
<DD>
Vectors.
<DT><CODE><cl_GV.h></CODE>
<DD>
General vectors.
<DT><CODE><cl_GV_integer.h></CODE>
<DD>
General vectors over cl_I.
<DT><CODE><cl_GV_rational.h></CODE>
<DD>
General vectors over cl_RA.
<DT><CODE><cl_GV_real.h></CODE>
<DD>
General vectors over cl_R.
<DT><CODE><cl_GV_complex.h></CODE>
<DD>
General vectors over cl_N.
<DT><CODE><cl_GV_modinteger.h></CODE>
<DD>
General vectors of modular integers.
<DT><CODE><cl_SV.h></CODE>
<DD>
Simple vectors.
<DT><CODE><cl_SV_integer.h></CODE>
<DD>
Simple vectors over cl_I.
<DT><CODE><cl_SV_rational.h></CODE>
<DD>
Simple vectors over cl_RA.
<DT><CODE><cl_SV_real.h></CODE>
<DD>
Simple vectors over cl_R.
<DT><CODE><cl_SV_complex.h></CODE>
<DD>
Simple vectors over cl_N.
<DT><CODE><cl_SV_ringelt.h></CODE>
<DD>
Simple vectors of general ring elements.
<DT><CODE><cl_univpoly.h></CODE>
<DD>
Univariate polynomials.
<DT><CODE><cl_univpoly_integer.h></CODE>
<DD>
Univariate polynomials over the integers.
<DT><CODE><cl_univpoly_rational.h></CODE>
<DD>
Univariate polynomials over the rational numbers.
<DT><CODE><cl_univpoly_real.h></CODE>
<DD>
Univariate polynomials over the real numbers.
<DT><CODE><cl_univpoly_complex.h></CODE>
<DD>
Univariate polynomials over the complex numbers.
<DT><CODE><cl_univpoly_modint.h></CODE>
<DD>
Univariate polynomials over modular integer rings.
<DT><CODE><cl_timing.h></CODE>
<DD>
Timing facilities.
<DT><CODE><cln.h></CODE>
<DD>
Includes all of the above.
</DL>
<H2><A NAME="SEC64" HREF="cln_toc.html#TOC64">11.3 An Example</A></H2>
<P>
(This section still needs to be written.)
</P>
<H2><A NAME="SEC65" HREF="cln_toc.html#TOC65">11.4 Debugging support</A></H2>
<P>
When debugging a CLN application with GNU <CODE>gdb</CODE>, two facilities are
available from the library:
</P>
<UL>
<LI>The library does type checks, range checks, consistency checks at
many places. When one of these fails, the function <CODE>cl_abort()</CODE> is
called. Its default implementation is to perform an <CODE>exit(1)</CODE>, so
you won't have a core dump. But for debugging, it is best to set a
breakpoint at this function:
<PRE>
(gdb) break cl_abort
</PRE>
When this breakpoint is hit, look at the stack's backtrace:
<PRE>
(gdb) where
</PRE>
<LI>The debugger's normal <CODE>print</CODE> command doesn't know about
CLN's types and therefore prints mostly useless hexadecimal addresses.
CLN offers a function <CODE>cl_print</CODE>, callable from the debugger,
for printing number objects. In order to get this function, you have
to define the macro <SAMP>`CL_DEBUG'</SAMP> and then include all the header files
for which you want <CODE>cl_print</CODE> debugging support. For example:
<PRE>
#define CL_DEBUG
#include <cl_string.h>
</PRE>
Now, if you have in your program a variable <CODE>cl_string s</CODE>, and
inspect it under <CODE>gdb</CODE>, the output may look like this:
<PRE>
(gdb) print s
$7 = {<cl_gcpointer> = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
word = 134568800}}, }
(gdb) call cl_print(s)
(cl_string) ""
$8 = 134568800
</PRE>
Note that the output of <CODE>cl_print</CODE> goes to the program's error output,
not to gdb's standard output.
Note, however, that the above facility does not work with all CLN types,
only with number objects and similar. Therefore CLN offers a member function
<CODE>debug_print()</CODE> on all CLN types. The same macro <SAMP>`CL_DEBUG'</SAMP>
is needed for this member function to be implemented. Under <CODE>gdb</CODE>,
you call it like this:
<PRE>
(gdb) print s
$7 = {<cl_gcpointer> = { = {pointer = 0x8055b60, heappointer = 0x8055b60,
word = 134568800}}, }
(gdb) call s.debug_print()
(cl_string) ""
(gdb) define cprint
>call ($1).debug_print()
>end
(gdb) cprint s
(cl_string) ""
</PRE>
Unfortunately, this feature does not seem to work under all circumstances.
</UL>
<P><HR><P>
Go to the <A HREF="cln_1.html">first</A>, <A HREF="cln_10.html">previous</A>, <A HREF="cln_12.html">next</A>, <A HREF="cln_13.html">last</A> section, <A HREF="cln_toc.html">table of contents</A>.
</BODY>
</HTML>
|
