A ``yourmod.so`` file is now in the same directory and your module,
``yourmod``, is available for you to import as you normally would.
+
Compiling with ``distutils``
============================
dependency resolution. Recompilation will be skipped if the target file
is up to date with its main source file and dependencies.
+
+Configuring the C-Build
+------------------------
+
If you have include files in non-standard places you can pass an
``include_path`` parameter to ``cythonize``::
ext_modules = cythonize("src/*.pyx", include_path = [...]),
)
-If you need to specify compiler options, libraries to link with or other linker
-options you will need to create ``Extension`` instances manually (note
-that glob syntax can still be used to specify multiple extensions in one line)::
+Often, Python packages that offer a C-level API provide a way to find
+the necessary include files, e.g. for NumPy::
+
+ include_path = [numpy.get_include()]
+
+If you need to specify compiler options, libraries to link with or other
+linker options you will need to create ``Extension`` instances manually
+(note that glob syntax can still be used to specify multiple extensions
+in one line)::
from distutils.core import setup
from distutils.extension import Extension
# distutils: libraries = spam eggs
# distutils: include_dirs = /opt/food/include
+If you have some C files that have been wrapped with Cython and you want to
+compile them into your extension, you can define the distutils ``sources``
+parameter::
+
+ # distutils: sources = helper.c, another_helper.c
+
+Note that these sources are added to the list of sources of the current
+extension module. Spelling this out in the :file:`setup.py` file looks
+as follows::
+
+ from distutils.core import setup
+ from Cython.Build import cythonize
+ from distutils.extension import Extension
+
+ sourcefiles = ['example.pyx', 'helper.c', 'another_helper.c']
+
+ extensions = [Extension("example", sourcefiles)]
+
+ setup(
+ ext_modules = cythonize(extensions)
+ )
+
+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
+
+
+Distributing Cython modules
+----------------------------
+
+It is strongly recommended that you distribute the generated ``.c`` files as well
+as your Cython sources, so that users can install your module without needing
+to have Cython available.
+
+It is also recommended that Cython compilation not be enabled by default in the
+version you distribute. Even if the user has Cython installed, he/she probably
+doesn't want to use it just to install your module. Also, the installed version
+may not be the same one you used, and may not compile your sources correctly.
+
+This simply means that the :file:`setup.py` file that you ship with will just
+be a normal distutils file on the generated `.c` files, for the basic example
+we would have instead::
+
+ from distutils.core import setup
+ from distutils.extension import Extension
+
+ setup(
+ ext_modules = [Extension("example", ["example.c"])]
+ )
+
+This is easy to combine with :func:`cythonize` by changing the file extension
+of the extension module sources::
+
+ from distutils.core import setup
+ from distutils.extension import Extension
+
+ USE_CYTHON = ... # command line option, try-import, ...
+
+ ext = '.pyx' if USE_CYTHON else '.c'
+
+ extensions = [Extension("example", ["example"+ext])]
+
+ if USE_CYTHON:
+ from Cython.Build import cythonize
+ extensions = cythonize(extensions)
+
+ setup(
+ ext_modules = extensions
+ )
+
Compiling with ``pyximport``
=============================
$ python setup.py build_ext --inplace
-Cython Files Depending on C Files
-===================================
-
-When you have come C files that have been wrapped with cython and you want to
-compile them into your extension the basic :file:`setup.py` file to do this
-would be::
-
- from distutils.core import setup
- from Cython.Build import cythonize
- from distutils.extension import Extension
-
- sourcefiles = ['example.pyx', 'helper.c', 'another_helper.c']
-
- extensions = [Extension("example", sourcefiles)]
-
- setup(
- ext_modules = cythonize(extensions)
- )
-
-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.
-
-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
===================================
)
-Distributing Cython modules
-============================
-
-It is strongly recommended that you distribute the generated ``.c`` files as well
-as your Cython sources, so that users can install your module without needing
-to have Cython available.
-
-It is also recommended that Cython compilation not be enabled by default in the
-version you distribute. Even if the user has Cython installed, he/she probably
-doesn't want to use it just to install your module. Also, the installed version
-may not be the same one you used, and may not compile your sources correctly.
-
-This simply means that the :file:`setup.py` file that you ship with will just
-be a normal distutils file on the generated `.c` files, for the basic example
-we would have instead::
-
- from distutils.core import setup
- from distutils.extension import Extension
-
- setup(
- ext_modules = [Extension("example", ["example.c"])]
- )
-
-This is easy to combine with :func:`cythonize` by changing the file extension
-of the extension module sources::
-
- from distutils.core import setup
- from distutils.extension import Extension
-
- USE_CYTHON = ... # command line option, try-import, ...
-
- ext = '.pyx' if USE_CYTHON else '.c'
-
- extensions = [Extension("example", ["example"+ext])]
-
- if USE_CYTHON:
- from Cython.Build import cythonize
- extensions = cythonize(extensions)
-
- setup(
- ext_modules = extensions
- )
-
-
.. _pyximport:
Pyximport