← Back to branch summary

~ubuntu-branches/ubuntu/hardy/swig1.3/hardy

« back to all changes in this revision

Viewing changes to Doc/Manual/Modules.html

  • Committer: Bazaar Package Importer
  • Author(s): Adam Conrad
  • Date: 2005-12-05 01:16:04 UTC
  • mfrom: (1.2.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20051205011604-ygx904it6413k3go
Tags: 1.3.27-1ubuntu1
Resynchronise with Debian again, for the new subversion packages.

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/Manual/Modules.html
2
2
<html>
3
3
<head>
4
4
<title>Working with Modules</title>
 
5
<link rel="stylesheet" type="text/css" href="style.css">
5
6
</head>
6
7
 
7
8
<body bgcolor="#ffffff">
8
9
<H1><a name="Modules"></a>15 Working with Modules</H1>
9
10
<!-- INDEX -->
 
11
<div class="sectiontoc">
10
12
<ul>
11
13
<li><a href="#Modules_nn2">The SWIG runtime code</a>
12
 
<li><a href="#Modules_nn3">A word of caution about static libraries</a>
13
 
<li><a href="#Modules_nn4">References</a>
14
 
<li><a href="#Modules_nn5">Reducing the wrapper file size</a>
 
14
<li><a href="#external_run_time">External access to the runtime</a>
 
15
<li><a href="#Modules_nn4">A word of caution about static libraries</a>
 
16
<li><a href="#Modules_nn5">References</a>
 
17
<li><a href="#Modules_nn6">Reducing the wrapper file size</a>
15
18
</ul>
 
19
</div>
16
20
<!-- INDEX -->
17
21
 
18
22
 
19
23
 
 
24
<p>
20
25
When first working with SWIG, users commonly start by creating a
21
26
single module.  That is, you might define a single SWIG interface that
22
27
wraps some set of C/C++ code.  You then compile all of the generated
24
29
this approach is problematic---the size of the generated wrapper code
25
30
can be rather large.  Moreover, it is probably easier to manage the
26
31
target language interface when it is broken up into smaller pieces.
 
32
</p>
27
33
 
28
34
<p>
29
35
This chapter describes the problem of using SWIG in programs
33
39
<H2><a name="Modules_nn2"></a>15.1 The SWIG runtime code</H2>
34
40
 
35
41
 
 
42
<p>
36
43
Many of SWIG's target languages generate a set of functions
37
44
commonly known as the "SWIG runtime."   These functions are 
38
45
primarily related to the runtime type system which checks pointer
41
48
such as Java, use the language's built in static type checking and
42
49
have no need for a SWIG runtime. All the dynamically typed / interpreted
43
50
languages rely on the SWIG runtime.
 
51
</p>
44
52
 
45
53
<p>
46
54
The runtime functions are private to each SWIG-generated
68
76
languages provide.  One solution is to load all modules before spawning any threads.
69
77
</p>
70
78
 
71
 
<H2><a name="Modules_nn3"></a>15.2 A word of caution about static libraries</H2>
72
 
 
73
 
 
 
79
<H2><a name="external_run_time"></a>15.2 External access to the runtime</H2>
 
80
 
 
81
 
 
82
<p>As described in <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>,
 
83
the functions <tt>SWIG_TypeQuery</tt>, <tt>SWIG_NewPointerObj</tt>, and others sometimes need
 
84
to be called.  Calling these functions from a typemap is supported, since the typemap code
 
85
is embedded into the <tt>_wrap.c</tt> file, which has those declerations available.  If you need
 
86
to call the SWIG run-time functions from another C file, there is one header you need
 
87
to include.  To generate the header that needs to be included, run the following command:
 
88
 
 
89
<div class="code"><pre>
 
90
$ swig -python -external-runtime &lt;filename&gt;
 
91
</pre></div>
 
92
 
 
93
<p>The filename argument is optional and if it is not passed, then the default filename will
 
94
be something like <tt>swigpyrun.h</tt>, depending on the language.  This header file should
 
95
be treated like any of the other _wrap.c output files, and should be regenerated when the
 
96
_wrap files are.  After including this header, your code will be able to call <tt>SWIG_TypeQuery</tt>,
 
97
<tt>SWIG_NewPointerObj</tt>, <tt>SWIG_ConvertPtr</tt> and others.  The exact argument paramaters
 
98
for these functions might differ between language modules; please check the language module chapters
 
99
for more information.</p>
 
100
 
 
101
<p>Inside this header the functions are declared static and are included inline into the file,
 
102
and thus the file does not need to be linked against any SWIG libraries or code (you might still
 
103
need to link against the language libraries like libpython-2.3).  Data is shared between this
 
104
file and the _wrap.c files through a global variable in the scripting language.  It is also
 
105
possible to copy this header file along with the generated wrapper files into your own package,
 
106
so that you can distribute a package that can be compiled without SWIG installed (this works
 
107
because the header file is self contained, and does not need to link with anything).</p>
 
108
 
 
109
<H2><a name="Modules_nn4"></a>15.3 A word of caution about static libraries</H2>
 
110
 
 
111
 
 
112
<p>
74
113
When working with multiple SWIG modules, you should take care not to use static
75
114
libraries.  For example, if you have a static library <tt>libfoo.a</tt> and you link a collection
76
115
of SWIG modules with that library, each module will get its own private copy of the library code inserted
77
116
into it. This is very often <b>NOT</b> what you want and it can lead to unexpected or bizarre program
78
117
behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libaries.
79
 
 
80
 
<H2><a name="Modules_nn4"></a>15.3 References</H2>
81
 
 
82
 
 
 
118
</p>
 
119
 
 
120
<H2><a name="Modules_nn5"></a>15.4 References</H2>
 
121
 
 
122
 
 
123
<p>
83
124
Due to the complexity of working with shared libraries and multiple modules, it might be a good idea to consult
84
125
an outside reference.  John Levine's "Linkers and Loaders" is highly recommended.
 
126
</p>
85
127
 
86
 
<H2><a name="Modules_nn5"></a>15.4 Reducing the wrapper file size</H2>
 
128
<H2><a name="Modules_nn6"></a>15.5 Reducing the wrapper file size</H2>
87
129
 
88
130
 
89
131
<p>
92
134
There are a couple of alternative solutions for reducing the size of a wrapper file through the use of command line options and features.
93
135
</p>
94
136
 
 
137
<p>
95
138
<b>-fcompact</b><br>
96
139
This command line option will compact the size of the wrapper file without changing the code generated into the wrapper file.
97
140
It simply removes blank lines and joins lines of code together.
98
141
This is useful for compilers that have a maximum file size that can be handled.
 
142
</p>
99
143
 
100
144
<p>
101
145
<b>-fvirtual</b><br>
103
147
Consider the following inheritance hierarchy:
104
148
</p>
105
149
 
106
 
<blockquote>
 
150
<div class="code">
107
151
<pre>
108
152
struct Base {
109
153
  virtual void method();
115
159
  ...
116
160
};
117
161
</pre>
118
 
</blockquote>
 
162
</div>
 
163
 
 
164
<p>
119
165
Normally wrappers are generated for both methods, whereas this command line option will suppress the generation of a wrapper for <tt>Derived::method</tt>.
120
166
Normal polymorphic behaviour remains as <tt>Derived::method</tt> will still be called should you have
121
167
a <tt>Derived</tt> instance and call the wrapper for <tt>Base::method</tt>.
 
168
</p>
122
169
 
123
170
<p>
124
171
<b>%feature("compactdefaultargs")</b><br>