Commit 807d143a authored by Stefan Behnel's avatar Stefan Behnel

move some build docs from user guide to reference to reduce redundancy

parent 47a0950d
...@@ -43,6 +43,7 @@ paths to libraries you need to link with] ...@@ -43,6 +43,7 @@ paths to libraries you need to link with]
A ``yourmod.so`` file is now in the same directory and your module, A ``yourmod.so`` file is now in the same directory and your module,
``yourmod``, is available for you to import as you normally would. ``yourmod``, is available for you to import as you normally would.
Compiling with ``distutils`` Compiling with ``distutils``
============================ ============================
...@@ -67,6 +68,10 @@ The ``cythonize`` command also allows for multi-threaded compilation and ...@@ -67,6 +68,10 @@ The ``cythonize`` command also allows for multi-threaded compilation and
dependency resolution. Recompilation will be skipped if the target file dependency resolution. Recompilation will be skipped if the target file
is up to date with its main source file and dependencies. 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 If you have include files in non-standard places you can pass an
``include_path`` parameter to ``cythonize``:: ``include_path`` parameter to ``cythonize``::
...@@ -78,9 +83,15 @@ If you have include files in non-standard places you can pass an ...@@ -78,9 +83,15 @@ If you have include files in non-standard places you can pass an
ext_modules = cythonize("src/*.pyx", include_path = [...]), ext_modules = cythonize("src/*.pyx", include_path = [...]),
) )
If you need to specify compiler options, libraries to link with or other linker Often, Python packages that offer a C-level API provide a way to find
options you will need to create ``Extension`` instances manually (note the necessary include files, e.g. for NumPy::
that glob syntax can still be used to specify multiple extensions in one line)::
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.core import setup
from distutils.extension import Extension from distutils.extension import Extension
...@@ -109,6 +120,79 @@ If your options are static (for example you do not need to call a tool like ...@@ -109,6 +120,79 @@ If your options are static (for example you do not need to call a tool like
# distutils: libraries = spam eggs # distutils: libraries = spam eggs
# distutils: include_dirs = /opt/food/include # 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`` Compiling with ``pyximport``
============================= =============================
......
...@@ -55,37 +55,6 @@ current directory use: ...@@ -55,37 +55,6 @@ current directory use:
$ python setup.py build_ext --inplace $ 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 Multiple Cython Files in a Package
=================================== ===================================
...@@ -106,50 +75,6 @@ them through :func:`cythonize`:: ...@@ -106,50 +75,6 @@ them through :func:`cythonize`::
) )
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:
Pyximport Pyximport
......
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