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

Python docs on static linking section edits

Browse source
This commit is contained in:
William S Fulton 2016-06-12 00:13:07 +01:00
commit 64f5d23b13
2 changed files with 45 additions and 43 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_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_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_both_global_modules">Both modules are global</a>
<li><a href="Python.html#Python_package_search_static">Statically linked C modules</a>
</ul> </ul>
</ul> </ul>
<li><a href="Python.html#Python_python3support">Python 3 Support</a> <li><a href="Python.html#Python_python3support">Python 3 Support</a>

83
Doc/Manual/Python.html
View file

@ -122,7 +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> <li><a href="#Python_package_search_static">Statically linked C modules</a>
</ul> </ul>
</ul> </ul>
<li><a href="#Python_python3support">Python 3 Support</a> <li><a href="#Python_python3support">Python 3 Support</a>
@ -6068,73 +6068,74 @@ as desired.
<H4><a name="Python_package_search_static">36.11.6.4 Statically linked C modules</a></H4> <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 <p>It is strongly recommended to use dynamically linked modules for the C
portion of your pair of python modules. See the section on portion of your pair of Python modules.
<a href="#Python_nn8">Static Linking</a>. If for some reason you still need If for some reason you still need
to link the C module of the pair of python modules generated by swig into 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 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. 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>
<p>When python is extended with C code the python interpreter needs to be <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 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 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 called in the correct way when the module is dynamically loaded. However
when the code is not dynamically loaded (because it is statically linked) when the code is not dynamically loaded (because it is statically linked)
Then the initialization method for the module created by swig is not Then the initialization method for the module created by SWIG is not
called automatically. And the python interpreter has no idea that the called automatically and the Python interpreter has no idea that the
new swig C module exists. new SWIG C module exists.
</p> </p>
<p>Before python3, one could simply call the init method created by swig <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 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 loaded. The specific name of this method is not given here because statically
linked modules are not encouraged with swig linked modules are not encouraged with SWIG
(<a href="#Python_nn8">Static Linking</a>). However one can find this (<a href="Python.html#Python_nn8">Static Linking</a>). However one can find this
init function in the _wrap.c file generated by swig. init function in the C file generated by SWIG.
</p> </p>
<p>Assuming you have found the init function in the _wrap.c file and you <p>If you are really keen on static linking there are two ways
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
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.
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
Python2 and Python3 treat this init function differently. And they way they treat it affects how the pure Python module will be able to
they treat it differently affects how the pure python module will be able to
locate the C module. locate the C module.
</p> </p>
<p>The details concerning this are covered completly in the documentation <p>The details concerning this are covered completly in the documentation
for python itself. Links to the relavent sections follow: for Python itself. Links to the relavent sections follow:
</p> </p>
<ul> <ul>
<li><a href="https://docs.python.org/2/extending/extending.html#methodtable"/>Extending in python2</li> <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"/a>Extending in python3</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> </ul>
<p>There are two keys things to understand. The first of which is that in <p>There are two keys things to understand. The first is that in
python2 the init() function returns void. But in python3, the init() funcion Python 2 the init() function returns void. In Python 3 the init() function
returns a PyObject * which points to the new module. Secondly when returns a PyObject * which points to the new module. Secondly, when
you call the init() method manually, you are the python importer. So, you you call the init() method manually, you are the Python importer. So, you
determine which package the C module will be located in. determine which package the C module will be located in.
</p> </p>
<p>So, if you are using python3 it is important that you follow what is <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 described in the Python documentation linked above. In particular, you can't
simply call the init() function generated by swig and cast the PyObject 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 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 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 not be able to find it. You need to register your module with the Python
interpreter as descibed in the python docs. interpreter as described in the Python docs.
</p> </p>
<p>With python2 things are somewhat more simple. In this case the init function <p>With Python 2 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> 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 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 because it tries both the pure Python module it is part of and the global
globally. If you wish to not have the statically linked module be a 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 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. to do this (remember you are now the Python importer) or use dynamic linking.
</p> </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>