| 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> |