Commit 9a435c01 authored by Stefan Behnel's avatar Stefan Behnel

update userguide to use cythonize() for building

parent 53ee50c7
...@@ -29,6 +29,7 @@ The other, and probably better, way is to use the :mod:`distutils` extension ...@@ -29,6 +29,7 @@ The other, and probably better, way is to use the :mod:`distutils` extension
provided with Cython. The benifit of this method is that it will give the provided with Cython. The benifit of this method is that it will give the
platform specific compilation options, acting like a stripped down autotools. platform specific compilation options, acting like a stripped down autotools.
Basic setup.py Basic setup.py
=============== ===============
The distutils extension provided with Cython allows you to pass ``.pyx`` files The distutils extension provided with Cython allows you to pass ``.pyx`` files
...@@ -39,12 +40,10 @@ extension, say with filename :file:`example.pyx` the associated :file:`setup.py` ...@@ -39,12 +40,10 @@ extension, say with filename :file:`example.pyx` the associated :file:`setup.py`
would be:: would be::
from distutils.core import setup from distutils.core import setup
from distutils.extension import Extension from Cython.Build import cythonize
from Cython.Distutils import build_ext
setup( setup(
cmdclass = {'build_ext': build_ext}, ext_modules = cythonize("example.pyx")
ext_modules = [Extension("example", ["example.pyx"])]
) )
To understand the :file:`setup.py` more fully look at the official To understand the :file:`setup.py` more fully look at the official
...@@ -55,6 +54,7 @@ current directory use: ...@@ -55,6 +54,7 @@ current directory use:
$ python setup.py build_ext --inplace $ python setup.py build_ext --inplace
Cython Files Depending on C Files Cython Files Depending on C Files
=================================== ===================================
...@@ -63,14 +63,15 @@ compile them into your extension the basic :file:`setup.py` file to do this ...@@ -63,14 +63,15 @@ compile them into your extension the basic :file:`setup.py` file to do this
would be:: would be::
from distutils.core import setup from distutils.core import setup
from Cython.Build import cythonize
from distutils.extension import Extension from distutils.extension import Extension
from Cython.Distutils import build_ext
sourcefiles = ['example.pyx', 'helper.c', 'another_helper.c'] sourcefiles = ['example.pyx', 'helper.c', 'another_helper.c']
extensions = [Extension("example", sourcefiles)]
setup( setup(
cmdclass = {'build_ext': build_ext}, ext_modules = cythonize(extensions)
ext_modules = [Extension("example", sourcefiles)]
) )
Notice that the files have been given a name, this is not necessary, but it Notice that the files have been given a name, this is not necessary, but it
...@@ -88,17 +89,33 @@ to find the ``.h`` and library files when linking to external libraries. ...@@ -88,17 +89,33 @@ to find the ``.h`` and library files when linking to external libraries.
Multiple Cython Files in a Package Multiple Cython Files in a Package
=================================== ===================================
TODO To automatically compile multiple Cython files without listing all of them
explicitly, you can use glob patterns::
setup(
ext_modules = cythonize("package/*.pyx")
)
You can also use glob patterns in :class:`Extension` objects if you pass
them through :func:`cythonize`::
extensions = [Extension("*", "*.pyx")]
setup(
ext_modules = cythonize(extensions)
)
Distributing Cython modules Distributing Cython modules
============================ ============================
It is strongly recommended that you distribute the generated ``.c`` files as well 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 as your Cython sources, so that users can install your module without needing
to have Cython available. to have Cython available.
It is also recommended that Cython compilation not be enabled by default in the 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 probably 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 version he has 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. 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 This simply means that the :file:`setup.py` file that you ship with will just
...@@ -112,6 +129,26 @@ we would have instead:: ...@@ -112,6 +129,26 @@ we would have instead::
ext_modules = [Extension("example", ["example.c"])] 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:
......
...@@ -26,7 +26,6 @@ handling facilities, including the try-except and try-finally statements, is ...@@ -26,7 +26,6 @@ handling facilities, including the try-except and try-finally statements, is
available to you -- even in the midst of manipulating C data. available to you -- even in the midst of manipulating C data.
Cython Hello World Cython Hello World
=================== ===================
...@@ -37,17 +36,15 @@ So lets start with the canonical python hello world:: ...@@ -37,17 +36,15 @@ So lets start with the canonical python hello world::
print "Hello World" print "Hello World"
So the first thing to do is rename the file to :file:`helloworld.pyx`. Now we Save this code in a file named :file:`helloworld.pyx`. Now we need to create
need to make the :file:`setup.py`, which is like a python Makefile (for more the :file:`setup.py`, which is like a python Makefile (for more information
information see :ref:`compilation`). Your :file:`setup.py` should look like:: see :ref:`compilation`). Your :file:`setup.py` should look like::
from distutils.core import setup from distutils.core import setup
from distutils.extension import Extension from Cython.Build import cythonize
from Cython.Distutils import build_ext
setup( setup(
cmdclass = {'build_ext': build_ext}, ext_modules = cythonize("helloworld.pyx")
ext_modules = [Extension("helloworld", ["helloworld.pyx"])]
) )
To use this to build your Cython file use the commandline options: To use this to build your Cython file use the commandline options:
......
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