[pypy-svn] r64297 - pypy/trunk/pypy/doc
cfbolz at codespeak.net
cfbolz at codespeak.net
Fri Apr 17 19:00:27 CEST 2009
Author: cfbolz
Date: Fri Apr 17 19:00:26 2009
New Revision: 64297
Added:
pypy/trunk/pypy/doc/getting-started-python.txt
- copied, changed from r64287, pypy/trunk/pypy/doc/getting-started.txt
pypy/trunk/pypy/doc/getting-started-translation.txt
- copied, changed from r64287, pypy/trunk/pypy/doc/getting-started.txt
Modified:
pypy/trunk/pypy/doc/docindex.txt
pypy/trunk/pypy/doc/getting-started.txt
pypy/trunk/pypy/doc/glossary.txt
pypy/trunk/pypy/doc/translation.txt
Log:
(cfbolz, pedronis): puh. split up getting started into two parts, one for a more
"user-oriented" perspective where one can just run Python code and one for the
translation toolchain.
Modified: pypy/trunk/pypy/doc/docindex.txt
==============================================================================
--- pypy/trunk/pypy/doc/docindex.txt (original)
+++ pypy/trunk/pypy/doc/docindex.txt Fri Apr 17 19:00:26 2009
@@ -306,8 +306,8 @@
.. _`translation`: translation.html
.. _`GenC backend`: translation.html#genc
.. _`CLI backend`: cli-backend.html
-.. _`py.py`: getting-started.html#main-entry-point
-.. _`translatorshell.py`: getting-started.html#try-out-the-translator
+.. _`py.py`: getting-started-python.html#the-py.py-interpreter
+.. _`translatorshell.py`: getting-started-translation.html#try-out-the-translator
.. _JIT: jit/index.html
.. _`JIT Generation in PyPy`: jit/index.html
.. _`just-in-time compiler generator`: jit/index.html
@@ -318,12 +318,11 @@
.. _`Stackless Transform`: translation.html#the-stackless-transform
.. _`PyPy Prolog Interpreter`: prolog-interpreter.html
.. _`Prolog Interpreter`: prolog-interpreter.html
-.. _`main PyPy-translation scripts`: getting-started.html#translating-the-pypy-python-interpreter
-.. _`translate.py`: getting-started.html#translating-the-pypy-python-interpreter
+.. _`main PyPy-translation scripts`: getting-started-python.html#translating-the-pypy-python-interpreter
.. _`.NET`: http://www.microsoft.com/net/
.. _Mono: http://www.mono-project.com/
.. _`"standard library"`: rlib.html
-.. _`graph viewer`: getting-started.html#try-out-the-translator
+.. _`graph viewer`: getting-started-translation.html#try-out-the-translator
.. _`compatibility matrix`: image/compat-matrix.png
.. include:: _ref.txt
Copied: pypy/trunk/pypy/doc/getting-started-python.txt (from r64287, pypy/trunk/pypy/doc/getting-started.txt)
==============================================================================
--- pypy/trunk/pypy/doc/getting-started.txt (original)
+++ pypy/trunk/pypy/doc/getting-started-python.txt Fri Apr 17 19:00:26 2009
@@ -1,458 +1,28 @@
-==================================
-PyPy - Getting Started
-==================================
+==============================================
+Getting Started with PyPy's Python Interpreter
+==============================================
.. contents::
.. sectnum::
-.. _howtopypy:
-
-What is PyPy ?
-==============
-
-PyPy is an implementation of the Python_ programming language written in
-Python itself, flexible and easy to experiment with.
-We target a large variety of platforms, small and large, by providing a
-compiler toolsuite that can produce custom Python versions. Platform, memory
-and threading models are aspects of the translation process - as
-opposed to encoding low level details into the language implementation itself.
-Eventually, dynamic optimization techniques - implemented as another
-translation aspect - should become robust against language changes. `more...`_
-
-.. _Python: http://docs.python.org/ref
-.. _`more...`: architecture.html
-
-Just the facts
-==============
-
-.. _gettingpypy:
-.. _`latest stable version via subversion`:
-.. _`get via Subversion`:
-
-Svn-check out & run the latest PyPy as a two-liner
---------------------------------------------------
-
-Before you can play with PyPy, you will need to obtain a copy
-of the sources. This can be done either by `downloading them
-from the download page`_ or by checking them out from the
-repository using subversion. We suggest using subversion as it
-offers access to the most recent versions.
-
-.. _`downloading them from the download page`: download.html
-
-If you choose to use subversion_, you must first install it
-if you don't already have it. We have
-some `help on installing subversion`_ for PyPy. Once it is installed,
-you can then issue the following command on your command line,
-DOS box, or terminal::
-
- svn co http://codespeak.net/svn/pypy/dist pypy-dist
-
-This will check out the most recent stable release from subversion and
-place it into a directory named ``pypy-dist``, and will get you the PyPy
-source in ``pypy-dist/pypy`` and documentation files in
-``pypy-dist/pypy/doc``. If you would prefer to check out the "cutting edge"
-version of PyPy - which may not always be stable! - then check out
-from ``http://codespeak.net/svn/pypy/trunk`` intead.
-
-After checkout you can start the PyPy interpreter via::
-
- python pypy-svn/pypy/bin/py.py
-
-Have fun :-)
-Note that you will need a C compiler that is supported by CPython's distutils.
-This gives you a PyPy prompt, i.e. a very compliant Python
-interpreter implemented in Python. PyPy passes around `98% of
-CPythons core language regression tests`_. When starting this way,
-the PyPy interpreter is running on top of CPython, and as such it
-runs around 2000 times slower than CPython itself.
-Many extension modules are not enabled by default; to use them you need
-to pass ``--withmod-NAME`` arguments (for example, ``--withmod-_rawffi``
-is required to import our version of ctypes).
-
-This is probably not something you want to play with for too long,
-though, as it is really slow. Instead, you should use PyPy to `translate
-itself to lower level languages`_ after which it runs standalone, is not
-dependant on CPython anymore and becomes faster (its performance is within
-the same order of magnitude as CPython itself).
-
-.. _`98% of CPythons core language regression tests`: http://codespeak.net:8099/summary?category=lib-python&branch=%3Ctrunk%3E
-
-Have a look at `interesting starting points`_
-for some guidance on how to continue.
-
-.. _`help on installing subversion`: svn-help.html
-.. _subversion: svn-help.html
-
-Understanding PyPy's architecture
----------------------------------
-
-For in-depth information about architecture and coding documentation
-head over to the `documentation section`_ where you'll find lots of
-interesting information. Additionally, in true hacker spirit, you
-may just `start reading sources`_ .
-
-.. _`documentation section`: docindex.html
-
-Running all of PyPy's tests
----------------------------
-
-If you want to see `if PyPy works on your machine/platform`_
-you can simply run PyPy's large test suite with::
-
- cd pypy
- python test_all.py directory-or-files
-
-test_all.py is just another name for `py.test`_ which is the
-testing tool that we are using and enhancing for PyPy.
-**Note that running all the tests takes a very long time, and
-enormous amounts of memory if you are trying to run them all
-in the same process; test_all.py is only suitable to run a
-subset of them at a time.** To run them all daily we have a BuildBot based
-setup, a summary of its results can be seen at http://codespeak.net:8099/summary.
-
-.. _`if PyPy works on your machine/platform`: docindex.html#status
-.. _`autotest driver`: http://codespeak.net/pipermail/pypy-dev/2006q3/003273.html
-
-Filing bugs or feature requests
--------------------------------
-
-You may file `bug reports`_ on our issue tracker which is
-also accessible through the 'issues' top menu of
-the PyPy website. `using the development tracker`_ has
-more detailed information on specific features of the tracker.
-
-.. _`using the development tracker`: coding-guide.html#using-development-tracker
-
-.. _`interesting starting points`:
-
-Interesting Starting Points in PyPy
-===================================
-
-To get started with PyPy, you can either play with `the py.py
-interpreter`_ and the `special PyPy features`_, or directly proceed to
-`translating the PyPy Python interpreter`_. This allows you to try out
-real Python applications in a fast version of PyPy, compiled via C,
-.NET or Java, with or without special features included.
-
-Main entry point
-------------------------------------------
-
-The py.py interpreter
-+++++++++++++++++++++
-
-To start interpreting Python with PyPy, install a C compiler that is
-supported by distutils and use Python 2.4 or greater to run PyPy::
-
- cd pypy
- python bin/py.py
-
-After a few seconds (remember: this is running on top of CPython),
-you should be at the PyPy prompt, which is the same as the Python
-prompt, but with an extra ">".
-
-Now you are ready to start running Python code. Most Python
-modules should work if they don't involve CPython extension
-modules. Here is an example of determining PyPy's performance
-in pystones::
-
- >>>> from test import pystone
- >>>> pystone.main(10)
-
-The parameter is the number of loops to run through the test. The
-default is 50000, which is far too many to run in a non-translated
-PyPy version (i.e. when PyPy's interpreter itself is being interpreted
-by CPython).
-
-py.py options
-+++++++++++++
-
-To list the PyPy interpreter command line options, type::
-
- cd pypy
- python bin/py.py --help
-
-py.py supports most of the options that CPython supports too (in addition to a
-large amount of options that can be used to customize py.py).
-As an example of using PyPy from the command line, you could type::
-
- python py.py -c "from test import pystone; pystone.main(10)"
-
-Alternatively, as with regular Python, you can simply give a
-script name on the command line::
-
- python py.py ../../lib-python/2.5.2/test/pystone.py 10
-
-See our `configuration sections`_ for details about what all the commandline
-options do.
-
-Special PyPy features
---------------------------
-
-Interpreter-level console
-+++++++++++++++++++++++++
-
-There are quite a few extra features of the PyPy console: If you press
-<Ctrl-C> on the console you enter the interpreter-level console, a
-usual CPython console. You can then access internal objects of PyPy
-(e.g. the object space) and any variables you have created on the PyPy
-prompt with the prefix ``w_``::
-
- .. >>> import py ; py.test.skip("skipchunk")
- >>>> a = 123
- >>>> <Ctrl-C>
- *** Entering interpreter-level console ***
- >>> w_a
- W_IntObject(123)
-
-Note that the prompt of the interpreter-level console is only '>>>' since
-it runs on CPython level. If you want to return to PyPy, press <Ctrl-D> (under
-Linux) or <Ctrl-Z>, <Enter> (under Windows).
-
-You may be interested in reading more about the distinction between
-`interpreter-level and app-level`_.
-
-.. _`interpreter-level and app-level`: coding-guide.html#interpreter-level
-
-.. _`trace example`:
-
-Tracing bytecode and operations on objects
-++++++++++++++++++++++++++++++++++++++++++
-
-You can use the trace object space to monitor the interpretation
-of bytecodes in connection with object space operations. To enable
-it, set ``__pytrace__=1`` on the interactive PyPy console::
-
- >>>> __pytrace__ = 1
- Tracing enabled
- >>>> a = 1 + 2
- |- <<<< enter <inline>a = 1 + 2 @ 1 >>>>
- |- 0 LOAD_CONST 0 (W_IntObject(1))
- |- 3 LOAD_CONST 1 (W_IntObject(2))
- |- 6 BINARY_ADD
- |- add(W_IntObject(1), W_IntObject(2)) -> W_IntObject(3)
- |- 7 STORE_NAME 0 (a)
- |- hash(W_StringObject('a')) -> W_IntObject(-468864544)
- |- int_w(W_IntObject(-468864544)) -> -468864544
- |-10 LOAD_CONST 2 (<W_NoneObject()>)
- |-13 RETURN_VALUE
- |- <<<< leave <inline>a = 1 + 2 @ 1 >>>>
-
-
-.. _ `lazily computed objects`:
-
-Lazily computed objects
-+++++++++++++++++++++++
-
-One of the original features provided by PyPy is the "thunk"
-object space, providing lazily-computed objects in a fully
-transparent manner::
-
- cd pypy
- python bin/py.py -o thunk
-
- >>>> from __pypy__ import thunk
- >>>> def longcomputation(lst):
- .... print "computing..."
- .... return sum(lst)
- ....
- >>>> x = thunk(longcomputation, range(5))
- >>>> y = thunk(longcomputation, range(10))
-
-From the application perspective, ``x`` and ``y`` represent
-exactly the objects being returned by the ``longcomputation()``
-invocations. You can put these objects into a dictionary
-without triggering the computation::
-
- >>>> d = {5: x, 10: y}
- >>>> result = d[5]
- >>>> result
- computing...
- 10
- >>>> type(d[10])
- computing...
- <type 'int'>
- >>>> d[10]
- 45
-
-It is interesting to note that this lazy-computing Python extension
-is solely implemented in a small `objspace/thunk.py`_ file consisting
-of around 200 lines of code. Since the 0.8.0 release you
-can `translate PyPy with the thunk object space`_.
-
-More
-++++
-
-If you know more about pypy-exclusive features, choose one from the following,
-go to `objspace proxies`_ document.
-
-.. _`objspace proxies`: objspace-proxies.html
-
-Running the tests
-+++++++++++++++++
-
-The PyPy project uses test-driven-development. Right now, there are
-a couple of different categories of tests which you can run.
-To run all the unit tests::
-
- cd pypy
- python test_all.py
-
-(this is not recommended, since it takes hours and uses huge amounts of RAM).
-Alternatively, you may run subtests by going to the correct subdirectory
-and running them individually::
-
- python test_all.py interpreter/test/test_pyframe.py
-
-``test_all.py`` is actually just a synonym for `py.test`_ which is
-our external testing tool. If you have installed that you
-can as well just issue ``py.test DIRECTORY_OR_FILE`` in order
-to perform test runs or simply start it without arguments to
-run all tests below the current directory.
-
-Finally, there are the CPython regression tests which you can
-run like this (this will take hours and hours and hours)::
-
- cd lib-python/2.5.2/test
- python ../../../pypy/test_all.py
-
-.. _`installed py.test`: https://codespeak.net/py/current/doc/download.html
-
-Demos
-+++++
-
-The `demo/`_ directory contains examples of various aspects of PyPy,
-ranging from running regular Python programs (that we used as compliance goals)
-over experimental distribution mechanisms to examples translating
-sufficiently static programs into low level code.
-
-.. _`try out the translator`:
-
-Trying out the translator
--------------------------
-
-The translator is a tool based on the PyPy interpreter which can translate
-sufficiently static Python programs into low-level code. To be able to use it
-you need to (if you want to look at the flowgraphs, which you obviously
-should):
-
- * Download and install Pygame_.
-
- * Download and install `Dot Graphviz`_ (optional if you have an internet
- connection: the flowgraph viewer then connects to
- codespeak.net and lets it convert the flowgraph by a graphviz server).
-
-To start the interactive translator shell do::
-
- cd pypy
- python bin/translatorshell.py
-
-Test snippets of translatable code are provided in the file
-``pypy/translator/test/snippet.py``, which is imported under the name
-``snippet``. For example::
-
- >>> t = Translation(snippet.is_perfect_number)
- >>> t.view()
-
-After that, the graph viewer pops up, that lets you interactively inspect the
-flow graph. To move around, click on something that you want to inspect.
-To get help about how to use it, press 'H'. To close it again, press 'Q'.
-
-Trying out the type annotator
-+++++++++++++++++++++++++++++
-
-We have a type annotator that can completely infer types for functions like
-``is_perfect_number`` (as well as for much larger examples)::
-
- >>> t.annotate([int])
- >>> t.view()
-
-Move the mouse over variable names (in red) to see their inferred types.
-
-
-Translating the flow graph to C code
-++++++++++++++++++++++++++++++++++++
-
-The graph can be turned into C code::
-
- >>> t.rtype()
- >>> f = t.compile_c()
-
-The first command replaces the operations with other low level versions that
-only use low level types that are available in C (e.g. int). To try out the
-compiled version::
-
- >>> f(5)
- False
- >>> f(6)
- True
-
-Translating the flow graph to CLI or JVM code
-+++++++++++++++++++++++++++++++++++++++++++++
-
-PyPy also contains a `CLI backend`_ and JVM backend which
-can translate flow graphs into .NET executables or a JVM jar
-file respectively. Both are able to translate the entire
-interpreter. You can try out the CLI and JVM backends
-from the interactive translator shells as follows::
-
- >>> def myfunc(a, b): return a+b
- ...
- >>> t = Translation(myfunc)
- >>> t.annotate([int, int])
- >>> f = t.compile_cli() # or compile_jvm()
- >>> f(4, 5)
- 9
-
-The object returned by ``compile_cli`` or ``compile_jvm``
-is a wrapper around the real
-executable: the parameters are passed as command line arguments, and
-the returned value is read from the standard output.
-
-Once you have compiled the snippet, you can also try to launch the
-executable directly from the shell. You will find the
-executable in one of the ``/tmp/usession-*`` directories::
-
- # For CLI:
- $ mono /tmp/usession-dist-<username>/main.exe 4 5
- 9
-
- # For JVM:
- $ java -cp /tmp/usession-dist-<username>/pypy pypy.Main 4 5
- 9
-
-To translate and run for the CLI you must have the SDK installed: Windows
-users need the `.NET Framework SDK 2.0`_, while Linux and Mac users
-can use Mono_.
-
-To translate and run for the JVM you must have a JDK installed (at
-least version 5) as well as the `Jasmin JVM assembler`_. In particular,
-you need a script in your path called ``jasmin`` which will execute
-the assembler. For example, the contents might be:
-
- #!/bin/bash
- java -jar $PATH_TO_JASMIN_JAR "$@"
-
-.. _`Jasmin JVM assembler`: http://jasmin.sourceforge.net/
-
-A slightly larger example
-+++++++++++++++++++++++++
-
-There is a small-to-medium demo showing the translator and the annotator::
-
- cd demo
- python bpnn.py
-
-This causes ``bpnn.py`` to display itself as a call graph and class
-hierarchy. Clicking on functions shows the flow graph of the particular
-function. Clicking on a class shows the attributes of its instances. All
-this information (call graph, local variables' types, attributes of
-instances) is computed by the annotator.
-
-As soon as you close the PyGame window, the function is turned into C code,
-compiled and executed.
-
-.. _`translate itself to lower level languages`:
+PyPy's Python interpreter is a very compliant Python
+interpreter implemented in Python. When translated to C, it passes most of
+`CPythons core language regression tests`_ and comes with many of the extension
+modules included in the standard library including ``ctypes``. It can run large
+libraries such as Django_ and Twisted_. There are some small behavioral
+differences to CPython and some missing extensions, for details see `CPython
+differences`_.
+
+.. _Django: http://djangoproject.org
+.. _Twisted: http://twistedmatrix.com
+
+.. _`CPython differences`: cpython_differences.html
+
+To actually use PyPy's Python interpreter, the first thing you typically do is
+translate it to get a reasonably performing interpreter. This is described in
+the next section. If you just want to play around a bit, you can also try
+untranslated `py.py interpreter`_ (which is extremely slow, but still fast
+enough for tiny examples).
Translating the PyPy Python interpreter
---------------------------------------
@@ -463,24 +33,22 @@
.. _`windows document`: windows.html
You can translate the whole of PyPy's Python interpreter to low level C code,
-`CLI code`_, or `JVM code`_. (This is the largest and ultimate example of
-RPython program that our translation toolchain can process.)
+`CLI code`_, or `JVM code`_.
1. Install dependencies. You need (these are Debian package names,
adapt as needed):
* gcc
* ``python-dev``
- * ``python-ctypes``
+ * ``python-ctypes`` if you are still using Python2.4
* ``libffi-dev``
* ``libz-dev`` (for the optional ``zlib`` module)
* ``libbz2-dev`` (for the optional ``bz2`` module)
* ``libncurses-dev`` (for the optional ``_minimal_curses`` module)
* ``libgc-dev`` (only when translating with `--opt=0, 1` or `size`)
-2. Be warned that translation is time-consuming (30 min to
- over one hour) and extremely RAM-hungry (kill it if it
- starts swapping heavily). If you have less than 1.5 GB of
+2. Translation is somewhat time-consuming (30 min to
+ over one hour) and RAM-hungry. If you have less than 1.5 GB of
RAM (or a slow machine) you might want to pick the
`optimization level`_ `1` in the next step. A level of
`2` or `3` gives much better results, though.
@@ -501,11 +69,26 @@
If everything works correctly this will create an executable
``pypy-c`` in the current directory. Type ``pypy-c --help``
-to see the options it supports -- mainly the same basic
+to see the options it supports – mainly the same basic
options as CPython. In addition, ``pypy-c --info`` prints the
translation options that where used to produce this particular
-executable. This executable can be moved around or copied on
-other machines; see Installation_ below.
+executable. The executable behaves mostly like a normal Python interpreter::
+
+ $ ./pypy-c
+ Python 2.5.2 (64177, Apr 16 2009, 16:33:13)
+ [PyPy 1.0.0] on linux2
+ Type "help", "copyright", "credits" or "license" for more information.
+ And now for something completely different: ``this sentence is false''
+ >>>> 46 - 4
+ 42
+ >>>> from test import pystone
+ >>>> pystone.main()
+ Pystone(1.1) time for 50000 passes = 2.57
+ This machine benchmarks at 19455.3 pystones/second
+ >>>>
+
+This executable can be moved around or copied on other machines; see
+Installation_ below.
The ``translate.py`` script takes a very large number of options controlling
what to translate and how. See ``translate.py -h``. Some of the more
@@ -518,19 +101,11 @@
choose between using
the `Boehm-Demers-Weiser garbage collector`_, our reference
counting implementation or four of own collector implementations
- (Boehm's collector is the default).
+ (the default depends on the optimization level).
Find a more detailed description of the various options in our `configuration
sections`_.
-You can also use the translate.py script to try out several smaller
-programs, e.g. a slightly changed version of Pystone::
-
- cd pypy/translator/goal
- python translate.py targetrpystonedalone
-
-This will produce the executable "targetrpystonedalone-c".
-
.. _`configuration sections`: config/index.html
.. _`translate PyPy with the thunk object space`:
@@ -538,15 +113,53 @@
Translating with the thunk object space
++++++++++++++++++++++++++++++++++++++++
+One of the original features provided by PyPy is the "thunk"
+object space, providing lazily-computed objects in a fully
+transparent manner::
+
+ cd pypy
+ python bin/py.py -o thunk
-It is also possible to experimentally translate a PyPy version using
-the "thunk" object space::
+ >>>> from __pypy__ import thunk
+ >>>> def longcomputation(lst):
+ .... print "computing..."
+ .... return sum(lst)
+ ....
+ >>>> x = thunk(longcomputation, range(5))
+ >>>> y = thunk(longcomputation, range(10))
+
+From the application perspective, ``x`` and ``y`` represent
+exactly the objects being returned by the ``longcomputation()``
+invocations. You can put these objects into a dictionary
+without triggering the computation::
+
+ >>>> d = {5: x, 10: y}
+ >>>> result = d[5]
+ >>>> result
+ computing...
+ 10
+ >>>> type(d[10])
+ computing...
+ <type 'int'>
+ >>>> d[10]
+ 45
+
+It is interesting to note that this lazy-computing Python extension
+is solely implemented in a small `objspace/thunk.py`_ file consisting
+of around 200 lines of code.
+
+It is also possible to translate a PyPy version using the "thunk" object
+space::
cd pypy/translator/goal
python translate.py targetpypystandalone.py --objspace=thunk
-the examples in `lazily computed objects`_ should work in the translated
-result.
+the example above should work in the translated result.
+
+If you want know more about pypy-exclusive features go to `objspace proxies`_
+document.
+
+.. _`objspace proxies`: objspace-proxies.html
.. _`CLI code`:
@@ -604,7 +217,9 @@
And now for something completely different: ``# assert did not crash''
>>>>
-Alternatively, you can run it using ``java -jar pypy-jvm.jar``.
+Alternatively, you can run it using ``java -jar pypy-jvm.jar``. At the moment
+the executable does not provide any interesting features, like integration with
+Java.
Installation
++++++++++++
@@ -634,153 +249,69 @@
etc.
-.. _`start reading sources`:
+.. _`py.py interpreter`:
-Where to start reading the sources
-----------------------------------
+Running the Python Interpreter Without Translation
+---------------------------------------------------
-PyPy is made from parts that are relatively independent from each other.
-You should start looking at the part that attracts you most (all paths are
-relative to the PyPy top level directory). You may look at our `directory reference`_
-or start off at one of the following points:
-
-* `pypy/interpreter`_ contains the bytecode interpreter: bytecode dispatcher
- in pyopcode.py_, frame and code objects in eval.py_ and pyframe.py_,
- function objects and argument passing in function.py_ and argument.py_,
- the object space interface definition in baseobjspace.py_, modules in
- module.py_ and mixedmodule.py_. Core types supporting the bytecode
- interpreter are defined in typedef.py_.
-
-* `pypy/interpreter/pyparser`_ contains a recursive descent parser,
- and input data files that allow it to parse both Python 2.3 and 2.4
- syntax. Once the input data has been processed, the parser can be
- translated by the above machinery into efficient code.
-
-* `pypy/interpreter/astcompiler`_ contains the compiler. This
- contains a modified version of the compiler package from CPython
- that fixes some bugs and is translatable. That the compiler and
- parser are translatable is new in 0.8.0 and it makes using the
- resulting binary interactively much more pleasant.
-
-* `pypy/objspace/std`_ contains the `Standard object space`_. The main file
- is objspace.py_. For each type, the files ``xxxtype.py`` and
- ``xxxobject.py`` contain respectively the definition of the type and its
- (default) implementation.
-
-* `pypy/objspace`_ contains a few other object spaces: the thunk_,
- trace_ and flow_ object spaces. The latter is a relatively short piece
- of code that builds the control flow graphs when the bytecode interpreter
- runs in it.
-
-* `pypy/translator`_ contains the code analysis and generation stuff.
- Start reading from translator.py_, from which it should be easy to follow
- the pieces of code involved in the various translation phases.
-
-* `pypy/annotation`_ contains the data model for the type annotation that
- can be inferred about a graph. The graph "walker" that uses this is in
- `pypy/annotation/annrpython.py`_.
-
-* `pypy/rpython`_ contains the code of the RPython typer. The typer transforms
- annotated flow graphs in a way that makes them very similar to C code so
- that they can be easy translated. The graph transformations are controlled
- by the stuff in `pypy/rpython/rtyper.py`_. The object model that is used can
- be found in `pypy/rpython/lltypesystem/lltype.py`_. For each RPython type
- there is a file rxxxx.py that contains the low level functions needed for
- this type.
-
-* `pypy/rlib`_ contains the RPython standard library, things that you can
- use from rpython.
-
-.. _optionaltool:
-
-Additional Tools for running (and hacking) PyPy
------------------------------------------------
-
-We use some optional tools for developing PyPy. They are not required to run
-the basic tests or to get an interactive PyPy prompt but they help to
-understand and debug PyPy especially for the ongoing translation work.
-
-graphviz & pygame for flow graph viewing (highly recommended)
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-graphviz and pygame are both necessary if you
-want to look at generated flow graphs:
-
- graphviz: http://www.graphviz.org/Download.php
-
- pygame: http://www.pygame.org/download.shtml
-
-CTypes (highly recommended)
-++++++++++++++++++++++++++++
-
-`ctypes`_ is included in CPython 2.5 and higher. CPython 2.4 users needs to
-install it (version 0.9.9.6 or later) if they want to run low-level tests. See
-the `download page of ctypes`_.
-
-.. _`download page of ctypes`: http://sourceforge.net/project/showfiles.php?group_id=71702
-.. _`ctypes`: http://starship.python.net/crew/theller/ctypes/
-
-.. _`py.test`:
-
-py.test and the py lib
-+++++++++++++++++++++++
-
-The `py library`_ is used for supporting PyPy development and
-running our tests against code and documentation as well as
-compliance tests. You don't need to install the py library because
-it ships with PyPy and `pypy/test_all.py`_ is an alias for ``py.test``
-but if you want to have the ``py.test`` tool generally in your
-path, you might like to visit:
-
- http://codespeak.net/py/dist/download.html
-
-Getting involved
-================
-
-PyPy employs an open development process. You are invited to join our
-`pypy-dev mailing list`_ or look at the other `contact
-possibilities`_. We are also doing coding Sprints which are
-separately announced and often happen around Python conferences such
-as EuroPython or Pycon. Take a look at the list of upcoming events_ to
-plan where to meet with us.
-
-.. _events: http://codespeak.net/pypy/trunk/pypy/doc/news.html
-.. _`pypy-dev mailing list`: http://codespeak.net/mailman/listinfo/pypy-dev
-.. _`contact possibilities`: index.html
+The py.py interpreter
++++++++++++++++++++++
+
+To start interpreting Python with PyPy, install a C compiler that is
+supported by distutils and use Python 2.4 or greater to run PyPy::
-.. _`py library`: http://codespeak.net/py
+ cd pypy
+ python bin/py.py
+
+After a few seconds (remember: this is running on top of CPython),
+you should be at the PyPy prompt, which is the same as the Python
+prompt, but with an extra ">".
+
+Now you are ready to start running Python code. Most Python
+modules should work if they don't involve CPython extension
+modules. Here is an example of determining PyPy's performance
+in pystones::
+
+ >>>> from test import pystone
+ >>>> pystone.main(10)
+
+The parameter is the number of loops to run through the test. The
+default is 50000, which is far too many to run in a non-translated
+PyPy version (i.e. when PyPy's interpreter itself is being interpreted
+by CPython).
+
+py.py options
++++++++++++++
+
+To list the PyPy interpreter command line options, type::
+
+ cd pypy
+ python bin/py.py --help
+
+py.py supports most of the options that CPython supports too (in addition to a
+large amount of options that can be used to customize py.py).
+As an example of using PyPy from the command line, you could type::
+
+ python py.py -c "from test import pystone; pystone.main(10)"
+
+Alternatively, as with regular Python, you can simply give a
+script name on the command line::
+
+ python py.py ../../lib-python/2.5.2/test/pystone.py 10
+
+See our `configuration sections`_ for details about what all the commandline
+options do.
-.. _`Spidermonkey`: http://www.mozilla.org/js/spidermonkey/
-.. _`Google summer of code`: http://code.google.com/soc
-.. _`.NET Framework SDK 2.0`: http://msdn.microsoft.com/netframework/downloads/updates/default.aspx
.. _Mono: http://www.mono-project.com/Main_Page
.. _`CLI backend`: cli-backend.html
+.. _`Boehm-Demers-Weiser garbage collector`: http://www.hpl.hp.com/personal/Hans_Boehm/gc/
.. _clr: clr-module.html
+.. _`CPythons core language regression tests`: http://codespeak.net:8099/summary?category=lib-python&branch=%3Ctrunk%3E
+
+.. include:: _ref.txt
+
+
-.. _`Dot Graphviz`: http://www.graphviz.org/
-.. _Pygame: http://www.pygame.org/
-.. _pyopcode.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/pyopcode.py
-.. _eval.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/eval.py
-.. _pyframe.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/pyframe.py
-.. _function.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/function.py
-.. _argument.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/argument.py
-.. _baseobjspace.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/baseobjspace.py
-.. _module.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/module.py
-.. _mixedmodule.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/mixedmodule.py
-.. _typedef.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/typedef.py
-.. _Standard object space: objspace.html#the-standard-object-space
-.. _objspace.py: ../../pypy/objspace/std/objspace.py
-.. _thunk: ../../pypy/objspace/thunk.py
-.. _trace: ../../pypy/objspace/trace.py
-.. _flow: ../../pypy/objspace/flow/
-.. _translator.py: ../../pypy/translator/translator.py
-.. _mailing lists: index.html
-.. _documentation: docindex.html
-.. _unit tests: coding-guide.html#test-design
-.. _bug reports: https://codespeak.net/issue/pypy-dev/
-.. _`directory reference`: docindex.html#directory-reference
-.. _`Boehm-Demers-Weiser garbage collector`: http://www.hpl.hp.com/personal/Hans_Boehm/gc/
-.. include:: _ref.txt
Copied: pypy/trunk/pypy/doc/getting-started-translation.txt (from r64287, pypy/trunk/pypy/doc/getting-started.txt)
==============================================================================
--- pypy/trunk/pypy/doc/getting-started.txt (original)
+++ pypy/trunk/pypy/doc/getting-started-translation.txt Fri Apr 17 19:00:26 2009
@@ -1,338 +1,18 @@
-==================================
-PyPy - Getting Started
-==================================
+===============================================================================
+PyPy - Getting Started with the Translation Toolchain and Development Process
+===============================================================================
.. contents::
.. sectnum::
-.. _howtopypy:
-
-What is PyPy ?
-==============
-
-PyPy is an implementation of the Python_ programming language written in
-Python itself, flexible and easy to experiment with.
-We target a large variety of platforms, small and large, by providing a
-compiler toolsuite that can produce custom Python versions. Platform, memory
-and threading models are aspects of the translation process - as
-opposed to encoding low level details into the language implementation itself.
-Eventually, dynamic optimization techniques - implemented as another
-translation aspect - should become robust against language changes. `more...`_
-
-.. _Python: http://docs.python.org/ref
-.. _`more...`: architecture.html
-
-Just the facts
-==============
-
-.. _gettingpypy:
-.. _`latest stable version via subversion`:
-.. _`get via Subversion`:
-
-Svn-check out & run the latest PyPy as a two-liner
---------------------------------------------------
-
-Before you can play with PyPy, you will need to obtain a copy
-of the sources. This can be done either by `downloading them
-from the download page`_ or by checking them out from the
-repository using subversion. We suggest using subversion as it
-offers access to the most recent versions.
-
-.. _`downloading them from the download page`: download.html
-
-If you choose to use subversion_, you must first install it
-if you don't already have it. We have
-some `help on installing subversion`_ for PyPy. Once it is installed,
-you can then issue the following command on your command line,
-DOS box, or terminal::
-
- svn co http://codespeak.net/svn/pypy/dist pypy-dist
-
-This will check out the most recent stable release from subversion and
-place it into a directory named ``pypy-dist``, and will get you the PyPy
-source in ``pypy-dist/pypy`` and documentation files in
-``pypy-dist/pypy/doc``. If you would prefer to check out the "cutting edge"
-version of PyPy - which may not always be stable! - then check out
-from ``http://codespeak.net/svn/pypy/trunk`` intead.
-
-After checkout you can start the PyPy interpreter via::
-
- python pypy-svn/pypy/bin/py.py
-
-Have fun :-)
-Note that you will need a C compiler that is supported by CPython's distutils.
-This gives you a PyPy prompt, i.e. a very compliant Python
-interpreter implemented in Python. PyPy passes around `98% of
-CPythons core language regression tests`_. When starting this way,
-the PyPy interpreter is running on top of CPython, and as such it
-runs around 2000 times slower than CPython itself.
-Many extension modules are not enabled by default; to use them you need
-to pass ``--withmod-NAME`` arguments (for example, ``--withmod-_rawffi``
-is required to import our version of ctypes).
-
-This is probably not something you want to play with for too long,
-though, as it is really slow. Instead, you should use PyPy to `translate
-itself to lower level languages`_ after which it runs standalone, is not
-dependant on CPython anymore and becomes faster (its performance is within
-the same order of magnitude as CPython itself).
-
-.. _`98% of CPythons core language regression tests`: http://codespeak.net:8099/summary?category=lib-python&branch=%3Ctrunk%3E
-
-Have a look at `interesting starting points`_
-for some guidance on how to continue.
-
-.. _`help on installing subversion`: svn-help.html
-.. _subversion: svn-help.html
-
-Understanding PyPy's architecture
----------------------------------
-
-For in-depth information about architecture and coding documentation
-head over to the `documentation section`_ where you'll find lots of
-interesting information. Additionally, in true hacker spirit, you
-may just `start reading sources`_ .
-
-.. _`documentation section`: docindex.html
-
-Running all of PyPy's tests
----------------------------
-
-If you want to see `if PyPy works on your machine/platform`_
-you can simply run PyPy's large test suite with::
-
- cd pypy
- python test_all.py directory-or-files
-
-test_all.py is just another name for `py.test`_ which is the
-testing tool that we are using and enhancing for PyPy.
-**Note that running all the tests takes a very long time, and
-enormous amounts of memory if you are trying to run them all
-in the same process; test_all.py is only suitable to run a
-subset of them at a time.** To run them all daily we have a BuildBot based
-setup, a summary of its results can be seen at http://codespeak.net:8099/summary.
-
-.. _`if PyPy works on your machine/platform`: docindex.html#status
-.. _`autotest driver`: http://codespeak.net/pipermail/pypy-dev/2006q3/003273.html
-
-Filing bugs or feature requests
--------------------------------
-
-You may file `bug reports`_ on our issue tracker which is
-also accessible through the 'issues' top menu of
-the PyPy website. `using the development tracker`_ has
-more detailed information on specific features of the tracker.
-
-.. _`using the development tracker`: coding-guide.html#using-development-tracker
-
-.. _`interesting starting points`:
-
-Interesting Starting Points in PyPy
-===================================
-
-To get started with PyPy, you can either play with `the py.py
-interpreter`_ and the `special PyPy features`_, or directly proceed to
-`translating the PyPy Python interpreter`_. This allows you to try out
-real Python applications in a fast version of PyPy, compiled via C,
-.NET or Java, with or without special features included.
-
-Main entry point
-------------------------------------------
-
-The py.py interpreter
-+++++++++++++++++++++
-
-To start interpreting Python with PyPy, install a C compiler that is
-supported by distutils and use Python 2.4 or greater to run PyPy::
-
- cd pypy
- python bin/py.py
-
-After a few seconds (remember: this is running on top of CPython),
-you should be at the PyPy prompt, which is the same as the Python
-prompt, but with an extra ">".
-
-Now you are ready to start running Python code. Most Python
-modules should work if they don't involve CPython extension
-modules. Here is an example of determining PyPy's performance
-in pystones::
-
- >>>> from test import pystone
- >>>> pystone.main(10)
-
-The parameter is the number of loops to run through the test. The
-default is 50000, which is far too many to run in a non-translated
-PyPy version (i.e. when PyPy's interpreter itself is being interpreted
-by CPython).
-
-py.py options
-+++++++++++++
-
-To list the PyPy interpreter command line options, type::
-
- cd pypy
- python bin/py.py --help
-
-py.py supports most of the options that CPython supports too (in addition to a
-large amount of options that can be used to customize py.py).
-As an example of using PyPy from the command line, you could type::
-
- python py.py -c "from test import pystone; pystone.main(10)"
-
-Alternatively, as with regular Python, you can simply give a
-script name on the command line::
-
- python py.py ../../lib-python/2.5.2/test/pystone.py 10
-
-See our `configuration sections`_ for details about what all the commandline
-options do.
-
-Special PyPy features
---------------------------
-
-Interpreter-level console
-+++++++++++++++++++++++++
-
-There are quite a few extra features of the PyPy console: If you press
-<Ctrl-C> on the console you enter the interpreter-level console, a
-usual CPython console. You can then access internal objects of PyPy
-(e.g. the object space) and any variables you have created on the PyPy
-prompt with the prefix ``w_``::
-
- .. >>> import py ; py.test.skip("skipchunk")
- >>>> a = 123
- >>>> <Ctrl-C>
- *** Entering interpreter-level console ***
- >>> w_a
- W_IntObject(123)
-
-Note that the prompt of the interpreter-level console is only '>>>' since
-it runs on CPython level. If you want to return to PyPy, press <Ctrl-D> (under
-Linux) or <Ctrl-Z>, <Enter> (under Windows).
-
-You may be interested in reading more about the distinction between
-`interpreter-level and app-level`_.
-
-.. _`interpreter-level and app-level`: coding-guide.html#interpreter-level
-
-.. _`trace example`:
-
-Tracing bytecode and operations on objects
-++++++++++++++++++++++++++++++++++++++++++
-
-You can use the trace object space to monitor the interpretation
-of bytecodes in connection with object space operations. To enable
-it, set ``__pytrace__=1`` on the interactive PyPy console::
-
- >>>> __pytrace__ = 1
- Tracing enabled
- >>>> a = 1 + 2
- |- <<<< enter <inline>a = 1 + 2 @ 1 >>>>
- |- 0 LOAD_CONST 0 (W_IntObject(1))
- |- 3 LOAD_CONST 1 (W_IntObject(2))
- |- 6 BINARY_ADD
- |- add(W_IntObject(1), W_IntObject(2)) -> W_IntObject(3)
- |- 7 STORE_NAME 0 (a)
- |- hash(W_StringObject('a')) -> W_IntObject(-468864544)
- |- int_w(W_IntObject(-468864544)) -> -468864544
- |-10 LOAD_CONST 2 (<W_NoneObject()>)
- |-13 RETURN_VALUE
- |- <<<< leave <inline>a = 1 + 2 @ 1 >>>>
-
-
-.. _ `lazily computed objects`:
-
-Lazily computed objects
-+++++++++++++++++++++++
-
-One of the original features provided by PyPy is the "thunk"
-object space, providing lazily-computed objects in a fully
-transparent manner::
-
- cd pypy
- python bin/py.py -o thunk
-
- >>>> from __pypy__ import thunk
- >>>> def longcomputation(lst):
- .... print "computing..."
- .... return sum(lst)
- ....
- >>>> x = thunk(longcomputation, range(5))
- >>>> y = thunk(longcomputation, range(10))
-
-From the application perspective, ``x`` and ``y`` represent
-exactly the objects being returned by the ``longcomputation()``
-invocations. You can put these objects into a dictionary
-without triggering the computation::
-
- >>>> d = {5: x, 10: y}
- >>>> result = d[5]
- >>>> result
- computing...
- 10
- >>>> type(d[10])
- computing...
- <type 'int'>
- >>>> d[10]
- 45
-
-It is interesting to note that this lazy-computing Python extension
-is solely implemented in a small `objspace/thunk.py`_ file consisting
-of around 200 lines of code. Since the 0.8.0 release you
-can `translate PyPy with the thunk object space`_.
-
-More
-++++
-
-If you know more about pypy-exclusive features, choose one from the following,
-go to `objspace proxies`_ document.
-
-.. _`objspace proxies`: objspace-proxies.html
-
-Running the tests
-+++++++++++++++++
-
-The PyPy project uses test-driven-development. Right now, there are
-a couple of different categories of tests which you can run.
-To run all the unit tests::
-
- cd pypy
- python test_all.py
-
-(this is not recommended, since it takes hours and uses huge amounts of RAM).
-Alternatively, you may run subtests by going to the correct subdirectory
-and running them individually::
-
- python test_all.py interpreter/test/test_pyframe.py
-
-``test_all.py`` is actually just a synonym for `py.test`_ which is
-our external testing tool. If you have installed that you
-can as well just issue ``py.test DIRECTORY_OR_FILE`` in order
-to perform test runs or simply start it without arguments to
-run all tests below the current directory.
-
-Finally, there are the CPython regression tests which you can
-run like this (this will take hours and hours and hours)::
-
- cd lib-python/2.5.2/test
- python ../../../pypy/test_all.py
-
-.. _`installed py.test`: https://codespeak.net/py/current/doc/download.html
-
-Demos
-+++++
-
-The `demo/`_ directory contains examples of various aspects of PyPy,
-ranging from running regular Python programs (that we used as compliance goals)
-over experimental distribution mechanisms to examples translating
-sufficiently static programs into low level code.
-
.. _`try out the translator`:
Trying out the translator
-------------------------
The translator is a tool based on the PyPy interpreter which can translate
-sufficiently static Python programs into low-level code. To be able to use it
+sufficiently static Python programs into low-level code (in particular it can
+be used to translate the `full Python interpreter`_). To be able to use it
you need to (if you want to look at the flowgraphs, which you obviously
should):
@@ -452,187 +132,23 @@
As soon as you close the PyGame window, the function is turned into C code,
compiled and executed.
-.. _`translate itself to lower level languages`:
-
-Translating the PyPy Python interpreter
----------------------------------------
-
-(**Note**: for some hints on how to translate the Python interpreter under
-Windows, see the `windows document`_)
-
-.. _`windows document`: windows.html
-
-You can translate the whole of PyPy's Python interpreter to low level C code,
-`CLI code`_, or `JVM code`_. (This is the largest and ultimate example of
-RPython program that our translation toolchain can process.)
-
-1. Install dependencies. You need (these are Debian package names,
- adapt as needed):
-
- * gcc
- * ``python-dev``
- * ``python-ctypes``
- * ``libffi-dev``
- * ``libz-dev`` (for the optional ``zlib`` module)
- * ``libbz2-dev`` (for the optional ``bz2`` module)
- * ``libncurses-dev`` (for the optional ``_minimal_curses`` module)
- * ``libgc-dev`` (only when translating with `--opt=0, 1` or `size`)
-
-2. Be warned that translation is time-consuming (30 min to
- over one hour) and extremely RAM-hungry (kill it if it
- starts swapping heavily). If you have less than 1.5 GB of
- RAM (or a slow machine) you might want to pick the
- `optimization level`_ `1` in the next step. A level of
- `2` or `3` gives much better results, though.
-
-3. Run::
-
- cd pypy/translator/goal
- python translate.py --opt=3 targetpypystandalone.py
-
- possibly replacing ``--opt=3`` with ``--opt=1`` or another
- `optimization level`_ of your choice.
-
- On Linux 32-bit Intel machines, if you don't need threads, you
- can get some extra speed (and extra translation time) by adding
- ``--gcrootfinder=asmgcc`` just after the ``--opt`` option.
-
-.. _`optimization level`: config/opt.html
-
-If everything works correctly this will create an executable
-``pypy-c`` in the current directory. Type ``pypy-c --help``
-to see the options it supports -- mainly the same basic
-options as CPython. In addition, ``pypy-c --info`` prints the
-translation options that where used to produce this particular
-executable. This executable can be moved around or copied on
-other machines; see Installation_ below.
-
-The ``translate.py`` script takes a very large number of options controlling
-what to translate and how. See ``translate.py -h``. Some of the more
-interesting options are:
-
- * ``--stackless``: this produces a pypy-c that includes features
- inspired by `Stackless Python <http://www.stackless.com>`__.
-
- * ``--gc=boehm|ref|marknsweep|semispace|generation|hybrid``:
- choose between using
- the `Boehm-Demers-Weiser garbage collector`_, our reference
- counting implementation or four of own collector implementations
- (Boehm's collector is the default).
-
-Find a more detailed description of the various options in our `configuration
-sections`_.
+Translating Full Programs
++++++++++++++++++++++++++
-You can also use the translate.py script to try out several smaller
-programs, e.g. a slightly changed version of Pystone::
+To translate full RPython programs, there is the script ``translate.py`` in
+``translator/goal``. Examples for this are a slightly changed version of
+Pystone::
cd pypy/translator/goal
python translate.py targetrpystonedalone
This will produce the executable "targetrpystonedalone-c".
-.. _`configuration sections`: config/index.html
-
-.. _`translate PyPy with the thunk object space`:
-
-Translating with the thunk object space
-++++++++++++++++++++++++++++++++++++++++
-
-
-It is also possible to experimentally translate a PyPy version using
-the "thunk" object space::
-
- cd pypy/translator/goal
- python translate.py targetpypystandalone.py --objspace=thunk
-
-the examples in `lazily computed objects`_ should work in the translated
-result.
-
-.. _`CLI code`:
-
-Translating using the CLI backend
-+++++++++++++++++++++++++++++++++
-
-To create a standalone .NET executable using the `CLI backend`_::
-
- ./translate.py --backend=cli targetpypystandalone.py
-
-The executable and all its dependecies will be stored in the
-./pypy-cli-data directory. To run pypy.NET, you can run
-./pypy-cli-data/main.exe. If you are using Linux or Mac, you can use
-the convenience ./pypy-cli script::
-
- $ ./pypy-cli
- Python 2.5.2 (64219, Apr 17 2009, 13:54:38)
- [PyPy 1.0.0] on linux2
- Type "help", "copyright", "credits" or "license" for more information.
- And now for something completely different: ``distopian and utopian chairs''
- >>>>
-
-Moreover, at the moment it's not possible to do the full translation
-using only the tools provided by the Microsoft .NET SDK, since
-``ilasm`` crashes when trying to assemble the pypy-cli code due to its
-size. Microsoft .NET SDK 2.0.50727.42 is affected by this bug; other
-version could be affected as well: if you find a version of the SDK
-that works, please tell us.
-
-Windows users that want to compile their own pypy-cli can install
-Mono_: if a Mono installation is detected the translation toolchain
-will automatically use its ``ilasm2`` tool to assemble the
-executables.
-
-To try out the experimental .NET integration, check the documentation of the
-clr_ module.
-
-.. _`JVM code`:
-
-Translating using the JVM backend
-+++++++++++++++++++++++++++++++++
-
-To create a standalone JVM executable::
-
- ./translate.py --backend=jvm targetpypystandalone.py
-
-This will create a jar file ``pypy-jvm.jar`` as well as a convenience
-script ``pypy-jvm`` for executing it. To try it out, simply run
-``./pypy-jvm``::
-
- $ ./pypy-jvm
- Python 2.5.2 (64214, Apr 17 2009, 08:11:23)
- [PyPy 1.0.0] on darwin
- Type "help", "copyright", "credits" or "license" for more information.
- And now for something completely different: ``# assert did not crash''
- >>>>
-
-Alternatively, you can run it using ``java -jar pypy-jvm.jar``.
-
-Installation
-++++++++++++
-
-A prebuilt ``pypy-c`` can be installed in a standard location like
-``/usr/local/bin``, although some details of this process are still in
-flux. It can also be copied to other machines as long as their system
-is "similar enough": some details of the system on which the translation
-occurred might be hard-coded in the executable.
-
-For installation purposes, note that the executable needs to be able to
-find its version of the Python standard library in the following three
-directories: ``lib-python/2.5.2``, ``lib-python/modified-2.5.2`` and
-``pypy/lib``. They are located by "looking around" starting from the
-directory in which the executable resides. The current logic is to try
-to find a ``PREFIX`` from which the directories
-``PREFIX/lib-python/2.5.2`` and ``PREFIX/lib-python/modified.2.5.2`` and
-``PREFIX/pypy/lib`` can all be found. The prefixes that are tried are::
-
- .
- ./share/pypy-1.0
- ..
- ../share/pypy-1.0
- ../..
- ../../share/pypy-1.0
- ../../..
- etc.
+The largest example of this process is to translate the `full Python
+interpreter`_. There is also an FAQ about how to set up this process for `your
+own interpreters`_.
+.. _`your own interpreters`: faq.html#how-do-i-compile-my-own-interpreters
.. _`start reading sources`:
@@ -693,12 +209,122 @@
.. _optionaltool:
+
+Running PyPy's unit tests
+-------------------------
+
+The PyPy project uses test-driven-development. Right now, there are
+a couple of different categories of tests which you can run.
+To run all the unit tests::
+
+ cd pypy
+ python test_all.py
+
+(this is not recommended, since it takes hours and uses huge amounts of RAM).
+Alternatively, you may run subtests by going to the correct subdirectory
+and running them individually::
+
+ python test_all.py interpreter/test/test_pyframe.py
+
+``test_all.py`` is actually just a synonym for `py.test`_ which is
+our external testing tool. If you have installed that you
+can as well just issue ``py.test DIRECTORY_OR_FILE`` in order
+to perform test runs or simply start it without arguments to
+run all tests below the current directory.
+
+Finally, there are the CPython regression tests which you can
+run like this (this will take hours and hours and hours)::
+
+ cd lib-python/2.5.2/test
+ python ../../../pypy/test_all.py
+
+.. _`installed py.test`: https://codespeak.net/py/current/doc/download.html
+
+Special Introspection Features of the Untranslated Python Interpreter
+---------------------------------------------------------------------
+
+If you are interested in the inner workings of the PyPy Python interpreter,
+there are some features of the untranslated Python interpreter that allow you
+to introspect its internals.
+
+Interpreter-level console
++++++++++++++++++++++++++
+
+If you start an untranslated Python interpreter via::
+
+ python pypy-svn/pypy/bin/py.py
+
+If you press
+<Ctrl-C> on the console you enter the interpreter-level console, a
+usual CPython console. You can then access internal objects of PyPy
+(e.g. the `object space`_) and any variables you have created on the PyPy
+prompt with the prefix ``w_``::
+
+ >>>> a = 123
+ >>>> <Ctrl-C>
+ *** Entering interpreter-level console ***
+ >>> w_a
+ W_IntObject(123)
+
+The mechanism works in both directions. If you define a variable with the ``w_`` prefix on the interpreter-level, you will see it on the app-level::
+
+ >>> w_l = space.newlist([space.wrap(1), space.wrap("abc")])
+ >>> <Ctrl-D>
+ *** Leaving interpreter-level console ***
+
+ KeyboardInterrupt
+ >>>> l
+ [1, 'abc']
+
+.. _`object space`: objspace.html
+
+Note that the prompt of the interpreter-level console is only '>>>' since
+it runs on CPython level. If you want to return to PyPy, press <Ctrl-D> (under
+Linux) or <Ctrl-Z>, <Enter> (under Windows).
+
+You may be interested in reading more about the distinction between
+`interpreter-level and app-level`_.
+
+.. _`interpreter-level and app-level`: coding-guide.html#interpreter-level
+
+.. _`trace example`:
+
+Tracing bytecode and operations on objects
+++++++++++++++++++++++++++++++++++++++++++
+
+You can use the trace object space to monitor the interpretation
+of bytecodes in connection with object space operations. To enable
+it, set ``__pytrace__=1`` on the interactive PyPy console::
+
+ >>>> __pytrace__ = 1
+ Tracing enabled
+ >>>> a = 1 + 2
+ |- <<<< enter <inline>a = 1 + 2 @ 1 >>>>
+ |- 0 LOAD_CONST 0 (W_IntObject(1))
+ |- 3 LOAD_CONST 1 (W_IntObject(2))
+ |- 6 BINARY_ADD
+ |- add(W_IntObject(1), W_IntObject(2)) -> W_IntObject(3)
+ |- 7 STORE_NAME 0 (a)
+ |- hash(W_StringObject('a')) -> W_IntObject(-468864544)
+ |- int_w(W_IntObject(-468864544)) -> -468864544
+ |-10 LOAD_CONST 2 (<W_NoneObject()>)
+ |-13 RETURN_VALUE
+ |- <<<< leave <inline>a = 1 + 2 @ 1 >>>>
+
+Demos
+-------
+
+The `demo/`_ directory contains examples of various aspects of PyPy,
+ranging from running regular Python programs (that we used as compliance goals)
+over experimental distribution mechanisms to examples translating
+sufficiently static programs into low level code.
+
Additional Tools for running (and hacking) PyPy
-----------------------------------------------
We use some optional tools for developing PyPy. They are not required to run
the basic tests or to get an interactive PyPy prompt but they help to
-understand and debug PyPy especially for the ongoing translation work.
+understand and debug PyPy especially for the translation process.
graphviz & pygame for flow graph viewing (highly recommended)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -710,7 +336,7 @@
pygame: http://www.pygame.org/download.shtml
-CTypes (highly recommended)
+CTypes on Python 2.4
++++++++++++++++++++++++++++
`ctypes`_ is included in CPython 2.5 and higher. CPython 2.4 users needs to
@@ -735,23 +361,24 @@
http://codespeak.net/py/dist/download.html
Getting involved
-================
+-----------------
PyPy employs an open development process. You are invited to join our
`pypy-dev mailing list`_ or look at the other `contact
-possibilities`_. We are also doing coding Sprints which are
+possibilities`_. Usually we give out commit rights fairly liberally, so if you
+want to do something with PyPy, you can become a committer. We are also doing
+coding Sprints which are
separately announced and often happen around Python conferences such
-as EuroPython or Pycon. Take a look at the list of upcoming events_ to
-plan where to meet with us.
+as EuroPython or Pycon. Upcoming events are usually announced on `the blog`_.
-.. _events: http://codespeak.net/pypy/trunk/pypy/doc/news.html
+.. _`full Python interpreter`: getting-started-python.html
+.. _`the blog`: http://morepypy.blogspot.com
.. _`pypy-dev mailing list`: http://codespeak.net/mailman/listinfo/pypy-dev
.. _`contact possibilities`: index.html
.. _`py library`: http://codespeak.net/py
.. _`Spidermonkey`: http://www.mozilla.org/js/spidermonkey/
-.. _`Google summer of code`: http://code.google.com/soc
.. _`.NET Framework SDK 2.0`: http://msdn.microsoft.com/netframework/downloads/updates/default.aspx
.. _Mono: http://www.mono-project.com/Main_Page
@@ -778,9 +405,8 @@
.. _mailing lists: index.html
.. _documentation: docindex.html
.. _unit tests: coding-guide.html#test-design
-.. _bug reports: https://codespeak.net/issue/pypy-dev/
.. _`directory reference`: docindex.html#directory-reference
-.. _`Boehm-Demers-Weiser garbage collector`: http://www.hpl.hp.com/personal/Hans_Boehm/gc/
.. include:: _ref.txt
+
Modified: pypy/trunk/pypy/doc/getting-started.txt
==============================================================================
--- pypy/trunk/pypy/doc/getting-started.txt (original)
+++ pypy/trunk/pypy/doc/getting-started.txt Fri Apr 17 19:00:26 2009
@@ -29,8 +29,8 @@
.. _`latest stable version via subversion`:
.. _`get via Subversion`:
-Svn-check out & run the latest PyPy as a two-liner
---------------------------------------------------
+Svn-check out
+-------------
Before you can play with PyPy, you will need to obtain a copy
of the sources. This can be done either by `downloading them
@@ -40,11 +40,8 @@
.. _`downloading them from the download page`: download.html
-If you choose to use subversion_, you must first install it
-if you don't already have it. We have
-some `help on installing subversion`_ for PyPy. Once it is installed,
-you can then issue the following command on your command line,
-DOS box, or terminal::
+If you choose to use subversion, you must issue the following command on your
+command line, DOS box, or terminal::
svn co http://codespeak.net/svn/pypy/dist pypy-dist
@@ -55,34 +52,17 @@
version of PyPy - which may not always be stable! - then check out
from ``http://codespeak.net/svn/pypy/trunk`` intead.
-After checkout you can start the PyPy interpreter via::
+Where to go from here
+----------------------
- python pypy-svn/pypy/bin/py.py
+After you succesfully managed to get PyPy's source you can read more about:
-Have fun :-)
-Note that you will need a C compiler that is supported by CPython's distutils.
-This gives you a PyPy prompt, i.e. a very compliant Python
-interpreter implemented in Python. PyPy passes around `98% of
-CPythons core language regression tests`_. When starting this way,
-the PyPy interpreter is running on top of CPython, and as such it
-runs around 2000 times slower than CPython itself.
-Many extension modules are not enabled by default; to use them you need
-to pass ``--withmod-NAME`` arguments (for example, ``--withmod-_rawffi``
-is required to import our version of ctypes).
-
-This is probably not something you want to play with for too long,
-though, as it is really slow. Instead, you should use PyPy to `translate
-itself to lower level languages`_ after which it runs standalone, is not
-dependant on CPython anymore and becomes faster (its performance is within
-the same order of magnitude as CPython itself).
+ - `Building and using PyPy's Python interpreter`_
+ - `Learning more about the translation toolchain and how to develop (with) PyPy`_
-.. _`98% of CPythons core language regression tests`: http://codespeak.net:8099/summary?category=lib-python&branch=%3Ctrunk%3E
+.. _`Building and using PyPy's Python interpreter`: getting-started-python.html
+.. _`Learning more about the translation toolchain and how to develop (with) PyPy`: getting-started-translation.html
-Have a look at `interesting starting points`_
-for some guidance on how to continue.
-
-.. _`help on installing subversion`: svn-help.html
-.. _subversion: svn-help.html
Understanding PyPy's architecture
---------------------------------
@@ -93,26 +73,7 @@
may just `start reading sources`_ .
.. _`documentation section`: docindex.html
-
-Running all of PyPy's tests
----------------------------
-
-If you want to see `if PyPy works on your machine/platform`_
-you can simply run PyPy's large test suite with::
-
- cd pypy
- python test_all.py directory-or-files
-
-test_all.py is just another name for `py.test`_ which is the
-testing tool that we are using and enhancing for PyPy.
-**Note that running all the tests takes a very long time, and
-enormous amounts of memory if you are trying to run them all
-in the same process; test_all.py is only suitable to run a
-subset of them at a time.** To run them all daily we have a BuildBot based
-setup, a summary of its results can be seen at http://codespeak.net:8099/summary.
-
-.. _`if PyPy works on your machine/platform`: docindex.html#status
-.. _`autotest driver`: http://codespeak.net/pipermail/pypy-dev/2006q3/003273.html
+.. _`start reading sources`: getting-started-translation.html#start-reading-sources
Filing bugs or feature requests
-------------------------------
@@ -123,664 +84,7 @@
more detailed information on specific features of the tracker.
.. _`using the development tracker`: coding-guide.html#using-development-tracker
-
-.. _`interesting starting points`:
-
-Interesting Starting Points in PyPy
-===================================
-
-To get started with PyPy, you can either play with `the py.py
-interpreter`_ and the `special PyPy features`_, or directly proceed to
-`translating the PyPy Python interpreter`_. This allows you to try out
-real Python applications in a fast version of PyPy, compiled via C,
-.NET or Java, with or without special features included.
-
-Main entry point
-------------------------------------------
-
-The py.py interpreter
-+++++++++++++++++++++
-
-To start interpreting Python with PyPy, install a C compiler that is
-supported by distutils and use Python 2.4 or greater to run PyPy::
-
- cd pypy
- python bin/py.py
-
-After a few seconds (remember: this is running on top of CPython),
-you should be at the PyPy prompt, which is the same as the Python
-prompt, but with an extra ">".
-
-Now you are ready to start running Python code. Most Python
-modules should work if they don't involve CPython extension
-modules. Here is an example of determining PyPy's performance
-in pystones::
-
- >>>> from test import pystone
- >>>> pystone.main(10)
-
-The parameter is the number of loops to run through the test. The
-default is 50000, which is far too many to run in a non-translated
-PyPy version (i.e. when PyPy's interpreter itself is being interpreted
-by CPython).
-
-py.py options
-+++++++++++++
-
-To list the PyPy interpreter command line options, type::
-
- cd pypy
- python bin/py.py --help
-
-py.py supports most of the options that CPython supports too (in addition to a
-large amount of options that can be used to customize py.py).
-As an example of using PyPy from the command line, you could type::
-
- python py.py -c "from test import pystone; pystone.main(10)"
-
-Alternatively, as with regular Python, you can simply give a
-script name on the command line::
-
- python py.py ../../lib-python/2.5.2/test/pystone.py 10
-
-See our `configuration sections`_ for details about what all the commandline
-options do.
-
-Special PyPy features
---------------------------
-
-Interpreter-level console
-+++++++++++++++++++++++++
-
-There are quite a few extra features of the PyPy console: If you press
-<Ctrl-C> on the console you enter the interpreter-level console, a
-usual CPython console. You can then access internal objects of PyPy
-(e.g. the object space) and any variables you have created on the PyPy
-prompt with the prefix ``w_``::
-
- .. >>> import py ; py.test.skip("skipchunk")
- >>>> a = 123
- >>>> <Ctrl-C>
- *** Entering interpreter-level console ***
- >>> w_a
- W_IntObject(123)
-
-Note that the prompt of the interpreter-level console is only '>>>' since
-it runs on CPython level. If you want to return to PyPy, press <Ctrl-D> (under
-Linux) or <Ctrl-Z>, <Enter> (under Windows).
-
-You may be interested in reading more about the distinction between
-`interpreter-level and app-level`_.
-
-.. _`interpreter-level and app-level`: coding-guide.html#interpreter-level
-
-.. _`trace example`:
-
-Tracing bytecode and operations on objects
-++++++++++++++++++++++++++++++++++++++++++
-
-You can use the trace object space to monitor the interpretation
-of bytecodes in connection with object space operations. To enable
-it, set ``__pytrace__=1`` on the interactive PyPy console::
-
- >>>> __pytrace__ = 1
- Tracing enabled
- >>>> a = 1 + 2
- |- <<<< enter <inline>a = 1 + 2 @ 1 >>>>
- |- 0 LOAD_CONST 0 (W_IntObject(1))
- |- 3 LOAD_CONST 1 (W_IntObject(2))
- |- 6 BINARY_ADD
- |- add(W_IntObject(1), W_IntObject(2)) -> W_IntObject(3)
- |- 7 STORE_NAME 0 (a)
- |- hash(W_StringObject('a')) -> W_IntObject(-468864544)
- |- int_w(W_IntObject(-468864544)) -> -468864544
- |-10 LOAD_CONST 2 (<W_NoneObject()>)
- |-13 RETURN_VALUE
- |- <<<< leave <inline>a = 1 + 2 @ 1 >>>>
-
-
-.. _ `lazily computed objects`:
-
-Lazily computed objects
-+++++++++++++++++++++++
-
-One of the original features provided by PyPy is the "thunk"
-object space, providing lazily-computed objects in a fully
-transparent manner::
-
- cd pypy
- python bin/py.py -o thunk
-
- >>>> from __pypy__ import thunk
- >>>> def longcomputation(lst):
- .... print "computing..."
- .... return sum(lst)
- ....
- >>>> x = thunk(longcomputation, range(5))
- >>>> y = thunk(longcomputation, range(10))
-
-From the application perspective, ``x`` and ``y`` represent
-exactly the objects being returned by the ``longcomputation()``
-invocations. You can put these objects into a dictionary
-without triggering the computation::
-
- >>>> d = {5: x, 10: y}
- >>>> result = d[5]
- >>>> result
- computing...
- 10
- >>>> type(d[10])
- computing...
- <type 'int'>
- >>>> d[10]
- 45
-
-It is interesting to note that this lazy-computing Python extension
-is solely implemented in a small `objspace/thunk.py`_ file consisting
-of around 200 lines of code. Since the 0.8.0 release you
-can `translate PyPy with the thunk object space`_.
-
-More
-++++
-
-If you know more about pypy-exclusive features, choose one from the following,
-go to `objspace proxies`_ document.
-
-.. _`objspace proxies`: objspace-proxies.html
-
-Running the tests
-+++++++++++++++++
-
-The PyPy project uses test-driven-development. Right now, there are
-a couple of different categories of tests which you can run.
-To run all the unit tests::
-
- cd pypy
- python test_all.py
-
-(this is not recommended, since it takes hours and uses huge amounts of RAM).
-Alternatively, you may run subtests by going to the correct subdirectory
-and running them individually::
-
- python test_all.py interpreter/test/test_pyframe.py
-
-``test_all.py`` is actually just a synonym for `py.test`_ which is
-our external testing tool. If you have installed that you
-can as well just issue ``py.test DIRECTORY_OR_FILE`` in order
-to perform test runs or simply start it without arguments to
-run all tests below the current directory.
-
-Finally, there are the CPython regression tests which you can
-run like this (this will take hours and hours and hours)::
-
- cd lib-python/2.5.2/test
- python ../../../pypy/test_all.py
-
-.. _`installed py.test`: https://codespeak.net/py/current/doc/download.html
-
-Demos
-+++++
-
-The `demo/`_ directory contains examples of various aspects of PyPy,
-ranging from running regular Python programs (that we used as compliance goals)
-over experimental distribution mechanisms to examples translating
-sufficiently static programs into low level code.
-
-.. _`try out the translator`:
-
-Trying out the translator
--------------------------
-
-The translator is a tool based on the PyPy interpreter which can translate
-sufficiently static Python programs into low-level code. To be able to use it
-you need to (if you want to look at the flowgraphs, which you obviously
-should):
-
- * Download and install Pygame_.
-
- * Download and install `Dot Graphviz`_ (optional if you have an internet
- connection: the flowgraph viewer then connects to
- codespeak.net and lets it convert the flowgraph by a graphviz server).
-
-To start the interactive translator shell do::
-
- cd pypy
- python bin/translatorshell.py
-
-Test snippets of translatable code are provided in the file
-``pypy/translator/test/snippet.py``, which is imported under the name
-``snippet``. For example::
-
- >>> t = Translation(snippet.is_perfect_number)
- >>> t.view()
-
-After that, the graph viewer pops up, that lets you interactively inspect the
-flow graph. To move around, click on something that you want to inspect.
-To get help about how to use it, press 'H'. To close it again, press 'Q'.
-
-Trying out the type annotator
-+++++++++++++++++++++++++++++
-
-We have a type annotator that can completely infer types for functions like
-``is_perfect_number`` (as well as for much larger examples)::
-
- >>> t.annotate([int])
- >>> t.view()
-
-Move the mouse over variable names (in red) to see their inferred types.
-
-
-Translating the flow graph to C code
-++++++++++++++++++++++++++++++++++++
-
-The graph can be turned into C code::
-
- >>> t.rtype()
- >>> f = t.compile_c()
-
-The first command replaces the operations with other low level versions that
-only use low level types that are available in C (e.g. int). To try out the
-compiled version::
-
- >>> f(5)
- False
- >>> f(6)
- True
-
-Translating the flow graph to CLI or JVM code
-+++++++++++++++++++++++++++++++++++++++++++++
-
-PyPy also contains a `CLI backend`_ and JVM backend which
-can translate flow graphs into .NET executables or a JVM jar
-file respectively. Both are able to translate the entire
-interpreter. You can try out the CLI and JVM backends
-from the interactive translator shells as follows::
-
- >>> def myfunc(a, b): return a+b
- ...
- >>> t = Translation(myfunc)
- >>> t.annotate([int, int])
- >>> f = t.compile_cli() # or compile_jvm()
- >>> f(4, 5)
- 9
-
-The object returned by ``compile_cli`` or ``compile_jvm``
-is a wrapper around the real
-executable: the parameters are passed as command line arguments, and
-the returned value is read from the standard output.
-
-Once you have compiled the snippet, you can also try to launch the
-executable directly from the shell. You will find the
-executable in one of the ``/tmp/usession-*`` directories::
-
- # For CLI:
- $ mono /tmp/usession-dist-<username>/main.exe 4 5
- 9
-
- # For JVM:
- $ java -cp /tmp/usession-dist-<username>/pypy pypy.Main 4 5
- 9
-
-To translate and run for the CLI you must have the SDK installed: Windows
-users need the `.NET Framework SDK 2.0`_, while Linux and Mac users
-can use Mono_.
-
-To translate and run for the JVM you must have a JDK installed (at
-least version 5) as well as the `Jasmin JVM assembler`_. In particular,
-you need a script in your path called ``jasmin`` which will execute
-the assembler. For example, the contents might be:
-
- #!/bin/bash
- java -jar $PATH_TO_JASMIN_JAR "$@"
-
-.. _`Jasmin JVM assembler`: http://jasmin.sourceforge.net/
-
-A slightly larger example
-+++++++++++++++++++++++++
-
-There is a small-to-medium demo showing the translator and the annotator::
-
- cd demo
- python bpnn.py
-
-This causes ``bpnn.py`` to display itself as a call graph and class
-hierarchy. Clicking on functions shows the flow graph of the particular
-function. Clicking on a class shows the attributes of its instances. All
-this information (call graph, local variables' types, attributes of
-instances) is computed by the annotator.
-
-As soon as you close the PyGame window, the function is turned into C code,
-compiled and executed.
-
-.. _`translate itself to lower level languages`:
-
-Translating the PyPy Python interpreter
----------------------------------------
-
-(**Note**: for some hints on how to translate the Python interpreter under
-Windows, see the `windows document`_)
-
-.. _`windows document`: windows.html
-
-You can translate the whole of PyPy's Python interpreter to low level C code,
-`CLI code`_, or `JVM code`_. (This is the largest and ultimate example of
-RPython program that our translation toolchain can process.)
-
-1. Install dependencies. You need (these are Debian package names,
- adapt as needed):
-
- * gcc
- * ``python-dev``
- * ``python-ctypes``
- * ``libffi-dev``
- * ``libz-dev`` (for the optional ``zlib`` module)
- * ``libbz2-dev`` (for the optional ``bz2`` module)
- * ``libncurses-dev`` (for the optional ``_minimal_curses`` module)
- * ``libgc-dev`` (only when translating with `--opt=0, 1` or `size`)
-
-2. Be warned that translation is time-consuming (30 min to
- over one hour) and extremely RAM-hungry (kill it if it
- starts swapping heavily). If you have less than 1.5 GB of
- RAM (or a slow machine) you might want to pick the
- `optimization level`_ `1` in the next step. A level of
- `2` or `3` gives much better results, though.
-
-3. Run::
-
- cd pypy/translator/goal
- python translate.py --opt=3 targetpypystandalone.py
-
- possibly replacing ``--opt=3`` with ``--opt=1`` or another
- `optimization level`_ of your choice.
-
- On Linux 32-bit Intel machines, if you don't need threads, you
- can get some extra speed (and extra translation time) by adding
- ``--gcrootfinder=asmgcc`` just after the ``--opt`` option.
-
-.. _`optimization level`: config/opt.html
-
-If everything works correctly this will create an executable
-``pypy-c`` in the current directory. Type ``pypy-c --help``
-to see the options it supports -- mainly the same basic
-options as CPython. In addition, ``pypy-c --info`` prints the
-translation options that where used to produce this particular
-executable. This executable can be moved around or copied on
-other machines; see Installation_ below.
-
-The ``translate.py`` script takes a very large number of options controlling
-what to translate and how. See ``translate.py -h``. Some of the more
-interesting options are:
-
- * ``--stackless``: this produces a pypy-c that includes features
- inspired by `Stackless Python <http://www.stackless.com>`__.
-
- * ``--gc=boehm|ref|marknsweep|semispace|generation|hybrid``:
- choose between using
- the `Boehm-Demers-Weiser garbage collector`_, our reference
- counting implementation or four of own collector implementations
- (Boehm's collector is the default).
-
-Find a more detailed description of the various options in our `configuration
-sections`_.
-
-You can also use the translate.py script to try out several smaller
-programs, e.g. a slightly changed version of Pystone::
-
- cd pypy/translator/goal
- python translate.py targetrpystonedalone
-
-This will produce the executable "targetrpystonedalone-c".
-
-.. _`configuration sections`: config/index.html
-
-.. _`translate PyPy with the thunk object space`:
-
-Translating with the thunk object space
-++++++++++++++++++++++++++++++++++++++++
-
-
-It is also possible to experimentally translate a PyPy version using
-the "thunk" object space::
-
- cd pypy/translator/goal
- python translate.py targetpypystandalone.py --objspace=thunk
-
-the examples in `lazily computed objects`_ should work in the translated
-result.
-
-.. _`CLI code`:
-
-Translating using the CLI backend
-+++++++++++++++++++++++++++++++++
-
-To create a standalone .NET executable using the `CLI backend`_::
-
- ./translate.py --backend=cli targetpypystandalone.py
-
-The executable and all its dependecies will be stored in the
-./pypy-cli-data directory. To run pypy.NET, you can run
-./pypy-cli-data/main.exe. If you are using Linux or Mac, you can use
-the convenience ./pypy-cli script::
-
- $ ./pypy-cli
- Python 2.5.2 (64219, Apr 17 2009, 13:54:38)
- [PyPy 1.0.0] on linux2
- Type "help", "copyright", "credits" or "license" for more information.
- And now for something completely different: ``distopian and utopian chairs''
- >>>>
-
-Moreover, at the moment it's not possible to do the full translation
-using only the tools provided by the Microsoft .NET SDK, since
-``ilasm`` crashes when trying to assemble the pypy-cli code due to its
-size. Microsoft .NET SDK 2.0.50727.42 is affected by this bug; other
-version could be affected as well: if you find a version of the SDK
-that works, please tell us.
-
-Windows users that want to compile their own pypy-cli can install
-Mono_: if a Mono installation is detected the translation toolchain
-will automatically use its ``ilasm2`` tool to assemble the
-executables.
-
-To try out the experimental .NET integration, check the documentation of the
-clr_ module.
-
-.. _`JVM code`:
-
-Translating using the JVM backend
-+++++++++++++++++++++++++++++++++
-
-To create a standalone JVM executable::
-
- ./translate.py --backend=jvm targetpypystandalone.py
-
-This will create a jar file ``pypy-jvm.jar`` as well as a convenience
-script ``pypy-jvm`` for executing it. To try it out, simply run
-``./pypy-jvm``::
-
- $ ./pypy-jvm
- Python 2.5.2 (64214, Apr 17 2009, 08:11:23)
- [PyPy 1.0.0] on darwin
- Type "help", "copyright", "credits" or "license" for more information.
- And now for something completely different: ``# assert did not crash''
- >>>>
-
-Alternatively, you can run it using ``java -jar pypy-jvm.jar``.
-
-Installation
-++++++++++++
-
-A prebuilt ``pypy-c`` can be installed in a standard location like
-``/usr/local/bin``, although some details of this process are still in
-flux. It can also be copied to other machines as long as their system
-is "similar enough": some details of the system on which the translation
-occurred might be hard-coded in the executable.
-
-For installation purposes, note that the executable needs to be able to
-find its version of the Python standard library in the following three
-directories: ``lib-python/2.5.2``, ``lib-python/modified-2.5.2`` and
-``pypy/lib``. They are located by "looking around" starting from the
-directory in which the executable resides. The current logic is to try
-to find a ``PREFIX`` from which the directories
-``PREFIX/lib-python/2.5.2`` and ``PREFIX/lib-python/modified.2.5.2`` and
-``PREFIX/pypy/lib`` can all be found. The prefixes that are tried are::
-
- .
- ./share/pypy-1.0
- ..
- ../share/pypy-1.0
- ../..
- ../../share/pypy-1.0
- ../../..
- etc.
-
-
-.. _`start reading sources`:
-
-Where to start reading the sources
-----------------------------------
-
-PyPy is made from parts that are relatively independent from each other.
-You should start looking at the part that attracts you most (all paths are
-relative to the PyPy top level directory). You may look at our `directory reference`_
-or start off at one of the following points:
-
-* `pypy/interpreter`_ contains the bytecode interpreter: bytecode dispatcher
- in pyopcode.py_, frame and code objects in eval.py_ and pyframe.py_,
- function objects and argument passing in function.py_ and argument.py_,
- the object space interface definition in baseobjspace.py_, modules in
- module.py_ and mixedmodule.py_. Core types supporting the bytecode
- interpreter are defined in typedef.py_.
-
-* `pypy/interpreter/pyparser`_ contains a recursive descent parser,
- and input data files that allow it to parse both Python 2.3 and 2.4
- syntax. Once the input data has been processed, the parser can be
- translated by the above machinery into efficient code.
-
-* `pypy/interpreter/astcompiler`_ contains the compiler. This
- contains a modified version of the compiler package from CPython
- that fixes some bugs and is translatable. That the compiler and
- parser are translatable is new in 0.8.0 and it makes using the
- resulting binary interactively much more pleasant.
-
-* `pypy/objspace/std`_ contains the `Standard object space`_. The main file
- is objspace.py_. For each type, the files ``xxxtype.py`` and
- ``xxxobject.py`` contain respectively the definition of the type and its
- (default) implementation.
-
-* `pypy/objspace`_ contains a few other object spaces: the thunk_,
- trace_ and flow_ object spaces. The latter is a relatively short piece
- of code that builds the control flow graphs when the bytecode interpreter
- runs in it.
-
-* `pypy/translator`_ contains the code analysis and generation stuff.
- Start reading from translator.py_, from which it should be easy to follow
- the pieces of code involved in the various translation phases.
-
-* `pypy/annotation`_ contains the data model for the type annotation that
- can be inferred about a graph. The graph "walker" that uses this is in
- `pypy/annotation/annrpython.py`_.
-
-* `pypy/rpython`_ contains the code of the RPython typer. The typer transforms
- annotated flow graphs in a way that makes them very similar to C code so
- that they can be easy translated. The graph transformations are controlled
- by the stuff in `pypy/rpython/rtyper.py`_. The object model that is used can
- be found in `pypy/rpython/lltypesystem/lltype.py`_. For each RPython type
- there is a file rxxxx.py that contains the low level functions needed for
- this type.
-
-* `pypy/rlib`_ contains the RPython standard library, things that you can
- use from rpython.
-
-.. _optionaltool:
-
-Additional Tools for running (and hacking) PyPy
------------------------------------------------
-
-We use some optional tools for developing PyPy. They are not required to run
-the basic tests or to get an interactive PyPy prompt but they help to
-understand and debug PyPy especially for the ongoing translation work.
-
-graphviz & pygame for flow graph viewing (highly recommended)
-+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-graphviz and pygame are both necessary if you
-want to look at generated flow graphs:
-
- graphviz: http://www.graphviz.org/Download.php
-
- pygame: http://www.pygame.org/download.shtml
-
-CTypes (highly recommended)
-++++++++++++++++++++++++++++
-
-`ctypes`_ is included in CPython 2.5 and higher. CPython 2.4 users needs to
-install it (version 0.9.9.6 or later) if they want to run low-level tests. See
-the `download page of ctypes`_.
-
-.. _`download page of ctypes`: http://sourceforge.net/project/showfiles.php?group_id=71702
-.. _`ctypes`: http://starship.python.net/crew/theller/ctypes/
-
-.. _`py.test`:
-
-py.test and the py lib
-+++++++++++++++++++++++
-
-The `py library`_ is used for supporting PyPy development and
-running our tests against code and documentation as well as
-compliance tests. You don't need to install the py library because
-it ships with PyPy and `pypy/test_all.py`_ is an alias for ``py.test``
-but if you want to have the ``py.test`` tool generally in your
-path, you might like to visit:
-
- http://codespeak.net/py/dist/download.html
-
-Getting involved
-================
-
-PyPy employs an open development process. You are invited to join our
-`pypy-dev mailing list`_ or look at the other `contact
-possibilities`_. We are also doing coding Sprints which are
-separately announced and often happen around Python conferences such
-as EuroPython or Pycon. Take a look at the list of upcoming events_ to
-plan where to meet with us.
-
-.. _events: http://codespeak.net/pypy/trunk/pypy/doc/news.html
-.. _`pypy-dev mailing list`: http://codespeak.net/mailman/listinfo/pypy-dev
-.. _`contact possibilities`: index.html
-
-.. _`py library`: http://codespeak.net/py
-
-.. _`Spidermonkey`: http://www.mozilla.org/js/spidermonkey/
-.. _`Google summer of code`: http://code.google.com/soc
-
-.. _`.NET Framework SDK 2.0`: http://msdn.microsoft.com/netframework/downloads/updates/default.aspx
-.. _Mono: http://www.mono-project.com/Main_Page
-.. _`CLI backend`: cli-backend.html
-.. _clr: clr-module.html
-
-.. _`Dot Graphviz`: http://www.graphviz.org/
-.. _Pygame: http://www.pygame.org/
-.. _pyopcode.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/pyopcode.py
-.. _eval.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/eval.py
-.. _pyframe.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/pyframe.py
-.. _function.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/function.py
-.. _argument.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/argument.py
-.. _baseobjspace.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/baseobjspace.py
-.. _module.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/module.py
-.. _mixedmodule.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/mixedmodule.py
-.. _typedef.py: http://codespeak.net/svn/pypy/trunk/pypy/interpreter/typedef.py
-.. _Standard object space: objspace.html#the-standard-object-space
-.. _objspace.py: ../../pypy/objspace/std/objspace.py
-.. _thunk: ../../pypy/objspace/thunk.py
-.. _trace: ../../pypy/objspace/trace.py
-.. _flow: ../../pypy/objspace/flow/
-.. _translator.py: ../../pypy/translator/translator.py
-.. _mailing lists: index.html
-.. _documentation: docindex.html
-.. _unit tests: coding-guide.html#test-design
.. _bug reports: https://codespeak.net/issue/pypy-dev/
-.. _`directory reference`: docindex.html#directory-reference
-.. _`Boehm-Demers-Weiser garbage collector`: http://www.hpl.hp.com/personal/Hans_Boehm/gc/
.. include:: _ref.txt
Modified: pypy/trunk/pypy/doc/glossary.txt
==============================================================================
--- pypy/trunk/pypy/doc/glossary.txt (original)
+++ pypy/trunk/pypy/doc/glossary.txt Fri Apr 17 19:00:26 2009
@@ -217,14 +217,14 @@
in the `annotator pass`_ section.
.. _applevel: coding-guide.html#application-level
-.. _`target language`: getting-started.html#trying-out-the-translator
+.. _`target language`: getting-started-translation.html#trying-out-the-translator
.. _`just in time compiler`: jit/index.html
.. _`the jit docs`: jit/index.html
.. _`type inference article on Wikipedia`: http://en.wikipedia.org/wiki/Type_inference
.. _`annotator pass`: translation.html#the-annotation-pass
.. _`The RPython Typer`: translation.html#the-rpython-typer
-.. _`backends`: getting-started.html#trying-out-the-translator
-.. _Tool: getting-started.html#trying-out-the-translator
+.. _`backends`: getting-started-translation.html#trying-out-the-translator
+.. _Tool: getting-started-translation.html#trying-out-the-translator
.. _`translation-aspects`: translation-aspects.html
.. _`PyPy's garbage collectors`: garbage_collection.html
.. _`Restricted Python`: coding-guide.html#restricted-python
Modified: pypy/trunk/pypy/doc/translation.txt
==============================================================================
--- pypy/trunk/pypy/doc/translation.txt (original)
+++ pypy/trunk/pypy/doc/translation.txt Fri Apr 17 19:00:26 2009
@@ -106,7 +106,7 @@
.. _`bytecode evaluator`: interpreter.html
.. _`abstract interpretation`: theory.html#abstract-interpretation
.. _`Flow Object Space`: objspace.html#the-flow-object-space
-.. _`interactive interface`: getting-started.html#try-out-the-translator
+.. _`interactive interface`: getting-started-translation.html#try-out-the-translator
.. _`translatorshell.py`: ../../pypy/bin/translatorshell.py
.. _`flow model`:
@@ -704,8 +704,8 @@
The Object-Oriented backends target platforms that are less C-like and support
classes, instance etc. If such a platform is targetted, the `OO type system` is
-used while rtyping. Of the OO backends, currently only gencli can translate the
-full PyPy, but the Java backend is getting close.
+used while rtyping. Of the OO backends, both gencli and genjava can translate
+the full Python interpreter.
.. _`oo type system`: rtyper.html#oo-type
More information about the Pypy-commit
mailing list