From 830762427983ca5fc2e60893066d42573cd15fa5 Mon Sep 17 00:00:00 2001 From: Robert Bradshaw Date: Thu, 7 Apr 2011 17:16:59 -0700 Subject: [PATCH] Move compilation block to before directives, add note about cython.inline. --- docs/src/reference/compilation.rst | 207 +++++++++++++++++------------ 1 file changed, 120 insertions(+), 87 deletions(-) diff --git a/docs/src/reference/compilation.rst b/docs/src/reference/compilation.rst index b8490f1e..fff850d7 100644 --- a/docs/src/reference/compilation.rst +++ b/docs/src/reference/compilation.rst @@ -13,9 +13,128 @@ Cython code, unlike Python, must be compiled. This happens in two stages: * The ``.c`` file is compiled by a C compiler to a ``.so`` file (or a ``.pyd`` file on Windows) + +The following sub-sections describe several ways to build your +extension modules, and how to pass directives to the Cython compiler. + +Compiling from the command line +=============================== + +Run the Cython compiler command with your options and list of ``.pyx`` +files to generate. For example:: + + $ cython -a yourmod.pyx + +This creates a ``yourmod.c`` file, and the -a switch produces a +generated html file. Pass the ``-h`` flag for a complete list of +supported flags. + +Compiling your ``.c`` files will vary depending on your operating +system. Python documentation for writing extension modules should +have some details for your system. Here we give an example on a Linux +system:: + + $ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing -I/usr/include/python2.5 -o yourmod.so yourmod.c + +[``gcc`` will need to have paths to your included header files and +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`` +============================ + +First, make sure that ``distutils`` package is installed in your +system. The following assumes a Cython file to be compiled called +*hello.pyx*. Now, create a ``setup.py`` script:: + + from distutils.core import setup + from distutils.extension import Extension + from Cython.Distutils import build_ext + + ext_modules = [Extension("spam", ["spam.pyx"]), + Extension("ham", ["ham.pyx"])] + # You can add directives for each extension too + # by attaching the `pyrex_directives` + for e in ext modules: + e.pyrex_directives = {"boundscheck": False} + setup( + name = "My hello app", + cmdclass = {"build_ext": build_ext}, + ext_modules = ext_modules + ) + +Run the command ``python setup.py build_ext --inplace`` in your +system's command shell and you are done. Import your new extension +module into your python shell or script as normal. + +Cython provides utility code to automatically generate lists of +Extension objects from ```.pyx`` files, so one can write:: + + from distutils.core import setup + from Cython.Build import cythonize + + setup( + name = "My hello app", + ext_modules = cythonize("*.pyx"), + ) + +to compile all ``.pyx`` files in a given directory. +The ``cythonize`` command also allows for multi-threaded compilation and +dependency resolution. + +Compiling with ``pyximport`` +============================= + +For generating Cython code right in your pure python module just type:: + + >>> import pyximport; pyximport.install() + >>> import helloworld + Hello World + +This allows you to automatically run Cython on every ``.pyx`` that +Python is trying to import. You should use this for simple Cython +builds only where no extra C libraries and no special building setup +is needed. + +In the case that Cython fails to compile a Python module, *pyximport* +will fall back to loading the source modules instead. + +It is also possible to compile new ``.py`` modules that are being +imported (including the standard library and installed packages). For +using this feature, just tell that to ``pyximport``:: + + >>> pyximport.install(pyimport = True) + +Compiling with ``cython.inline`` +============================= + +One can also compile Cython in a fashion similar to SciPy's ``weave.inline``. +For example:: + + >>> import cython + >>> def f(a): + ... ret = cython.inline("return a+b", b=3) + ... + +Unbound variables are automatically pulled from the surrounding local +and global scopes, and the result of the compilation is cached for +efficient re-use. + +Compiling with Sage +=================== + +The Sage notebook allows transparently editing and compiling Cython +code simply by typing ``%cython`` at the top of a cell and evaluate +it. Variables and functions defined in a Cython cell are imported into the +running session. Please check `Sage documentation +`_ for details. + You can tailor the behavior of the Cython compiler by specifying the directives below. +==================== Compiler directives ==================== @@ -112,6 +231,7 @@ Locally For local blocks, you need to cimport the special builtin ``cython`` module:: + #!python cimport cython Then you can use the directives either as decorators or in a with @@ -127,90 +247,3 @@ statement, like this:: .. Warning:: These two methods of setting directives are **not** affected by overriding the directive on the command-line using the -X option. - -The following sub-sections describe several ways to build your -extension modules, and how to pass directives to the Cython compiler. - -Compiling from the command line -=============================== - -Run the Cython compiler command with your options and list of ``.pyx`` -files to generate. For example:: - - $ cython -a yourmod.pyx - -This creates a ``yourmod.c`` file, and the -a switch produces a -generated html file. Pass the ``-h`` flag for a complete list of -supported flags. - -Compiling your ``.c`` files will vary depending on your operating -system. Python documentation for writing extension modules should -have some details for your system. Here we give an example on a Linux -system:: - - $ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing -I/usr/include/python2.5 -o yourmod.so yourmod.c - -[``gcc`` will need to have paths to your included header files and -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`` -============================ - -First, make sure that ``distutils`` package is installed in your -system. The following assumes a Cython file to be compiled called -*hello.pyx*. Now, create a ``setup.py`` script:: - - from distutils.core import setup - from distutils.extension import Extension - from Cython.Distutils import build_ext - - ext_modules = [Extension("spam", ["spam.pyx"]), - Extension("ham", ["ham.pyx"])] - # You can add directives for each extension too - # by attaching the `pyrex_directives` - for e in ext modules: - e.pyrex_directives = {"boundscheck": False} - setup( - name = ’My hello app’, - cmdclass = {’build_ext’: build_ext}, - ext_modules = ext_modules - ) - -Run the command ``python setup.py build_ext --inplace`` in your -system's command shell and you are done. Import your new extension -module into your python shell or script as normal. - -Compiling with ``pyximport`` -============================= - -For generating Cython code right in your pure python module just type:: - - >>> import pyximport; pyximport.install() - >>> import helloworld - Hello World - -This allows you to automatically run Cython on every ``.pyx`` that -Python is trying to import. You should use this for simple Cython -builds only where no extra C libraries and no special building setup -is needed. - -In the case that Cython fails to compile a Python module, *pyximport* -will fall back to loading the source modules instead. - -It is also possible to compile new ``.py`` modules that are being -imported (including the standard library and installed packages). For -using this feature, just tell that to ``pyximport``:: - - >>> pyximport.install(pyimport = True) - -Compiling with Sage -=================== - -The Sage notebook allows transparently editing and compiling Cython -code simply by typing ``%cython`` at the top of a cell and evaluate -it. Variables and functions defined in a Cython cell imported into the -running session. Please check `Sage documentation -`_ for details. -- 2.26.2