diff options
-rw-r--r-- | Doc/Manual/Python.html | 72 |
1 files changed, 72 insertions, 0 deletions
diff --git a/Doc/Manual/Python.html b/Doc/Manual/Python.html index a4af54de5..a6325342e 100644 --- a/Doc/Manual/Python.html +++ b/Doc/Manual/Python.html @@ -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></li> </ul> </ul> <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. </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> |