[pypy-commit] pypy default: moved architecture overview to architecture section

Wed May 9 13:29:22 EDT 2018

Author: Matt Jackson <email at mwjackson.net>
Branch: 
Changeset: r94510:89bbc53df999
Date: 2018-04-22 08:29 +0100
http://bitbucket.org/pypy/pypy/changeset/89bbc53df999/

Log:	moved architecture overview to architecture section

	added short building & coding style intro

diff --git a/pypy/doc/architecture.rst b/pypy/doc/architecture.rst
--- a/pypy/doc/architecture.rst
+++ b/pypy/doc/architecture.rst
@@ -73,3 +73,63 @@
 This division between bytecode evaluator and object space gives a lot of
 flexibility.  One can plug in different :doc:`object spaces <objspace>` to get
 different or enriched behaviours of the Python objects.
+
+Layers
+------
+
+RPython
+~~~~~~~
+:ref:`RPython <rpython:language>` is the language in which we write interpreters.
+Not the entire PyPy project is written in RPython, only the parts that are
+compiled in the translation process. The interesting point is that RPython
+has no parser, it's compiled from the live python objects, which makes it
+possible to do all kinds of metaprogramming during import time. In short,
+Python is a meta programming language for RPython.
+
+The RPython standard library is to be found in the ``rlib`` subdirectory.
+
+Consult `Getting Started with RPython`_ for further reading
+
+Translation
+~~~~~~~~~~~
+The translation toolchain - this is the part that takes care of translating
+RPython to flow graphs and then to C. There is more in the
+:doc:`architecture <architecture>` document written about it.
+
+It lives in the ``rpython`` directory: ``flowspace``, ``annotator``
+and ``rtyper``.
+
+PyPy Interpreter
+~~~~~~~~~~~~~~~~
+This is in the ``pypy`` directory.  ``pypy/interpreter`` is a standard
+interpreter for Python written in RPython.  The fact that it is
+RPython is not apparent at first.  Built-in modules are written in
+``pypy/module/*``.  Some modules that CPython implements in C are
+simply written in pure Python; they are in the top-level ``lib_pypy``
+directory.  The standard library of Python (with a few changes to
+accomodate PyPy) is in ``lib-python``.
+
+JIT Compiler
+~~~~~~~~~~~~
+:ref:`Just-in-Time Compiler (JIT) <rpython:jit>`: we have a tracing JIT that traces the
+interpreter written in RPython, rather than the user program that it
+interprets.  As a result it applies to any interpreter, i.e. any
+language.  But getting it to work correctly is not trivial: it
+requires a small number of precise "hints" and possibly some small
+refactorings of the interpreter.  The JIT itself also has several
+almost-independent parts: the tracer itself in ``rpython/jit/metainterp``, the
+optimizer in ``rpython/jit/metainterp/optimizer`` that optimizes a list of
+residual operations, and the backend in ``rpython/jit/backend/<machine-name>``
+that turns it into machine code.  Writing a new backend is a
+traditional way to get into the project.
+
+Garbage Collectors
+~~~~~~~~~~~~~~~~~~
+Garbage Collectors (GC): as you may notice if you are used to CPython's
+C code, there are no ``Py_INCREF/Py_DECREF`` equivalents in RPython code.
+:ref:`rpython:garbage-collection` is inserted
+during translation.  Moreover, this is not reference counting; it is a real
+GC written as more RPython code.  The best one we have so far is in
+``rpython/memory/gc/incminimark.py``.
+
+.. _`Getting started with RPython`: http://rpython.readthedocs.org/en/latest/getting-started.html
diff --git a/pypy/doc/contributing.rst b/pypy/doc/contributing.rst
--- a/pypy/doc/contributing.rst
+++ b/pypy/doc/contributing.rst
@@ -32,7 +32,7 @@
 Getting involved
 ----------------
 
-PyPy employs relatively standard open-source development process.  You are
+PyPy employs a relatively standard open-source development process.  You are
 invited to join our `pypy-dev mailing list`_, our IRC channel (#pypy on freenode)
 or look at the other :ref:`contact possibilities <contact>`.  Usually we give
 out commit rights fairly liberally, so if you want to do something with PyPy,
@@ -69,8 +69,8 @@
 ---------------
 
 PyPy development is based a typical fork/pull request based workflow, centered
-around Mercurial (hg). If you have not used this workflow before, a good
-can be found here:
+around Mercurial (hg), hosted on Bitbucket. If you have not used this workflow
+before, a good introduction can be found here:
 
     https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow
 
@@ -161,85 +161,16 @@
 Architecture
 ============
 
-PyPy has layers. Just like Ogres or onions.
-Those layers help us keep the respective parts separated enough
-to be worked on independently and make the complexity manageable. This is,
-again, just a sanity requirement for such a complex project. For example writing
-a new optimization for the JIT usually does **not** involve touching a Python
-interpreter at all or the JIT assembler backend or the garbage collector.
-Instead it requires writing small tests in
+PyPy has layers. Just like ogres or onions. Those layers help us keep the
+respective parts separated enough to be worked on independently and make the
+complexity manageable. This is, again, just a sanity requirement for such
+a complex project. For example writing a new optimization for the JIT usually
+does **not** involve touching a Python interpreter at all or the JIT assembler
+backend or the garbage collector. Instead it requires writing small tests in
 ``rpython/jit/metainterp/optimizeopt/test/test_*`` and fixing files there.
 After that, you can just compile PyPy and things should just work.
 
-The short list of layers for further reading. For each of those layers, a good
-entry point is a test subdirectory in respective directories. It usually
-describes (better or worse) the interfaces between the submodules. For the
-``pypy`` subdirectory, most tests are small snippets of python programs that
-check for correctness (calls ``AppTestXxx``) that will call the appropriate
-part of the interpreter. For the ``rpython`` directory, most tests are small
-RPython interpreters that perform certain tasks. To see how they translate
-to low-level graphs, run them with ``--view``. To see small interpreters
-with a JIT compiler, use ``--viewloops`` option.
-
-Layers
-------
-
-RPython
-~~~~~~~
-:ref:`RPython <rpython:language>` is the language in which we write interpreters.
-Not the entire PyPy project is written in RPython, only the parts that are
-compiled in the translation process. The interesting point is that RPython
-has no parser, it's compiled from the live python objects, which makes it
-possible to do all kinds of metaprogramming during import time. In short,
-Python is a meta programming language for RPython.
-
-The RPython standard library is to be found in the ``rlib`` subdirectory.
-
-Consult `Getting Started with RPython`_ for further reading
-
-Translation
-~~~~~~~~~~~
-The translation toolchain - this is the part that takes care of translating
-RPython to flow graphs and then to C. There is more in the
-:doc:`architecture <architecture>` document written about it.
-
-It lives in the ``rpython`` directory: ``flowspace``, ``annotator``
-and ``rtyper``.
-
-PyPy Interpreter
-~~~~~~~~~~~~~~~~
-This is in the ``pypy`` directory.  ``pypy/interpreter`` is a standard
-interpreter for Python written in RPython.  The fact that it is
-RPython is not apparent at first.  Built-in modules are written in
-``pypy/module/*``.  Some modules that CPython implements in C are
-simply written in pure Python; they are in the top-level ``lib_pypy``
-directory.  The standard library of Python (with a few changes to
-accomodate PyPy) is in ``lib-python``.
-
-JIT Compiler
-~~~~~~~~~~~~
-:ref:`Just-in-Time Compiler (JIT) <rpython:jit>`: we have a tracing JIT that traces the
-interpreter written in RPython, rather than the user program that it
-interprets.  As a result it applies to any interpreter, i.e. any
-language.  But getting it to work correctly is not trivial: it
-requires a small number of precise "hints" and possibly some small
-refactorings of the interpreter.  The JIT itself also has several
-almost-independent parts: the tracer itself in ``rpython/jit/metainterp``, the
-optimizer in ``rpython/jit/metainterp/optimizer`` that optimizes a list of
-residual operations, and the backend in ``rpython/jit/backend/<machine-name>``
-that turns it into machine code.  Writing a new backend is a
-traditional way to get into the project.
-
-Garbage Collectors
-~~~~~~~~~~~~~~~~~~
-Garbage Collectors (GC): as you may notice if you are used to CPython's
-C code, there are no ``Py_INCREF/Py_DECREF`` equivalents in RPython code.
-:ref:`rpython:garbage-collection` is inserted
-during translation.  Moreover, this is not reference counting; it is a real
-GC written as more RPython code.  The best one we have so far is in
-``rpython/memory/gc/incminimark.py``.
-
-.. _`Getting started with RPython`: http://rpython.readthedocs.org/en/latest/getting-started.html
+Further Reading: :doc:`architecture <architecture>`
 
 Where to start?
 ---------------
@@ -275,6 +206,25 @@
    ``xxxobject.py`` contains the implementation for objects of type ``xxx``,
    as a first approximation.  (Some types have multiple implementations.)
 
+Building
+========
+
+For building PyPy, we recommend installing a pre-built PyPy first (see
+:doc:`install`). It is possible to build PyPy with CPython, but it will take a
+lot longer to run -- depending on your architecture, between two and three
+times as long.
+
+Further Reading: :doc:`Build <build>`
+
+Coding Guide
+============
+
+As well as the usual pep8 and formatting standards, there are a number of
+naming conventions and coding styles that are important to understand before
+browsing the source.
+
+Further Reading: :doc:`Coding Guide <coding-guide>`
+
 Testing
 =======
 
