Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <title>SWIG and Pike</title> | |
5 | <link rel="stylesheet" type="text/css" href="style.css"> | |
6 | </head> | |
7 | ||
8 | <body bgcolor="#ffffff"> | |
9 | <H1><a name="Pike"></a>25 SWIG and Pike</H1> | |
10 | <!-- INDEX --> | |
11 | <div class="sectiontoc"> | |
12 | <ul> | |
13 | <li><a href="#Pike_nn2">Preliminaries</a> | |
14 | <ul> | |
15 | <li><a href="#Pike_nn3">Running SWIG</a> | |
16 | <li><a href="#Pike_nn4">Getting the right header files</a> | |
17 | <li><a href="#Pike_nn5">Using your module</a> | |
18 | </ul> | |
19 | <li><a href="#Pike_nn6">Basic C/C++ Mapping</a> | |
20 | <ul> | |
21 | <li><a href="#Pike_nn7">Modules</a> | |
22 | <li><a href="#Pike_nn8">Functions</a> | |
23 | <li><a href="#Pike_nn9">Global variables</a> | |
24 | <li><a href="#Pike_nn10">Constants and enumerated types</a> | |
25 | <li><a href="#Pike_nn11">Constructors and Destructors</a> | |
26 | <li><a href="#Pike_nn12">Static Members</a> | |
27 | </ul> | |
28 | </ul> | |
29 | </div> | |
30 | <!-- INDEX --> | |
31 | ||
32 | ||
33 | ||
34 | <p> | |
35 | This chapter describes SWIG support for Pike. As of this writing, the | |
36 | SWIG Pike module is still under development and is not considered | |
37 | ready for prime time. The Pike module is being developed against the | |
38 | Pike 7.4.10 release and may not be compatible with previous versions | |
39 | of Pike. | |
40 | </p> | |
41 | ||
42 | <p> | |
43 | This chapter covers most SWIG features, but certain low-level details | |
44 | are covered in less depth than in earlier chapters. At the very | |
45 | least, make sure you read the "<a href="SWIG.html#SWIG">SWIG Basics</a>" | |
46 | chapter.<br> | |
47 | </p> | |
48 | ||
49 | <H2><a name="Pike_nn2"></a>25.1 Preliminaries</H2> | |
50 | ||
51 | ||
52 | <H3><a name="Pike_nn3"></a>25.1.1 Running SWIG</H3> | |
53 | ||
54 | ||
55 | <p> | |
56 | Suppose that you defined a SWIG module such as the following: | |
57 | </p> | |
58 | ||
59 | <div class="code"> | |
60 | <pre>%module example<br><br>%{<br>#include "example.h"<br>%}<br><br>int fact(int n);<br></pre> | |
61 | </div> | |
62 | ||
63 | <p> | |
64 | To build a C extension module for Pike, run SWIG using the <tt>-pike</tt> option : | |
65 | </p> | |
66 | ||
67 | <div class="code"> | |
68 | <pre>$ <b>swig -pike example.i</b><br></pre> | |
69 | </div> | |
70 | ||
71 | <p> | |
72 | If you're building a C++ extension, be sure to add the <tt>-c++</tt> option: | |
73 | </p> | |
74 | ||
75 | <div class="code"> | |
76 | <pre>$ <b>swig -c++ -pike example.i</b><br></pre> | |
77 | </div> | |
78 | ||
79 | <p> | |
80 | This creates a single source file named <tt>example_wrap.c</tt> (or <tt>example_wrap.cxx</tt>, if you | |
81 | ran SWIG with the <tt>-c++</tt> option). | |
82 | The SWIG-generated source file contains the low-level wrappers that need | |
83 | to be compiled and linked with the rest of your C/C++ application to | |
84 | create an extension module. | |
85 | </p> | |
86 | ||
87 | <p> | |
88 | The name of the wrapper file is derived from the name of the input | |
89 | file. For example, if the input file is <tt>example.i</tt>, the name | |
90 | of the wrapper file is <tt>example_wrap.c</tt>. To change this, you | |
91 | can use the <tt>-o</tt> option: | |
92 | </p> | |
93 | ||
94 | <div class="code"> | |
95 | <pre>$ <b>swig -pike -o pseudonym.c example.i</b><br></pre> | |
96 | </div> | |
97 | <H3><a name="Pike_nn4"></a>25.1.2 Getting the right header files</H3> | |
98 | ||
99 | ||
100 | <p> | |
101 | In order to compile the C/C++ wrappers, the compiler needs to know the | |
102 | path to the Pike header files. These files are usually contained in a | |
103 | directory such as | |
104 | </p> | |
105 | ||
106 | <div class="code"> | |
107 | <pre>/usr/local/pike/7.4.10/include/pike<br></pre> | |
108 | </div> | |
109 | ||
110 | <p> | |
111 | There doesn't seem to be any way to get Pike itself to reveal the | |
112 | location of these files, so you may need to hunt around for them. | |
113 | You're looking for files with the names <tt>global.h</tt>, <tt>program.h</tt> | |
114 | and so on. | |
115 | </p> | |
116 | ||
117 | <H3><a name="Pike_nn5"></a>25.1.3 Using your module</H3> | |
118 | ||
119 | ||
120 | <p> | |
121 | To use your module, simply use Pike's <tt>import</tt> statement: | |
122 | </p> | |
123 | ||
124 | <div class="code"><pre> | |
125 | $ <b>pike</b> | |
126 | Pike v7.4 release 10 running Hilfe v3.5 (Incremental Pike Frontend) | |
127 | > <b>import example;</b> | |
128 | > <b>fact(4);</b> | |
129 | (1) Result: 24 | |
130 | </pre></div> | |
131 | ||
132 | <H2><a name="Pike_nn6"></a>25.2 Basic C/C++ Mapping</H2> | |
133 | ||
134 | ||
135 | <H3><a name="Pike_nn7"></a>25.2.1 Modules</H3> | |
136 | ||
137 | ||
138 | <p> | |
139 | All of the code for a given SWIG module is wrapped into a single Pike | |
140 | module. Since the name of the shared library that implements your | |
141 | module ultimately determines the module's name (as far as Pike is | |
142 | concerned), SWIG's <tt>%module</tt> directive doesn't really have any | |
143 | significance. | |
144 | </p> | |
145 | ||
146 | <H3><a name="Pike_nn8"></a>25.2.2 Functions</H3> | |
147 | ||
148 | ||
149 | <p> | |
150 | Global functions are wrapped as new Pike built-in functions. For | |
151 | example, | |
152 | </p> | |
153 | ||
154 | <div class="code"><pre> | |
155 | %module example | |
156 | ||
157 | int fact(int n); | |
158 | </pre></div> | |
159 | ||
160 | <p> | |
161 | creates a new built-in function <tt>example.fact(n)</tt> that works | |
162 | exactly as you'd expect it to: | |
163 | </p> | |
164 | ||
165 | <div class="code"><pre> | |
166 | > <b>import example;</b> | |
167 | > <b>fact(4);</b> | |
168 | (1) Result: 24 | |
169 | </pre></div> | |
170 | ||
171 | <H3><a name="Pike_nn9"></a>25.2.3 Global variables</H3> | |
172 | ||
173 | ||
174 | <p> | |
175 | Global variables are currently wrapped as a pair of of functions, one to get | |
176 | the current value of the variable and another to set it. For example, the | |
177 | declaration | |
178 | </p> | |
179 | ||
180 | <div class="code"><pre> | |
181 | %module example | |
182 | ||
183 | double Foo; | |
184 | </pre></div> | |
185 | ||
186 | <p> | |
187 | will result in two functions, <tt>Foo_get()</tt> and <tt>Foo_set()</tt>: | |
188 | </p> | |
189 | ||
190 | <div class="code"><pre> | |
191 | > <b>import example;</b> | |
192 | > <b>Foo_get();</b> | |
193 | (1) Result: 3.000000 | |
194 | > <b>Foo_set(3.14159);</b> | |
195 | (2) Result: 0 | |
196 | > <b>Foo_get();</b> | |
197 | (3) Result: 3.141590 | |
198 | </pre></div> | |
199 | ||
200 | <H3><a name="Pike_nn10"></a>25.2.4 Constants and enumerated types</H3> | |
201 | ||
202 | ||
203 | <p> | |
204 | Enumerated types in C/C++ declarations are wrapped as Pike constants, | |
205 | not as Pike enums. | |
206 | </p> | |
207 | ||
208 | <H3><a name="Pike_nn11"></a>25.2.5 Constructors and Destructors</H3> | |
209 | ||
210 | ||
211 | <p> | |
212 | Constructors are wrapped as <tt>create()</tt> methods, and destructors are | |
213 | wrapped as <tt>destroy()</tt> methods, for Pike classes. | |
214 | </p> | |
215 | ||
216 | <H3><a name="Pike_nn12"></a>25.2.6 Static Members</H3> | |
217 | ||
218 | ||
219 | <p> | |
220 | Since Pike doesn't support static methods or data for Pike classes, static | |
221 | member functions in your C++ classes are wrapped as regular functions and | |
222 | static member variables are wrapped as pairs of functions (one to get the | |
223 | value of the static member variable, and another to set it). The names of | |
224 | these functions are prepended with the name of the class. | |
225 | For example, given this C++ class declaration: | |
226 | </p> | |
227 | ||
228 | <div class="code"><pre> | |
229 | class Shape | |
230 | { | |
231 | public: | |
232 | static void print(); | |
233 | static int nshapes; | |
234 | }; | |
235 | </pre></div> | |
236 | ||
237 | <p> | |
238 | SWIG will generate a <tt>Shape_print()</tt> method that invokes the static | |
239 | <tt>Shape::print()</tt> member function, as well as a pair of methods, | |
240 | <tt>Shape_nshapes_get()</tt> and <tt>Shape_nshapes_set()</tt>, to get and set | |
241 | the value of <tt>Shape::nshapes</tt>. | |
242 | </p> | |
243 | ||
244 | </body> | |
245 | </html> |