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

This document describes building and installing Zope3 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.3.4!

Quick Start
-----------

The following commands should get you up and running with the
development version of Zope3 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

* python setup.py build_ext -i

  (On Unix, typing "make" will do the same thing.)

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

* python z3.py

  (On Unix, typing "make run" will do the same thing.)

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

   http://yourhost:8080/manage

where yourhost is the name or address of the machine running Zope 3.

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 Zope3 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 Zope3 tree, where this file lives.  All other
existing Zope3 documentation is linked from somewhere in the Zope
project Wiki::

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

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.3.4 or later to run anything related to
  Zope3.

* The Python you run Zope with *must* have threads compiled in.  This
  is typically the case for a vanilla build on platforms that support
  threads, 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 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!
