third_party/cython/src/USAGE.txt

   1 Cython - Usage Instructions
   2 ==========================
   3
   4 Building Cython extensions using distutils
   5 -----------------------------------------
   6
   7 Cython comes with an experimental distutils extension for compiling
   8 Cython modules, contributed by Graham Fawcett of the University of
   9 Windsor (fawcett@uwindsor.ca).
  10
  11 The Demos directory contains a setup.py file demonstrating its use. To
  12 compile the demos:
  13
  14 (1)  cd Demos
  15
  16 (2)  python setup.py build_ext --inplace
  17
  18          or
  19
  20      python setup.py build --build-lib=.
  21
  22 (You may get a screed of warnings from the C compiler, but you can
  23 ignore these -- as long as there are no actual errors, things are
  24 probably okay.)
  25
  26 Try out the extensions with:
  27
  28      python run_primes.py
  29      python run_spam.py
  30      python run_numeric_demo.py
  31
  32
  33 Building Cython extensions by hand
  34 ---------------------------------
  35
  36 You can also invoke the Cython compiler on its own to translate a .pyx
  37 file to a .c file. On Unix,
  38
  39      cython filename.pyx
  40
  41 On other platforms,
  42
  43      python cython.py filename.pyx
  44
  45 It's then up to you to compile and link the .c file using whatever
  46 procedure is appropriate for your platform. The file
  47 Makefile.nodistutils in the Demos directory shows how to do this for
  48 one particular Unix system.
  49
  50
  51 Command line options
  52 --------------------
  53
  54 The cython command supports the following options:
  55
  56   Short Long              Argument    Description
  57   -----------------------------------------------------------------------------
  58   -v    --version                     Display version number of cython compiler
  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)
  62   -o    --output-file     <filename>  Specify name of generated C file (only
  63                                       one source file allowed if this is used)
  64   -p, --embed-positions               If specified, the positions in Cython files of each
  65                                       function definition is embedded in its docstring.
  66   -z, --pre-import <module>           If specified, assume undeclared names in this
  67                                       module. Emulates the behavior of putting
  68                                       "from <module> import *" at the top of the file.
  69
  70
  71 Anything else is taken as the name of a Cython source file and compiled
  72 to a C source file. Multiple Cython source files can be specified
  73 (unless -o is used), in which case each source file is treated as the
  74 source of a distinct extension module and compiled separately to
  75 produce its own C file.