py subversion directory structure
=================================

The directory release layout of the repository is
going to follow this scheme:: 

    svn/py/dist             # latest stable code base (may or may not be a release) 
    svn/py/release/X.Y.Z    # tagged releases  
    svn/py/branch/X.Y       # contains release branch development
    svn/py/trunk            # head development 

Scenario "no svn and just let me play, please" 
==============================================

If you don't have a subversion client you can download 
specific versions by going to 

    http://codespeak.net/download/py 

and pick a suitable archive file. You need to 
unpack it and may want to run `setup.py` to install 
it in a system-wide manner. 

Installation Scenario "svn + stay close to released versions" 
------------------------------------------------------------- 

If you have a subversion client (you can easily install
one, look at PyPy's `svn help document`_) it is recommended that you choose the following 
method to install, irrespective if you want to install 
things via distutils.   Start by issueing the following 
shell command (or a graphical equivalent):: 

    svn co http://codespeak.net/svn/py/dist py-dist

Now we want to make sure that the `py-dist/py/bin` directory 
gets on your shell search path in order to have "py.test" 
directly available.  You basically have two choices: 

1) include in your local shell environment startup the equivalent 
   of ``eval `python .../py-dist/py/env.py```.  
   XXX describe this in more detail (rip out from `getting started`_). 

2) go to the `py-dist` directory and run `python setup.py install`. 

.. _`getting started`: getting-started.html 
.. _`svn help document`: http://codespeak.net/pypy/index.cgi?doc/getting_started.html#subversion

If you later want to upgrade your version of the py lib
to the newest release you simply issue:: 

    svn up

or to switch to the development trunk via:: 

    svn switch http://codespeak.net/svn/py/trunk 

or to a specific version via:: 

    svn switch http://codespeak.net/svn/py/tag/py-X.Y.Z 

or to a specific release branch:: 

    svn switch http://codespeak.net/svn/py/branch/py-X.Y 

If you choose the option No. 2) above you have to repeat 
the distutils install after each checkout/switch. 

.. _`svn-external scenario`: 


Installation Scenario "svn + include py lib as an external" 
===========================================================

OK, so you want to have the py lib supporting your 
application and are using subversion?  Great because
things are quite easy and flexible for this scenario. 

Tying the py lib into your subversion controled project
-------------------------------------------------------

On the `DIRECTORY` which contains your root package issue:: 

    svn pe 'svn:externals' DIRECTORY 

and add the following line to your (possibly empty) list 
of svn-externals:: 

    py http://codespeak.net/svn/py/dist 

This will make your projcet follow the most recent 
release of the py lib. (please substitute `dist` for `trunk`
if you want to follow py lib development, this will let 
you catch interaction problems early on ...). 
If you now issue an `svn up` on your `DIRECTORY` you 
will retrieve the external into your application. 

If you want to follow a minor release branch seamlessly
then use the following line:: 

    py http://codespeak.net/svn/py/branch/py-X.Y 

where `X.Y` indicate the branch you want to follow. 

If you want to use a very fixed version of the py lib
you can tie to a specific release::  

    py http://codespeak.net/svn/py/tag/py-X.Y.Z 

Integrating the py lib into your distribution
----------------------------------------------

XXX