← Back to branch summary

~ubuntu-branches/ubuntu/edgy/swig1.3/edgy

« back to all changes in this revision

Viewing changes to Doc/Manual/Scripting.html

  • Committer: Bazaar Package Importer
  • Author(s): Adam Conrad
  • Date: 2005-12-05 01:16:04 UTC
  • mfrom: (1.2.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20051205011604-ygx904it6413k3go
Tags: 1.3.27-1ubuntu1
Resynchronise with Debian again, for the new subversion packages.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/Manual/Scripting.html
2
2
<html>
3
3
<head>
4
4
<title>Scripting Languages</title>
 
5
<link rel="stylesheet" type="text/css" href="style.css">
5
6
</head>
6
7
 
7
8
<body bgcolor="#ffffff">
8
9
<H1><a name="Scripting"></a>4 Scripting Languages</H1>
9
10
<!-- INDEX -->
 
11
<div class="sectiontoc">
10
12
<ul>
11
13
<li><a href="#Scripting_nn2">The two language view of the world</a>
12
14
<li><a href="#Scripting_nn3">How does a scripting language talk to C?</a>
24
26
<li><a href="#Scripting_nn12">Static linking</a>
25
27
</ul>
26
28
</ul>
 
29
</div>
27
30
<!-- INDEX -->
28
31
 
29
32
 
30
33
 
 
34
<p>
31
35
This chapter provides a brief overview of scripting language extension
32
36
programming and the mechanisms by which scripting language interpreters
33
37
access C and C++ code.
 
38
</p>
34
39
 
35
40
<H2><a name="Scripting_nn2"></a>4.1 The two language view of the world</H2>
36
41
 
66
71
<H2><a name="Scripting_nn3"></a>4.2 How does a scripting language talk to C?</H2>
67
72
 
68
73
 
 
74
<p>
69
75
Scripting languages are built around a parser that knows how
70
76
to execute commands and scripts.  Within this parser, there is a
71
77
mechanism for executing commands and accessing variables.
75
81
most languages define a special API for adding new commands.
76
82
Furthermore, a special foreign function interface defines how these
77
83
new commands are supposed to hook into the interpreter.
 
84
</p>
78
85
 
79
86
<p>
80
87
Typically, when you add a new command to a scripting interpreter
92
99
<p>
93
100
Suppose you have an ordinary C function like this :</p>
94
101
 
95
 
<blockquote><pre>
 
102
<div class="code"><pre>
96
103
int fact(int n) {
97
104
        if (n &lt;= 1) return 1;
98
105
        else return n*fact(n-1);
99
106
}
100
 
</pre></blockquote>
 
107
</pre></div>
101
108
 
102
109
<p>
103
110
In order to access this function from a scripting language, it is
115
122
As an example, the Tcl wrapper function for the <tt>fact()</tt>
116
123
function above example might look like the following : </p>
117
124
 
118
 
<blockquote><pre>
 
125
<div class="code"><pre>
119
126
int wrap_fact(ClientData clientData, Tcl_Interp *interp,
120
127
                int argc, char *argv[]) {
121
128
        int result;
130
137
        return TCL_OK;
131
138
}
132
139
 
133
 
</pre></blockquote>
 
140
</pre></div>
134
141
 
135
142
<p>
136
143
Once you have created a wrapper function, the final step is to tell the
139
146
loaded. For example, adding the above function to the Tcl interpreter
140
147
requires code like the following :</p>
141
148
 
142
 
<blockquote><pre>
 
149
<div class="code"><pre>
143
150
int Wrap_Init(Tcl_Interp *interp) {
144
151
        Tcl_CreateCommand(interp, "fact", wrap_fact, (ClientData) NULL,
145
152
                                (Tcl_CmdDeleteProc *) NULL);
146
153
        return TCL_OK;
147
154
}
148
 
</pre></blockquote>
 
155
</pre></div>
149
156
 
150
157
<p>
151
158
When executed, Tcl will now have a new command called "<tt>fact</tt>"
167
174
language interpeter. For example, suppose you had the following
168
175
variable:</p>
169
176
 
170
 
<blockquote><pre>
 
177
<div class="code"><pre>
171
178
double Foo = 3.5;
172
 
</pre></blockquote>
 
179
</pre></div>
173
180
 
174
181
<p>
175
182
It might be nice to access it from a script as follows (shown for Perl):</p>
176
183
 
177
 
<blockquote><pre>
 
184
<div class="targetlang"><pre>
178
185
$a = $Foo * 2.3;   # Evaluation
179
186
$Foo = $a + 2.0;   # Assignment
180
 
</pre></blockquote>
 
187
</pre></div>
181
188
 
182
189
<p>
183
190
To provide such access, variables are commonly manipulated using a
197
204
<H3><a name="Scripting_nn6"></a>4.2.3 Constants</H3>
198
205
 
199
206
 
 
207
<p>
200
208
In many cases, a C program or library may define a large collection of
201
209
constants.  For example:
 
210
</p>
202
211
 
203
 
<blockquote><pre>
 
212
<div class="code"><pre>
204
213
#define RED   0xff0000
205
214
#define BLUE  0x0000ff
206
215
#define GREEN 0x00ff00
207
 
</pre></blockquote>
208
 
 
 
216
</pre></div>
 
217
<p>
209
218
To make constants available, their values can be stored in scripting
210
219
language variables such as <tt>$RED</tt>, <tt>$BLUE</tt>, and
211
220
<tt>$GREEN</tt>.  Virtually all scripting languages provide C
212
221
functions for creating variables so installing constants is usually
213
222
a trivial exercise.
 
223
</p>
214
224
 
215
225
<H3><a name="Scripting_nn7"></a>4.2.4 Structures and classes</H3>
216
226
 
217
227
 
 
228
<p>
218
229
Although scripting languages have no trouble accessing simple
219
230
functions and variables, accessing C/C++ structures and classes
220
231
present a different problem.  This is because the implementation
222
233
data representation and layout.  Furthermore, certain language features
223
234
are difficult to map to an interpreter.  For instance, what
224
235
does C++ inheritance mean in a Perl interface?
 
236
</p>
225
237
 
226
238
<p>
227
239
The most straightforward technique for handling structures is to
229
241
representation of a structure.  For example, 
230
242
</p>
231
243
 
232
 
<blockquote><pre>
 
244
<div class="code"><pre>
233
245
struct Vector {
234
246
        Vector();
235
247
        ~Vector();
236
248
        double x,y,z;
237
249
};
238
250
 
239
 
</pre></blockquote>
 
251
</pre></div>
 
252
 
 
253
<p>
240
254
can be transformed into the following set of functions :
 
255
</p>
241
256
 
242
 
<blockquote><pre>
 
257
<div class="code"><pre>
243
258
Vector *new_Vector();
244
259
void delete_Vector(Vector *v);
245
260
double Vector_x_get(Vector *v);
246
261
double Vector_y_get(Vector *v);
247
 
double Vector_y_get(Vector *v);
 
262
double Vector_z_get(Vector *v);
248
263
void Vector_x_set(Vector *v, double x);
249
264
void Vector_y_set(Vector *v, double y);
250
265
void Vector_z_set(Vector *v, double z);
251
266
 
252
 
</pre></blockquote>
253
 
 
 
267
</pre></div>
 
268
<p>
254
269
Now, from an interpreter these function might be used as follows:
 
270
</p>
255
271
 
256
 
<blockquote><pre>
 
272
<div class="targetlang"><pre>
257
273
% set v [new_Vector]
258
274
% Vector_x_set $v 3.5
259
275
% Vector_y_get $v
260
276
% delete_Vector $v
261
277
% ...
262
 
</pre></blockquote>
 
278
</pre></div>
263
279
 
264
280
<p>
265
281
Since accessor functions provide a mechanism for accessing the
279
295
C++ class). For example, if you
280
296
have the following C definition :</p>
281
297
 
282
 
<blockquote><pre>
 
298
<div class="code"><pre>
283
299
class Vector {
284
300
public:
285
301
        Vector();
286
302
        ~Vector();
287
303
        double x,y,z;
288
304
};
289
 
</pre></blockquote>
 
305
</pre></div>
290
306
 
291
307
<p>
292
308
A proxy classing mechanism would allow you to access the structure in
293
309
a more natural manner from the interpreter. For example, in Python, you might want to do this:
294
310
</p>
295
311
 
296
 
<blockquote><pre>
 
312
<div class="targetlang"><pre>
297
313
&gt;&gt;&gt; v = Vector()
298
314
&gt;&gt;&gt; v.x = 3
299
315
&gt;&gt;&gt; v.y = 4
300
316
&gt;&gt;&gt; v.z = -13
301
317
&gt;&gt;&gt; ...
302
318
&gt;&gt;&gt; del v
303
 
</pre></blockquote>
 
319
</pre></div>
304
320
 
305
321
<p>
306
322
Similarly, in Perl5 you may want the interface to work like this:</p>
307
323
 
308
 
<blockquote><pre>
 
324
<div class="targetlang"><pre>
309
325
$v = new Vector;
310
326
$v-&gt;{x} = 3;
311
327
$v-&gt;{y} = 4;
312
328
$v-&gt;{z} = -13;
313
329
 
314
 
</pre></blockquote>
315
 
 
 
330
</pre></div>
 
331
<p>
316
332
Finally, in Tcl :
 
333
</p>
317
334
 
318
 
<blockquote><pre>
 
335
<div class="targetlang"><pre>
319
336
Vector v
320
337
v configure -x 3 -y 4 -z 13
321
338
 
322
 
</pre></blockquote>
 
339
</pre></div>
323
340
 
324
341
<p>
325
342
When proxy classes are used, two objects are at really work--one in
349
366
manual pages for your compiler and linker.  However, the procedure
350
367
for a few common machines is shown below:</p>
351
368
 
352
 
<blockquote><pre>
 
369
<div class="shell"><pre>
353
370
# Build a shared library for Solaris
354
371
gcc -c example.c example_wrap.c -I/usr/local/include
355
372
ld -G example.o example_wrap.o -o example.so
356
373
 
357
374
# Build a shared library for Linux
358
 
agcc -fpic -c example.c example_wrap.c -I/usr/local/include
 
375
gcc -fpic -c example.c example_wrap.c -I/usr/local/include
359
376
gcc -shared example.o example_wrap.o -o example.so
360
377
 
361
378
# Build a shared library for Irix
362
379
gcc -c example.c example_wrap.c -I/usr/local/include
363
380
ld -shared example.o example_wrap.o -o example.so
364
381
 
365
 
</pre></blockquote>
 
382
</pre></div>
366
383
 
367
384
<p>
368
385
To use your shared library, you simply use the corresponding command
370
387
import your module and allow you to start using it. For example:
371
388
</p>
372
389
 
373
 
<blockquote><pre>
 
390
<div class="targetlang"><pre>
374
391
% load ./example.so
375
392
% fact 4
376
393
24
377
394
%
378
 
</pre></blockquote>
 
395
</pre></div>
379
396
 
380
397
<p>
381
398
When working with C++ codes, the process of building shared libraries
384
401
can build a shared C++ module by following the above procedures, but
385
402
changing the link line to the following :</p>
386
403
 
387
 
<blockquote><pre>
 
404
<div class="shell"><pre>
388
405
c++ -shared example.o example_wrap.o -o example.so
389
 
</pre></blockquote>
 
406
</pre></div>
390
407
 
391
408
<H3><a name="Scripting_nn11"></a>4.3.2 Linking with shared libraries</H3>
392
409
 
398
415
these libraries at run-time. Otherwise, you may get an error such as
399
416
the following :</p>
400
417
 
401
 
<blockquote><pre>
 
418
<div class="targetlang"><pre>
402
419
&gt;&gt;&gt; import graph
403
420
Traceback (innermost last):
404
421
  File "&lt;stdin&gt;", line 1, in ?
408
425
successfully map soname 'libgraph.so' under any of the filenames /usr/lib/libgraph.so:/
409
426
lib/libgraph.so:/lib/cmplrs/cc/libgraph.so:/usr/lib/cmplrs/cc/libgraph.so:
410
427
&gt;&gt;&gt;
411
 
</pre></blockquote>
 
428
</pre></div>
412
429
<p>
413
430
 
414
431
What this error means is that the extension module created by SWIG