PageRenderTime 9ms CodeModel.GetById 2ms app.highlight 3ms RepoModel.GetById 1ms app.codeStats 0ms

/trunk/Doc/Manual/Modules.html

#
HTML | 349 lines | 284 code | 63 blank | 2 comment | 0 complexity | b3adb0e7c5e9fe71337f328b5eb46888 MD5 | raw file
  1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  2<html>
  3<head>
  4<title>Working with Modules</title>
  5<link rel="stylesheet" type="text/css" href="style.css">
  6</head>
  7
  8<body bgcolor="#ffffff">
  9<H1><a name="Modules"></a>15 Working with Modules</H1>
 10<!-- INDEX -->
 11<div class="sectiontoc">
 12<ul>
 13<li><a href="#Modules_introduction">Modules Introduction</a>
 14<li><a href="#Modules_nn1">Basics</a>
 15<li><a href="#Modules_nn2">The SWIG runtime code</a>
 16<li><a href="#Modules_external_run_time">External access to the runtime</a>
 17<li><a href="#Modules_nn4">A word of caution about static libraries</a>
 18<li><a href="#Modules_nn5">References</a>
 19<li><a href="#Modules_nn6">Reducing the wrapper file size</a>
 20</ul>
 21</div>
 22<!-- INDEX -->
 23
 24
 25
 26<H2><a name="Modules_introduction"></a>15.1 Modules Introduction</H2>
 27
 28
 29<p>
 30Each invocation of SWIG requires a module name to be specified.
 31The module name is used to name the resulting target language extension module. 
 32Exactly what this means and what the name is used for
 33depends on the target language, for example the name can define
 34a target language namespace or merely be a useful name for naming files or helper classes.
 35Essentially, a module comprises target language wrappers for a chosen collection of global variables/functions, structs/classes and other C/C++ types.
 36</p>
 37
 38<p>
 39The module name can be supplied in one of two ways. 
 40The first is to specify it with the special <tt>%module</tt>
 41directive. This directive must appear at the beginning of the interface file.
 42The general form of this directive is:
 43</p>
 44
 45<div class="code"><pre>
 46<tt>%module(option1="value1",option2="value2",...) modulename</tt>
 47</pre></div>
 48
 49<p>
 50where the modulename is mandatory and the options add one or more optional additional features.
 51Typically no options are specified, for example:
 52</p>
 53
 54<div class="code"><pre>
 55<tt>%module mymodule</tt>
 56</pre></div>
 57
 58<p>
 59The second way to specify the module name is with the <tt>-module</tt> command line option, for example <tt>-module mymodule</tt>.
 60If the module name is supplied on the command line, it overrides the name specified by the
 61<tt>%module</tt> directive.
 62</p>
 63
 64<p>
 65When first working with SWIG, users commonly start by creating a
 66single module.  That is, you might define a single SWIG interface that
 67wraps some set of C/C++ code.  You then compile all of the generated
 68wrapper code together and use it.   For large applications, however,
 69this approach is problematic---the size of the generated wrapper code
 70can be rather large.  Moreover, it is probably easier to manage the
 71target language interface when it is broken up into smaller pieces.
 72</p>
 73
 74<p>
 75This chapter describes the problem of using SWIG in programs
 76where you want to create a collection of modules. 
 77Each module in the collection is created via separate invocations of SWIG.
 78</p>
 79
 80<H2><a name="Modules_nn1"></a>15.2 Basics</H2>
 81
 82
 83<p>
 84The basic usage case with multiple modules is when modules do not have
 85cross-references (ie. when wrapping multiple independent C APIs). In that case,
 86swig input files should just work out of the box - you simply create multiple
 87wrapper .cxx files, link them into your application, and insert/load each in the
 88scripting language runtime as you would do for the single module case.
 89</p>
 90
 91<p>
 92A bit more complex is the case in which modules need to share information.
 93For example, when one module extends the class of another by deriving from
 94it:
 95</p>
 96
 97<div class="code"><pre>
 98// File: base.h
 99class base {
100public:
101  int foo();
102};
103</pre></div>
104&nbsp;
105
106<div class="code"><pre>
107// File: base_module.i
108%module base_module
109
110%{
111#include "base.h"
112%}
113%include "base.h"
114</pre></div>
115&nbsp;
116
117<div class="code"><pre>
118// File: derived_module.i
119%module derived_module
120
121%import "base_module.i"
122
123%inline %{
124class derived : public base {
125public:
126  int bar();
127};
128%}
129</pre></div>
130
131<p>To create the wrapper properly, module <tt>derived_module</tt> needs to know about the
132<tt>base</tt> class and that its interface is covered in another module. The
133line <tt>%import "base_module.i"</tt> lets SWIG know exactly that. Oftentimes
134the <tt>.h</tt> file is passed to <tt>%import</tt> instead of the <tt>.i</tt>, 
135which unfortunately doesn't work for all language modules. For example, Python requires the
136name of module that the base class exists in so that the proxy classes can fully inherit the
137base class's methods. Typically you will get a warning when the module name is missing, eg:
138</p>
139
140<div class="shell"> <pre>
141derived_module.i:8: Warning 401: Base class 'base' ignored - unknown module name for base. Either
142import
143the appropriate module interface file or specify the name of the module in the %import directive.
144</pre></div>
145
146<p>
147It is sometimes desirable to import the header file rather than the interface file and overcome
148the above warning. 
149For example in the case of the imported interface being quite large, it may be desirable to
150simplify matters and just import a small header file of dependent types.
151This can be done by specifying the optional <tt>module</tt> attribute in the <tt>%import</tt> directive.
152The <tt>derived_module.i</tt> file shown above could be replaced with the following:
153
154<div class="code"><pre>
155// File: derived_module.i
156%module derived_module
157
158%import(module="base_module") "base.h"
159
160%inline %{
161class derived : public base {
162public:
163  int bar();
164};
165</pre></div>
166
167<p>
168Note that "base_module" is the module name and is the same as that specified in <tt>%module</tt>
169in <tt>base_module.i</tt> as well as the <tt>%import</tt> in <tt>derived_module.i</tt>.
170</p>
171
172<p>
173Another issue
174to beware of is that multiple dependent wrappers should not be linked/loaded
175in parallel from multiple threads as SWIG provides no locking - for more on that
176issue, read on.
177</p>
178
179<H2><a name="Modules_nn2"></a>15.3 The SWIG runtime code</H2>
180
181
182<p>
183Many of SWIG's target languages generate a set of functions commonly known as
184the "SWIG runtime." These functions are primarily related to the runtime type
185system which checks pointer types and performs other tasks such as proper
186casting of pointer values in C++. As a general rule, the statically typed target
187languages, such as Java, use the language's built in static type checking and
188have no need for a SWIG runtime. All the dynamically typed / interpreted
189languages rely on the SWIG runtime.
190</p>
191
192<p>
193The runtime functions are private to each SWIG-generated module. That is, the
194runtime functions are declared with "static" linkage and are visible only to the
195wrapper functions defined in that module. The only problem with this approach is
196that when more than one SWIG module is used in the same application, those
197modules often need to share type information. This is especially true for C++
198programs where SWIG must collect and share information about inheritance
199relationships that cross module boundaries.
200</p>
201
202<p>
203To solve the problem of sharing information across modules, a pointer to the
204type information is stored in a global variable in the target language
205namespace. During module initialization, type information is loaded into the
206global data structure of type information from all modules.
207</p>
208
209<p>
210There are a few trade offs with this approach. This type information is global
211across all SWIG modules loaded, and can cause type conflicts between modules
212that were not designed to work together. To solve this approach, the SWIG
213runtime code uses a define SWIG_TYPE_TABLE to provide a unique type table. This
214behavior can be enabled when compiling the generated _wrap.cxx or _wrap.c file
215by adding -DSWIG_TYPE_TABLE=myprojectname to the command line argument.
216</p>
217
218<p>
219Then, only modules compiled with SWIG_TYPE_TABLE set to myprojectname will share
220type information. So if your project has three modules, all three should be
221compiled with -DSWIG_TYPE_TABLE=myprojectname, and then these three modules will
222share type information. But any other project's types will not interfere or
223clash with the types in your module.
224</p>
225
226<p>
227Another issue relating to the global type table is thread safety. If two modules
228try and load at the same time, the type information can become corrupt. SWIG
229currently does not provide any locking, and if you use threads, you must make
230sure that modules are loaded serially. Be careful if you use threads and the
231automatic module loading that some scripting languages provide. One solution is
232to load all modules before spawning any threads, or use SWIG_TYPE_TABLE to
233separate type tables so they do not clash with each other.
234</p>
235
236<p>
237Lastly, SWIG uses a #define SWIG_RUNTIME_VERSION, located in Lib/swigrun.swg and
238near the top of every generated module. This number gets incremented when the
239data structures change, so that SWIG modules generated with different versions
240can peacefully coexist. So the type structures are separated by the
241(SWIG_TYPE_TABLE, SWIG_RUNTIME_VERSION) pair, where by default SWIG_TYPE_TABLE
242is empty. Only modules compiled with the same pair will share type information.
243</p>
244
245<H2><a name="Modules_external_run_time"></a>15.4 External access to the runtime</H2>
246
247
248<p>As described in <a href="Typemaps.html#Typemaps_runtime_type_checker">The run-time type checker</a>,
249the functions <tt>SWIG_TypeQuery</tt>, <tt>SWIG_NewPointerObj</tt>, and others sometimes need
250to be called.  Calling these functions from a typemap is supported, since the typemap code
251is embedded into the <tt>_wrap.c</tt> file, which has those declarations available.  If you need
252to call the SWIG run-time functions from another C file, there is one header you need
253to include.  To generate the header that needs to be included, run the following command:
254
255<div class="shell"><pre>
256$ swig -python -external-runtime &lt;filename&gt;
257</pre></div>
258
259<p>The filename argument is optional and if it is not passed, then the default filename will
260be something like <tt>swigpyrun.h</tt>, depending on the language.  This header file should
261be treated like any of the other _wrap.c output files, and should be regenerated when the
262_wrap files are.  After including this header, your code will be able to call <tt>SWIG_TypeQuery</tt>,
263<tt>SWIG_NewPointerObj</tt>, <tt>SWIG_ConvertPtr</tt> and others.  The exact argument parameters
264for these functions might differ between language modules; please check the language module chapters
265for more information.</p>
266
267<p>Inside this header the functions are declared static and are included inline into the file,
268and thus the file does not need to be linked against any SWIG libraries or code (you might still
269need to link against the language libraries like libpython-2.3).  Data is shared between this
270file and the _wrap.c files through a global variable in the scripting language.  It is also
271possible to copy this header file along with the generated wrapper files into your own package,
272so that you can distribute a package that can be compiled without SWIG installed (this works
273because the header file is self-contained, and does not need to link with anything).</p>
274
275<p>
276This header will also use the -DSWIG_TYPE_TABLE described above, so when
277compiling any code which includes the generated header file should define the
278SWIG_TYPE_TABLE to be the same as the module whose types you are trying to
279access.
280</p>
281
282<H2><a name="Modules_nn4"></a>15.5 A word of caution about static libraries</H2>
283
284
285<p>
286When working with multiple SWIG modules, you should take care not to use static
287libraries.  For example, if you have a static library <tt>libfoo.a</tt> and you link a collection
288of SWIG modules with that library, each module will get its own private copy of the library code inserted
289into it. This is very often <b>NOT</b> what you want and it can lead to unexpected or bizarre program
290behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libraries.
291</p>
292
293<H2><a name="Modules_nn5"></a>15.6 References</H2>
294
295
296<p>
297Due to the complexity of working with shared libraries and multiple modules, it might be a good idea to consult
298an outside reference.  John Levine's "Linkers and Loaders" is highly recommended.
299</p>
300
301<H2><a name="Modules_nn6"></a>15.7 Reducing the wrapper file size</H2>
302
303
304<p>
305Using multiple modules with the <tt>%import</tt> directive is the most common approach to modularising large projects.
306In this way a number of different wrapper files can be generated, thereby avoiding the generation of a single large wrapper file.
307There are a couple of alternative solutions for reducing the size of a wrapper file through the use of command line options and features.
308</p>
309
310<p>
311<b>-fcompact</b><br>
312This command line option will compact the size of the wrapper file without changing the code generated into the wrapper file.
313It simply removes blank lines and joins lines of code together.
314This is useful for compilers that have a maximum file size that can be handled.
315</p>
316
317<p>
318<b>-fvirtual</b><br>
319This command line option will remove the generation of superfluous virtual method wrappers.
320Consider the following inheritance hierarchy:
321</p>
322
323<div class="code">
324<pre>
325struct Base {
326  virtual void method();
327  ...
328};
329
330struct Derived : Base {
331  virtual void method();
332  ...
333};
334</pre>
335</div>
336
337<p>
338Normally wrappers are generated for both methods, whereas this command line option will suppress the generation of a wrapper for <tt>Derived::method</tt>.
339Normal polymorphic behaviour remains as <tt>Derived::method</tt> will still be called should you have
340a <tt>Derived</tt> instance and call the wrapper for <tt>Base::method</tt>.
341</p>
342
343<p>
344<b>%feature("compactdefaultargs")</b><br>
345This feature can reduce the number of wrapper methods when wrapping methods with default arguments. The section on <a href="SWIGPlus.html#SWIGPlus_default_args">default arguments</a> discusses the feature and its limitations.
346</p>
347
348</body>
349</html>