USAGE.txt 2.59 KB
Newer Older
1
Cython - Usage Instructions
William Stein's avatar
William Stein committed
2 3
==========================

4
Building Cython extensions using distutils
William Stein's avatar
William Stein committed
5 6
-----------------------------------------

7 8
Cython comes with an experimental distutils extension for compiling
Cython modules, contributed by Graham Fawcett of the University of
William Stein's avatar
William Stein committed
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32
Windsor (fawcett@uwindsor.ca).

The Demos directory contains a setup.py file demonstrating its use. To
compile the demos:

(1)  cd Demos

(2)  python setup.py build_ext --inplace

         or

     python setup.py build --build-lib=.

(You may get a screed of warnings from the C compiler, but you can
ignore these -- as long as there are no actual errors, things are
probably okay.)

Try out the extensions with:

     python run_primes.py
     python run_spam.py
     python run_numeric_demo.py


33
Building Cython extensions by hand
William Stein's avatar
William Stein committed
34 35
---------------------------------

36
You can also invoke the Cython compiler on its own to translate a .pyx
William Stein's avatar
William Stein committed
37 38
file to a .c file. On Unix,

39
     cython filename.pyx
William Stein's avatar
William Stein committed
40 41 42

On other platforms,

43
     python cython.py filename.pyx
William Stein's avatar
William Stein committed
44 45 46 47 48 49 50 51 52 53

It's then up to you to compile and link the .c file using whatever
procedure is appropriate for your platform. The file
Makefile.nodistutils in the Demos directory shows how to do this for
one particular Unix system.


Command line options
--------------------

54
The cython command supports the following options:
William Stein's avatar
William Stein committed
55 56 57

  Short Long              Argument    Description
  -----------------------------------------------------------------------------
58
  -v    --version                     Display version number of cython compiler
William Stein's avatar
William Stein committed
59
  -l    --create-listing              Write error messages to a .lis file
60
  -I    --include-dir     <directory> Search for include files in named
61
                                      directory (may be repeated)
William Stein's avatar
William Stein committed
62
  -o    --output-file     <filename>  Specify name of generated C file (only
63 64 65 66 67 68
                                      one source file allowed if this is used)
  -p, --embed-positions               If specified, the positions in Cython files of each
                                      function definition is embedded in its docstring.
  -z, --pre-import <module>           If specified, assume undeclared names in this
                                      module. Emulates the behavior of putting
                                      "from <module> import *" at the top of the file.
William Stein's avatar
William Stein committed
69

70 71 72

Anything else is taken as the name of a Cython source file and compiled
to a C source file. Multiple Cython source files can be specified
William Stein's avatar
William Stein committed
73 74 75
(unless -o is used), in which case each source file is treated as the
source of a distinct extension module and compiled separately to
produce its own C file.