sipref.html

这是关于RFC3261实现sip的源代码

<h1><a class="toc-backref" href="#id30" name="installing-sip">3&nbsp;&nbsp;&nbsp;Installing SIP</a></h1>
<div class="section" id="downloading-sip">
<h2><a class="toc-backref" href="#id31" name="downloading-sip">3.1&nbsp;&nbsp;&nbsp;Downloading SIP</a></h2>
<p>You can get the latest release of the SIP source code from
<a class="reference" href="http://www.riverbankcomputing.co.uk/sip/download.php">http://www.riverbankcomputing.co.uk/sip/download.php</a>.</p>
<p>SIP is also included with all of the major Linux distributions.  However, it
may be a version or two out of date.</p>
<p>You may also find more up to date pre-compiled binaries on
<a class="reference" href="http://sourceforge.net/project/showfiles.php?group_id=61057">SourceForge</a>.</p>
</div>
<div class="section" id="configuring-sip">
<h2><a class="toc-backref" href="#id32" name="configuring-sip">3.2&nbsp;&nbsp;&nbsp;Configuring SIP</a></h2>
<p>After unpacking the source package (either a <tt class="docutils literal"><span class="pre">.tar.gz</span></tt> or a <tt class="docutils literal"><span class="pre">.zip</span></tt> file
depending on your platform) you should then check for any <tt class="docutils literal"><span class="pre">README</span></tt> files
that relate to your platform.</p>
<p>Next you need to configure SIP by executing the <tt class="docutils literal"><span class="pre">configure.py</span></tt> script.  For
example:</p>
<pre class="literal-block">
python configure.py
</pre>
<p>This assumes that the Python interpreter is on your path.  Something like the
following may be appropriate on Windows:</p>
<pre class="literal-block">
c:\python24\python configure.py
</pre>
<p>If you have multiple versions of Python installed then make sure you use the
interpreter for which you wish SIP to generate bindings for.</p>
<p>The full set of command line options is:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td>
<kbd><span class="option">-h</span></kbd></td>
<td>Display a help message.</td></tr>
<tr><td>
<kbd><span class="option">-a</span></kbd></td>
<td>Export all symbols in any SIP generated module and the SIP module
itself.  This was the default behaviour of SIP prior to v4.2.
Normally only a module's inititialisation function is exported.  This
option is deprecated as the <tt class="docutils literal"><span class="pre">ModuleMakefile</span></tt> class of <a class="reference" href="#the-sip-build-system">The SIP Build
System</a> allows this to be specified on a per module basis.</td></tr>
<tr><td>
<kbd><span class="option">-b</span> <var>dir</var></kbd></td>
<td>The SIP code generator will be installed in the directory <tt class="docutils literal"><span class="pre">dir</span></tt>.</td></tr>
<tr><td>
<kbd><span class="option">-d</span> <var>dir</var></kbd></td>
<td>The SIP module will be installed in the directory <tt class="docutils literal"><span class="pre">dir</span></tt>.</td></tr>
<tr><td>
<kbd><span class="option">-e</span> <var>dir</var></kbd></td>
<td>The SIP header file will be installed in the directory <tt class="docutils literal"><span class="pre">dir</span></tt>.</td></tr>
<tr><td>
<kbd><span class="option">-k</span></kbd></td>
<td>The SIP module will be built as a static library.  This is useful when
building the SIP module as a Python builtin (see
<a class="reference" href="#builtin-modules-and-custom-interpreters">Builtin Modules and Custom Interpreters</a>).</td></tr>
<tr><td>
<kbd><span class="option">-p</span> <var>plat</var></kbd></td>
<td>Explicitly specify the platform/compiler to be used by the build
system, otherwise a platform specific default will be used.  The
<tt class="docutils literal"><span class="pre">-h</span></tt> option will display all the supported platform/compilers and
the default.</td></tr>
<tr><td>
<kbd><span class="option">-u</span></kbd></td>
<td>The SIP module will be built with debugging symbols.</td></tr>
<tr><td>
<kbd><span class="option">-v</span> <var>dir</var></kbd></td>
<td>By default <tt class="docutils literal"><span class="pre">.sip</span></tt> files will be installed in the directory <tt class="docutils literal"><span class="pre">dir</span></tt>.</td></tr>
</tbody>
</table>
<p>The configure.py script takes many other options that allows the build system
to be finely tuned.  These are of the form <tt class="docutils literal"><span class="pre">name=value</span></tt> or <tt class="docutils literal"><span class="pre">name+=value</span></tt>.
The <tt class="docutils literal"><span class="pre">-h</span></tt> option will display each supported <tt class="docutils literal"><span class="pre">name</span></tt>, although not all are
applicable to all platforms.</p>
<p>The <tt class="docutils literal"><span class="pre">name=value</span></tt> form means that <tt class="docutils literal"><span class="pre">value</span></tt> will replace the existing value of
<tt class="docutils literal"><span class="pre">name</span></tt>.</p>
<p>The <tt class="docutils literal"><span class="pre">name+=value</span></tt> form means that <tt class="docutils literal"><span class="pre">value</span></tt> will be appended to the existing
value of <tt class="docutils literal"><span class="pre">name</span></tt>.</p>
<p>For example, the following will disable support for C++ exceptions (and so
reduce the size of module binaries) when used with GCC:</p>
<pre class="literal-block">
python configure.py CXXFLAGS+=-fno-exceptions
</pre>
<p>A pure Python module called <tt class="docutils literal"><span class="pre">sipconfig.py</span></tt> is generated by <tt class="docutils literal"><span class="pre">configure.py</span></tt>.
This defines each <tt class="docutils literal"><span class="pre">name</span></tt> and its corresponding <tt class="docutils literal"><span class="pre">value</span></tt>.  Looking at it will
give you a good idea of how the build system uses the different options.  It is
covered in detail in <a class="reference" href="#the-sip-build-system">The SIP Build System</a>.</p>
<div class="section" id="configuring-sip-using-mingw">
<h3><a class="toc-backref" href="#id33" name="configuring-sip-using-mingw">3.2.1&nbsp;&nbsp;&nbsp;Configuring SIP Using MinGW</a></h3>
<p>SIP, and the modules it generates, can be built with MinGW, the Windows port of
GCC.  You must use the <tt class="docutils literal"><span class="pre">-p</span></tt> command line option to specify the correct
platform.  For example:</p>
<pre class="literal-block">
c:\python24\python configure.py -p win32-g++
</pre>
</div>
<div class="section" id="configuring-sip-using-the-borland-c-compiler">
<h3><a class="toc-backref" href="#id34" name="configuring-sip-using-the-borland-c-compiler">3.2.2&nbsp;&nbsp;&nbsp;Configuring SIP Using the Borland C++ Compiler</a></h3>
<p>SIP, and the modules it generates, can be built with the free Borland C++
compiler.  You must use the <tt class="docutils literal"><span class="pre">-p</span></tt> command line option to specify the correct
platform.  For example:</p>
<pre class="literal-block">
c:\python24\python configure.py -p win32-borland
</pre>
<p>You must also make sure you have a Borland-compatible version of the Python
library.  If you are using the standard Python distribution (built using the
Microsoft compiler) then you must convert the format of the Python library.
For example:</p>
<pre class="literal-block">
coff2omf python24.lib python24_bcpp.lib
</pre>
</div>
</div>
<div class="section" id="building-sip">
<h2><a class="toc-backref" href="#id35" name="building-sip">3.3&nbsp;&nbsp;&nbsp;Building SIP</a></h2>
<p>The next step is to build SIP by running your platform's <tt class="docutils literal"><span class="pre">make</span></tt> command.  For
example:</p>
<pre class="literal-block">
make
</pre>
<p>The final step is to install SIP by running the following command:</p>
<pre class="literal-block">
make install
</pre>
<p>(Depending on your system you may require root or administrator privileges.)</p>
<p>This will install the various SIP components.</p>
</div>
</div>
<div class="section" id="using-sip">
<h1><a class="toc-backref" href="#id36" name="using-sip">4&nbsp;&nbsp;&nbsp;Using SIP</a></h1>
<p>Bindings are generated by the SIP code generator from a number of specification
files, typically with a <tt class="docutils literal"><span class="pre">.sip</span></tt> extension.  Specification files look very
similar to C and C++ header files, but often with additional information (in
the form of a <em>directive</em> or an <em>annotation</em>) and code so that the bindings
generated can be finely tuned.</p>
<div class="section" id="a-simple-c-example">
<h2><a class="toc-backref" href="#id37" name="a-simple-c-example">4.1&nbsp;&nbsp;&nbsp;A Simple C++ Example</a></h2>
<p>We start with a simple example.  Let's say you have a (fictional) C++ library
that implements a single class called <tt class="docutils literal"><span class="pre">Word</span></tt>.  The class has one constructor
that takes a <tt class="docutils literal"><span class="pre">\0</span></tt> terminated character string as its single argument.  The
class has one method called <tt class="docutils literal"><span class="pre">reverse()</span></tt> which takes no arguments and returns
a <tt class="docutils literal"><span class="pre">\0</span></tt> terminated character string.  The interface to the class is defined in
a header file called <tt class="docutils literal"><span class="pre">word.h</span></tt> which might look something like this:</p>
<pre class="literal-block">
// Define the interface to the word library.

class Word {
    const char *the_word;

public:
    Word(const char *w);

    char *reverse() const;
};
</pre>
<p>The corresponding SIP specification file would then look something like this:</p>
<pre class="literal-block">
// Define the SIP wrapper to the word library.

%Module word 0

class Word {

%TypeHeaderCode
#include &lt;word.h&gt;
%End

public:
    Word(const char *w);

    char *reverse() const;
};
</pre>
<p>Obviously a SIP specification file looks very much like a C++ (or C) header
file, but SIP does not include a full C++ parser.  Let's look at the
differences between the two files.</p>
<blockquote>
<ul class="simple">
<li>The <a class="reference" href="#module">%Module</a> directive has been added <a class="footnote-reference" href="#id4" id="id1" name="id1">[1]</a>.  This is used to name the
Python module that is being created and to give it a <em>generation</em> number.
In this example these are <tt class="docutils literal"><span class="pre">word</span></tt> and <tt class="docutils literal"><span class="pre">0</span></tt> respectively.  The
generation number is effectively the version number of the module.</li>
<li>The <a class="reference" href="#typeheadercode">%TypeHeaderCode</a> directive has been added.  The text between this
and the following <a class="reference" href="#end">%End</a> directive is included literally in the code
that SIP generates.  Normally it is used, as in this case, to
<tt class="docutils literal"><span class="pre">#include</span></tt> the corresponding C++ (or C) header file <a class="footnote-reference" href="#id5" id="id2" name="id2">[2]</a>.</li>
<li>The declaration of the private variable <tt class="docutils literal"><span class="pre">this_word</span></tt> has been removed.
SIP does not support access to either private or protected instance
variables.</li>
</ul>
</blockquote>
<p>If we want to we can now generate the C++ code in the current directory by
running the following command:</p>
<pre class="literal-block">
sip -c . word.sip
</pre>
<p>However, that still leaves us with the task of compiling the generated code and
linking it against all the necessary libraries.  It's much easier to use the
SIP build system to do the whole thing.</p>