[pypy-svn] r36623 - pypy/dist/pypy/doc

[simonb at codespeak.net]

Author: simonb
Date: Fri Jan 12 22:20:25 2007
New Revision: 36623

Added:
   pypy/dist/pypy/doc/standalone-howto.txt
Log:
rough guide to creating standalone executables with rpython

Added: pypy/dist/pypy/doc/standalone-howto.txt
==============================================================================
--- (empty file)
+++ pypy/dist/pypy/doc/standalone-howto.txt	Fri Jan 12 22:20:25 2007
@@ -0,0 +1,125 @@
+========================================================
+HOWTO: compile RPython code into a standalone executable
+========================================================
+
+First, see this Disclaimer_ in the FAQ.
+Next, understand the restrictions on RPython_ code.
+Pay close attention to the description of tuples and 
+dicts. 
+
+Take this example program::
+
+    import os
+    
+    def main(argv):
+        os.write(1, "Hello world!\n")
+    
+        return 0
+
+To compile::
+
+    from pypy.translator.interactive import Translation
+    t = Translation(main, standalone=True, gc='ref')
+    
+    t.source(backend='c')
+    path = t.compile()
+    print path
+
+The path is the location of the executable.
+
+To see the translation in motion, try removing
+the ``argv`` argument to main, or the ``return 0``.
+
+Type inference happens in the Annotator_.
+Keep this in mind as you write RPython code.
+After annotation the low level code generation
+(the implementation of the types)
+happens in the RTyper_.
+
+These steps can be spelled out explicitly::
+
+    t.annotate()
+    t.rtype()
+    t.source(backend='c')
+    path = t.compile()
+
+After the ``annotate()`` or ``rtype()`` call
+you can view the resulting flow graph with
+a pygame/dot based graphing tool::
+
+    t.annotate()
+    t.view()
+    t.rtype()
+    t.view()
+
+Here are some debugging tips:
+
+- make sure the program runs before you try and compile it. 
+  The semantics of RPython compiled code should be the same as regular python.
+- try assert'ing things in your code, for example ``assert isinstance(num, int)``,
+  this can provide hints to the translation process that can help pinpoint the 
+  problem.
+
+RType'ing is tricky! 
+
+Take this example::
+
+    def abs(num):
+        if num < 0:
+            num = -num
+        return num
+    
+If you want to use this function with
+different argument types (eg. ``int`` and ``float``)
+the translation will fail. In order
+to generate a different function for each argument
+type we need to set an attribute::
+
+    abs._annspecialcase_ = "specialize:argtype(0)"
+
+As another example::
+
+    def sum(l):
+        total = 0
+        for v in l:
+            total += v
+        return total
+    
+    sum._annspecialcase_ = "specialize:argtype(0)"
+
+Note that 
+if you use a function like this with a
+*tuple* argument, each tuple of distinct length is considered to
+be a unique type: PyPy will compile (specialize)
+a different ``sum`` function for each different length.
+
+Here is an example of using rctypes_::
+
+    import ctypes
+    from ctypes import c_int, c_char_p
+    import pypy.rpython.rctypes.implementation
+    
+    libc = ctypes.cdll.LoadLibrary('libc.so.6')
+    
+    write = libc.write
+    write.argtypes = [c_int, c_char_p, c_int]
+    write.restype = c_int
+    
+    def main(argv):
+    
+        msg = "Hello world!\n"
+        write(1, msg, len(msg))
+    
+        return 0
+
+PyPy implements the `ctypes semantics`_ as the corresponding native c-code
+equivalents.
+
+    
+.. _`Disclaimer`: faq.html#id10
+.. _`RPython`: coding-guide.html#restricted-python
+.. _`Annotator`: dynamic-language-translation.html#annotator
+.. _`RTyper`: dynamic-language-translation.html#rtyper
+.. _`rctypes`: rctypes.html
+.. _`ctypes semantics`: http://docs.python.org/dev/lib/module-ctypes.html
+