Beginning of module documentation.
git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2008-maciekd@10795 626c5289-ae23-0410-ae9c-e8d60b6d4f22
This commit is contained in:
Maciej Drwal
parent
54860c9595
commit
5b00567154
2 changed files with 194 additions and 0 deletions
193
Doc/Manual/C.html
Normal file
193
Doc/Manual/C.html
Normal file
|
|
@ -0,0 +1,193 @@
|
|||
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||||
<html>
|
||||
<head>
|
||||
<title>SWIG and C</title>
|
||||
<link rel="stylesheet" type="text/css" href="style.css">
|
||||
</head>
|
||||
<body bgcolor="#FFFFFF">
|
||||
<H1><a name="C"></a>36 SWIG and C</H1>
|
||||
<!-- INDEX -->
|
||||
<div class="sectiontoc">
|
||||
<ul>
|
||||
<li><a href="#c_overview">Overview</a>
|
||||
<li><a href="#c_preliminaries">Preliminaries</a>
|
||||
<ul>
|
||||
<li><a href="#c_running_swig">Running SWIG</a>
|
||||
<li><a href="#c_commandline">Command line options</a>
|
||||
<li><a href="#c_dynamic">Compiling dynamic module</a>
|
||||
<li><a href="#c_using_module">Using generated module</a>
|
||||
</ul>
|
||||
<li><a href="#c_basic_c_wrapping">Basic C wrapping</a>
|
||||
<ul>
|
||||
<li><a href="#c_c_functions">Functions</a>
|
||||
<li><a href="#c_c_variables">Variables</a>
|
||||
</ul>
|
||||
<li><a href="#c_basic_cpp_wrapping">Basic C++ wrapping</a>
|
||||
<ul>
|
||||
<li><a href="#c_classes">Classes</a>
|
||||
</ul>
|
||||
<li><a href="#c_exceptions">Exception handling</a>
|
||||
</ul>
|
||||
</div>
|
||||
<!-- INDEX -->
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
This chapter describes SWIG's support for creating ANSI C wrappers. This module has a special purpose and thus is different from most other modules.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<b>NOTE:</b> this module is still under development.
|
||||
</p>
|
||||
|
||||
|
||||
<H2><a name="c_overview"></a>36.1 Overview</H2>
|
||||
|
||||
|
||||
<p>
|
||||
SWIG is normally used to generate scripting language interface to C or C++ libraries. In the process, it performs analysis of library header files, generates intermediary C code, from which a set of language specific functions is constructed, which can be then accessed in the scripting language code. Having the C code needed to generate wrapper functions for specific language module, we are only one step away from being able to generate pure ANSI C interface to the input C or C++ library. Then we can think of C as just any other target language supported by SWIG.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
With wrapper interface generated by SWIG, it is easy to use functionality of C++ libraries inside application code written in C. The module may also be useful to generate custom API for a library, to suit particular needs, e.g. to supply the function calls with error checking or to implement "design by contract" approach.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Flattening C++ language constructs into a set of C-style functions obviously comes with many limitations and inconveniences. All data and functions becomes global. Manipulating objects requires explicit calls to special functions. We are losing the high level abstraction and have to work around it.
|
||||
</p>
|
||||
|
||||
<H2><a name="c_preliminaries"></a>36.2 Preliminaries</H2>
|
||||
|
||||
|
||||
<H3><a name="c_running_swig"></a>36.2.1 Running SWIG</H3>
|
||||
|
||||
|
||||
<p>
|
||||
Consider following simple example. Suppose we have an interface file like:
|
||||
</p>
|
||||
|
||||
<div class="code">
|
||||
<pre>
|
||||
/* File: example.i */
|
||||
%module test
|
||||
%{
|
||||
#include "stuff.h"
|
||||
%}
|
||||
int fact(int n);
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<p>
|
||||
To build a C module, run SWIG using the <tt>-c</tt> option :</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
%swig -c example.i
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
If building C++, add the <tt>-c++</tt> option:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
$ swig -c++ -c example.i
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
This will generate <tt>example_wrap.c</tt> file or, in the latter case, <tt>example_wrap.cxx</tt> file, along with <tt>example_proxy.h</tt> and <tt>example_proxy.c</tt> files. The name of the file is derived from the name of the input file. To change this, you can use the <tt>-o</tt> option.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The <tt>wrap</tt> file contains the wrapper functions, which perform the main functionality of SWIG: they translate input arguments from C to C++, make call to original functions and all the neccessery actions, and translate C++ output back to C data. The <tt>proxy</tt> header file contains the interface we can use in C application code. The additional <tt>.c</tt> file contains calls to the wrapper functions, allowing us to preserve names of the original functions.
|
||||
</p>
|
||||
|
||||
<H3><a name="c_commandline"></a>36.2.2 Command line options</H3>
|
||||
|
||||
|
||||
<p>
|
||||
The following table list the additional commandline options available for the C module. They can also be seen by using:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
swig -c -help
|
||||
</pre></div>
|
||||
|
||||
<table summary="C specific options">
|
||||
<tr>
|
||||
<th>C specific options</th>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>-noproxy</td>
|
||||
<td>do not generate proxy files (i.e. <i>filename</i><tt>_proxy.h</tt> and <i>filename</i><tt>_proxy.c</tt>)</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>-noexcept</td>
|
||||
<td>generate wrappers with no support of exception handling; see <a href="#c_exceptions">Exceptions</a> chapter for more details </td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
<H3><a name="c_dynamic"></a>36.2.3 Compiling dynamic module</H3>
|
||||
|
||||
|
||||
The next step is to build dynamically loadable module, which we can link to our application. This can be done easily, for example using <tt>gcc</tt> compiler (Linux, MINGW, etc.):
|
||||
|
||||
<div class="code"><pre>
|
||||
$ swig -c example.i
|
||||
$ gcc -c example_wrap.c
|
||||
$ gcc -shared example_wrap.o -o libexample.so
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Or, for C++ input:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
$ swig -c++ -c example.i
|
||||
$ g++ -c example_wrap.c
|
||||
$ g++ -shared example_wrap.o -o libexample.so
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
Now the shared library module is ready to use. Note that the name of generated module is important: is should be prefixed with <tt>lib</tt>, and have the specific extension, like <tt>.dll</tt> for Windows or <tt>.so</tt> for Unix systems.
|
||||
</p>
|
||||
|
||||
<H3><a name="c_using_module"></a>36.2.4 Using generated module</H3>
|
||||
|
||||
|
||||
<p>
|
||||
The simplest way to use generated shared module is to link it to the application code on the compiling stage. We have to compile the proxy file as well. The process is usually similar to the shown below:
|
||||
</p>
|
||||
|
||||
<div class="code"><pre>
|
||||
$ gcc runme.c example_proxy.c -L. -lexample -o runme
|
||||
</pre></div>
|
||||
|
||||
<p>
|
||||
This will compile application code (<tt>runme.c</tt>), along with proxy and link it against the generated shared module. Following the <tt>-L</tt> option is the path to the directory containing the shared module. The output executable is ready to use. The last thing to do is to supply the operating system the information of location of our module. This is system dependant, for instance Unix systems look for shared modules in certain directories, like <tt>/usr/lib</tt>, and additionally we can set the environment variable <tt>LD_LIBRARY_PATH</tt> for other directories.
|
||||
</p>
|
||||
|
||||
<H2><a name="c_basic_c_wrapping"></a>36.3 Basic C wrapping</H2>
|
||||
|
||||
|
||||
<H3><a name="c_c_functions"></a>36.3.1 Functions</H3>
|
||||
|
||||
|
||||
<H3><a name="c_c_variables"></a>36.3.2 Variables</H3>
|
||||
|
||||
|
||||
<H2><a name="c_basic_cpp_wrapping"></a>36.4 Basic C++ wrapping</H2>
|
||||
|
||||
|
||||
<H3><a name="c_classes"></a>36.4.1 Classes</H3>
|
||||
|
||||
|
||||
<H2><a name="c_exceptions"></a>36.5 Exception handling</H2>
|
||||
|
||||
|
||||
</body>
|
||||
</html>
|
||||
|
||||
|
||||
|
|
@ -14,6 +14,7 @@ Varargs.html
|
|||
Warnings.html
|
||||
Modules.html
|
||||
Allegrocl.html
|
||||
C.html
|
||||
CSharp.html
|
||||
Chicken.html
|
||||
Guile.html
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue