Commits

Rami Chowdhury committed 7d1d8fe

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.

Comments (0)

Files changed (4)

pypy/doc/build.rst

 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.
 
 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
 
 
 .. 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

pypy/doc/getting-started-dev.rst

-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
 -------------------------
 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
 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:
 
 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.

pypy/doc/getting-started.rst

-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/

pypy/doc/index.rst

 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>`.
 .. _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 ^^
 
 
 ----------------
 
 .. toctree::
-   :maxdepth: 1
+  :maxdepth: 1
 
-   extradoc
+  extradoc
 .. TODO: Remove this? Or fill it with links to papers?
 
 
 * :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