Log message for revision 109858:
Merge 'tseaver-clarify_install_docs' branch.
Changed:
A Zope/branches/2.12/doc/INSTALL-buildout.rst
U Zope/branches/2.12/doc/INSTALL.rst
U Zope/branches/2.12/doc/index.rst
A Zope/branches/2.12/doc/operation.rst
-=-
Copied: Zope/branches/2.12/doc/INSTALL-buildout.rst (from rev 109567,
Zope/branches/tseaver-clarify_install_docs/doc/INSTALL-buildout.rst)
===
--- Zope/branches/2.12/doc/INSTALL-buildout.rst (rev 0)
+++ Zope/branches/2.12/doc/INSTALL-buildout.rst 2010-03-08 22:54:01 UTC (rev
109858)
@@ -0,0 +1,181 @@
+Installing and Zope with ``zc.buildout``
+
+
+.. highlight:: bash
+
+This document descibes how to get going with Zope using ``zc.buildout``.
+
+
+About ``zc.buildout``
+-
+
+`zc.buildout http://www.buildout.org/`_ is a powerful tool for creating
+repeatable builds of a given software configuration and environment. The
+Zope developers use ``zc.buildout`` to develop Zope itself, as well as
+the underlying packages it uses.
+
+Prerequisites
+-
+
+In order to use Zope, you must have the following pre-requisites
+available:
+
+- A supported version of Python, including the development support if
+ installed from system-level packages. Supported versions include:
+
+ * 2.6.x
+
+- Zope needs the Python ``zlib`` module to be importable. If you are
+ building your own Python from source, please be sure that you have the
+ headers installed which correspond to your system's ``zlib``.
+
+- A C compiler capable of building extension modules for your Python
+ (gcc recommended). This is not necessary for Windows as binary
+ releases of the parts that would need compiling are always made
+ available.
+
+- If you wish to install Zope as a Service on Windows, you will need
+ to have the `pywin32`__ package installed.
+
+ __ https://sourceforge.net/projects/pywin32/
+
+
+Installing standalone Zope using zc.buildout
+
+
+In this configuration, we use ``zc.buildout`` to install the Zope software,
+but then generate server instances outside the buildout environment.
+
+Installing the Zope software
+
+
+Installing the Zope software using ``zc.buildout`` involves the following
+steps:
+
+- Download the Zope 2 source distribution from `PyPI`__
+
+ __ http://pypi.python.org/pypi/Zope2
+
+- Bootstrap the buildout
+
+- Run the buildout
+
+On Linux, this can be done as follows::
+
+ $ wget http://pypi.python.org/packages/source/Z/Zope2/Zope2-Zope
version.tar.gz
+ $ tar xfvz Zope2-Zope version.tar.gz
+ $ cd Zope2-Zope version
+ $ /path/to/your/python bootstrap/bootstrap.py
+ $ bin/buildout
+
+
+Creating a Zope instance
+
+
+Once you've installed Zope, you will need to create an instance
+home. This is a directory that contains configuration and data for a
+Zope server process. The instance home is created using the
+``mkzopeinstance`` script::
+
+ $ bin/mkzopeinstance
+
+You can specify the Python interpreter to use for the instance
+explicitly::
+
+ $ bin/mkzopeinstance --python=$PWD/bin/zopepy
+
+You will be asked to provide a user name and password for an
+administrator's account during ``mkzopeinstance``. To see the available
+command-line options, run the script with the ``--help`` option::
+
+ $ bin/mkzopeinstance --help
+
+.. note::
+ The traditional inplace build is no longer supported. If using
+ ``mkzopeinstance``, always do so outside the buildout environment.
+
+
+Creating a buildout-based Zope instance
+---
+
+Rather than installing Zope separately from your instance, you may wish
+to use ``zc.buildout`` to create a self-contained environment, containing
+both the Zope software and the configuration and data for your server.
+This procedure involves the following steps:
+
+- Create the home directory for the buildout, including
+ ``etc``, ``logs`` and ``var`` subdirectories.
+
+- Fetch the buildout bootstrap script into the environment.
+
+- Create a buildout configuration as follows:
+
+.. topic:: buildout.cfg
+ :class: file
+
+ ::
+
+ [buildout]
+ parts = instance
+ extends = http://download.zope.org/Zope2/index/Zope version/versions.cfg
+
+ [instance]
+ recipe = zc.recipe.egg
+ eggs = Zope2
+ interpreter = py
+ scripts = runzope zopectl
+ initialization =
+ import sys
+ sys.argv[1:1] = ['-C',r'${buildout:directory}/etc/zope.conf']
+
+This is the minimum but all the usual buildout techniques can be
+used.
+
+- Bootstrap the buildout
+
+- Run the buildout
+
+- Create a Zope configuration file. A minimal version would be:
+
+.. topic:: etc/zope.cfg
+ :class: file
+
+ ::
+
+ %define INSTANCE path to your instance directory
+
+ python $INSTANCE/bin/py[.exe on Windows]
+
+ instancehome $INSTANCE
+
+A
