compilation.rst 3.01 KB
Newer Older
Peter Alexander's avatar
Peter Alexander committed
1 2 3 4 5 6 7 8
.. highlight:: cython

.. _compilation:

***********
Compilation
***********

9
Cython code, unlike Python, must be compiled.  This happens in two stages:
Peter Alexander's avatar
Peter Alexander committed
10

11
  * A ``.pyx`` file is compiles by Cython to a ``.c`` file.
12

13 14
  * The ``.c`` file is compiled by a C comiler to a ``.so`` file (or a
    ``.pyd`` file on Windows)
15

16 17
The following sub-sections describe several ways to build your
extension modules.
Peter Alexander's avatar
Peter Alexander committed
18 19 20 21 22

=====================
From the Command Line
=====================

23 24
Run the Cython compiler command with your options and list of ``.pyx``
  files to generate.  For example::
25 26 27

    $ cython -a yourmod.pyx

28 29
This creates a ``yourmod.c`` file (and the -a switch produces a
generated html file).
30

31 32 33 34
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::
35 36 37

    $ gcc -shared -pthread -fPIC -fwrapv -O2 -Wall -fno-strict-aliasing -I/usr/include/python2.5 -o yourmod.so yourmod.c

38 39
[``gcc`` will need to have paths to your included header files and
paths to libraries you need to link with]
40

41 42
A ``yourmod.so`` file is now in the same directory and your module,
``yourmod``, is available for you to import as you normally would.
43

Peter Alexander's avatar
Peter Alexander committed
44 45 46 47
=========
Distutils
=========

48 49 50
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::
51 52 53 54 55 56 57 58 59 60 61 62 63

    from distutils.core import setup
    from distutils.extension import Extension
    from Cython.Distutils import build_ext

    ext_modules = [Extension("hello", ["hello.pyx"])]

    setup(
        name = ’Hello world app’,
        cmdclass = {’build_ext’: build_ext},
        ext_modules = ext_modules
    )

64 65 66
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.
67

Peter Alexander's avatar
Peter Alexander committed
68 69 70 71
=========
Pyximport
=========

72
For generating Cython code right in your pure python module just type::
73 74

    >>> import pyximport; pyximport.install()
75
    >>> import helloworld  
76 77
    Hello World

78 79 80 81
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.
82

83 84
In the case that Cython fails to compile a Python module, *pyximport*
will fall back to loading the source modules instead.
85

86 87 88
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``::
89 90 91

    >>> pyximport.install(pyimport = True)

Peter Alexander's avatar
Peter Alexander committed
92 93 94 95
====
Sage
====

96 97 98 99 100
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
<http://www.sagemath.org/doc/>` for details.