From a6b8bae5ead883b45eae07ac1915b644b50ccbbb Mon Sep 17 00:00:00 2001 From: Robert Bradshaw Date: Sun, 25 Jan 2009 01:56:00 -0800 Subject: [PATCH] sharing declarations, compiling --- docs/external_C_code.rst | 22 +++++++++++++++++----- docs/sharing_declarations.rst | 2 +- docs/source_files_and_compilation.rst | 10 +++++++--- 3 files changed, 25 insertions(+), 9 deletions(-) diff --git a/docs/external_C_code.rst b/docs/external_C_code.rst index 9e0ac729..6514c73f 100644 --- a/docs/external_C_code.rst +++ b/docs/external_C_code.rst @@ -1,6 +1,6 @@ .. highlight:: cython -.. external-C-code: +.. _external-C-code: ********************************** Interfacing with External C Code @@ -13,10 +13,12 @@ variables from the library that you want to use. 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 ======================= @@ -63,7 +65,12 @@ match the C ones, and in some cases they shouldn't or can't. In particular: 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:: @@ -121,7 +128,8 @@ match the C ones, and in some cases they shouldn't or can't. In particular: 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. @@ -129,6 +137,10 @@ match the C ones, and in some cases they shouldn't or can't. In particular: 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 @@ -280,7 +292,7 @@ Using Cython Declarations from C ================================== 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:: diff --git a/docs/sharing_declarations.rst b/docs/sharing_declarations.rst index a75642c1..7648e41b 100644 --- a/docs/sharing_declarations.rst +++ b/docs/sharing_declarations.rst @@ -24,7 +24,7 @@ statement. 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 ` that one wants to use in several modules. What a Definition File contains ================================ diff --git a/docs/source_files_and_compilation.rst b/docs/source_files_and_compilation.rst index 9ce98973..08ef2fa6 100644 --- a/docs/source_files_and_compilation.rst +++ b/docs/source_files_and_compilation.rst @@ -70,9 +70,13 @@ would be:: 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 -- 2.26.2