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

[arigo at codespeak.net]

Author: arigo
Date: Tue Sep 27 19:38:41 2005
New Revision: 17917

Modified:
   pypy/dist/pypy/doc/_ref.txt
   pypy/dist/pypy/doc/faq.txt
Log:
* Added a FAQ entry from mwh's mail on pypy-dev (27 Sep 2005).
* Added How do I compile my own RPython programs.
* Reformatted the FAQ.


Modified: pypy/dist/pypy/doc/_ref.txt
==============================================================================
--- pypy/dist/pypy/doc/_ref.txt	(original)
+++ pypy/dist/pypy/doc/_ref.txt	Tue Sep 27 19:38:41 2005
@@ -67,6 +67,7 @@
 .. _`pypy/translator/c/src/`: ../../pypy/translator/c/src
 .. _`pypy/translator/c/src/ll_os.h`: ../../pypy/translator/c/src/ll_os.h
 .. _`pypy/translator/c/test/test_extfunc.py`: ../../pypy/translator/c/test/test_extfunc.py
+.. _`pypy/translator/goal/targetnopstandalone.py`: ../../pypy/translator/goal/targetnopstandalone.py
 .. _`translator/java/`: ../../pypy/translator/java
 .. _`translator/llvm/`: ../../pypy/translator/llvm
 .. _`translator/tool/`: ../../pypy/translator/tool
\ No newline at end of file

Modified: pypy/dist/pypy/doc/faq.txt
==============================================================================
--- pypy/dist/pypy/doc/faq.txt	(original)
+++ pypy/dist/pypy/doc/faq.txt	Tue Sep 27 19:38:41 2005
@@ -1,55 +1,107 @@
-
+==========================
 Frequently Asked Questions
 ==========================
 
-How fast is PyPy?
+.. contents::
 
-    As of August 2005, PyPy was succesfully translated to C.
-    The version of PyPy that still runs on top of CPython
-    is slower by a factor of 2000 compared to CPython. The translated
-    versions seems to be roughly 300 times slower than CPython.
-    On the other hand, the really interesting question is: Why is
-    PyPy so slow?
 
-.. _whysoslow:
+General
+============================================================
 
-Why is PyPy so slow?
+Do I have to rewrite my programs in RPython?
+--------------------------------------------
 
-    Our translation process does not try to optimize the produced code
-    very much.  So far the project has been focused on getting a well
-    tested very compliant self-contained static Python implementation.
-    During end 2005 and 2006 we are targetting optimizations at various 
-    levels.  If you then still think that PyPy is slow then we will 
-    have to find a better answer :-) 
-
-What is RPython? 
-
-    RPython is the restricted subset of the Python language that 
-    we are able to translate to machine level code.  A major part of 
-    PyPy's interpreter and type implementations is written 
-    in this restricted style.  For a more exhaustive definitions
-    please refer to `RPython`_. 
+No.  PyPy always runs your code in its own interpreter, which is a full
+and compliant Python 2.4 interpreter.  RPython_ is only the language in
+which parts of PyPy itself are written.
 
-Do I have to rewrite my programs in RPython?
+I am getting strange errors while playing with PyPy, what should I do?
+----------------------------------------------------------------------
+
+It seems that a lot of strange, unexplainable problems can be magically
+solved by removing all the \*.pyc files from the PyPy source
+tree. Another thing you can do is removing the pypy/_cache
+completely. If the error is persistent and still annoys you after this
+treatment please send us a bug report (or even better, a fix :-)
 
-    No.  PyPy always runs your code in its own interpreter, which is
-    a full and compliant Python 2.4 interpreter.  RPython is only
-    the language in which parts of PyPy itself are written.
+
+Using the PyPy translator
+============================================================
 
 How do I compile PyPy?
+----------------------
 
-    See the `getting-started`_ guide.  Note that at the moment this
-    produces an executable that contains a lot of things that are
-    hard-coded for your particular system (including paths), so it's
-    not really suitable for being installed or redistributed.
+See the `getting-started`_ guide.  Note that at the moment this produces
+an executable that contains a lot of things that are hard-coded for your
+particular system (including paths and other stuff), so it's not
+suitable for being installed or redistributed.
+
+How do I compile my own programs?
+---------------------------------
+
+Start from the example of
+`pypy/translator/goal/targetnopstandalone.py`_, which you compile by
+typing::
+
+    python translate_pypy.py targetnopstandalone
+
+You can have a look at intermediate C source code, which is (at the
+moment) put in ``/tmp/usession-*/testing_1/testing_1.c``.  Of course,
+all the function and stuff indirectly used by your ``entry_point()``
+function has to be RPython_.
+
+
+Compiling to other languages
+============================================================
+
+Couldn't we simply take a Python syntax tree and turn it into Lisp?
+-------------------------------------------------------------------
+
+It's not necessarily nonsense, but it's not really The PyPy Way.  It's
+pretty hard, without some kind of type inference, to translate, say this
+Python::
+
+    a + b
+
+into anything significantly more efficient than this Common Lisp::
+
+    (py:add a b)
+
+And making type inference possible is what RPython is all about.
+
+You could make ``#'py:add`` a generic function and see if a given CLOS
+implementation is fast enough to give a useful speed (but I think the
+coercion rules would probably drive you insane first).  -- mwh
+
+
+Speed
+============================================================
+
+How fast is PyPy?
+-----------------
+
+As of August 2005, PyPy was successfully translated to C.  The version
+of PyPy that still runs on top of CPython is slower by a factor of 2000
+compared to CPython. This translated version was roughly 300 times
+slower than CPython, and is now about 20-30 times slower than CPython.
+On the other hand, the really interesting question is: Why is PyPy so
+slow?
+
+.. _whysoslow:
+
+Why is PyPy so slow?
+--------------------
+
+Our translation process does not try to optimize the produced code very
+much.  So far the project has been focused on getting a well tested very
+compliant self-contained static Python implementation.  During end 2005
+and 2006 we are targetting optimizations at various levels.  If you then
+still think that PyPy is slow then we will have to find a better answer
+:-)
 
-I am getting strange errors while playing with PyPy, what should I do?
 
-    It seems that a lot of strange, unexplainable problems can be magically
-    solved by removing all the \*.pyc files from the PyPy source tree. Another
-    thing you can do is removing the pypy/_cache completely. If the error is
-    persistent and still annoys you after this treatment please send us a bug
-    report (or even better, a fix :-)
 
 .. _`RPython`: coding-guide.html#rpython
 .. _`getting-started`: getting-started.html
+
+.. include:: _ref.txt