Author: Rami Chowdhury <[email protected]>
Branch: improve-docs
Changeset: r66384:7d1d8febf184
Date: 2013-08-28 13:45 +0100
http://bitbucket.org/pypy/pypy/changeset/7d1d8febf184/
Log: Split out getting-started doc
Extract the relevant portions into index, getting-started-dev, and
build documents, and remove generic (and less useful) getting-
started document.
diff --git a/pypy/doc/build.rst b/pypy/doc/build.rst
--- a/pypy/doc/build.rst
+++ b/pypy/doc/build.rst
@@ -1,7 +1,41 @@
Building PyPy from Source
=========================
-For building PyPy, it is recommended to install a pre-build PyPy first (see
+Clone the repository
+--------------------
+
+If you prefer to compile your own PyPy, or if you want to modify it, 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 mercurial. We suggest using mercurial if one wants to access
+the current development.
+
+.. _downloading them from the download page: http://pypy.org/download.html
+
+You must issue the following command on your
+command line, DOS box, or terminal::
+
+ hg clone http://bitbucket.org/pypy/pypy pypy
+
+This will clone the repository and place it into a directory
+named ``pypy``, and will get you the PyPy source in ``pypy/pypy`` and
+documentation files in ``pypy/pypy/doc``.
+We try to ensure that the tip is always stable, but it might
+occasionally be broken. You may want to check out `our nightly tests`_:
+find a revision (12-chars alphanumeric string, e.g. "963e808156b3")
+that passed at least the
+``{linux32}`` tests (corresponding to a ``+`` sign on the
+line ``success``) and then, in your cloned repository, switch to this revision
+using::
+
+ hg up -r XXXXX
+
+where XXXXX is the revision id.
+
+.. _our nightly tests: http://buildbot.pypy.org/summary?branch=<trunk>
+
+
+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.
@@ -66,7 +100,18 @@
If everything works correctly this will create an executable ``pypy-c`` in the
current directory. The executable behaves mostly like a normal Python
-interpreter (see :doc:`cpython differences`).
+interpreter (see :doc:`cpython_differences`).
+
+
+.. _translate-pypy:
+
+Translating with non-standard options
+-------------------------------------
+
+It is possible to have non-standard features enabled for translation,
+but they are not really tested any more. Look, for example, at the
+:doc:`objspace proxies <objspace-proxies>` document.
+
Installation
@@ -99,3 +144,27 @@
.. TODO windows
+
+
+Where to go from here
+---------------------
+
+Congratulations! Now that you've successfully built your own PyPy, you might
+want to `start writing a fast JITed interpreter with PyPy`_, or look at some
+:doc:`projects we need help with <project-ideas>`, or just dive deeper into
+the docs:
+
+.. toctree::
+ :maxdepth: 1
+
+ getting-started-dev
+ cpython_differences
+ gc_info
+ jit-hooks
+ stackless
+ cppyy
+ objspace-proxies
+ sandbox
+
+
+.. _start writing a fast JITed interpreter with PyPy:
http://morepypy.blogspot.com/2011/04/tutorial-writing-interpreter-with-pypy.html
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
@@ -1,39 +1,8 @@
-Getting Started with PyPy's Development Process
-===============================================
+Getting Started Developing With PyPy
+====================================
.. contents::
-.. _start-reading-sources:
-
-Where to start reading the sources
-----------------------------------
-
-PyPy is made from parts that are relatively independent of 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
:doc:`directory reference <dir-reference>`
-or start off at one of the following points:
-
-* `pypy/interpreter`_ contains the bytecode interpreter: bytecode dispatcher
- in `pypy/interpreter/pyopcode.py`_, frame and code objects in
`pypy/interpreter/eval.py`_ and `pypy/interpreter/pyframe.py`_,
- function objects and argument passing in `pypy/interpreter/function.py`_
and `pypy/interpreter/argument.py`_,
- the object space interface definition in
`pypy/interpreter/baseobjspace.py`_, modules in
- `pypy/interpreter/module.py`_ and `pypy/interpreter/mixedmodule.py`_. Core
types supporting the bytecode
- interpreter are defined in `pypy/interpreter/typedef.py`_.
-
-* :source:`pypy/interpreter/pyparser` contains a recursive descent parser,
- and grammar files that allow it to parse the syntax of various Python
- versions. Once the grammar has been processed, the parser can be
- translated by the above machinery into efficient code.
-
-* :source:`pypy/interpreter/astcompiler` contains the compiler. This
- contains a modified version of the compiler package from CPython
- that fixes some bugs and is translatable.
-
-* :source:`pypy/objspace/std` contains the :ref:`Standard object space
<standard-object-space>`. The main file
- is :source:`pypy/objspace/std/objspace.py`. For each type, the files
``xxxtype.py`` and
- ``xxxobject.py`` contain respectively the definition of the type and its
- (default) implementation.
-
Running PyPy's unit tests
-------------------------
@@ -96,9 +65,15 @@
Interpreter-level console
~~~~~~~~~~~~~~~~~~~~~~~~~
-If you start an untranslated Python interpreter via::
+To start interpreting Python with PyPy, install a C compiler that is
+supported by distutils and use Python 2.7 or greater to run PyPy::
- python pypy/bin/pyinteractive.py
+ cd pypy
+ python bin/pyinteractive.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 ">".
If you press
<Ctrl-C> on the console you enter the interpreter-level console, a
@@ -129,6 +104,28 @@
You may be interested in reading more about the distinction between
:ref:`interpreter-level and app-level <interpreter-level>`.
+pyinteractive.py options
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To list the PyPy interpreter command line options, type::
+
+ cd pypy
+ python bin/pyinteractive.py --help
+
+pyinteractive.py supports most of the options that CPython supports too (in
addition to a
+large amount of options that can be used to customize pyinteractive.py).
+As an example of using PyPy from the command line, you could type::
+
+ python pyinteractive.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 pyinteractive.py ../../lib-python/2.7/test/pystone.py 10
+
+See our :doc:`configuration sections <config/index>` for details about what
all the commandline
+options do.
+
.. _trace example:
@@ -201,12 +198,46 @@
PyPy employs an open development process. You are invited to join our
`pypy-dev mailing list`_ 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, 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. Upcoming events are usually announced on `the blog`_.
+want to do something with PyPy, you can become a committer. We also run
frequent
+coding sprints which are separately announced and often happen around Python
+conferences such as EuroPython or PyCon. Upcoming events are usually announced
+on `the blog`_.
.. _the blog: http://morepypy.blogspot.com
.. _pypy-dev mailing list: http://python.org/mailman/listinfo/pypy-dev
.. _py library: http://pylib.org
+
+
+.. _start-reading-sources:
+
+Where to start reading the sources
+----------------------------------
+
+PyPy is made from parts that are relatively independent of 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
:doc:`directory reference <dir-reference>`
+or start off at one of the following points:
+
+* :source:`pypy/interpreter` contains the bytecode interpreter: bytecode
dispatcher
+ in :source:`pypy/interpreter/pyopcode.py`, frame and code objects in
+ :source:`pypy/interpreter/eval.py` and
:source:`pypy/interpreter/pyframe.py`,
+ function objects and argument passing in
:source:`pypy/interpreter/function.py`
+ and :source:`pypy/interpreter/argument.py`, the object space interface
+ definition in :source:`pypy/interpreter/baseobjspace.py`, modules in
+ :source:`pypy/interpreter/module.py` and
:source:`pypy/interpreter/mixedmodule.py`.
+ Core types supporting the bytecode interpreter are defined in
:source:`pypy/interpreter/typedef.py`.
+
+* :source:`pypy/interpreter/pyparser` contains a recursive descent parser,
+ and grammar files that allow it to parse the syntax of various Python
+ versions. Once the grammar has been processed, the parser can be
+ translated by the above machinery into efficient code.
+
+* :source:`pypy/interpreter/astcompiler` contains the compiler. This
+ contains a modified version of the compiler package from CPython
+ that fixes some bugs and is translatable.
+
+* :source:`pypy/objspace/std` contains the :ref:`Standard object space
<standard-object-space>`. The main file
+ is :source:`pypy/objspace/std/objspace.py`. For each type, the files
``xxxtype.py`` and
+ ``xxxobject.py`` contain respectively the definition of the type and its
+ (default) implementation.
diff --git a/pypy/doc/getting-started.rst b/pypy/doc/getting-started.rst
deleted file mode 100644
--- a/pypy/doc/getting-started.rst
+++ /dev/null
@@ -1,154 +0,0 @@
-Getting Started
-==================================
-
-.. contents::
-
-
-
-.. _Python: http://docs.python.org/reference/
-
-:doc:`Downloading and installing PyPy <install>`
-
-Just the facts
---------------
-
-.. _prebuilt-pypy:
-
-Download a pre-built PyPy
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The quickest way to start using PyPy is to download a prebuilt binary for your
-OS and architecture. You can either use the `most recent release`_ or one of
-our `development nightly build`_. Please note that the nightly builds are not
-guaranteed to be as stable as official releases, use them at your own risk.
-
-.. _most recent release: http://pypy.org/download.html
-.. _development nightly build: http://buildbot.pypy.org/nightly/trunk/
-
-
-Installing PyPy
-~~~~~~~~~~~~~~~
-
-PyPy is ready to be executed as soon as you unpack the tarball or the zip
-file, with no need to install it in any specific location::
-
- $ tar xf pypy-2.1.tar.bz2
- $ ./pypy-2.1/bin/pypy
- Python 2.7.3 (480845e6b1dd, Jul 31 2013, 11:05:31)
- [PyPy 2.1.0 with GCC 4.4.3] on linux2
- Type "help", "copyright", "credits" or "license" for more information.
- And now for something completely different: ``PyPy is an exciting
technology
- that lets you to write fast, portable, multi-platform interpreters with
less
- effort''
- >>>>
-
-If you want to make PyPy available system-wide, you can put a symlink to the
-``pypy`` executable in ``/usr/local/bin``. It is important to put a symlink
-and not move the binary there, else PyPy would not be able to find its
-library.
-
-If you want to install 3rd party libraries, the most convenient way is to
-install distribute_ and pip_:
-
- $ curl -O http://python-distribute.org/distribute_setup.py
-
- $ curl -O https://raw.github.com/pypa/pip/master/contrib/get-pip.py
-
- $ ./pypy-2.1/bin/pypy distribute_setup.py
-
- $ ./pypy-2.1/bin/pypy get-pip.py
-
- $ ./pypy-2.1/bin/pip install pygments # for example
-
-3rd party libraries will be installed in ``pypy-2.1/site-packages``, and
-the scripts in ``pypy-2.1/bin``.
-
-
-Installing using virtualenv
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-It is often convenient to run pypy inside a virtualenv. To do this
-you need a recent version of virtualenv -- 1.6.1 or greater. You can
-then install PyPy both from a precompiled tarball or from a mercurial
-checkout::
-
- # from a tarball
- $ virtualenv -p /opt/pypy-c-jit-41718-3fb486695f20-linux/bin/pypy
my-pypy-env
-
- # from the mercurial checkout
- $ virtualenv -p /path/to/pypy/pypy/translator/goal/pypy-c my-pypy-env
-
-Note that bin/python is now a symlink to bin/pypy.
-
-.. _distribute: http://www.python-distribute.org/
-.. _pip: http://pypi.python.org/pypi/pip
-
-
-
-
-Clone the repository
-~~~~~~~~~~~~~~~~~~~~
-
-If you prefer to :doc:`compile PyPy by yourself <getting-started-python>`, or
if you want to modify it, 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 mercurial. We suggest using mercurial if one wants to access
-the current development.
-
-.. _downloading them from the download page: http://pypy.org/download.html
-
-You must issue the following command on your
-command line, DOS box, or terminal::
-
- hg clone http://bitbucket.org/pypy/pypy pypy
-
-This will clone the repository and place it into a directory
-named ``pypy``, and will get you the PyPy source in
-``pypy/pypy`` and documentation files in ``pypy/pypy/doc``.
-We try to ensure that the tip is always stable, but it might
-occasionally be broken. You may want to check out `our nightly tests`_:
-find a revision (12-chars alphanumeric string, e.g. "963e808156b3")
-that passed at least the
-``{linux32}`` tests (corresponding to a ``+`` sign on the
-line ``success``) and then, in your cloned repository, switch to this revision
-using::
-
- hg up -r XXXXX
-
-where XXXXX is the revision id.
-
-.. _our nightly tests: http://buildbot.pypy.org/summary?branch=<trunk>
-
-
-Where to go from here
-----------------------
-
-After you successfully manage to get PyPy's source you can read more about:
-
- - :doc:`Building and using PyPy's Python interpreter <getting-started-python>`
- - :doc:`Learning more about the RPython toolchain and how to develop (with)
PyPy <getting-started-dev>`
- - `Tutorial for how to write an interpreter with the RPython toolchain and
make it fast`_
- - `Look at our benchmark results`_
-
-.. _Tutorial for how to write an interpreter with the RPython toolchain and
make it fast:
http://morepypy.blogspot.com/2011/04/tutorial-writing-interpreter-with-pypy.html
-.. _Look at our benchmark results: http://speed.pypy.org
-
-
-Understanding PyPy's architecture
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For in-depth information about architecture and coding documentation
-head over to the :doc:`documentation section <project-documentation>` where
you'll find lots of
-interesting information. Additionally, in true hacker spirit, you
-may just :ref:`start reading sources <start-reading-sources>`.
-
-
-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. :ref:`Using the development tracker
<using-development-tracker>` has
-more detailed information on specific features of the tracker.
-
-.. _bug reports: https://bugs.pypy.org/
diff --git a/pypy/doc/index.rst b/pypy/doc/index.rst
--- a/pypy/doc/index.rst
+++ b/pypy/doc/index.rst
@@ -4,7 +4,7 @@
Welcome to the documentation for PyPy, a fast_, compliant alternative
implementation of the Python_ language.
-* If you want to find out more about what PyPy is, have a look at our
:doc:`introduction <introduction>`
+* If you want to find out more about what PyPy is, have a look at our
:doc:`introduction`
or consult the `PyPy website`_.
* If you're interested in trying PyPy out, check out the :doc:`installation
instructions <install>`.
@@ -20,41 +20,51 @@
.. _PyPy website: http://pypy.org/
+.. _getting-started-index:
+
Getting Started
---------------
.. toctree::
- :maxdepth: 1
+ :maxdepth: 1
- introduction
- install
- build
- faq
+ introduction
+ install
+ build
+ faq
+
+
+.. _using-pypy:
Using PyPy
----------
.. toctree::
- :maxdepth: 1
+ :maxdepth: 1
- cpython_differences
- gc_info
- jit-hooks
- stackless
- cppyy
- objspace-proxies
- sandbox
+ cpython_differences
+ gc_info
+ jit-hooks
+ stackless
+ cppyy
+ objspace-proxies
+ sandbox
+.. _developing-pypy:
+
Development documentation
-------------------------
.. toctree::
- :maxdepth: 1
+ :maxdepth: 1
- how-to-contribute
- project-ideas
- project-documentation
+ getting-started-dev
+ how-to-contribute
+ architecture
+ project-ideas
+ project-documentation
+
.. TODO: audit ^^
@@ -65,9 +75,9 @@
----------------
.. toctree::
- :maxdepth: 1
+ :maxdepth: 1
- extradoc
+ extradoc
.. TODO: Remove this? Or fill it with links to papers?
@@ -109,3 +119,34 @@
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
+
+
+.. TODO figure out what to do with these!
+
+.. toctree::
+ :hidden:
+
+ configuration
+ contributor
+ cppyy_backend
+ cppyy_example
+ ctypes-implementation
+ discussion/jit-profiler
+ discussions
+ eventhistory
+ extending
+ getting-started-dev
+ how-to-release
+ release-2.0.1
+ release-2.0.2
+ release-2.1.0
+ release-2.1.0-beta1
+ release-2.1.0-beta2
+ releases/index
+ whatsnew-1.9
+ whatsnew-2.0
+ whatsnew-2.0.0-beta1
+ whatsnew-2.1
+ whatsnew-head
+ you-want-to-help
+ __pypy__-module
_______________________________________________
pypy-commit mailing list
[email protected]
http://mail.python.org/mailman/listinfo/pypy-commit
