Author: Rami Chowdhury <[email protected]> Branch: improve-docs Changeset: r66385:275734994ef5 Date: 2013-08-28 13:46 +0100 http://bitbucket.org/pypy/pypy/changeset/275734994ef5/
Log: Add more getting-started stuff into getting-started-python diff --git a/pypy/doc/getting-started-python.rst b/pypy/doc/getting-started-python.rst --- a/pypy/doc/getting-started-python.rst +++ b/pypy/doc/getting-started-python.rst @@ -1,236 +0,0 @@ -Getting Started with PyPy's Python Interpreter -============================================== - -.. contents:: - - -PyPy's Python interpreter is a very compliant Python -interpreter implemented in RPython. When compiled, it passes most of -`CPython's 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 with CPython and some missing extensions, for details see :doc:`cpython_differences` - -To actually use PyPy's Python interpreter, the first thing to do is to -`download a pre-built PyPy`_ for your architecture. - -.. _CPython's core language regression tests: http://buildbot.pypy.org/summary?category=applevel&branch=%3Ctrunk%3E -.. _Django: http://djangoproject.com -.. _Twisted: http://twistedmatrix.com -.. _download a pre-built PyPy: http://pypy.org/download.html - - -.. _translate-pypy: - -Translating the PyPy Python interpreter ---------------------------------------- - -.. note:: For some hints on how to translate the Python interpreter under - Windows, see the :doc:`windows document <rpython:windows>`. - -You can translate the whole of PyPy's Python interpreter to low level C code. -If you intend to build using gcc, check to make sure that -the version you have is not 4.2 or you will run into `this bug`_. - -.. _this bug: https://bugs.launchpad.net/ubuntu/+source/gcc-4.2/+bug/187391 - -1. First `download a pre-built PyPy`_ for your architecture which you will - use to translate your Python interpreter. It is, of course, possible to - translate with a CPython 2.6 or later, but this is not the preferred way, - because it will take a lot longer to run -- depending on your architecture, - between two and three times as long. - -2. Install build-time dependencies. On a Debian box these are:: - - [user@debian-box ~]$ sudo apt-get install \ - gcc make python-dev libffi-dev libsqlite3-dev pkg-config \ - libz-dev libbz2-dev libncurses-dev libexpat1-dev \ - libssl-dev libgc-dev python-sphinx python-greenlet - - On a Fedora-16 box these are:: - - [user@fedora-or-rh-box ~]$ sudo yum install \ - gcc make python-devel libffi-devel lib-sqlite3-devel pkgconfig \ - zlib-devel bzip2-devel ncurses-devel expat-devel \ - openssl-devel gc-devel python-sphinx python-greenlet - - On SLES11: - - $ sudo zypper install gcc make python-devel pkg-config \ - zlib-devel libopenssl-devel libbz2-devel sqlite3-devel \ - libexpat-devel libffi-devel python-curses - - The above command lines are split with continuation characters, giving the necessary dependencies first, then the optional ones. - - * ``pkg-config`` (to help us locate libffi files) - * ``libz-dev`` (for the optional ``zlib`` module) - * ``libbz2-dev`` (for the optional ``bz2`` module) - * ``libsqlite3-dev`` (for the optional ``sqlite3`` module via cffi) - * ``libncurses-dev`` (for the optional ``_minimal_curses`` module) - * ``libexpat1-dev`` (for the optional ``pyexpat`` module) - * ``libssl-dev`` (for the optional ``_ssl`` module) - * ``libgc-dev`` (for the Boehm garbage collector: only needed when translating with `--opt=0, 1` or `size`) - * ``python-sphinx`` (for the optional documentation build. You need version 1.0.7 or later) - - -3. Translation is time-consuming -- 45 minutes on a very fast machine -- - and RAM-hungry. As of March 2011, you will need **at least** 2 GB of - memory on a - 32-bit machine and 4GB on a 64-bit machine. If your memory resources - are constrained, or your machine is slow you might want to pick the - :doc:`optimization level <config/opt>` `1` in the next step. A level of - `2` or `3` or `jit` gives much better results, though. But if all - you want to do is to test that some new feature that you just wrote - translates, level 1 is enough. - - Let me stress this again: at ``--opt=1`` you get the Boehm - GC, which is here mostly for historical and for testing reasons. - You really do not want to pick it for a program you intend to use. - The resulting ``pypy-c`` is slow. - -4. Run:: - - cd pypy/goal - python ../../rpython/bin/rpython --opt=jit targetpypystandalone.py - - possibly replacing ``--opt=jit`` with another :doc:`optimization level <config/opt>` - of your choice. Typical example: ``--opt=2`` gives a good (but of - course slower) Python interpreter without the JIT. - -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. The executable behaves mostly like a normal Python interpreter:: - - $ ./pypy-c - Python 2.7.3 (480845e6b1dd, Jul 31 2013, 11:05:31) - [PyPy 2.1.0 with GCC 4.7.1] on linux2 - Type "help", "copyright", "credits" or "license" for more information. - And now for something completely different: ``RPython magically makes you rich - and famous (says so on the tin)'' - - >>>> 46 - 4 - 42 - >>>> from test import pystone - >>>> pystone.main() - Pystone(1.1) time for 50000 passes = 0.220015 - This machine benchmarks at 227257 pystones/second - >>>> pystone.main() - Pystone(1.1) time for 50000 passes = 0.060004 - This machine benchmarks at 833278 pystones/second - >>>> - -Note that pystone gets faster as the JIT kicks in. -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``. The default options -should be suitable for mostly everybody by now. -Find a more detailed description of the various options in our :doc:`configuration -sections <config/index>`. - - -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 -~~~~~~~~~~~~ - -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. - -PyPy dynamically finds the location of its libraries depending on the location -of the executable. The directory hierarchy of a typical PyPy installation -looks like this:: - - ./bin/pypy - ./include/ - ./lib_pypy/ - ./lib-python/2.7 - ./site-packages/ - -The hierarchy shown above is relative to a PREFIX directory. PREFIX is -computed by starting from the directory where the executable resides, and -"walking up" the filesystem until we find a directory containing ``lib_pypy`` -and ``lib-python/2.7``. - -The archives (.tar.bz2 or .zip) containing PyPy releases already contain the -correct hierarchy, so to run PyPy it's enough to unpack the archive, and run -the ``bin/pypy`` executable. - -To install PyPy system wide on unix-like systems, it is recommended to put the -whole hierarchy alone (e.g. in ``/opt/pypy2.1``) and put a symlink to the -``pypy`` executable into ``/usr/bin`` or ``/usr/local/bin`` - -If the executable fails to find suitable libraries, it will report -``debug: WARNING: library path not found, using compiled-in sys.path`` -and then attempt to continue normally. If the default path is usable, -most code will be fine. However, the ``sys.prefix`` will be unset -and some existing libraries assume that this is never the case. - - -.. _pyinteractive.py interpreter: - -Running the Python Interpreter Without Translation --------------------------------------------------- - -The pyinteractive.py interpreter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To start interpreting Python with PyPy, install a C compiler that is -supported by distutils and use Python 2.5 or greater to run PyPy:: - - 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 ">". - -Now you are ready to start running Python code. Most Python -modules should work if they don't involve CPython extension -modules. **This is slow, and most C modules are not present by -default even if they are standard!** 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). - - -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. _______________________________________________ pypy-commit mailing list [email protected] http://mail.python.org/mailman/listinfo/pypy-commit
