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 Demos/freeze 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>`_