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

Merge branch 'mromberg-extend'

Browse source 
* mromberg-extend:
  Python docs on static linking section edits
  Add more documentation about statically linked python modules.
This commit is contained in:
William S Fulton 2016-06-12 00:13:30 +01:00
commit b8cbe1399b
2 changed files with 74 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

1
Doc/Manual/Contents.html
View file

@ -1600,6 +1600,7 @@
<li><a href="Python.html#Python_package_search_both_package_modules">Both modules in the same package</a>
<li><a href="Python.html#Python_package_search_wrapper_split">Split modules</a>
<li><a href="Python.html#Python_package_search_both_global_modules">Both modules are global</a>
<li><a href="Python.html#Python_package_search_static">Statically linked C modules</a>
</ul>
</ul>
<li><a href="Python.html#Python_python3support">Python 3 Support</a>

73
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_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_static">Statically linked C modules</a>
</ul>
</ul>
<li><a href="#Python_python3support">Python 3 Support</a>
@ -6065,6 +6066,78 @@ loaded modules. So, one may place the module either globally or in a package
as desired.
</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.
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.
Please also see the <a href="Python.html#Python_nn8">Static Linking</a> section.
</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 Python 3, 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.html#Python_nn8">Static Linking</a>). However one can find this
init function in the C file generated by SWIG.
</p>
<p>If you are really keen on static linking 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.
Python 2 and Python 3 treat this init function differently. And the way
they treat it 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</a></li>
<li><a href="https://docs.python.org/3.6/extending/extending.html#the-module-s-method-table-and-initialization-function">Extending in python3</a></li>
</ul>
<p>There are two keys things to understand. The first is that in
Python 2 the init() function returns void. In Python 3 the init() function
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 Python 3 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 Python 3 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 described in the Python docs.
</p>
<p>With Python 2 things are somewhat more simple. In this case the init function
returns void. 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 pure Python module it is part of and the global
module. If you wish not to 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>