Author: Maciej Fijalkowski <[email protected]> Branch: improve-docs-2 Changeset: r62884:75c166d74765 Date: 2013-03-30 04:59 +0200 http://bitbucket.org/pypy/pypy/changeset/75c166d74765/
Log: continue working on improving docs diff --git a/pypy/doc/dir-reference.rst b/pypy/doc/dir-reference.rst new file mode 100644 --- /dev/null +++ b/pypy/doc/dir-reference.rst @@ -0,0 +1,140 @@ +PyPy directory cross-reference +------------------------------ + +Here is a fully referenced alphabetical two-level deep +directory overview of PyPy: + +================================= ============================================ +Directory explanation/links +================================= ============================================ +`pypy/bin/`_ command-line scripts, mainly + `pypy/bin/pyinteractive.py`_ + +`pypy/config/`_ handles the numerous options for building + and running PyPy + +`pypy/doc/`_ text versions of PyPy developer + documentation + +`pypy/doc/config/`_ documentation for the numerous translation + options + +`pypy/doc/discussion/`_ drafts of ideas and documentation + +``doc/*/`` other specific documentation topics or tools + +`pypy/interpreter/`_ `bytecode interpreter`_ and related objects + (frames, functions, modules,...) + +`pypy/interpreter/pyparser/`_ interpreter-level Python source parser + +`pypy/interpreter/astcompiler/`_ interpreter-level bytecode compiler, + via an AST representation + +`pypy/module/`_ contains `mixed modules`_ + implementing core modules with + both application and interpreter level code. + Not all are finished and working. Use + the ``--withmod-xxx`` + or ``--allworkingmodules`` translation + options. + +`pypy/objspace/`_ `object space`_ implementations + +`pypy/objspace/std/`_ the StdObjSpace_ implementing CPython's + objects and types + +`pypy/tool/`_ various utilities and hacks used + from various places + +`pypy/tool/algo/`_ general-purpose algorithmic and mathematic + tools + +`pypy/tool/pytest/`_ support code for our `testing methods`_ + + +`rpython/annotator/`_ `type inferencing code`_ for + `RPython`_ programs + +`rpython/config/`_ handles the numerous options for RPython + + +`rpython/flowspace/`_ the FlowObjSpace_ implementing + `abstract interpretation`_ + +`rpython/rlib/`_ a `"standard library"`_ for RPython_ + programs + +`rpython/rtyper/`_ the `RPython Typer`_ + +`rpython/rtyper/lltypesystem/`_ the `low-level type system`_ for + C-like backends + +`rpython/rtyper/ootypesystem/`_ the `object-oriented type system`_ + for OO backends + +`rpython/memory/`_ the `garbage collector`_ construction + framework + +`rpython/translator/`_ translation_ backends and support code + +`rpython/translator/backendopt/`_ general optimizations that run before a + backend generates code + +`rpython/translator/c/`_ the `GenC backend`_, producing C code + from an + RPython program (generally via the rtyper_) + +`rpython/translator/cli/`_ the `CLI backend`_ for `.NET`_ + (Microsoft CLR or Mono_) + +`pypy/goal/`_ our `main PyPy-translation scripts`_ + live here + +`rpython/translator/jvm/`_ the Java backend + +`rpython/translator/tool/`_ helper tools for translation + +`dotviewer/`_ `graph viewer`_ + +``*/test/`` many directories have a test subdirectory + containing test + modules (see `Testing in PyPy`_) + +``_cache/`` holds cache files from various purposes +================================= ============================================ + +.. _`bytecode interpreter`: interpreter.html +.. _`Testing in PyPy`: coding-guide.html#testing-in-pypy +.. _`mixed modules`: coding-guide.html#mixed-modules +.. _`modules`: coding-guide.html#modules +.. _`basil`: http://people.cs.uchicago.edu/~jriehl/BasilTalk.pdf +.. _`object space`: objspace.html +.. _FlowObjSpace: objspace.html#the-flow-object-space +.. _`transparent proxies`: objspace-proxies.html#tproxy +.. _`Differences between PyPy and CPython`: cpython_differences.html +.. _`What PyPy can do for your objects`: objspace-proxies.html +.. _`Continulets and greenlets`: stackless.html +.. _StdObjSpace: objspace.html#the-standard-object-space +.. _`abstract interpretation`: http://en.wikipedia.org/wiki/Abstract_interpretation +.. _`rpython`: coding-guide.html#rpython +.. _`type inferencing code`: translation.html#the-annotation-pass +.. _`RPython Typer`: translation.html#rpython-typer +.. _`testing methods`: coding-guide.html#testing-in-pypy +.. _`translation`: translation.html +.. _`GenC backend`: translation.html#genc +.. _`CLI backend`: cli-backend.html +.. _`py.py`: getting-started-python.html#the-py.py-interpreter +.. _`translatorshell.py`: getting-started-dev.html#try-out-the-translator +.. _JIT: jit/index.html +.. _`JIT Generation in PyPy`: jit/index.html +.. _`just-in-time compiler generator`: jit/index.html +.. _rtyper: rtyper.html +.. _`low-level type system`: rtyper.html#low-level-type +.. _`object-oriented type system`: rtyper.html#oo-type +.. _`garbage collector`: garbage_collection.html +.. _`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-dev.html#try-out-the-translator diff --git a/pypy/doc/getting-started-dev.rst b/pypy/doc/getting-started-dev.rst --- a/pypy/doc/getting-started-dev.rst +++ b/pypy/doc/getting-started-dev.rst @@ -6,6 +6,9 @@ This should really write a word of two about **WHAT** is RPython + +XXX ltratt blog post +XXX "how to write interpreters" links XXX XXX XXX diff --git a/pypy/doc/how-to-contribute.rst b/pypy/doc/how-to-contribute.rst new file mode 100644 --- /dev/null +++ b/pypy/doc/how-to-contribute.rst @@ -0,0 +1,78 @@ +How to contribute to PyPy +------------------------- + +This page describes how to contribute to the PyPy project. The first thing +to remember is that PyPy project is very different than most projects out there. +It's also different from a classic compiler project, so academic courses +about compilers often don't apply or lead in the wrong direction. + +Don't just hack +--------------- + +The first and most important rule how not to contribute to PyPy is +"just hacking". This won't work. There are two major reasons why not +-- build times are large and PyPy has very thick layer separation which +make it harder to "just hack a feature". + +Test driven development +----------------------- + +Instead, we practice a lot of test driven development. This is partly because +of very high quality requirements for compilers and partly because there is +simply no other way to get around such complex project, that will keep you sane. +There are probably people out there who are smart enough not to need it, we're +not one of those. Familiarity with `pytest`_ is a must-have before +doing anything else. +This leads to the next issue: + +Layers +------ + +PyPy has layers. 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. + +* **python interpreter** - it's the part implemented in the ``pypy/`` directory. + It's implemented in RPython, which is a high level static language with + classes, garbage collection, just-in-time compiler generation and the ability + to call C. A cool part about it is that it can be run untranslated, so all + the tests are runnable without translating PyPy. + + **interpreter** contains the interpreter core + + **objspace** contains implementations of various objects exported to + the Python layer + + **module** directory contains extension modules written in RPython + +* **rpython compiler** that resides in ``rpython/annotator`` and + ``rpython/rtyper`` directories. Consult `introduction to RPython`_ for + further reading + +* **JIT generator** lives in ``rpython/jit`` directory. optimizations live + in ``rpython/jit/metainterp/optimizeopt``, the main JIT in + ``rpython/jit/metainterp`` (runtime part) and + ``rpython/jit/codewriter`` (translation-time part). Backends live in + ``rpython/jit/backend``. + +* **garbage collection** lives in ``rpython/memory`` + +The rest of directories serve specific niche goal and are unlikely a good +entry point. + +.. _`introduction to RPython`: getting-started-dev.rst _______________________________________________ pypy-commit mailing list [email protected] http://mail.python.org/mailman/listinfo/pypy-commit
