.. highlight:: cython
-.. external-C-code:
+.. _external-C-code:
**********************************
Interfacing with External C Code
You can also use public declarations to make C functions and variables defined
in a Cython module available to external C code. The need for this is expected
to be less frequent, but you might want to do it, for example, if you are
-embedding Python in another application as a scripting language. Just as a
+`embedding Python`_ in another application as a scripting language. Just as a
Cython module can be used as a bridge to allow Python code to call C code, it
can also be used to allow C code to call Python code.
+.. _embedding Python: http://www.freenet.org.nz/python/embeddingpyrex/
+
External declarations
=======================
1. Don't use ``const``. Cython doesn't know anything about ``const``, so just
leave it out. Most of the time this shouldn't cause any problem, although
- on rare occasions you might have to use a cast.
+ on rare occasions you might have to use a cast. You can also explicitly
+ declare something like::
+
+ ctypedef char* const_char_ptr "const char*"
+
+ though in most cases this will not be needed.
.. warning::
ctypedef int size_t
will work okay whatever the actual size of a :ctype:`size_t` is (provided the header
- file defines it correctly).
+ file defines it correctly). Conversion to and from Python types, if any, will also
+ be used for this new type.
5. If the header file uses macros to define constants, translate them into a
dummy ``enum`` declaration.
6. If the header file defines a function using a macro, declare it as though
it were an ordinary function, with appropriate argument and result types.
+7. For archaic reasons C uses the keyword :keyword:`void` to declare a function
+ taking no parameters. In Cython as in Python, simply declare such functions
+ as :meth:`foo()`.
+
A few more tricks and tips:
* If you want to include a C header because it's needed by another header, but
==================================
Cython provides two methods for making C declarations from a Cython module
-available for use by external C code – public declarations and C API
+available for use by external C code---public declarations and C API
declarations.
.. note::
A ``.pxd`` file that consists solely of extern declarations does not need
to correspond to an actual ``.pyx`` file or Python module. This can make it a
convenient place to put common declarations, for example declarations of
-functions from an external library that one wants to use in several modules.
+functions from an :ref:`external library <external-C-code>` that one wants to use in several modules.
What a Definition File contains
================================
Notice that the files have been given a name, this is not necessary, but it
makes the file easier to format if the list gets long.
-If any of the files depend on include paths information can be passed to the
-:obj:`Extension` class through the :keyword:`include_dirs` option, which is a
-list of paths to the include directories.
+The :class:`Extension` class takes many options, and a fuller explanation can
+be found in the `distutils documentation`_. Some useful options to know about
+are ``include_dirs``, ``libraries``, and ``library_dirs`` which specify where
+to find the ``.h`` and library files when linking to external libraries.
+
+.. _distutils documentation: http://docs.python.org/extending/building.html
+
Multiple Cython Files in a Package