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

Add more documentation about statically linked python modules.

Browse source
This commit is contained in:
Mike Romberg 2016-06-11 16:08:24 -06:00
commit 2bb732008a
1 changed files with 72 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

72
Doc/Manual/Python.html
View file

@ -122,6 +122,7 @@
<li><a href="#Python_package_search_both_package_modules">Both modules in the same package</a> <li><a href="#Python_package_search_both_package_modules">Both modules in the same package</a>
<li><a href="#Python_package_search_wrapper_split">Split modules</a> <li><a href="#Python_package_search_wrapper_split">Split modules</a>
<li><a href="#Python_package_search_both_global_modules">Both modules are global</a> <li><a href="#Python_package_search_both_global_modules">Both modules are global</a>
<li><a href="#Python_package_search_static">Statically linked C modules</a></li>
</ul> </ul>
</ul> </ul>
<li><a href="#Python_python3support">Python 3 Support</a> <li><a href="#Python_python3support">Python 3 Support</a>
@ -6065,6 +6066,77 @@ loaded modules. So, one may place the module either globally or in a package
as desired. as desired.
</p> </p>
<H4><a name="Python_package_search_static">36.11.6.4 Statically linked C modules</a></H4>
<p>It is strongly recommended to use dynamically linked modules for the C
portion of your pair of python modules. See the section on
<a href="#Python_nn8">Static Linking</a>. If for some reason you still need
to link the C module of the pair of python modules generated by swig into
your interpreter, then this section provides some details on how this impacts
the pure python modules ability to locate the other part of the pair.
</p>
<p>When python is extended with C code the python interpreter needs to be
informed about details of the new C functions that have been linked into
the executable. The code to do this is created by swig and is automatically
called in the correct way when the module is dynamically loaded. However
when the code is not dynamically loaded (because it is statically linked)
Then the initialization method for the module created by swig is not
called automatically. And the python interpreter has no idea that the
new swig C module exists.
</p>
<p>Before python3, one could simply call the init method created by swig
which would have normally been called when the shared object was dynamically
loaded. The specific name of this method is not given here because statically
linked modules are not encouraged with swig
(<a href="#Python_nn8">Static Linking</a>). However one can find this
init function in the _wrap.c file generated by swig.
</p>
<p>Assuming you have found the init function in the _wrap.c file and you
are still undeterred by what has been said so far, then there are two ways
to initialize the swig generated C module with the init method. Which way
you use depends on what version of python your module is being linked with.
Python2 and Python3 treat this init function differently. And they way
they treat it differently affects how the pure python module will be able to
locate the C module.
</p>
<p>The details concerning this are covered completly in the documentation
for python itself. Links to the relavent sections follow:
</p>
<ul>
<li><a href="https://docs.python.org/2/extending/extending.html#methodtable"/>Extending in python2</li>
<li><a href="https://docs.python.org/3.6/extending/extending.html#the-module-s-method-table-and-initialization-function"/a>Extending in python3</a></li>
</ul>
<p>There are two keys things to understand. The first of which is that in
python2 the init() function returns void. But in python3, the init() funcion
returns a PyObject * which points to the new module. Secondly when
you call the init() method manually, you are the python importer. So, you
determine which package the C module will be located in.
</p>
<p>So, if you are using python3 it is important that you follow what is
described in the python documentation linked above. In particular, you can't
simply call the init() function generated by swig and cast the PyObject
pointer it returns over the side. If you do then python3 still will have no
idea that your C module exists and the pure python half of your wrapper will
not be able to find it. You need to register your module with the python
interpreter as descibed in the python docs.
</p>
<p>With python2 things are somewhat more simple. In this case the init function
returns void. And calling it will register your new C module as a <b>global</b>
module. The pure python part of the swig wrapper will be able to find it
because it tries both the package the pure python module is part of and
globally. If you wish to not have the statically linked module be a global
module then you will either need to refer to the python documentation on how
to do this (remember you are now the python importer) or use dynamic linking.
</p>
<H2><a name="Python_python3support">36.12 Python 3 Support</a></H2> <H2><a name="Python_python3support">36.12 Python 3 Support</a></H2>