8
8
<body bgcolor="#ffffff">
10
<a name="n1"></a><H1>24 SWIG and Chicken</H1>
10
<H1><a name="Chicken"></a>17 SWIG and Chicken</H1>
13
<li><a href="#n2">Preliminaries</a>
15
<li><a href="#n3">Running SWIG in C mode</a>
16
<li><a href="#n4">Running SWIG in C++ mode</a>
18
<li><a href="#n5">Code Generation</a>
20
<li><a href="#n6">Naming Conventions</a>
21
<li><a href="#n7">Modules and Prefixes</a>
22
<li><a href="#n8">Constants and Variables</a>
23
<li><a href="#n9">Functions</a>
25
<li><a href="#n10">TinyCLOS</a>
26
<li><a href="#n11">Compilation</a>
27
<li><a href="#n12">Linkage</a>
29
<li><a href="#n13">Customized Interpreter</a>
31
<li><a href="#n14">Typemaps</a>
32
<li><a href="#n15">Pointers</a>
33
<li><a href="#n16">Unsupported features</a>
13
<li><a href="#Chicken_nn2">Preliminaries</a>
15
<li><a href="#Chicken_nn3">Running SWIG in C mode</a>
16
<li><a href="#Chicken_nn4">Running SWIG in C++ mode</a>
18
<li><a href="#Chicken_nn5">Code Generation</a>
20
<li><a href="#Chicken_nn6">Naming Conventions</a>
21
<li><a href="#Chicken_nn7">Modules and Prefixes</a>
22
<li><a href="#Chicken_nn8">Constants and Variables</a>
23
<li><a href="#Chicken_nn9">Functions</a>
25
<li><a href="#Chicken_nn10">TinyCLOS</a>
26
<li><a href="#Chicken_nn11">Compilation</a>
27
<li><a href="#Chicken_nn12">Linkage</a>
29
<li><a href="#Chicken_nn13">Shared library</a>
30
<li><a href="#Chicken_nn14">Static binary</a>
32
<li><a href="#Chicken_nn15">Typemaps</a>
33
<li><a href="#Chicken_nn16">Pointers</a>
34
<li><a href="#Chicken_nn17">Unsupported features</a>
61
<a name="n2"></a><H2>24.1 Preliminaries</H2>
64
<H2><a name="Chicken_nn2"></a>17.1 Preliminaries</H2>
65
68
CHICKEN support was introduced to SWIG in version 1.3.18. SWIG
66
69
relies on some recent additions to CHICKEN, which are only
67
70
present in releases of CHICKEN with version number
68
<strong>greater than or equal to <tt>1.0</tt></strong>.
71
<strong>greater than or equal to <tt>1.40</tt></strong>.
70
<br></br> CHICKEN can be downloaded from <a
71
href="http://www.call-with-current-continuation.org/chicken.html">http://www.call-with-current-continuation.org/chicken.html</a>
73
<br> CHICKEN can be downloaded from <a
74
href="http://www.call-with-current-continuation.org/">http://www.call-with-current-continuation.org/</a>
73
76
You may want to look at any of the examples in Examples/chicken/
74
77
or Examples/GIFPlot/Chicken for the basic steps to run SWIG
82
<a name="n3"></a><H3>24.1.1 Running SWIG in C mode</H3>
85
<H3><a name="Chicken_nn3"></a>17.1.1 Running SWIG in C mode</H3>
86
89
To run SWIG CHICKEN in C mode, use
87
90
the -chicken option.
89
94
<pre>% swig -chicken example.i</pre>
91
98
To allow the wrapper to take advantage of future CHICKEN code
92
99
generation improvements, part of the wrapper is direct CHICKEN
93
100
function calls (<tt>example_wrap.c</tt>) and part is CHICKEN
94
101
Scheme (<tt>example.scm</tt>). The basic Scheme code must
95
102
be compiled to C using your system's CHICKEN compiler.
97
106
<pre>% chicken example.scm -output-file oexample.c</pre>
99
110
So for the C mode of SWIG CHICKEN, <tt>example_wrap.c</tt> and
100
111
<tt>oexample.c</tt> are the files that must be compiled to
101
112
object files and linked into your project.
104
<a name="n4"></a><H3>24.1.2 Running SWIG in C++ mode</H3>
115
<H3><a name="Chicken_nn4"></a>17.1.2 Running SWIG in C++ mode</H3>
108
119
To run SWIG CHICKEN in C++ mode, use
109
120
the -chicken -c++ option.
111
124
<pre>% swig -chicken -c++ example.i</pre>
113
128
This will generate <tt>example_wrap.cxx</tt>,
114
129
<tt>example.scm</tt>, <tt>example-generic.scm</tt> and
115
130
<tt>example-clos.scm</tt>. The basic Scheme code must be
116
131
compiled to C using your system's CHICKEN compiler.
118
135
<pre>% chicken example.scm -output-file oexample.c</pre>
120
139
So for the C++ mode of SWIG CHICKEN, <tt>example_wrap.cxx</tt>
121
140
and <tt>oexample.c</tt> are the files that must be compiled to
122
141
object files and linked into your project.
126
<a name="n5"></a><H2>24.2 Code Generation</H2>
129
<a name="n6"></a><H3>24.2.1 Naming Conventions</H3>
145
<H2><a name="Chicken_nn5"></a>17.2 Code Generation</H2>
148
<H3><a name="Chicken_nn6"></a>17.2.1 Naming Conventions</H3>
133
152
Given a C variable, function or constant declaration named
134
153
<tt>Foo_Bar_to_Foo_Baz</tt>, the declaration will be available
135
154
in CHICKEN as an identifier ending with
136
<tt>foo-bar->foo-baz</tt>. That is, an underscore is converted
137
to a dash, '_to_' is converted to an arro, and all characters
138
are sent to lowercase.
155
<tt>Foo-Bar->Foo-Baz</tt>. That is, an underscore is converted
156
to a dash and '_to_' is converted to an arrow.
142
160
Additionally, there is a <em>mixed</em> mode that can be
143
161
specified with the <tt>-mixed</tt> option on the SWIG command
144
162
line. In this mode, the above rules apply with the addition
145
163
that changes in case are indications to SWIG CHICKEN to place a
146
dash in the CHICKEN identifier. For example, a C declartaion
164
dash in the CHICKEN identifier and the name is converted to lowercase.
165
For example, a C declartaion
147
166
named <tt>someDeclaration_xyz</tt> will be available as the
148
167
CHICKEN identifier ending with <tt>some-declaration-xyz</tt>.
152
171
You may control what the CHICKEN identifier will be by using the
153
172
<tt>%rename</tt> SWIG directive in the SWIG interface file.
156
<a name="n7"></a><H3>24.2.2 Modules and Prefixes</H3>
175
<H3><a name="Chicken_nn7"></a>17.2.2 Modules and Prefixes</H3>
171
192
CHICKEN will be able to access the module using the <tt>(declare
172
193
(uses <i>modulename</i>))</tt> CHICKEN Scheme form.
176
197
Normally, for a C declaration <tt>Foo_Bar</tt> with a module
177
198
name of 'example', the corresponding CHICKEN identifier will be
178
<tt>example:foo-bar</tt>. <strong>The module name and a colon is
199
<tt>example:Foo-Bar</tt>. <strong>The module name and a colon is
179
200
prefixed to the CHICKEN identifier</strong> (following normal
180
201
naming conventions).
184
205
You may explicitly override the prefix with the SWIG command
185
206
line option <tt>-prefix <i>whateverprefix</i></tt>, or you may
296
324
<tt>-shared</tt> option if you want to create a dynamically
300
All the following examples assume that the module is named
301
'example' and the following occurs when run:
303
<pre>% chicken-config -home
304
CHICKEN_HOME=/usr/local/share/chicken</pre>
306
Substitute <tt>/usr/local/share/chicken</tt> as appropriate for
310
<a name="n13"></a><H3>24.5.1 Customized Interpreter</H3>
314
We will assume your files are in a directory
315
<tt>/home/jonah/examples</tt>. Make a file as follows:
318
(declare (unit precsi))
319
(declare (uses example))
321
;; any other code you want run before the main interpreter is executed
324
Run SWIG on your interface file as usual, create the 2 wrapper
325
object files, and then either
329
% cd /usr/local/share/chicken
330
% chicken /usr/local/share/chicken/src/csi.scm -optimize-level 3 -quiet \
331
-include-path /usr/local/share/chicken/src \
332
-prologue /usr/local/share/chicken/src/build.scm \
333
-prelude "(declare (uses posix precsi))" \
334
-output-file /home/jonah/examples/csi-example.c
335
% cd /home/jonah/examples
336
% chicken precsi.scm -optimize-level 3 --explicit-use \
337
-output-file precsi.c
338
% gcc precsi.c csi.c <i>wrapper_object_files</i> \
339
`chicken-config -libs` `chicken-config -extra-libs` -o csi-example
345
<pre>% extend-csi precsi -output-file csi-example</pre>
351
<a name="n14"></a><H2>24.6 Typemaps</H2>
328
<H3><a name="Chicken_nn13"></a>17.5.1 Shared library</H3>
332
The easiest way to use SWIG and CHICKEN is to use the csc compiler
333
wrapper provided by CHICKEN. Assume you have a SWIG interface file
334
in example.i and the C functions being wrapped are in example_impl.c.
339
$ swig -chicken example.i
340
$ csc -svk example.scm example_impl.c example_wrap.c
341
$ csi example.so test_script.scm
346
You must be careful not to name the example_impl.c file example.c because
347
when compiling example.scm, csc compiles that into example.c!
350
<H3><a name="Chicken_nn14"></a>17.5.2 Static binary</H3>
353
<p>Again, we can easily use csc to build a binary.</p>
357
$ swig -chicken example.i
358
$ csc -vk example.scm example_impl.c example_wrap.c test_script.scm -o example
363
<H2><a name="Chicken_nn15"></a>17.6 Typemaps</H2>
355
367
The Chicken module handles all types via typemaps. This information is
356
368
read from <code>Lib/chicken/typemaps.i</code> and
357
369
<code>Lib/chicken/chicken.swg</code>.
361
373
Two Chicken-specific typemaps are supported:
362
374
<code>clos_in</code> and <code>clos_out</code>. They are for
363
375
converting TinyCLOS to and from low-level CHICKEN SWIG. Here is
491
<a name="n15"></a><H2>24.7 Pointers</H2>
505
<H2><a name="Chicken_nn16"></a>17.7 Pointers</H2>
495
509
For pointer types, SWIG uses CHICKEN tagged pointers.
497
511
A tagged pointer is an ordinary CHICKEN pointer with an
498
extra slot for an arbitrary Scheme object. With SWIG
499
CHICKEN, this Scheme object is a reference to a type-info
512
extra slot for a void *. With SWIG
513
CHICKEN, this void * is a pointer to a type-info
500
514
structure. So each pointer used as input or output from
501
515
the SWIG-generated CHICKEN wrappers will have type
502
516
information attached to it. This will let the wrappers
508
522
To construct a Scheme object from a C pointer, the wrapper code
509
calls the function <code>swig_new_pointer_obj()</code>, passing
510
stack allocation space of size SWIG_ALLOCSZ_POINTER (see
511
definition in Lib/chicken/chickenrun.swg and also
512
<code>C_alloc()</code> in the CHICKEN documentation) and a
513
pointer to a struct representing the pointer type.
524
<code>SWIG_NewPointerObj(void *ptr, swig_type_info *type, int owner)</code>,
525
The function that calls <code>SWIG_NewPointerObj</code> must have a variable declared
526
<code>C_word *known_space = C_alloc(C_SIZEOF_SWIG_POINTER);</code>
527
It is ok to call <code>SWIG_NewPointerObj</code> more than once,
528
just make sure known_space has enough space for all the created pointers.
516
531
To get the pointer represented by a CHICKEN tagged pointer, the
517
wrapper code calls the function <code>swig_convert_ptr()</code>,
532
wrapper code calls the function
533
<code>SWIG_ConvertPtr(C_word s, void **result, swig_type_info *type, int flags)</code>,
518
534
passing a pointer to a struct representing the expected pointer
519
type. If the Scheme object passed was not a tagged pointer
520
representing a compatible pointer, a non-zero value is returned.
522
<p><strong>Warning:</strong> The Chicken typechecking code seems
523
to be broken (Bug #782468), so that type errors may not be
526
<a name="n16"></a><H2>24.8 Unsupported features</H2>
538
<H2><a name="Chicken_nn17"></a>17.8 Unsupported features</H2>
530
542
<li>No exception handling.</li>
b'\\ No newline at end of file'
added
removed
Doc/Manual/Chicken.html
