freeze: add --pymain example

Add an example of building a --pymain Python interpreter to the README
and to the Makefile.

Demos/freeze/Makefile

@@ -14,25 +14,28 @@ LDLIBS = $(PY_LDLIBS)
 
 
 # Name of executable
-TARGET = nCr
+TARGETS = nCr python
 
 # List of Cython source files, with main module first.
 CYTHON_SOURCE = combinatorics.pyx cmath.pyx
 CYTHON_SECONDARY = $(CYTHON_SOURCE:.pyx=.c) $(TARGETS:=.c)
 
 
-all : $(TARGET)
+all : $(TARGETS)
 
-$(TARGET) : $(TARGET).o $(CYTHON_SOURCE:.pyx=.o)
+$(TARGETS) : % : %.o $(CYTHON_SOURCE:.pyx=.o)
 
-$(TARGET).c :
+nCr.c :
 	$(CYTHON_FREEZE) $(CYTHON_SOURCE:.pyx=) > $@
 
+python.c :
+	$(CYTHON_FREEZE) --pymain $(CYTHON_SOURCE:.pyx=) > $@
+
 %.c : %.pyx
 	$(CYTHON) $(CYTHONFLAGS) $^
 
 clean:
-	$(RM) *.o $(CYTHON_SECONDARY) $(TARGET)
+	$(RM) *.o $(CYTHON_SECONDARY) $(TARGETS)
 
 .PHONY: clean
 .SECONDARY: $(CYTHON_SECONDARY)

Demos/freeze/README.rst

@@ -74,7 +74,27 @@ contains a Python interpreter and both Cython modules. ::
     $ ./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