[pypy-svn] r10790 - pypy/dist/pypy/documentation
hpk at codespeak.net
hpk at codespeak.net
Sun Apr 17 21:51:39 CEST 2005
Author: hpk
Date: Sun Apr 17 21:51:38 2005
New Revision: 10790
Added:
pypy/dist/pypy/documentation/getting_started.txt
- copied, changed from r10788, pypy/dist/pypy/documentation/howtopypy.txt
Removed:
pypy/dist/pypy/documentation/checking_ReST.txt
pypy/dist/pypy/documentation/howtopypy.txt
pypy/dist/pypy/documentation/howtosvn.txt
pypy/dist/pypy/documentation/optionaltool.txt
Modified:
pypy/dist/pypy/documentation/coding-style.txt
pypy/dist/pypy/documentation/redirections
Log:
third row of refactoring the documentation
Deleted: /pypy/dist/pypy/documentation/checking_ReST.txt
==============================================================================
--- /pypy/dist/pypy/documentation/checking_ReST.txt Sun Apr 17 21:51:38 2005
+++ (empty file)
@@ -1,9 +0,0 @@
-1. You need to have docutils installed.
-2. docutils/tools/buildhtml.py converts your ReST .txt files into .html
- files, and complains when your document has errors.
-3. There is one problem. It converts _every_ .txt to an .html, and there
- is no option to just specify one file. I get around this problem by
- making a directory and moving my new file there for testing, and then
- moving it back when I am done. 0 Elegance points for that fix ...
-
- Laura
\ No newline at end of file
Modified: pypy/dist/pypy/documentation/coding-style.txt
==============================================================================
--- pypy/dist/pypy/documentation/coding-style.txt (original)
+++ pypy/dist/pypy/documentation/coding-style.txt Sun Apr 17 21:51:38 2005
@@ -336,3 +336,78 @@
- each test directory needs a copy of pypy/tool/autopath.py which
upon import will make sure that sys.path contains the directory
where 'pypy' is in.
+
+PyPy Documentation
+==================
+
+Adding documentation
+--------------------
+
+Please add new or updated documentation by checking it in to the appropriate
+directory in subversion, usually under
+http://codespeak.net/svn/pypy/dist/pypy/documentation
+
++ Remember to run ``svn up`` **before** doing any commit.
++ All filenames should be lowercase, and documentation should be .txt files.
++ Mark-up the documentation with reST so it can generate a pretty html version.
++ On the server side a commit on the doc-subtree will immediately update the webpage.
+
+*Note* If you don't markup the textfile, it'll still be checked in, but when docutils
+runs the parser, it'll look ugly on the website. So run docutils yourself before you commit it.
+
+Some reST basics:
+-----------------
+
+There should be a title on your page. Do it like this::
+
+ Here is my Title
+ ==================
+
+ Here is a section title
+ -------------------------
+
+Make sure you have a blank line after your = or - lines or it will give you an error.
+For marking a block of code so it'll look right, you can::
+
+ Put a line of text ending with ::
+ indent your code at least one space
+ my code
+ more code
+ even more code
+ still more code
+
+End of the "block" occurs whenever you unindent back to the same level as the
+text with the ``::`` at the end.
+
+Using an underscore after a word like ``this_`` will make reST think you want a hyperlink.
+To avoid that (especially with things like ``wrap_``), you can use the `` back quote ``
+to mark it as plain text.
+
+You can get more info on reST markup at http://docutils.sourceforge.net/docs/rst/quickref.html
+
+
+Automatically testing documentation changes
+-------------------------------------------
+
+.. _`docutils home page`:
+.. _`docutils`: http://docutils.sourceforge.net/
+
+We automatically check referential integrity and ReST-conformance. In order to
+run the tests you need docutils_ installed. Then go to the local checkout
+of the documentation directory and run the tests::
+
+ cd .../pypy/documentation
+ python ../test_all.py
+
+If you see no failures chances are high that your modifications at least
+don't produce ReST-errors or wron local references. A side effect of running
+the tests is that you have `.html` files in the documentation directory
+which you can point your browser to!
+
+Additionally, if you also want to check for remote references inside
+the documentation issue::
+
+ python ../test_all.py --checkremote
+
+which will check that remote URLs are reachable.
+
Copied: pypy/dist/pypy/documentation/getting_started.txt (from r10788, pypy/dist/pypy/documentation/howtopypy.txt)
==============================================================================
--- pypy/dist/pypy/documentation/howtopypy.txt (original)
+++ pypy/dist/pypy/documentation/getting_started.txt Sun Apr 17 21:51:38 2005
@@ -5,10 +5,11 @@
.. contents::
.. sectnum::
+.. _howtopypy:
+
Just the facts
==============
-
Checking out & running PyPy as a two-liner
------------------------------------------
@@ -22,8 +23,7 @@
have fun :-)
-You can also go the more `detailed version`_ of this
-two-liner.
+You can also go the more `detailed version`_ of this two-liner.
Browsing via HTTP and getting an svn client
-------------------------------------------
@@ -32,7 +32,6 @@
(sorry, viewcvs is still not stable enough with subversion).
And here is some information to `install a subversion client`_.
-.. _`install a subversion client`: howtosvn.html
.. _`browse the pypy source code`: http://codespeak.net/svn/pypy/dist
coding style and testing
@@ -60,109 +59,16 @@
within the pypy project. Even better, come to our next sprint so that we can get
to know you.
-.. _`documentation start page`: http://codespeak.net/pypy/index.cgi?doc/index.html
-.. _`coding-style document`: http://codespeak.net/pypy/index.cgi?doc/coding-style.html
-.. _`py.test`: http://codespeak.net/py/current/doc/test.html
-
-
-PyPy Documentation
-==================
-
Viewing documentation
---------------------
-PyPy documentation is generated from reST textfiles in the pypy/documentation directory of
-our pypy-subversion repository. Go to the `documentation start page`_ and hit
-"recently modified" to get a list of recently modified documents. While in
-"doc-view" you also have a navigation area on the left side which maps all
-documentation files.
-
-Adding documentation
---------------------
-
-Please add new or updated documentation by checking it in to the appropriate
-directory in subversion, usually under
-http://codespeak.net/svn/pypy/dist/pypy/documentation
-
-+ Remember to run ``svn up`` **before** doing any commit.
-+ All filenames should be lowercase, and documentation should be .txt files.
-+ Mark-up the documentation with reST so it can generate a pretty html version.
-+ On the server side a commit on the doc-subtree will immediately update the webpage.
-
-*Note* If you don't markup the textfile, it'll still be checked in, but when docutils
-runs the parser, it'll look ugly on the website. So run docutils yourself before you commit it.
-
-Some reST basics:
------------------
-
-There should be a title on your page. Do it like this::
-
- Here is my Title
- ==================
-
- Here is a section title
- -------------------------
-
-Make sure you have a blank line after your = or - lines or it will give you an error.
-For marking a block of code so it'll look right, you can::
-
- Put a line of text ending with ::
- indent your code at least one space
- my code
- more code
- even more code
- still more code
-
-End of the "block" occurs whenever you unindent back to the same level as the
-text with the ``::`` at the end.
-
-Using an underscore after a word like this_ will make reST think you want a hyperlink.
-To avoid that (especially with things like ``wrap_``), you can use the `` back quote ``
-to mark it as plain text.
-
-You can get more info on reST markup at http://docutils.sourceforge.net/docs/rst/quickref.html
-
-Checking your work
-------------------------
-
-In order to make sure that what you commit looks reasonably pretty (or at least not
-entirely broken), you'll need to run the ``docutils`` parser on it. Unless you've
-installed it in the past, you probably don't have it installed. Open IDLE (or any
-Python interactive environment) and try "import docutils". If it imports, hooray!
-Otherwise, you'll need to download it.
-
-Go to sourceforge and download the ``snapshot`` version. Install it.
-
-*Note to Debian users:* Be sure you installed ``python2.2-dev``, which includes ``distutils``,
-before trying to install ``docutils``.
-
-Once you have ``docutils`` installed, you can use it go to your shell and use it like this::
-
- $ python ~/mypath/docutils/tools/buildhtml.py
- /// Processing directory: /home/anna/downloads/arObjSpaceDoc
- ::: Processing .txt: howtosvn.txt
- ::: Processing .txt: index.txt
-
-**WARNING** This will process **all** text documents in the directory and any subdirectories.
-I prefer to work on text in a separate directory, run the ``docutils`` parser to see what it
-looks like, then copy the .txt file over to my local /doc checkouts to commit it.
-
-Use a browser menu to go to ``File: Open: filename.html`` then you can see what it looks
-like. Look at the command shell to see what errors you've got on which lines and fix it
-in your textfile. You can then re-run the buildhtml.py script and see what errors you get.
-After it's fixed, you can commit the .txt file and it'll automagically be turned into html
-viewable on the website.
-
-
-Here are some sample reST textfiles to see what it looks like:
-
-+ ObjectSpace_
-+ ObjectSpaceInterface_
-
-.. _this: http://docutils.sourceforge.net/docs/rst/quickref.html
-.. _ObjectSpace: objspace.html
-.. _ObjectSpaceInterface: objspace.html#object-space-interface
+PyPy documentation is generated from reST textfiles in the pypy/documentation directory
+of our pypy-subversion repository. Go to the `documentation start page`_
+and look around.
+.. _`documentation start page`: index.html
+.. _`coding-style document`: coding-style.html
+.. _`py.test`: http://codespeak.net/py/current/doc/test.html
.. _`detailed version`:
@@ -177,7 +83,10 @@
follow these instructions, which assume that you
are working in a DOS box (Windows) or terminal (MacOS/X or Linux).
-1. Download subversion_ if you do not already have it.
+detailed steps
+--------------
+
+1. Download and install subversion_ if you do not already have it.
2. Change to the directory where you wish to install the source tree,
and use subversion to download the source::
@@ -262,7 +171,7 @@
.. _`installed py.test`: http://codespeak.net/py/current/doc/getting_started.html
Trying out the translator
-=========================
+-------------------------
The translator is a tool based on the PyPy interpreter which can translate
sufficiently static Python programs into low-level code.
@@ -305,7 +214,7 @@
Where to start reading the sources
-==================================
+----------------------------------
PyPy is made from parts that are relatively independent from each other.
You should start looking at the part that attracts you most:
@@ -336,7 +245,7 @@
To learn more
-=============
+-------------
* To learn more about PyPy and its development process, head
read around in the documentation_ and the wiki_, and consider
@@ -347,9 +256,47 @@
`unit tests`_ and file some `bug reports`_ (although we are not really
actively using the issue tracker yet, watch out :-)
+.. _optionaltool:
+
+Additional Tools for running (and hacking) PyPy
+-----------------------------------------------
+
+We use some optional tools for working on pypy. They are not required to run
+all the tests or to get an interactive PyPy prompt but they help to understand
+and debug PyPy.
+
+Recommended tools
++++++++++++++++++
+
+* graphviz::
+
+ (used for visualizing the control-flow)
+ http://www.research.att.com/sw/tools/graphviz/download.html_
+
+* pygame::
+
+ (to visualize control flow and annotation analysis of python programs)
+ http://www.pygame.org/download.shtml_
+
+ - on MAC OSX: XXX (please provide help on how to sanely
+ install pygame on OSX)
+
+Optional tools
+++++++++++++++
+
+* llvm:
+ One of our backends uses the `low level virtual machine`_ to generate
+ processor independant machine level code.
+
+* CLISP::
+
+ http://clisp.cons.org/_
+
+.. _`low level virtual machine`: http://llvm.cs.uiuc.edu/
+
+
--------------------------------------------------------------------------------
-.. _subversion: http://codespeak.net/pypy/index.cgi?doc/howtosvn.html
.. _Dot Graphviz: http://www.research.att.com/sw/tools/graphviz/
.. _Pygame: http://www.pygame.org/
.. _dist-pypy/pypy/interpreter: http://codespeak.net/svn/pypy/dist/pypy/interpreter/
@@ -378,3 +325,183 @@
.. _wiki: http://codespeak.net/moin/pypy/moin.cgi/FrontPage?action=show
.. _unit tests: http://codespeak.net/pypy/index.cgi?doc/testdesign.html
.. _bug reports: http://codespeak.net/issues/pypy/
+
+
+
+
+.. _subversion:
+.. _`install a subversion client`:
+.. _howtosvn:
+
+subversion
+==========
+
+
+The PyPy codebase, documentation and web pages are controlled by subversion.
+If you already know how to use it here is the URL you need to interact
+with subversion:
+
+``http://codespeak.net/svn/pypy/dist``
+
+If you don't know what to do then Jens-Uwe Mager has prepared some
+installation files which should help you to install subversion on
+your computer.
+
++ Download Unix source tarball or prepackaged versions_ for MacOS, Windows, FreeBSD and Linux
+
++ Additional information for Windows users:
+
+ * See Microsoft website_ if you have .DLL issues.
+
+ * Windows Installer file for Tortoise SVN (like Tortoise CVS) GUI_
+ (Pick the UNICODE version for Windows 2000 and XP and
+ see Win_ 2000, NT if you have problems loading it.)
+
++ Local copy of MacOS_ X binary tar ball
+ (This requires at least OS X 10.3)
+
++ Debian instructions below...
+
+btw, HowToInstallServer_ sketches how to install a subversion server on Linux (not as easy as the client install). You don't need to install server side files to get your client going.
+
+Getting started
+-----------------
+
+If you're just getting started with subversion, here's a simple how-to.
+For complete information, you can go read the subversion guide_.
+
+**Download and install the appropriate installation file of subversion above.**
+
+For linux:
+
+download the tarball. unzip and untar it. Then type *./configure*. Then, as root, *make* followed by *make install*. Voilà ... a subversion client.
+
+For Debian users::
+
+ $ apt-get install subversion-tools
+
+People using Debian *stable* first need to add the following line to ``/etc/apt/sources.list`` (thanks backports_!)::
+
+ deb http://fs.cs.fhm.edu/mirror/backports.org/debian stable subversion
+
+Note that you can always go look at the files online_ with your browser, located at: http://codespeak.net/svn/pypy/dist
+But, you'll want to check out your own local copies to work on.
+
+Check out and Check in
+----------------------------
+
+There are currently two directories you'll want to check out: /src and /doc
+In order to get the sourcecode and docs downloaded onto your drive, open a shell or commandline and type::
+
+ $ svn co http://codespeak.net/svn/pypy/dist
+ $ svn co http://codespeak.net/svn/pypy/extradoc
+
+If you are behind a dump proxy this may or may not work; see below.
+
+Once you've got the files checked out to your own system, you can use your favorite text editor to change to files. Be sure to read the coding-style_ and other documentation files before doing a lot of work on the source code. Before doing any work, make sure you're using the most recent update with::
+
+ $ svn up
+
+this will update whichever subdirectory you're in (doc or src).
+
+When you're ready to **check in** a file,
+
+cd to your local checked out sourcecode directory, and if necessary, copy the file over from wherever you worked on it::
+
+ $ cp ~/mydir/filename.ext filename.ext
+
+If you're adding a brand-new file::
+
+ $ svn add filename.ext
+
+Then, to **commit** it::
+
+ $ svn ci -m "your comments about what changes your committing"
+ $ your password: (this may not be necessary)
+
+You'll see something like the following::
+
+ Adding goals/stringcomp.py
+ Transmitting file data .
+ Committed revision 578.
+
+or::
+
+ Sending coding-style.txt
+ Transmitting file data .
+ Committed revision 631.
+
+Check online on the check-in archives_ and you'll see your revision. Feel free to add a documentation file on any major changes you've made!
+
+Some other useful subversion tricks:
+--------------------------------------
+
+**Be sure to remember ``svn`` in the commandline in the following commands.**
+
+``$ svn mv filename.ext``
+ to move or rename a file
+
+``$ svn rm filename.ext``
+ to remove (delete) a file
+
+``$ svn status``
+ will let you know what changes you've made compared to the current repository version
+
+``$ svn revert filename.ext``
+ will fix problems if you deleted or moved a file without telling svn.
+
+``$ svn cleanup``
+ last resort to fix it if you've got a totally messed up local copy.
+ Use this if you see error messages about ``locked`` files that you can't fix otherwise.
+
+Circumventing proxies
+----------------------------
+
+Some proxies don't let extended HTTP commands through. If you have an
+error complaining about a bad request, you can ask subversion to use the
+alternate port 8080 to connect to codespeak.net by adding the following
+lines in a file ``~/.subversion/servers`` (on Unix) or
+``%APPDATA%\Subversion\servers`` (on Windows)::
+
+ [groups]
+ codespeak = codespeak.net
+
+ [codespeak]
+ http-proxy-host = codespeak.net
+ http-proxy-port = 8080
+
+How to Avoid Line-ending Hell
+-----------------------------
+
+We will assume that whenever you create a .txt or a .py file, you would
+like other people to be able to read it with the line endings their
+OS prefers, even if that is different from the one your OS likes. This
+could occasionally be wrong -- say when you are specifically testing
+that code you are writing handles line endings properly -- but this is
+what you want by default. Binary files, on the other hand, should be
+stored exactly as is. This has to be set on every client. Here is how:
+
+In your home directory edit .subversion/config and comment in ::
+
+ enable-auto-props = yes
+
+ *.txt = svn:eol-style=native
+
+and add a line for .py files.
+
+--------------------------------------------------------------------------------
+
+
+.. _website: http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B259403
+.. _GUI: http://tortoisesvn.tigris.org/servlets/ProjectDocumentList?folderID=616
+.. _MacOS: http://codespeak.net/~jum/svn-1.1.3-darwin-ppc.tar.gz
+.. _versions: http://subversion.tigris.org/project_packages.html
+.. _Win: http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=4B6140F9-2D36-4977-8FA1-6F8A0F5DCA8F
+
+.. _guide: http://svnbook.red-bean.com/book.html#svn-ch-1
+.. _archives: http://codespeak.net/pipermail/pypy-svn/
+.. _online: http://codespeak.net/svn/pypy/dist/
+.. _coding-style: coding-style.html
+.. _HowToInstallServer: http://codespeak.net/moin/pypy/moin.cgi/HowToInstallServer
+.. _backports: http://www.backports.org
+
Deleted: /pypy/dist/pypy/documentation/howtopypy.txt
==============================================================================
--- /pypy/dist/pypy/documentation/howtopypy.txt Sun Apr 17 21:51:38 2005
+++ (empty file)
@@ -1,380 +0,0 @@
-==================================
-Getting started with PyPy
-==================================
-
-.. contents::
-.. sectnum::
-
-Just the facts
-==============
-
-
-Checking out & running PyPy as a two-liner
-------------------------------------------
-
-There is no public release yet, but you can easily do::
-
- svn co http://codespeak.net/svn/pypy/dist dist-pypy
-
-and after checkout you can get a PyPy interpreter via::
-
- python dist-pypy/pypy/interpreter/py.py
-
-have fun :-)
-
-You can also go the more `detailed version`_ of this
-two-liner.
-
-Browsing via HTTP and getting an svn client
--------------------------------------------
-
-You can `browse the pypy source code`_ directly via http.
-(sorry, viewcvs is still not stable enough with subversion).
-And here is some information to `install a subversion client`_.
-
-.. _`install a subversion client`: howtosvn.html
-.. _`browse the pypy source code`: http://codespeak.net/svn/pypy/dist
-
-coding style and testing
-------------------------
-
-We keep a strong focus on testing because we want to be able
-to refactor things all the time (without proper automated
-testing this would become very hard and fragile).
-
-For an overview of how we organize our codebase please look at our
-`coding-style document`_.
-
-For running all PyPy tests you can issue::
-
- cd dist-pypy/pypy/
- python test_all.py
-
-test_all.py really is another name for `py.test`_ which is a testing
-tool working from the current directory unless you specify
-filename/directory arguments.
-
-If you want to have write access to the codespeak respository
-please send a mail to <b>jum at anubis han de</b> or <b>hpk at merlinux de</b>
-in order to ask for a username and password. Please mention what you want to do
-within the pypy project. Even better, come to our next sprint so that we can get
-to know you.
-
-.. _`documentation start page`: http://codespeak.net/pypy/index.cgi?doc/index.html
-.. _`coding-style document`: http://codespeak.net/pypy/index.cgi?doc/coding-style.html
-.. _`py.test`: http://codespeak.net/py/current/doc/test.html
-
-
-PyPy Documentation
-==================
-
-Viewing documentation
----------------------
-
-PyPy documentation is generated from reST textfiles in the pypy/documentation directory of
-our pypy-subversion repository. Go to the `documentation start page`_ and hit
-"recently modified" to get a list of recently modified documents. While in
-"doc-view" you also have a navigation area on the left side which maps all
-documentation files.
-
-Adding documentation
---------------------
-
-Please add new or updated documentation by checking it in to the appropriate
-directory in subversion, usually under
-http://codespeak.net/svn/pypy/dist/pypy/documentation
-
-+ Remember to run ``svn up`` **before** doing any commit.
-+ All filenames should be lowercase, and documentation should be .txt files.
-+ Mark-up the documentation with reST so it can generate a pretty html version.
-+ On the server side a commit on the doc-subtree will immediately update the webpage.
-
-*Note* If you don't markup the textfile, it'll still be checked in, but when docutils
-runs the parser, it'll look ugly on the website. So run docutils yourself before you commit it.
-
-Some reST basics:
------------------
-
-There should be a title on your page. Do it like this::
-
- Here is my Title
- ==================
-
- Here is a section title
- -------------------------
-
-Make sure you have a blank line after your = or - lines or it will give you an error.
-For marking a block of code so it'll look right, you can::
-
- Put a line of text ending with ::
- indent your code at least one space
- my code
- more code
- even more code
- still more code
-
-End of the "block" occurs whenever you unindent back to the same level as the
-text with the ``::`` at the end.
-
-Using an underscore after a word like this_ will make reST think you want a hyperlink.
-To avoid that (especially with things like ``wrap_``), you can use the `` back quote ``
-to mark it as plain text.
-
-You can get more info on reST markup at http://docutils.sourceforge.net/docs/rst/quickref.html
-
-Checking your work
-------------------------
-
-In order to make sure that what you commit looks reasonably pretty (or at least not
-entirely broken), you'll need to run the ``docutils`` parser on it. Unless you've
-installed it in the past, you probably don't have it installed. Open IDLE (or any
-Python interactive environment) and try "import docutils". If it imports, hooray!
-Otherwise, you'll need to download it.
-
-Go to sourceforge and download the ``snapshot`` version. Install it.
-
-*Note to Debian users:* Be sure you installed ``python2.2-dev``, which includes ``distutils``,
-before trying to install ``docutils``.
-
-Once you have ``docutils`` installed, you can use it go to your shell and use it like this::
-
- $ python ~/mypath/docutils/tools/buildhtml.py
- /// Processing directory: /home/anna/downloads/arObjSpaceDoc
- ::: Processing .txt: howtosvn.txt
- ::: Processing .txt: index.txt
-
-**WARNING** This will process **all** text documents in the directory and any subdirectories.
-I prefer to work on text in a separate directory, run the ``docutils`` parser to see what it
-looks like, then copy the .txt file over to my local /doc checkouts to commit it.
-
-Use a browser menu to go to ``File: Open: filename.html`` then you can see what it looks
-like. Look at the command shell to see what errors you've got on which lines and fix it
-in your textfile. You can then re-run the buildhtml.py script and see what errors you get.
-After it's fixed, you can commit the .txt file and it'll automagically be turned into html
-viewable on the website.
-
-
-Here are some sample reST textfiles to see what it looks like:
-
-+ ObjectSpace_
-+ ObjectSpaceInterface_
-
-.. _this: http://docutils.sourceforge.net/docs/rst/quickref.html
-.. _ObjectSpace: objspace.html
-.. _ObjectSpaceInterface: objspace.html#object-space-interface
-
-
-.. _`detailed version`:
-
-The long'n detailed version
-===========================
-
-PyPy sources can be browsed on the web at:
-
- http://codespeak.net/svn/pypy/dist
-
-Once you are ready to download and try PyPy out,
-follow these instructions, which assume that you
-are working in a DOS box (Windows) or terminal (MacOS/X or Linux).
-
-1. Download subversion_ if you do not already have it.
-
-2. Change to the directory where you wish to install the source tree,
- and use subversion to download the source::
-
- svn co http://codespeak.net/svn/pypy/dist dist-pypy
-
- This will create a directory named ``dist-pypy``, and will get
- you the PyPy source in ``dist-pypy/pypy`` and documentation
- files in ``dist-pypy/pypy/documentation``.
-
-3. To start interpreting Python with PyPy, use Python 2.3 or greater::
-
- cd dist-pypy/pypy/interpreter
- python py.py
-
- After a few seconds, you should be at the PyPy prompt, which is
- the same as the Python prompt, but with an extra ">".
-
-4. Now you are ready to start running Python code. Some real Python
- modules will not run yet, and others will run too slowly to be
- worth waiting for, but a few are fun to run::
-
- >>>> from test2 import pystone
- >>>> pystone.main(10)
-
- Note that this is a slightly modified version of pystone -- the
- original version does not accept the parameter to main(). The
- parameter is the number of loops to run through the test, and the
- default is 50000, which is far too many to run in a reasonable time
- on the current PyPy implementation.
-
-
-5. To list the PyPy interpreter command line options, type::
-
- cd dist-pypy/pypy/interpreter
- python py.py --help
-
- As an example of using PyPy from the command line, you could type::
-
- python py.py -c "from test2 import pystone; pystone.main(10)"
-
- Alternatively, as with regular Python, you can simply give a
- script name on the command line::
-
- python py.py ../lib/test2/pystone.py
-
- (Note that this will run "forever" -- actually, "just" for many
- hours, with the current implementation of PyPy.)
-
-
-6. The PyPy project uses test-driven-development. Right now, there are
- a couple of different categories of tests which you can run.
- To run all the unit tests::
-
- cd dist-pypy/pypy
- python test_all.py
-
- Alternatively, you may run subtests by going to the correct subdirectory
- and running them individually::
-
- cd dist-pypy/pypy
- python test_all.py module/test/test_builtin.py
-
- ``test_all.py`` is actually just a synonym for `py.test`_ which is
- our external testing tool. If you have installed that then you
- can as well just issue ``py.test DIRECTORY_OR_FILE`` in order
- to perform test runs or simply start it without arguments to
- run all tests below the current directory.
-
- Finally, there are standard regression tests which you can
- run like this::
-
- cd dist-pypy/lib-python-2.3.4/test
- python ../../pypy/test_all.py
-
- or if you have `installed py.test`_ then you simply say::
-
- py.test
-
- from the lib-python-2.3.4/test directory.
-
-.. _`installed py.test`: http://codespeak.net/py/current/doc/getting_started.html
-
-Trying out the translator
-=========================
-
-The translator is a tool based on the PyPy interpreter which can translate
-sufficiently static Python programs into low-level code.
-
-1. Download and install `Dot Graphviz`_.
-
-2. Download and install Pygame_ if you do not already have it.
-
-3. Type::
-
- cd dist-pypy/pypy/translator
- python -i translator.py
-
- Test snippets of translatable code are provided in the file
- ``test/snippet.py``. For example::
-
- >>> t = Translator(test.is_perfect_number)
- >>> t.simplify()
- >>> t.view()
-
-4. We have a type annotator that can completely infer types for functions like
- ``is_perfect_number``::
-
- >>> t.annotate([int])
- >>> t.view()
-
- Move the mouse over variable names (in red) to see their inferred types.
-
-5. The graph can be turned into Pyrex code, with types if ``annotate()`` was
- called::
-
- >>> print t.pyrex()
- >>> f = t.compile()
- >>> f(28)
- 1
-
- Note how the strange-looking Pyrex code is unrelated to the original
- Python source code. This is because the Pyrex code is generated from the
- graph only, without reference to the original source.
-
-
-Where to start reading the sources
-==================================
-
-PyPy is made from parts that are relatively independent from each other.
-You should start looking at the part that attracts you most:
-
-* `dist-pypy/pypy/interpreter`_ contains the basic interpreter: bytecode dispatcher
- in pyopcode.py_, frame and code objects in eval.py_ and pyframe.py_,
- function objects and argument passing in function.py_ and argument.py_,
- the object space interface definition in baseobjspace.py_, modules in
- module.py_ and lazymodule.py_. Core types supporting the interpreter are
- defined in typedef.py_.
-
-* `dist-pypy/pypy/objspace/std`_ contains the `Standard object space`_. The main file
- is objspace.py_. For each type, the files ``xxxtype.py`` and
- ``xxxobject.py`` contain respectively the definition of the type and its
- (default) implementation.
-
-* `dist-pypy/pypy/objspace`_ contains a few other object spaces: the thunk_
- one, the trace_ one, the flow_ one. The latter is a relatively short piece
- of code that builds the control flow graphs when the interpreter runs in it.
-
-* `dist-pypy/pypy/translator`_ contains the code analysis and generation stuff.
- Start reading from translator.py_, from which it should be easy to follow
- the pieces of code involved in the various translation phases.
-
-* `dist-pypy/pypy/annotation`_ contains the data model for the type annotation that
- can be inferred about a graph. The graph "walker" that uses this is in
- `dist-pypy/pypy/translator/annrpython.py`_.
-
-
-To learn more
-=============
-
-* To learn more about PyPy and its development process, head
- read around in the documentation_ and the wiki_, and consider
- subscribing to the `mailing lists`_ (or simply
- read the archives online) or show up irc.freenode.net:6667, channel #pypy.
-
-* To help PyPy become Python-the-next-generation, you may write some
- `unit tests`_ and file some `bug reports`_ (although we are not really
- actively using the issue tracker yet, watch out :-)
-
---------------------------------------------------------------------------------
-
-.. _subversion: http://codespeak.net/pypy/index.cgi?doc/howtosvn.html
-.. _Dot Graphviz: http://www.research.att.com/sw/tools/graphviz/
-.. _Pygame: http://www.pygame.org/
-.. _dist-pypy/pypy/interpreter: http://codespeak.net/svn/pypy/dist/pypy/interpreter/
-.. _pyopcode.py: http://codespeak.net/svn/pypy/dist/pypy/interpreter/pyopcode.py
-.. _eval.py: http://codespeak.net/svn/pypy/dist/pypy/interpreter/eval.py
-.. _pyframe.py: http://codespeak.net/svn/pypy/dist/pypy/interpreter/pyframe.py
-.. _function.py: http://codespeak.net/svn/pypy/dist/pypy/interpreter/function.py
-.. _argument.py: http://codespeak.net/svn/pypy/dist/pypy/interpreter/argument.py
-.. _baseobjspace.py: http://codespeak.net/svn/pypy/dist/pypy/interpreter/baseobjspace.py
-.. _module.py: http://codespeak.net/svn/pypy/dist/pypy/interpreter/module.py
-.. _lazymodule.py: http://codespeak.net/svn/pypy/dist/pypy/interpreter/lazymodule.py
-.. _typedef.py: http://codespeak.net/svn/pypy/dist/pypy/interpreter/typedef.py
-.. _dist-pypy/pypy/objspace/std: http://codespeak.net/svn/pypy/dist/pypy/objspace/std/
-.. _Standard object space: http://codespeak.net/pypy/index.cgi?doc/stdobjspace.html
-.. _objspace.py: http://codespeak.net/svn/pypy/dist/pypy/objspace/std/objspace.py
-.. _dist-pypy/pypy/objspace: http://codespeak.net/svn/pypy/dist/pypy/objspace/
-.. _thunk: http://codespeak.net/svn/pypy/dist/pypy/objspace/thunk.py
-.. _trace: http://codespeak.net/svn/pypy/dist/pypy/objspace/trace.py
-.. _flow: http://codespeak.net/svn/pypy/dist/pypy/objspace/flow/
-.. _dist-pypy/pypy/translator: http://codespeak.net/svn/pypy/dist/pypy/translator/
-.. _translator.py: http://codespeak.net/svn/pypy/dist/pypy/translator/translator.py
-.. _dist-pypy/pypy/annotation: http://codespeak.net/svn/pypy/dist/pypy/annotation/
-.. _dist-pypy/pypy/translator/annrpython.py: http://codespeak.net/svn/pypy/dist/pypy/translator/annrpython.py
-.. _mailing lists: http://codespeak.net/pypy/index.cgi?lists
-.. _documentation: http://codespeak.net/pypy/index.cgi?doc
-.. _wiki: http://codespeak.net/moin/pypy/moin.cgi/FrontPage?action=show
-.. _unit tests: http://codespeak.net/pypy/index.cgi?doc/testdesign.html
-.. _bug reports: http://codespeak.net/issues/pypy/
Deleted: /pypy/dist/pypy/documentation/howtosvn.txt
==============================================================================
--- /pypy/dist/pypy/documentation/howtosvn.txt Sun Apr 17 21:51:38 2005
+++ (empty file)
@@ -1,171 +0,0 @@
-=================
-subversion
-=================
-
-The PyPy codebase, documentation and web pages are controlled by subversion.
-If you already know how to use it here is the URL you need to interact
-with subversion:
-
-``http://codespeak.net/svn/pypy/dist``
-
-If you don't know what to do then Jens-Uwe Mager has prepared some
-installation files which should help you to install subversion on
-your computer.
-
-+ Download Unix source tarball or prepackaged versions_ for MacOS, Windows, FreeBSD and Linux
-
-+ Additional information for Windows users:
-
- * See Microsoft website_ if you have .DLL issues.
-
- * Windows Installer file for Tortoise SVN (like Tortoise CVS) GUI_
- (Pick the UNICODE version for Windows 2000 and XP and
- see Win_ 2000, NT if you have problems loading it.)
-
-+ Local copy of MacOS_ X binary tar ball
- (This requires at least OS X 10.3)
-
-+ Debian instructions below...
-
-btw, HowToInstallServer_ sketches how to install a subversion server on Linux (not as easy as the client install). You don't need to install server side files to get your client going.
-
-Getting started
------------------
-
-If you're just getting started with subversion, here's a simple how-to.
-For complete information, you can go read the subversion guide_.
-
-**Download and install the appropriate installation file of subversion above.**
-
-For linux:
-
-download the tarball. unzip and untar it. Then type *./configure*. Then, as root, *make* followed by *make install*. Voilà ... a subversion client.
-
-For Debian users::
-
- $ apt-get install subversion-tools
-
-People using Debian *stable* first need to add the following line to ``/etc/apt/sources.list`` (thanks backports_!)::
-
- deb http://fs.cs.fhm.edu/mirror/backports.org/debian stable subversion
-
-Note that you can always go look at the files online_ with your browser, located at: http://codespeak.net/svn/pypy/dist
-But, you'll want to check out your own local copies to work on.
-
-Check out and Check in
-----------------------------
-
-There are currently two directories you'll want to check out: /src and /doc
-In order to get the sourcecode and docs downloaded onto your drive, open a shell or commandline and type::
-
- $ svn co http://codespeak.net/svn/pypy/dist
- $ svn co http://codespeak.net/svn/pypy/extradoc
-
-If you are behind a dump proxy this may or may not work; see below.
-
-Once you've got the files checked out to your own system, you can use your favorite text editor to change to files. Be sure to read the coding-style_ and other documentation files before doing a lot of work on the source code. Before doing any work, make sure you're using the most recent update with::
-
- $ svn up
-
-this will update whichever subdirectory you're in (doc or src).
-
-When you're ready to **check in** a file,
-
-cd to your local checked out sourcecode directory, and if necessary, copy the file over from wherever you worked on it::
-
- $ cp ~/mydir/filename.ext filename.ext
-
-If you're adding a brand-new file::
-
- $ svn add filename.ext
-
-Then, to **commit** it::
-
- $ svn ci -m "your comments about what changes your committing"
- $ your password: (this may not be necessary)
-
-You'll see something like the following::
-
- Adding goals/stringcomp.py
- Transmitting file data .
- Committed revision 578.
-
-or::
-
- Sending coding-style.txt
- Transmitting file data .
- Committed revision 631.
-
-Check online on the check-in archives_ and you'll see your revision. Feel free to add a documentation file on any major changes you've made!
-
-Some other useful subversion tricks:
---------------------------------------
-
-**Be sure to remember ``svn`` in the commandline in the following commands.**
-
-``$ svn mv filename.ext``
- to move or rename a file
-
-``$ svn rm filename.ext``
- to remove (delete) a file
-
-``$ svn status``
- will let you know what changes you've made compared to the current repository version
-
-``$ svn revert filename.ext``
- will fix problems if you deleted or moved a file without telling svn.
-
-``$ svn cleanup``
- last resort to fix it if you've got a totally messed up local copy.
- Use this if you see error messages about ``locked`` files that you can't fix otherwise.
-
-Circumventing proxies
-----------------------------
-
-Some proxies don't let extended HTTP commands through. If you have an
-error complaining about a bad request, you can ask subversion to use the
-alternate port 8080 to connect to codespeak.net by adding the following
-lines in a file ``~/.subversion/servers`` (on Unix) or
-``%APPDATA%\Subversion\servers`` (on Windows)::
-
- [groups]
- codespeak = codespeak.net
-
- [codespeak]
- http-proxy-host = codespeak.net
- http-proxy-port = 8080
-
-How to Avoid Line-ending Hell
------------------------------
-
-We will assume that whenever you create a .txt or a .py file, you would
-like other people to be able to read it with the line endings their
-OS prefers, even if that is different from the one your OS likes. This
-could occasionally be wrong -- say when you are specifically testing
-that code you are writing handles line endings properly -- but this is
-what you want by default. Binary files, on the other hand, should be
-stored exactly as is. This has to be set on every client. Here is how:
-
-In your home directory edit .subversion/config and comment in ::
-
- enable-auto-props = yes
-
- *.txt = svn:eol-style=native
-
-and add a line for .py files.
-
---------------------------------------------------------------------------------
-
-
-.. _website: http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B259403
-.. _GUI: http://tortoisesvn.tigris.org/servlets/ProjectDocumentList?folderID=616
-.. _MacOS: http://codespeak.net/~jum/svn-1.1.3-darwin-ppc.tar.gz
-.. _versions: http://subversion.tigris.org/project_packages.html
-.. _Win: http://www.microsoft.com/downloads/details.aspx?displaylang=en&FamilyID=4B6140F9-2D36-4977-8FA1-6F8A0F5DCA8F
-
-.. _guide: http://svnbook.red-bean.com/book.html#svn-ch-1
-.. _archives: http://codespeak.net/pipermail/pypy-svn/
-.. _online: http://codespeak.net/svn/pypy/dist/
-.. _coding-style: coding-style.html
-.. _HowToInstallServer: http://codespeak.net/moin/pypy/moin.cgi/HowToInstallServer
-.. _backports: http://www.backports.org
Deleted: /pypy/dist/pypy/documentation/optionaltool.txt
==============================================================================
--- /pypy/dist/pypy/documentation/optionaltool.txt Sun Apr 17 21:51:38 2005
+++ (empty file)
@@ -1,33 +0,0 @@
-Optional Tools for running (and hacking) PyPy
-=============================================
-
-In addition to the latest version of svn and Python, we use some optional
-tools to install for working on pypy. They are not required to run all the
-tests or to get an interactive PyPy prompt but they help to understand and
-debug PyPy.
-
-Recommended tools:
-------------------
-
-* graphviz::
-
- (used for visualizing the control-flow)
- http://www.research.att.com/sw/tools/graphviz/download.html_
-
-* pygame::
-
- (to visualize control flow and annotation analysis of python programs)
- http://www.pygame.org/download.shtml_
-
- - on MAC OSX, TRY THIS::
- Alex will reconstruct the process for us
-
-Optional tools:
----------------
-
-* CLISP::
-
- Optional (if you want to work on generating lisp code from pypy)
- http://clisp.cons.org/_
-
-
Modified: pypy/dist/pypy/documentation/redirections
==============================================================================
--- pypy/dist/pypy/documentation/redirections (original)
+++ pypy/dist/pypy/documentation/redirections Sun Apr 17 21:51:38 2005
@@ -9,5 +9,10 @@
'wrapping.html' : 'objspace.html#wrapping-rules',
'abstractobjspace.html' : 'theory.html#abstract-interpretation',
'multimethod.html' : 'theory.html#multimethods',
+
+ 'howtopypy.html' : 'getting_started.html#howtopypy',
+ 'howtosvn.html' : 'getting_started.html#howtosvn',
+ 'checking_ReST.html' : 'coding-style.html#pypy-documentation',
+ 'optionaltools.html' : 'coding-style.html#optionaltool',
}
More information about the Pypy-commit
mailing list