jyapayne/swig
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

- Updated documentation to use CSS and <div> instead of blockquotes

Browse source 
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/trunk@7003 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
John Lenz 2005-02-26 02:56:29 +00:00
commit 4737da0be0
35 changed files with 8013 additions and 4099 deletions
Download patch file Download diff file Expand all files Collapse all files

29
SWIG/Doc/Manual/Modules.html
View file

@ -2,22 +2,26 @@
<html>
<head>
<title>Working with Modules</title>
<link rel="stylesheet" type="text/css" href="style.css"/>
</head>
<body bgcolor="#ffffff">
<H1><a name="Modules"></a>15 Working with Modules</H1>
<!-- INDEX -->
<div class="sectiontoc">
<ul>
<li><a href="#Modules_nn2">The SWIG runtime code</a>
<li><a href="#external_run_time">External access to runtime system</a>
<li><a href="#external_run_time">External access to the runtime</a>
<li><a href="#Modules_nn4">A word of caution about static libraries</a>
<li><a href="#Modules_nn5">References</a>
<li><a href="#Modules_nn6">Reducing the wrapper file size</a>
</ul>
</div>
<!-- INDEX -->
<p>
When first working with SWIG, users commonly start by creating a
single module. That is, you might define a single SWIG interface that
wraps some set of C/C++ code. You then compile all of the generated
@ -25,6 +29,7 @@ wrapper code into a module and use it. For large applications, however,
this approach is problematic---the size of the generated wrapper code
can be rather large. Moreover, it is probably easier to manage the
target language interface when it is broken up into smaller pieces.
</p>
<p>
This chapter describes the problem of using SWIG in programs
@ -34,6 +39,7 @@ where you want to create a collection of modules.
<H2><a name="Modules_nn2"></a>15.1 The SWIG runtime code</H2>
<p>
Many of SWIG's target languages generate a set of functions
commonly known as the "SWIG runtime." These functions are
primarily related to the runtime type system which checks pointer
@ -42,6 +48,7 @@ values in C++. As a general rule, the statically typed target languages,
such as Java, use the language's built in static type checking and
have no need for a SWIG runtime. All the dynamically typed / interpreted
languages rely on the SWIG runtime.
</p>
<p>
The runtime functions are private to each SWIG-generated
@ -69,7 +76,8 @@ Be careful if you use threads and the automatic module loading that some scripti
languages provide. One solution is to load all modules before spawning any threads.
</p>
<H2><a name="external_run_time"></a>15.2 External access to the run-time system</a></H2>
<H2><a name="external_run_time"></a>15.2 External access to the runtime</H2>
<p>As described in <a href="Typemaps.html#runtime_type_checker">The run-time type checker</a>,
the functions <tt>SWIG_TypeQuery</tt>, <tt>SWIG_NewPointerObj</tt>, and others sometimes need
@ -78,9 +86,9 @@ is embedded into the <tt>_wrap.c</tt> file, which has those declerations availab
to call the SWIG run-time functions from another C file, there is one header you need
to include. To generate the header that needs to be included, run the following command:
<blockquote><pre>
<div class="code"><pre>
$ swig -python -external-runtime &lt;filename&gt;
</pre></blockquote>
</pre></div>
<p>The filename argument is optional and if it is not passed, then the default filename will
be something like <tt>swigpyrun.h</tt>, depending on the language. This header file should
@ -101,17 +109,21 @@ because the header file is self contained, and does not need to link with anythi
<H2><a name="Modules_nn4"></a>15.3 A word of caution about static libraries</H2>
<p>
When working with multiple SWIG modules, you should take care not to use static
libraries. For example, if you have a static library <tt>libfoo.a</tt> and you link a collection
of SWIG modules with that library, each module will get its own private copy of the library code inserted
into it. This is very often <b>NOT</b> what you want and it can lead to unexpected or bizarre program
behavior. When working with dynamically loadable modules, you should try to work exclusively with shared libaries.
</p>
<H2><a name="Modules_nn5"></a>15.4 References</H2>
<p>
Due to the complexity of working with shared libraries and multiple modules, it might be a good idea to consult
an outside reference. John Levine's "Linkers and Loaders" is highly recommended.
</p>
<H2><a name="Modules_nn6"></a>15.5 Reducing the wrapper file size</H2>
@ -122,10 +134,12 @@ In this way a number of different wrapper files can be generated, thereby avoidi
There are a couple of alternative solutions for reducing the size of a wrapper file through the use of command line options and features.
</p>
<p>
<b>-fcompact</b><br>
This command line option will compact the size of the wrapper file without changing the code generated into the wrapper file.
It simply removes blank lines and joins lines of code together.
This is useful for compilers that have a maximum file size that can be handled.
</p>
<p>
<b>-fvirtual</b><br>
@ -133,7 +147,7 @@ This command line option will remove the generation of superfluous virtual metho
Consider the following inheritance hierarchy:
</p>
<blockquote>
<div class="code">
<pre>
struct Base {
virtual void method();
@ -145,10 +159,13 @@ struct Derived : Base {
...
};
</pre>
</blockquote>
</div>
<p>
Normally wrappers are generated for both methods, whereas this command line option will suppress the generation of a wrapper for <tt>Derived::method</tt>.
Normal polymorphic behaviour remains as <tt>Derived::method</tt> will still be called should you have
a <tt>Derived</tt> instance and call the wrapper for <tt>Base::method</tt>.
</p>
<p>
<b>%feature("compactdefaultargs")</b><br>