Commit bad67e4a authored by Jeroen Demeyer's avatar Jeroen Demeyer

Clarify documentation regarding "cdef public"

parent 0558bdb4
......@@ -339,42 +339,57 @@ Public Declarations
---------------------
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
the public keyword::
accessible to C code that is linked together with the Cython-generated C file,
by declaring them with the public keyword::
cdef public struct Bunny: # public type declaration
int vorpalness
cdef public int spam # public variable declaration
cdef public void grail(Bunny *): # public function declaration
print "Ready the holy hand grenade"
cdef public void grail(Bunny *) # public function declaration
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
inclusion in other C code.
Users who are embedding Python in C with Cython need to make sure to call Py_Initialize()
and Py_Finalize(). For example, in the following snippet that includes :file:`modulename.h`::
A typical use case for this is building an extension module from multiple
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 "modulename.h"
#include "grail.h"
void grail() {
int main() {
Py_Initialize();
initmodulename();
initgrail();
Bunny b;
grail(b);
Py_Finalize();
}
Any C code wanting to make use of these declarations will need to be linked,
either statically or dynamically, with the extension module.
This C code can then be built together with the Cython-generated C code
in a single program (or library).
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
: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:
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