Add more documentation about statically linked python modules.

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>