========================================
Building and installing Zope from source
========================================

This document describes building and installing Zope 3 on Unix.  We will
provide Windows instructions in later releases. We will also provide binary
releases for some platforms.

Important notes
===============

ZOPE 3 REQUIRES PYTHON 2.4.4!

Quick Start
===========

The following commands should get you up and running with the development
version of Zope 3 on Unix:

* If you have not yet checked out the Subversion tree, do so::

    $ svn co svn://svn.zope.org/repos/main/Zope3/trunk/ Zope3
    $ cd Zope3
    $ make

* Copy sample_principals.zcml to principals.zcml, and edit the entries in your
  new principals.zcml.  At the very least, change the passwords!

* Run the server::
  
    $ bin/zopectl fg

You should shortly see logging messages indicating Zope 3 is listening on port
8080.  At that point you can connect to Zope 3 by directing your browser to::

    http://localhost:8080/manage

This will access the Zope 3 default management interface.  Note that this
release of Zope 3 requires recent versions of Mozilla or IE.

If you insist on using an older browser (or a text-based browser) you can use
the basic Zope 3 skin by putting '++skin++Basic' after the server part of the
URL::

    http://localhost:8080/++skin++Basic/manage

You will be prompted for a user name and password. Use the user name and
password you entered into your ``principals.zcml`` file.

Now you're off and running!

Resources
=========

If you haven't used Zope 3 before, you should head to the Zope web site and
read some documentation. The Zope 3 Python Programmers Tutorial is a good
place to start.  You can access it on the Zope site at::

    http://dev.zope.org/Zope3/ProgrammerTutorial

You will also find some additional documentation in the 'doc' directory of the
Zope 3 tree, where this file lives.  All other existing Zope 3 documentation
is linked from somewhere in the Zope project Wiki::

    http://wiki.zope.org/Zope3

You may also want to subscribe to the Zope3-dev mailing list::

    http://lists.zope.org/mailman/listinfo/zope3-dev

Have fun!

Random Details
==============

* There are some Python scripts in the top-level directory that will help you
  track changes during the development process.  Specifically, 'setup.py'
  helps you build the extension modules, and 'test.py' will run all of the
  unit tests (see UNITTEST.txt in the doc directory for more information on
  unit tests).

* You should be using Python 2.4.4 or later to run anything related to Zope 3.

* The Python you run Zope with *must* have threads compiled in.  This is
  typically the case for a vanilla build on platforms that support thread, but
  be sure this wasn't disabled if you use a custom build.  (If the Python
  statement "import thread" raises an exception, your Python interpreter does
  not support threads.) Warning: Zope will not run with a Python version that
  uses libpth.  You *must* use libpthread.

* To build Python extensions you need to have Python configuration information
  available. If your Python comes from an RPM you may need the python-devel
  package installed too. If you built Python from source all the configuration
  information should already be there.

* If you just want to use Zope components it's not necessary to build Zope but
  it's a good idea since it will compile Python C extensions for you.

Troubleshooting
===============

* We've seen segfaults when running the test suite.  This was invariably
  caused by having parts of Zope 2 or ZODB 3 (which goes with Zope 2)
  installed in site-packages or elsewhere on Python's module search path
  (sys.path).  So make sure you have no parts of Zope 2 or ZODB 3 on sys.path
  when running Zope 3!
