From 2bb732008a87b31cd043b4476389a8260fb69e55 Mon Sep 17 00:00:00 2001 From: Mike Romberg Date: Sat, 11 Jun 2016 16:08:24 -0600 Subject: [PATCH] Add more documentation about statically linked python modules. --- Doc/Manual/Python.html | 72 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) 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 @@
  • Both modules in the same package
  • Split modules
  • Both modules are global +
  • Statically linked C modules
  • Python 3 Support @@ -6065,6 +6066,77 @@ loaded modules. So, one may place the module either globally or in a package as desired.

    +

    36.11.6.4 Statically linked C modules

    + +

    It is strongly recommended to use dynamically linked modules for the C +portion of your pair of python modules. See the section on +Static Linking. 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. +

    + +

    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. +

    + +

    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 +(Static Linking). However one can find this +init function in the _wrap.c file generated by swig. +

    + +

    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. +

    + +

    The details concerning this are covered completly in the documentation +for python itself. Links to the relavent sections follow: +

    + + + +

    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. +

    + +

    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. +

    + +

    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 global +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. +

    +

    36.12 Python 3 Support