Commit bad67e4a authored by Jeroen Demeyer's avatar Jeroen Demeyer

Clarify documentation regarding "cdef public"

parent 0558bdb4
...@@ -339,42 +339,57 @@ Public Declarations ...@@ -339,42 +339,57 @@ Public Declarations
--------------------- ---------------------
You can make C types, variables and functions defined in a Cython module You can make C types, variables and functions defined in a Cython module
accessible to C code that is linked with the module, by declaring them with accessible to C code that is linked together with the Cython-generated C file,
the public keyword:: by declaring them with the public keyword::
cdef public struct Bunny: # public type declaration cdef public struct Bunny: # public type declaration
int vorpalness int vorpalness
cdef public int spam # public variable declaration cdef public int spam # public variable declaration
cdef public void grail(Bunny *): # public function declaration cdef public void grail(Bunny *) # public function declaration
print "Ready the holy hand grenade"
If there are any public declarations in a Cython module, a header file called If there are any public declarations in a Cython module, a header file called
:file:`modulename.h` file is generated containing equivalent C declarations for :file:`modulename.h` file is generated containing equivalent C declarations for
inclusion in other C code. inclusion in other C code.
Users who are embedding Python in C with Cython need to make sure to call Py_Initialize() A typical use case for this is building an extension module from multiple
and Py_Finalize(). For example, in the following snippet that includes :file:`modulename.h`:: C sources, one of them being Cython generated (i.e. with something like
``Extension("grail", sources=["grail.pyx", "grail_helper.c"])`` in ``setup.py``.
In this case, the file ``grail_helper.c`` just needs to add
``#include "grail.h"`` in order to access the public Cython variables.
A more advanced use case is embedding Python in C using Cython.
In this case, make sure to call Py_Initialize() and Py_Finalize().
For example, in the following snippet that includes :file:`grail.h`:
.. code-block:: c
#include <Python.h> #include <Python.h>
#include "modulename.h" #include "grail.h"
void grail() { int main() {
Py_Initialize(); Py_Initialize();
initmodulename(); initgrail();
Bunny b; Bunny b;
grail(b); grail(b);
Py_Finalize(); Py_Finalize();
} }
Any C code wanting to make use of these declarations will need to be linked, This C code can then be built together with the Cython-generated C code
either statically or dynamically, with the extension module. in a single program (or library).
If the Cython module resides within a package, then the name of the ``.h`` If the Cython module resides within a package, then the name of the ``.h``
file consists of the full dotted name of the module, e.g. a module called file consists of the full dotted name of the module, e.g. a module called
:mod:`foo.spam` would have a header file called :file:`foo.spam.h`. :mod:`foo.spam` would have a header file called :file:`foo.spam.h`.
.. NOTE::
On some operating systems like Linux, it is also possible to first
build the Cython extension in the usual way and then link against
the resulting ``.so`` file like a dynamic library.
Beware that this is not portable, so it should be avoided.
.. _api: .. _api:
C API Declarations C API Declarations
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment