PageRenderTime 237ms CodeModel.GetById 20ms RepoModel.GetById 1ms app.codeStats 0ms

/tags/rel-1.3.35/Doc/Manual/Guile.html

#
HTML | 895 lines | 722 code | 170 blank | 3 comment | 0 complexity | 0c6a115fe5fbd212e989680cda3fe978 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. <!-- Hand-written HTML -->
  3. <html>
  4. <head>
  5. <title>SWIG and Guile</title>
  6. <link rel="stylesheet" type="text/css" href="style.css">
  7. </head>
  8. <body bgcolor="#ffffff">
  9. <H1><a name="Guile"></a>19 SWIG and Guile</H1>
  10. <!-- INDEX -->
  11. <div class="sectiontoc">
  12. <ul>
  13. <li><a href="#Guile_nn2">Meaning of "Module"</a>
  14. <li><a href="#Guile_nn3">Using the SCM or GH Guile API</a>
  15. <li><a href="#Guile_nn4">Linkage</a>
  16. <ul>
  17. <li><a href="#Guile_nn5">Simple Linkage</a>
  18. <li><a href="#Guile_nn6">Passive Linkage</a>
  19. <li><a href="#Guile_nn7">Native Guile Module Linkage</a>
  20. <li><a href="#Guile_nn8">Old Auto-Loading Guile Module Linkage</a>
  21. <li><a href="#Guile_nn9">Hobbit4D Linkage</a>
  22. </ul>
  23. <li><a href="#Guile_nn10">Underscore Folding</a>
  24. <li><a href="#Guile_nn11">Typemaps</a>
  25. <li><a href="#Guile_nn12">Representation of pointers as smobs</a>
  26. <ul>
  27. <li><a href="#Guile_nn13">GH Smobs</a>
  28. <li><a href="#Guile_nn14">SCM Smobs</a>
  29. <li><a href="#Guile_nn15">Garbage Collection</a>
  30. </ul>
  31. <li><a href="#Guile_nn16">Exception Handling</a>
  32. <li><a href="#Guile_nn17">Procedure documentation</a>
  33. <li><a href="#Guile_nn18">Procedures with setters</a>
  34. <li><a href="#Guile_nn19">GOOPS Proxy Classes</a>
  35. <ul>
  36. <li><a href="#Guile_nn20">Naming Issues</a>
  37. <li><a href="#Guile_nn21">Linking</a>
  38. </ul>
  39. </ul>
  40. </div>
  41. <!-- INDEX -->
  42. <p>
  43. This section details guile-specific support in SWIG.
  44. <H2><a name="Guile_nn2"></a>19.1 Meaning of "Module"</H2>
  45. <p>
  46. There are three different concepts of "module" involved, defined
  47. separately for SWIG, Guile, and Libtool. To avoid horrible confusion,
  48. we explicitly prefix the context, e.g., "guile-module".
  49. <H2><a name="Guile_nn3"></a>19.2 Using the SCM or GH Guile API</H2>
  50. <p>The guile module can currently export wrapper files that use the guile GH interface or the
  51. SCM interface. This is controlled by an argument passed to swig. The "-gh" argument causes swig
  52. to output GH code, and the "-scm" argument causes swig to output SCM code. Right now the "-scm" argument
  53. is the default. The "-scm" wrapper generation assumes a guile version &gt;= 1.6 and has several advantages over
  54. the "-gh" wrapper generation including garbage collection and GOOPS support.
  55. The "-gh" wrapper generation can be used for older versions of guile.
  56. The guile GH wrapper code generation is depreciated and the
  57. SCM interface is the default. The SCM and GH interface differ greatly in how they store
  58. pointers and have completely different run-time code. See below for more info.
  59. <p>The GH interface to guile is deprecated. Read more about why in the
  60. <a href="http://www.gnu.org/software/guile/docs/guile-ref/GH-deprecation.html">Guile manual</a>.
  61. The idea of the GH interface was to provide a high level API that other languages and projects
  62. could adopt. This was a good idea, but didn't pan out well for general development. But for the
  63. specific, minimal uses that the SWIG typemaps put the GH interface to use is ideal for
  64. using a high level API. So even though the GH interface is depreciated, SWIG will continue to use
  65. the GH interface and provide mappings from the GH interface to whatever API we need.
  66. We can maintain this mapping where guile failed because SWIG uses a small subset of all the GH functions
  67. which map easily. All the guile typemaps like typemaps.i and std_vector.i
  68. will continue to use the GH functions to do things like create lists of values, convert strings to
  69. integers, etc. Then every language module will define a mapping between the GH interface and
  70. whatever custom API the language uses. This is currently implemented by the guile module to use
  71. the SCM guile API rather than the GH guile API.
  72. For example, here are some of the current mapping file for the SCM API</p>
  73. <div class="code"><pre>
  74. #define gh_append2(a, b) scm_append(scm_listify(a, b, SCM_UNDEFINED))
  75. #define gh_apply(a, b) scm_apply(a, b, SCM_EOL)
  76. #define gh_bool2scm SCM_BOOL
  77. #define gh_boolean_p SCM_BOOLP
  78. #define gh_car SCM_CAR
  79. #define gh_cdr SCM_CDR
  80. #define gh_cons scm_cons
  81. #define gh_double2scm scm_make_real
  82. ...
  83. </pre></div>
  84. <p>This file is parsed by SWIG at wrapper generation time, so every reference to a gh_ function is replaced
  85. by a scm_ function in the wrapper file. Thus the gh_ function calls will never be seen in the wrapper;
  86. the wrapper will look exactly like it was generated
  87. for the specific API. Currently only the guile language module has created a mapping policy from gh_ to scm_,
  88. but there is no reason other languages (like mzscheme or chicken) couldn't also use this.
  89. If that happens, there is A LOT less code duplication in the standard typemaps.</p>
  90. <H2><a name="Guile_nn4"></a>19.3 Linkage</H2>
  91. <p>
  92. Guile support is complicated by a lack of user community cohesiveness,
  93. which manifests in multiple shared-library usage conventions. A set of
  94. policies implementing a usage convention is called a <b>linkage</b>.
  95. <H3><a name="Guile_nn5"></a>19.3.1 Simple Linkage</H3>
  96. <p>
  97. The default linkage is the simplest; nothing special is done. In this
  98. case the function <code>SWIG_init()</code> is exported. Simple linkage
  99. can be used in several ways:
  100. </p>
  101. <ul>
  102. <li><b>Embedded Guile, no modules.</b> You want to embed a Guile
  103. interpreter into your program; all bindings made by SWIG shall show up
  104. in the root module. Then call <code>SWIG_init()</code> in the
  105. <code>inner_main()</code> function. See the "simple" and "matrix" examples under
  106. <code>Examples/guile</code>.
  107. <li><p><b>Dynamic module mix-in.</b> You want to create a Guile module
  108. using <code>define-module</code>, containing both Scheme code and
  109. bindings made by SWIG; you want to load the SWIG modules as shared
  110. libraries into Guile.</p>
  111. <div class="targetlang">
  112. <pre>
  113. (define-module (my module))
  114. (define my-so (dynamic-link "./example.so"))
  115. (dynamic-call "SWIG_init" my-so) ; make SWIG bindings
  116. ;; Scheme definitions can go here
  117. </pre>
  118. </div>
  119. <p>
  120. Newer Guile versions provide a shorthand for <code>dynamic-link</code>
  121. and <code>dynamic-call</code>:
  122. </p>
  123. <div class="targetlang">
  124. <pre>
  125. (load-extension "./example.so" "SWIG_init")
  126. </pre>
  127. </div>
  128. <p>
  129. You need to explicitly export those bindings made by SWIG that you
  130. want to import into other modules:
  131. </p>
  132. <div class="targetlang">
  133. <pre>
  134. (export foo bar)
  135. </pre>
  136. </div>
  137. <p>
  138. In this example, the procedures <code>foo</code> and <code>bar</code>
  139. would be exported. Alternatively, you can export all bindings with the
  140. following module-system hack:
  141. </p>
  142. <div class="targetlang">
  143. <pre>
  144. (module-map (lambda (sym var)
  145. (module-export! (current-module) (list sym)))
  146. (current-module))
  147. </pre>
  148. </div>
  149. <p>SWIG can also generate this Scheme stub (from
  150. <code>define-module</code> up to <code>export</code>)
  151. semi-automagically if you pass it the command-line argument
  152. <code>-scmstub</code>. The code will be exported in a file called
  153. <code><i>module</i>.scm</code> in the directory specified by <code>-outdir</code>
  154. or the current directory if <code>-outdir</code> is not specified.
  155. Since SWIG doesn't know how
  156. to load your extension module (with <code>dynamic-link</code> or
  157. <code>load-extension</code>), you need to supply this
  158. information by including a directive like this in the interface file:
  159. </p>
  160. <div class="code">
  161. <pre>
  162. %scheme %{ (load-extension "./example.so" "SWIG_init") %}
  163. </pre>
  164. </div>
  165. <p>
  166. (The <code>%scheme</code> directive allows to insert arbitrary Scheme
  167. code into the generated file <code><var>module.scm</var></code>; it is
  168. placed between the <code>define-module</code> form and the
  169. <code>export</code> form.)
  170. </p>
  171. </ul>
  172. <p>If you want to include several SWIG modules, you would need to rename
  173. <code>SWIG_init</code> via a preprocessor define to avoid symbol
  174. clashes. For this case, however, passive linkage is available.
  175. <H3><a name="Guile_nn6"></a>19.3.2 Passive Linkage</H3>
  176. <p>Passive linkage is just like simple linkage, but it generates an
  177. initialization function whose name is derived from the module and
  178. package name (see below).
  179. <p>You should use passive linkage rather than simple linkage when you
  180. are using multiple modules.
  181. <H3><a name="Guile_nn7"></a>19.3.3 Native Guile Module Linkage</H3>
  182. <p>SWIG can also generate wrapper code that does all the Guile module
  183. declarations on its own if you pass it the <code>-Linkage
  184. module</code> command-line option. This requires Guile 1.5.0 or later.
  185. <p>The module name is set with the <code>-package</code> and
  186. <code>-module</code> command-line options. Suppose you want to define
  187. a module with name <code>(my lib foo)</code>; then you would have to
  188. pass the options <code>-package <var>my</var>/<var>lib</var> -module
  189. <var>foo</var></code>. Note that the last part of the name can also be set
  190. via the SWIG directive <code>%module</code>.
  191. <p>You can use this linkage in several ways:
  192. <ul>
  193. <li><b>Embedded Guile with SWIG modules.</b> You want to embed a Guile
  194. interpreter into your program; the SWIG bindings shall be put into
  195. different modules. Simply call the function
  196. <code>scm_init_<var>my</var>_<var>modules</var>_<var>foo</var>_module</code>
  197. in the <code>inner_main()</code> function.
  198. <li><b>Dynamic Guile modules.</b> You want to load the SWIG modules as
  199. shared libraries into Guile; all bindings are automatically put in
  200. newly created Guile modules.
  201. <div class="targetlang">
  202. <pre>
  203. (define my-so (dynamic-link "./foo.so"))
  204. ;; create new module and put bindings there:
  205. (dynamic-call "scm_init_my_modules_foo_module" my-so)
  206. </pre>
  207. </div>
  208. Newer Guile versions have a shorthand procedure for this:
  209. <div class="targetlang">
  210. <pre>
  211. (load-extension "./foo.so" "scm_init_my_modules_foo_module")
  212. </pre>
  213. </div>
  214. </ul>
  215. <H3><a name="Guile_nn8"></a>19.3.4 Old Auto-Loading Guile Module Linkage</H3>
  216. <p>Guile used to support an autoloading facility for object-code
  217. modules. This support has been marked deprecated in version 1.4.1 and
  218. is going to disappear sooner or later. SWIG still supports building
  219. auto-loading modules if you pass it the <code>-Linkage ltdlmod</code>
  220. command-line option.
  221. <p>Auto-loading worked like this: Suppose a module with name <code>(my
  222. lib foo)</code> is required and not loaded yet. Guile will then search
  223. all directories in its search path
  224. for a Scheme file <code>my/modules/foo.scm</code> or a shared library
  225. <code><var>my</var>/<var>modules</var>/lib<var>foo</var>.so</code> (or
  226. <code><var>my</var>/<var>modules</var>/lib<var>foo</var>.la</code>;
  227. see the GNU libtool documentation). If a
  228. shared library is found that contains the symbol
  229. <code>scm_init_<var>my</var>_<var>modules</var>_<var>foo</var>_module</code>,
  230. the library is loaded, and the function at that symbol is called with
  231. no arguments in order to initialize the module.
  232. <p>When invoked with the <code>-Linkage ltdlmod</code> command-line
  233. option, SWIG generates an exported module initialization function with
  234. an appropriate name.
  235. <H3><a name="Guile_nn9"></a>19.3.5 Hobbit4D Linkage</H3>
  236. <p>
  237. The only other linkage supported at this time creates shared object
  238. libraries suitable for use by hobbit's <code>(hobbit4d link)</code>
  239. guile module. This is called the "hobbit" linkage, and requires also
  240. using the "-package" command line option to set the part of the module
  241. name before the last symbol. For example, both command lines:
  242. </p>
  243. <div class="shell">
  244. <pre>
  245. swig -guile -package my/lib foo.i
  246. swig -guile -package my/lib -module foo foo.i
  247. </pre>
  248. </div>
  249. <p>
  250. would create module <code>(my lib foo)</code> (assuming in the first
  251. case foo.i declares the module to be "foo"). The installed files are
  252. my/lib/libfoo.so.X.Y.Z and friends. This scheme is still very
  253. experimental; the (hobbit4d link) conventions are not well understood.
  254. </p>
  255. <H2><a name="Guile_nn10"></a>19.4 Underscore Folding</H2>
  256. <p>
  257. Underscores are converted to dashes in identifiers. Guile support may
  258. grow an option to inhibit this folding in the future, but no one has
  259. complained so far.
  260. <p>You can use the SWIG directives <code>%name</code> and
  261. <code>%rename</code> to specify the Guile name of the wrapped
  262. functions and variables (see CHANGES).
  263. <H2><a name="Guile_nn11"></a>19.5 Typemaps</H2>
  264. <p>
  265. The Guile module handles all types via typemaps. This
  266. information is read from <code>Lib/guile/typemaps.i</code>.
  267. Some non-standard typemap substitutions are supported:
  268. <ul>
  269. <li><code>$descriptor</code> expands to a type descriptor for use with
  270. the <code>SWIG_NewPointerObj()</code> and
  271. <code>SWIG_ConvertPtr</code> functions.
  272. <li>For pointer types, <code>$*descriptor</code> expands to a
  273. descriptor for the direct base type (i.e., one pointer is stripped),
  274. whereas <code>$basedescriptor</code> expands to a
  275. descriptor for the base type (i.e., all pointers are stripped).
  276. </ul>
  277. <p>A function returning <code>void</code> (more precisely, a function
  278. whose <code>out</code> typemap returns <code>SCM_UNSPECIFIED</code>) is
  279. treated as returning no values. In <code>argout</code> typemaps, one
  280. can use the macro <code>GUILE_APPEND_RESULT</code> in order to append
  281. a value to the list of function return values.
  282. <p>Multiple values can be passed up to Scheme in one of three ways:
  283. <ul>
  284. <li><p><em>Multiple values as lists.</em>
  285. By default, if more than one value is to
  286. be returned, a list of the values is created and returned; to switch
  287. back to this behavior, use</p>
  288. <div class="code">
  289. <pre>
  290. %values_as_list;</pre>
  291. </div>
  292. <li><p><em>Multiple values as vectors.</em>
  293. By issuing
  294. </p>
  295. <div class="code">
  296. <pre>
  297. %values_as_vector;</pre>
  298. </div>
  299. <p>
  300. vectors instead of lists will be used.
  301. <li><p><em>Multiple values for multiple-value continuations.</em>
  302. <strong>This is the most elegant way.</strong> By issuing
  303. </p>
  304. <div class="code">
  305. <pre>
  306. %multiple_values;</pre>
  307. </div>
  308. <p>
  309. multiple values are passed to the multiple-value
  310. continuation, as created by <code>call-with-values</code> or the
  311. convenience macro <code>receive</code>. The latter is available if you
  312. issue <code>(use-modules (srfi srfi-8))</code>. Assuming that your
  313. <code>divide</code> function
  314. wants to return two values, a quotient and a remainder, you can write:
  315. </p>
  316. <div class="targetlang">
  317. <pre>
  318. (receive (quotient remainder)
  319. (divide 35 17)
  320. <var>body</var>...)
  321. </pre>
  322. </div>
  323. <p>
  324. In <code><var>body</var></code>, the first result of
  325. <code>divide</code> will be bound to the variable
  326. <code>quotient</code>, and the second result to <code>remainder</code>.
  327. </p>
  328. </ul>
  329. <p>
  330. See also the "multivalue" example.
  331. </p>
  332. <p>Constants are exported as a function that returns the value. The
  333. %feature("constasvar") can be applied to any constant, immutable variable, or enum.
  334. Instead of exporting the constant as a function that must be called, the
  335. constant will appear as a scheme variable. See
  336. <a href="Customization.html#features">Features and the %feature directive</a>
  337. for info on how to apply the %feature.</p>
  338. <H2><a name="Guile_nn12"></a>19.6 Representation of pointers as smobs</H2>
  339. <p>
  340. For pointer types, SWIG uses Guile smobs. SWIG smobs print
  341. like this: <code>#&lt;swig struct xyzzy * 0x1234affe&gt;</code> Two of
  342. them are <code>equal?</code> if and only if they have the same type
  343. and value.
  344. <p>
  345. To construct a Scheme object from a C pointer, the wrapper code calls
  346. the function <code>SWIG_NewPointerObj()</code>, passing a pointer to a
  347. struct representing the pointer type. The type index to store in the
  348. upper half of the CAR is read from this struct.
  349. To get the pointer represented by a smob, the wrapper code calls the
  350. function <code>SWIG_ConvertPtr()</code>, passing a pointer to a struct
  351. representing the expected pointer type. See also
  352. <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>.
  353. If the Scheme object passed was not a SWIG smob representing a compatible
  354. pointer, a <code>wrong-type-arg</code> exception is raised.
  355. <H3><a name="Guile_nn13"></a>19.6.1 GH Smobs</H3>
  356. <p>
  357. In earlier versions of SWIG, C pointers were represented as Scheme
  358. strings containing a hexadecimal rendering of the pointer value and a
  359. mangled type name. As Guile allows registering user types, so-called
  360. "smobs" (small objects), a much cleaner representation has been
  361. implemented now. The details will be discussed in the following.
  362. </p>
  363. <p> A smob is a cons cell where the lower half of the CAR contains the smob type
  364. tag, while the upper half of the CAR and the whole CDR are available. Every
  365. module creates its own smob type in the clientdata field of the module. So the
  366. lower 16 bits of the car of the smob store the tag and the upper 16 bits store
  367. the index this type is in the array. We can then, given a smob, find its
  368. swig_type_info struct by using the tag (lower 16 bits of car) to find which
  369. module this type is in (since each tag is unique for the module). Then we use
  370. the upper 16 bits to index into the array of types attached to this module.
  371. Looking up the module from the tag is worst case O(# of modules) but average
  372. case O(1). This is because the modules are stored in a circularly linked list,
  373. and when we start searching the modules for the tag, we start looking with the
  374. module that the function doing the lookup is in. SWIG_Guile_ConvertPtr() takes
  375. as its first argument the swig_module_info * of the calling function, which is
  376. where we start comparing tags. Most types will be looked up in the same module
  377. that created them, so the first module we check will most likely be correct.
  378. Once we have a swig_type_info structure, we loop through the linked list of
  379. casts, using pointer comparisons.</p>
  380. <H3><a name="Guile_nn14"></a>19.6.2 SCM Smobs</H3>
  381. <p>The SCM interface (using the "-scm" argument to swig) uses swigrun.swg.
  382. The whole type system, when it is first initialized, creates two smobs named "swig" and "collected_swig".
  383. The swig smob is used for non-garbage collected smobs, while the collected_swig smob is used as described
  384. below. Each smob has the same format, which is a double cell created by SCM_NEWSMOB2()
  385. The first word of data is the pointer to the object and the second word of data is the swig_type_info *
  386. structure describing this type. This is a lot easier than the GH interface above because we can store
  387. a pointer to the type info structure right in the type. With the GH interface, there was not enough
  388. room in the smob to store two whole words of data so we needed to store part of the "swig_type_info address"
  389. in the smob tag. If a generated GOOPS module has been loaded, smobs will be wrapped by the corresponding
  390. GOOPS class.</p>
  391. <H3><a name="Guile_nn15"></a>19.6.3 Garbage Collection</H3>
  392. <p>Garbage collection is a feature of the new SCM interface, and it is automatically included
  393. if you pass the "-scm" flag to swig. Thus the swig garbage collection support requires guile &gt;1.6.
  394. Garbage collection works like this. Every swig_type_info structure stores in its clientdata field a pointer
  395. to the destructor for this type. The destructor is the generated wrapper around the delete function.
  396. So swig still exports a wrapper for the destructor, it just does not call scm_c_define_gsubr() for
  397. the wrapped delete function. So the only way to delete an object is from the garbage collector, since the
  398. delete function is not available to scripts. How swig determines if a type should be garbage collected
  399. is exactly like described in <a href="Customization.html#ownership">
  400. Object ownership and %newobject</a> in the SWIG manual. All typemaps use an $owner var, and
  401. the guile module replaces $owner with 0 or 1 depending on feature:new.</p>
  402. <H2><a name="Guile_nn16"></a>19.7 Exception Handling</H2>
  403. <p>
  404. SWIG code calls <code>scm_error</code> on exception, using the following
  405. mapping:
  406. <div class="code">
  407. <pre>
  408. MAP(SWIG_MemoryError, "swig-memory-error");
  409. MAP(SWIG_IOError, "swig-io-error");
  410. MAP(SWIG_RuntimeError, "swig-runtime-error");
  411. MAP(SWIG_IndexError, "swig-index-error");
  412. MAP(SWIG_TypeError, "swig-type-error");
  413. MAP(SWIG_DivisionByZero, "swig-division-by-zero");
  414. MAP(SWIG_OverflowError, "swig-overflow-error");
  415. MAP(SWIG_SyntaxError, "swig-syntax-error");
  416. MAP(SWIG_ValueError, "swig-value-error");
  417. MAP(SWIG_SystemError, "swig-system-error");
  418. </pre>
  419. </div>
  420. <p>
  421. The default when not specified here is to use "swig-error".
  422. See Lib/exception.i for details.
  423. <H2><a name="Guile_nn17"></a>19.8 Procedure documentation</H2>
  424. <p>If invoked with the command-line option <code>-procdoc
  425. <var>file</var></code>, SWIG creates documentation strings for the
  426. generated wrapper functions, describing the procedure signature and
  427. return value, and writes them to <var>file</var>. You need Guile 1.4
  428. or later to make use of the documentation files.
  429. <p>SWIG can generate documentation strings in three formats, which are
  430. selected via the command-line option <code>-procdocformat
  431. <var>format</var></code>:
  432. <ul>
  433. <li><code>guile-1.4</code> (default): Generates a format suitable for Guile 1.4.
  434. <li><code>plain</code>: Generates a format suitable for Guile 1.4.1 and
  435. later.
  436. <li><code>texinfo</code>: Generates texinfo source, which must be run
  437. through texinfo in order to get a format suitable for Guile 1.4.1 and
  438. later.
  439. </ul>
  440. <p>You need to register the generated documentation file with Guile
  441. like this:
  442. <div class="targetlang">
  443. <pre>
  444. (use-modules (ice-9 documentation))
  445. (set! documentation-files
  446. (cons "<var>file</var>" documentation-files))
  447. </pre>
  448. </div>
  449. <p>Documentation strings can be configured using the Guile-specific
  450. typemap argument <code>doc</code>. See <code>Lib/guile/typemaps.i</code> for
  451. details.
  452. <H2><a name="Guile_nn18"></a>19.9 Procedures with setters</H2>
  453. <p>For global variables, SWIG creates a single wrapper procedure
  454. <code>(<var>variable</var> :optional value)</code>, which is used for
  455. both getting and setting the value. For struct members, SWIG creates
  456. two wrapper procedures <code>(<var>struct</var>-<var>member</var>-get
  457. pointer)</code> and <code>(<var>struct-member</var>-set pointer value)</code>.
  458. <p>If invoked with the command-line option <code>-emit-setters</code>
  459. (<em>recommended</em>),
  460. SWIG will additionally create procedures with setters. For global
  461. variables, the procedure-with-setter <code><var>variable</var></code>
  462. is created, so you can use <code>(<var>variable</var>)</code> to get
  463. the value and <code>(set! (<var>variable</var>)
  464. <var>value</var>)</code> to set it. For struct members, the
  465. procedure-with-setter <code><var>struct</var>-<var>member</var></code>
  466. is created, so you can use <code>(<var>struct</var>-<var>member</var>
  467. <var>pointer</var>)</code> to get the value and <code>(set!
  468. (<var>struct</var>-<var>member</var> <var>pointer</var>)
  469. <var>value</var>)</code> to set it.
  470. <p>If invoked with the command-line option <code>-only-setters</code>,
  471. SWIG will <em>only</em> create procedures with setters, i.e., for
  472. struct members, the procedures <code>(<var>struct</var>-<var>member</var>-get
  473. pointer)</code> and <code>(<var>struct-member</var>-set pointer
  474. value)</code> are <em>not</em> generated.
  475. <H2><a name="Guile_nn19"></a>19.10 GOOPS Proxy Classes</H2>
  476. <p>SWIG can also generate classes and generic functions for use with
  477. Guile's Object-Oriented Programming System (GOOPS). GOOPS is a
  478. sophisticated object system in the spirit of the Common Lisp Object
  479. System (CLOS).
  480. <p>GOOPS support is
  481. only available with the new SCM interface (enabled with the
  482. <code>-scm</code> command-line option of SWIG). To enable GOOPS
  483. support, pass the <code>-proxy</code> argument to
  484. swig. This will export the GOOPS wrapper definitions into the
  485. <code><i>module</i>.scm</code> file in the directory specified by -outdir or the
  486. current directory. GOOPS support requires either passive or module linkage.</p>
  487. <p>The generated file will contain definitions of GOOPS classes mimicking the C++ class hierarchy.
  488. <p>Enabling GOOPS support implies <code>-emit-setters</code>.
  489. <p>If <code>-emit-slot-accessors</code> is also passed as an argument,
  490. then the generated file will contain accessor methods for all the
  491. slots in the classes and for global variables. The input class</p>
  492. <div class="code"><pre>
  493. class Foo {
  494. public:
  495. Foo(int i) : a(i) {}
  496. int a;
  497. int getMultBy(int i) { return a * i; }
  498. Foo getFooMultBy(int i) { return Foo(a * i); }
  499. };
  500. Foo getFooPlus(int i) { return Foo(a + i); }
  501. </pre></div>
  502. <p>
  503. will produce (if <code>-emit-slot-accessors</code> is not passed as a parameter)
  504. </p>
  505. <div class="targetlang"><pre>
  506. (define-class &lt;Foo&gt; (&lt;swig&gt;)
  507. (a #:allocation #:swig-virtual
  508. #:slot-ref primitive:Foo-a-get
  509. #:slot-set! primitive:Foo-a-set)
  510. #:metaclass &lt;swig-metaclass&gt;
  511. #:new-function primitive:new-Foo
  512. )
  513. (define-method (getMultBy (swig_smob &lt;Foo&gt;) i)
  514. (primitive:Foo-getMultBy (slot-ref swig_smob 'smob) i))
  515. (define-method (getFooMultBy (swig_smob &lt;Foo&gt;) i)
  516. (make &lt;Foo&gt; #:init-smob (primitive:Foo-getFooMultBy (slot-ref swig_smob 'smob) i)))
  517. (define-method (getFooPlus i)
  518. (make &lt;Foo&gt; #:init-smob (primitive:getFooPlus i)))
  519. (export &lt;Foo&gt; getMultBy getFooMultBy getFooPlus )
  520. </pre></div>
  521. <p>
  522. and will produce (if <code>-emit-slot-accessors</code> is passed as a parameter)
  523. </p>
  524. <div class="targetlang"><pre>
  525. (define-class &lt;Foo&gt; (&lt;swig&gt;)
  526. (a #:allocation #:swig-virtual
  527. #:slot-ref primitive:Foo-a-get
  528. #:slot-set! primitive:Foo-a-set
  529. <b>#:accessor a</b>)
  530. #:metaclass &lt;swig-metaclass&gt;
  531. #:new-function primitive:new-Foo
  532. )
  533. (define-method (getMultBy (swig_smob &lt;Foo&gt;) i)
  534. (primitive:Foo-getMultBy (slot-ref swig_smob 'smob) i))
  535. (define-method (getFooMultBy (swig_smob &lt;Foo&gt;) i)
  536. (make &lt;Foo&gt; #:init-smob (primitive:Foo-getFooMultBy (slot-ref swig_smob 'smob) i)))
  537. (define-method (getFooPlus i)
  538. (make &lt;Foo&gt; #:init-smob (primitive:getFooPlus i)))
  539. (export &lt;Foo&gt; <b>a</b> getMultBy getFooMultBy getFooPlus )
  540. </pre></div>
  541. <p>
  542. which can then be used by this code
  543. </p>
  544. <div class="targetlang"><pre>
  545. ;; not using getters and setters
  546. (define foo (make &lt;Foo&gt; #:args '(45)))
  547. (slot-ref foo 'a)
  548. (slot-set! foo 'a 3)
  549. (getMultBy foo 4)
  550. (define foo2 (getFooMultBy foo 7))
  551. (slot-ref foo 'a)
  552. (slot-ref (getFooPlus foo 4) 'a)
  553. ;; using getters and setters
  554. (define foo (make &lt;Foo&gt; #:args '(45)))
  555. (a foo)
  556. (set! (a foo) 5)
  557. (getMultBy foo 4)
  558. (a (getFooMultBy foo 7))
  559. </pre></div>
  560. <p>Notice that constructor arguments are passed as a list after the <code>#:args</code> keyword. Hopefully in
  561. the future the following will be valid <code>(make &lt;Foo&gt; #:a 5 #:b 4)</code></p>
  562. <p>Also note that the order the declarations occur in the .i file make a difference. For example,
  563. </p>
  564. <div class="code"><pre>
  565. %module test
  566. %{ #include "foo.h" %}
  567. %inline %{
  568. int someFunc(Foo &amp;a) {
  569. ...
  570. }
  571. %}
  572. %include "foo.h"
  573. </pre></div>
  574. <p>
  575. This is a valid SWIG file it will work as you think it will for primitive support, but the generated
  576. GOOPS file will be broken. Since the <code>someFunc</code> definition is parsed by SWIG before all the
  577. declarations in foo.h, the generated GOOPS file will contain the definition of <code>someFunc()</code>
  578. before the definition of &lt;Foo&gt;. The generated GOOPS file would look like
  579. </p>
  580. <div class="targetlang"><pre>
  581. ;;...
  582. (define-method (someFunc (swig_smob &lt;Foo&gt;))
  583. (primitive:someFunc (slot-ref swig_smob 'smob)))
  584. ;;...
  585. (define-class &lt;Foo&gt; (&lt;swig&gt;)
  586. ;;...
  587. )
  588. ;;...
  589. </pre></div>
  590. <p>
  591. Notice that &lt;Foo&gt; is used before it is defined. The fix is to just put the
  592. <code>%import "foo.h"</code> before the <code>%inline</code> block.
  593. </p>
  594. <H3><a name="Guile_nn20"></a>19.10.1 Naming Issues</H3>
  595. <p>As you can see in the example above, there are potential naming conflicts. The default exported
  596. accessor for the <code>Foo::a</code> variable is named <code>a</code>. The name of the wrapper global
  597. function is <code>getFooPlus</code>.
  598. If the <code>-useclassprefix</code> option is passed to swig, the name of all accessors and member
  599. functions will be prepended with the class name. So the accessor will be called <code>Foo-a</code> and
  600. the member functions will be called <code>Foo-getMultBy</code>. Also, if the
  601. <code>-goopsprefix goops:</code> argument is passed to swig, every identifier will be prefixed by
  602. <code>goops:</code></p>
  603. <p>Two guile-modules are created by SWIG. The first module contains the primitive definitions
  604. of all the wrapped functions and variables, and is located either in the _wrap.cxx file (with <code>-Linkage
  605. module</code>) or in the scmstub file (if <code>-Linkage passive -scmstub</code>). The name of this
  606. guile-module is the swig-module name (given on the command line with the -module argument or with the
  607. %module directive) concatenated with the string "-primitive". For
  608. example, if <code>%module Test</code> is set in the swig interface file, the name of the guile-module in
  609. the scmstub or <code>-Linkage module</code> will be <code>Test-primitive</code>. Also, the scmstub
  610. file will be named <code>Test-primitive.scm</code>.
  611. The string "primitive" can be changed by the <code>-primsuffix</code> swig
  612. argument. So the same interface, with the <code>-primsuffix base</code> will produce a module called
  613. <code>Test-base</code>.
  614. The second generated guile-module contains all the GOOPS class definitions and is located in
  615. a file named <i>module</i>.scm in the directory specified with -outdir or the current directory.
  616. The name of this guile-module is the name of the
  617. swig-module (given on the command line or with the <code>%module</code> directive).
  618. In the previous example, the GOOPS definitions will be in a file named Test.scm.</p>
  619. <p>Because of the naming conflicts, you can't in general use both the <code>-primitive</code> and the GOOPS
  620. guile-modules at the same time. To do this, you need to rename the exported symbols from one or both
  621. guile-modules. For example,</p>
  622. <div class="targetlang"><pre>
  623. (use-modules ((Test-primitive) #:renamer (symbol-prefix-proc 'primitive:)))
  624. (use-modules ((Test) #:renamer (symbol-prefix-proc 'goops:)))
  625. </pre></div>
  626. <p>TODO: Renaming class name prefixes?</p>
  627. <H3><a name="Guile_nn21"></a>19.10.2 Linking</H3>
  628. <p>The guile-modules generated above all need to be linked together. GOOPS support requires
  629. either passive or module linkage. The exported GOOPS guile-module will be the name of the swig-module
  630. and should be located in a file called <i>Module</i>.scm. This should be installed on the autoload
  631. path for guile, so that <code>(use-modules (<i>Package Module</i>))</code> will load everything needed.
  632. Thus, the top of the GOOPS guile-module will contain code to load everything needed by the interface
  633. (the shared library, the scmstub module, etc.).
  634. The <code>%goops</code> directive inserts arbitrary code into the generated GOOPS guile-module, and
  635. should be used to load the dependent libraries.</p>
  636. <p>This breaks up into three cases</p>
  637. <ul>
  638. <li><b>Passive Linkage without -scmstub</b>: Note that this linkage style has the potential for naming
  639. conflicts, since the primitive exported function and variable names are not wrapped in a guile-module
  640. and might conflict with names from the GOOPS guile-module (see above). Pass the -goopsprefix
  641. argument to solve this problem. If the <code>-exportprimitive</code> option is passed to SWIG the
  642. <code>(export ...)</code> code that would be exported into the scmstub file is exported at the bottom
  643. of the generated GOOPS guile-module.
  644. The <code>%goops</code> directive should contain code to load the .so library.
  645. <div class="code"><pre>
  646. %goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
  647. </pre></div>
  648. <p>
  649. Produces the following code at the top of the generated GOOPS guile-module
  650. (with the <code>-package my/modules -module foo</code> command line arguments)
  651. </p>
  652. <div class="targetlang"><pre>
  653. (define-module (my modules foo))
  654. ;; %goops directive goes here
  655. (load-extension "./foo.so" "scm_init_my_modules_foo_module")
  656. (use-modules (oop goops) (Swig common))
  657. </pre></div>
  658. </li>
  659. <li><p><b>Passive Linkage with -scmstub</b>: Here, the name of the scmstub file should be
  660. <code>Module-primitive.scm</code> (with <i>primitive</i> replaced with whatever is given with the <code>-primsuffix</code>
  661. argument. The code to load the <code>.so</code> library should be located in the <code>%scheme</code> directive,
  662. which will then be added to the scmstub file.
  663. Swig will automatically generate the line <code>(use-modules (<i>Package</i> <i>Module-primitive</i>))</code>
  664. into the GOOPS guile-module. So if <i>Module-primitive.scm</i> is on the autoload path for guile, the
  665. <code>%goops</code> directive can be empty. Otherwise, the <code>%goops</code> directive should contain
  666. whatever code is needed to load the <i>Module-primitive.scm</i> file into guile.</p>
  667. <div class="targetlang"><pre>
  668. %scheme %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
  669. // only include the following definition if (my modules foo) cannot
  670. // be loaded automatically
  671. %goops %{
  672. (primitive-load "/path/to/foo-primitive.scm")
  673. (primitive-load "/path/to/Swig/common.scm")
  674. %}
  675. </pre></div>
  676. <p>
  677. Produces the following code at the top of the generated GOOPS guile-module
  678. </p>
  679. <div class="targetlang"><pre>
  680. (define-module (my modules foo))
  681. ;; %goops directive goes here (if any)
  682. (primitive-load "/path/to/foo-primitive.scm")
  683. (primitive-load "/path/to/Swig/common.scm")
  684. (use-modules (oop goops) (Swig common))
  685. (use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
  686. 'primitive:)))
  687. </pre></div>
  688. </li>
  689. <li><p><b>Module Linkage</b>: This is very similar to passive linkage with a scmstub file.
  690. Swig will also automatically generate the line <code>(use-modules
  691. (<i>Package</i> <i>Module-primitive</i>))</code> into the GOOPS guile-module. Again the <code>%goops</code>
  692. directive should contain whatever code is needed to get that module loaded into guile.</p>
  693. <div class="code"><pre>
  694. %goops %{ (load-extension "./foo.so" "scm_init_my_modules_foo_module") %}
  695. </pre></div>
  696. <p>
  697. Produces the following code at the top of the generated GOOPS guile-module
  698. </p>
  699. <div class="targetlang"><pre>
  700. (define-module (my modules foo))
  701. ;; %goops directive goes here (if any)
  702. (load-extension "./foo.so" "scm_init_my_modules_foo_module")
  703. (use-modules (oop goops) (Swig common))
  704. (use-modules ((my modules foo-primitive) :renamer (symbol-prefix-proc
  705. 'primitive:)))
  706. </pre></div>
  707. </li>
  708. </ul>
  709. <p><b>(Swig common)</b>: The generated GOOPS guile-module also imports definitions from the
  710. (Swig common) guile-module.
  711. This module is included with SWIG and should be installed by SWIG into the autoload path for
  712. guile (based on the configure script and whatever arguments are passed). If it is not, then the
  713. <code>%goops</code> directive also needs to contain code to load the <code>common.scm</code> file
  714. into guile. Also note that if you are trying to install the generated wrappers on a computer without
  715. SWIG installed, you will need to include the common.swg file along with the install.</p>
  716. <p><b>Multiple Modules</b>: Type dependencies between modules is supported. For example, if
  717. <code>mod1</code> includes definitions of some classes, and <code>mod2</code> includes some classes
  718. derived from classes in <code>mod1</code>, the generated GOOPS file for <code>mod2</code> will declare
  719. the correct superclasses. The only problem is that since <code>mod2</code> uses symbols from
  720. <code>mod1</code>, the <code>mod2</code> GOOPS file must include a <code>(use-modules (mod2))</code>.
  721. Currently, SWIG does not automatically export this line; it must be included in the <code>%goops</code>
  722. directive of <code>mod2</code>. Maybe in the future SWIG can detect dependencies and export this line.
  723. (how do other language modules handle this problem?)</p>
  724. </body>
  725. </html>