psj.policy Installation
***********************

How to install psj.policy inside another package
================================================

To install psj.policy into the global Python environment (or a workingenv),
using a traditional Zope 2 instance, you can do this:

 * When you're reading this you have probably already run 
   ``easy_install psj.policy``. Find out how to install setuptools
   (and EasyInstall) here:
   http://peak.telecommunity.com/DevCenter/EasyInstall

 * If you are using Zope 2.9 (not 2.10), get `pythonproducts`_ and install it 
   via::

       python setup.py install --home /path/to/instance

   into your Zope instance.

 * Create a file called ``psj.policy-configure.zcml`` in the
   ``/path/to/instance/etc/package-includes`` directory.  The file
   should only contain this::

       <include package="psj.policy" />

.. _pythonproducts: http://plone.org/products/pythonproducts


Alternatively, if you are using zc.buildout and the plone.recipe.zope2instance
recipe to manage your project, you can do this:

 * Add ``psj.policy`` to the list of eggs to install, e.g.:
 
    [buildout]
    ...
    eggs =
        ...
        psj.policy
        
  * Tell the plone.recipe.zope2instance recipe to install a ZCML slug:
  
    [instance]
    recipe = plone.recipe.zope2instance
    ...
    zcml =
        psj.policy
        
  * Re-run buildout, e.g. with:
  
    $ ./bin/buildout
        
You can skip the ZCML slug if you are going to explicitly include the package
from another package's configure.zcml file.

Note, that the real installation is quite cumbersome, because it is
based on the collaboration with OpenOffice.org. See below to see, how
you can install psj.policy in detail.


Installing psj.policy via ``buildout``
======================================

We describe an installation on a freshly installed Ubuntu
system. Windows(TM) systems are not supported by time of writing
this.

1) Install the base system.

  We are using Ubuntu 6.06 server with LTS (Long time support)
  here. This means less stuff on your machine. The whole system
  described below will need less than 2.5 GB disk space.

  Make sure you choose `English (US)` as base system. Otherwise you
  will have to tweak the tests lateron. This is caused by OOos
  'intelligent' locale detection, which produces different documents
  depending on your system locale. The tests here rely on the US
  locale.

  Afterwards setup ``/etc/apt/sources.list`` so, that universe and
  multiverse repositories are included.

  Then, as superuser, run::

     # apt-get update

  to fetch the list of the newly added repositories.

  During base install we created a user `zope`.

2) Install additional packages:

  We need Python2.4. On our system this is the default version.  So we
  only have to do::

     # apt-get install python2.4-dev

  to get the headers for building Zope. More current distributions
  often come with Python2.5 as default and do not offer any Python2.4
  packages any more. In this case you have to grab the sources from
  the net and install Python2.4 by yourself.

  After Python is installed, you should be able to type::

     $ python2.4

  without an error message.

  Then, as superuser, do::

     # apt-get install subversion rpm unzip gcc libc6-dev \
                       libxslt1.1 libxslt1-dev xsltproc \
                       libsm6 sun-java5-bin \
                       libjpeg62 libjpeg62-dev libfreetype6 \
                       libfreetype6-dev tidy \
                       xvfb python2.4-profiler

  These are the generally needed packages for building and running
  ``psj.policy``. Some may be already installed on your
  system. Concerning the Java package (above Sun Java 1.5 is
  installed) you might get along with a different one.

  The tidy package is needed for postprocessing of HTML docs.

  The libsm6 and xvfb packages are needed for the X-server
  requirements of OOo. You don't have to run a X-server with this
  installation, not even a framebuffer server, but some libs are
  nonetheless needed by OOo to start. The xvfb package includes all
  this packages, so it's easier to include it.

  If you already have a running X-server on your system, then you
  don't have to install libsm6 nor xvfb.

  The profiler is needed only, if you want to run the tests, which is
  warmly recommended.

  We also install:: 

     # apt-get install openssh-server

  to be able access the machine remotely.


3) Fetch, build and install ``psj.policy``

  Now it's time to get the real code. As a normal user do::

     $ svn co https://svn.gnufix.de/repos/psj.policy/trunk \
              psj.policy

  This should populate your directory with a new subdir
  ``psj.policy``. Now change to it and run the bootstrapper::

     $ cd psj.policy
     $ python2.4 bootstrap/bootstrap.py

  This will create the ``buildout`` script and some subdirs. Run the
  buildout script::

     $ ./bin/buildout

  It will take a long time, because it has to fetch many, many
  packages and also a complete openoffice package of about 130 MB.

  To make the freshly created uno package available, you have to
  register the libs in the ``parts/openoffice/program``
  directory. This can be done as superuser::

     # ldconfig /home/zope/psj.policy/parts/openoffice/program

  or whatever the path on your system looks like.

  When you're done, the following should work without error::

     $ ./bin/zopepy
     
     >>> import uno

  What will *not* work, is the following::

     $ ./bin/zopepy

     >>> from lxml import etree

  This is, because OOo comes with (rather old) replacements for the
  XSLT and XML2 libs, which are normally already installed (in newer
  versions) on a recent Linux system. Therefore, we **remove** those
  OOo libs:: 

     $ rm parts/openoffice/program/libxslt.so*
     $ rm parts/openoffice/program/libxml2.so*

  Afterwards, both examples mentioned above should work.


4) Start the OOo server

  Now we should be able to start the OOo server::

     $ ./bin/oooctl start


5) Test the code

  Run::

     $ ./bin/instance test -s psj.policy

