NAME

cython_freeze - create a C file for embedding Cython modules

SYNOPSIS

cython_freeze [-o outfile] [-p] module [...]

DESCRIPTION

cython_freeze generates a C source file to embed a Python interpreter with one or more Cython modules built in. This allows one to create a single executable from Cython code, without having to have separate shared objects for each Cython module. A major advantage of this approach is that it allows debuging with gprof(1), which does not work with shared objects.

Unless -p is given, the first module's __name__ is set to "__main__" and is imported on startup; if -p is given, a normal Python interpreter is built, with the given modules built into the binary.

Note that this method differs from cython --embed. The --embed options modifies the resulting C source file to include a main() function, so it can only be used on a single Cython module. The advantage --embed is simplicity. This module, on the other hand, can be used with multiple modules, but it requires another C source file to be created.

OPTIONS

-o FILE, --outfile=FILE write output to FILE instead of standard output -p, --pymain do not automatically run the first module as main

EXAMPLE

In the example directory, there exist two Cython modules:

cmath.pyx A module that interfaces with the -lm library.

combinatorics.pyx A module that implements n-choose-r using cmath.

Both modules have the Python idiom if __name__ == "__main__", which only execute if that module is the "main" module. If run as main, cmath prints the factorial of the argument, while combinatorics prints n-choose-r.

The provided Makefile creates an executable, nCr, using combinatorics as the "main" module. It basically performs the following (ignoring the compiler flags)::

$ cython_freeze combinatorics cmath > nCr.c
$ cython combinatorics.pyx
$ cython cmath.pyx
$ gcc -c nCr.c
$ gcc -c combinatorics.c
$ gcc -c cmath.c
$ gcc nCr.o combinatorics.o cmath.o -o nCr

Because the combinatorics module was listed first, its __name__ is set to "__main__", while cmath's is set to "cmath". The executable now contains a Python interpreter and both Cython modules. ::

$ ./nCr
USAGE: ./nCr n r
Prints n-choose-r.
$ ./nCr 15812351235 12
5.10028093999e+113

You may wish to build a normal Python interpreter, rather than having one module as "main". This may happen if you want to use your module from an interactive shell or from another script, yet you still want it statically linked so you can profile it with gprof. To do this, add the --pymain flag to cython_freeze. In the Makefile, the python executable is built like this. ::

$ cython_freeze --pymain combinatorics cmath -o python.c
$ gcc -c python.c
$ gcc python.o combinatorics.o cmath.o -o python

Now python is a normal Python interpreter, but the cmath and combinatorics modules will be built into the executable. ::

$ python
Python 2.6.2 (release26-maint, Apr 19 2009, 01:58:18)
[GCC 4.3.3] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import cmath
>>> cmath.factorial(155)
4.7891429014634364e+273

PREREQUISITES

Cython 0.11.2 (or newer, assuming the API does not change)

SEE ALSO

• Python <http://www.python.org>_
• Cython <http://www.cython.org>_
• freeze.py <http://wiki.python.org/moin/Freeze>_