From 807d143ab3f711dd696fc09b582dad316651fade Mon Sep 17 00:00:00 2001 From: Stefan Behnel Date: Mon, 8 Jul 2013 18:42:18 +0200 Subject: [PATCH] move some build docs from user guide to reference to reduce redundancy --- docs/src/reference/compilation.rst | 90 +++++++++++++++++++++- .../src/userguide/source_files_and_compilation.rst | 75 ------------------ 2 files changed, 87 insertions(+), 78 deletions(-) diff --git a/docs/src/reference/compilation.rst b/docs/src/reference/compilation.rst index 0e7f355..05ac99d 100644 --- a/docs/src/reference/compilation.rst +++ b/docs/src/reference/compilation.rst @@ -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, ``yourmod``, is available for you to import as you normally would. + Compiling with ``distutils`` ============================ @@ -67,6 +68,10 @@ The ``cythonize`` command also allows for multi-threaded compilation and 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``:: @@ -78,9 +83,15 @@ If you have include files in non-standard places you can pass an 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 @@ -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: 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`` ============================= diff --git a/docs/src/userguide/source_files_and_compilation.rst b/docs/src/userguide/source_files_and_compilation.rst index 53d7b5b..1ec52e1 100644 --- a/docs/src/userguide/source_files_and_compilation.rst +++ b/docs/src/userguide/source_files_and_compilation.rst @@ -55,37 +55,6 @@ current directory use: $ 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 =================================== @@ -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 -- 2.7.4