PageRenderTime 46ms CodeModel.GetById 22ms RepoModel.GetById 0ms app.codeStats 0ms

/trunk/Doc/Manual/Pike.html

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