Log message for revision 96333:
ReSTify the installation docs, and note use of buildout vs. CMMI.
Changed:
U Zope/trunk/doc/INSTALL.txt
-=-
Modified: Zope/trunk/doc/INSTALL.txt
===================================================================
--- Zope/trunk/doc/INSTALL.txt 2009-02-09 19:59:39 UTC (rev 96332)
+++ Zope/trunk/doc/INSTALL.txt 2009-02-09 20:19:37 UTC (rev 96333)
@@ -1,206 +1,194 @@
+========================================
Building and installing Zope from source
-----------------------------------------
+========================================
- Welcome to Zope! This document describes building and installing
- Zope on UNIX and Linux.
+Welcome to Zope! This document describes building and installing
+Zope on UNIX and Linux.
- See WINDOWS.txt for information about Windows. See the PLATFORMS
- directory for notes about various other platforms.
+See ``doc/WINDOWS.txt`` for information about Windows. See the
+``doc/PLATFORMS`` directory for notes about various other platforms.
-System requirements when building from source
- * bash or another Bourne shell variant
+Prerequisites
+-------------
- * Python 2.4.2 or later installed somewhere in the system PATH
- (Python 2.5 is not supported)
+System requirements when building from source
- * GNU make
+- A supported version of Python, including the development support if
+ installed from system-level packages. Supported versions include::
- * A C compiler (gcc recommended)
+ o 2.4.x, (x >= 4)
-Recommendations
+ o 2.5.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``.
- - You are recommended to build and install Zope as a non-root user.
+- A C compiler capable of building extension modules for your Python
+ (gcc recommended).
+
Building Zope
+-------------
- To build Zope, run the conventional UNIX build sequence from within
- the Zope source tree::
+Zope is built using the ``zc.buildout`` library, which needs to be
+"boostrapped" with your Python version. E.g.::
- ./configure --prefix=/where/to/install/zope
- make
+ $ cd /path/to/zope
+ $ /path/to/your/python bootstrap/bootstrap.py
- If you do not specify a '--prefix' option, during a later step, Zope
- will be installed into a default location.
+The boostrap script creates a ``buildout`` script in ``bin``; run this
+script to finish building Zope::
- If the configure script cannot find a suitable Python interpreter
- for use with Zope, it will complain with an informative error
- message. If this happens, you may use the '--with-python'
- command-line option to 'configure' to specify which Python
- interpreter to use. Run './configure --help' to see other
- command-line options available via the configure script.
+ $ bin/buildout
- Optional: Building and Installing Zope 'In-Place' (SVN checkouts only)
- Older versions of Zope were typically run directly from the
- 'source' directory itself. This is useful for development
- purposes. You can regain that behavior by performing the
- following sequence of commands within a Zope source directory:
+Creating a Zope Instance
+------------------------
- ./configure
- make instance
+Once you've performed the install step, to begin actually using
+Zope, you will need to create an "instance home", which is a
+directory that contains configuration and data for a Zope server
+process. The instance home is created using the ``mkzopeinstance``
+script::
- This command also creates an administrative user with the
- specified username and password.
+ $ /bin/mkzopeinstance
- WARNING: "make instance" doesn't work on FreeBSD 5.0 and
- presumably other platforms. You should either use GNU make
- (gmake instance), or use "make install" instead.
+You will be asked to provide a user name and password for an
+administrator's account during ``mkzopeinstance``. To see the available
+ommand-line options, run the script with the ``--help`` option::
- Making an "In-Place" instance builds the binary files and creates
- the files necessary for a Zope instance to be run directly
- within the build directory (e.g. 'in-place'). You may start
- Zope by running::
+ $ bin/mkzopeinstance --help
- ./bin/zopectl start
- See ./log/event.log for any output which may happen during
- start of Zope. If anything goes wrong you will see there.
+Starting Zope as a Daemon
+-------------------------
- If you use
+Once an instance home has been created, the Zope server can now be
+started using this command::
- ./bin/zopectl fg
+ $ /path/to/zope/instance/bin/zopectl start
- instead, the output is generated to the screen. In this case
- Zope does not detach from terminal.
+During start, zope emits log messages into ./log/event.log
+You can examine it with the usual tools (cat, more, tail)
+and see if there are any errors preventing zope from starting.
- Optional: Building Zope Using The "Clean-Source-Tree" Method
- You can run the 'configure' command from outside of the Zope
- source tree. If you do so, the makefile will be written to your
- current directory. The files generated by the build process (via
- 'make') will be written to the directory from which you run
- 'configure'. You can then use 'make install' to install these
- files to their canonical locations. This feature is to support
- source locations which are not writable.
+Running Zope in the Foreground
+------------------------------
-Installing Zope
+By default, ``zopectl start`` will start a background process (a
+"daemon) that manages Zope. ``zopectl stop`` will stop the background
+process. To run Zope without detaching from the console, use the ``fg``
+command (short for ``foreground``)::
- To install Zope to the place you've specified via the '--prefix'
- option (or to the default location if you didn't specify a prefix),
- type::
+ $ /path/to/zope/instance/bin/zopectl fg
- make install
+In this mode, Zope emits its log messages to the console, and does not
+detach from terminal.
-Creating a Zope Instance Home
- Once you've performed the install step, to begin actually using
- Zope, you will need to create an "instance home", which is a
- directory that contains configuration and data for a Zope server
- process. The instance home is created using the 'mkzopeinstance.py'
- script::
+Configuring Zope
+----------------
- /where/to/install/zope/bin/mkzopeinstance.py
+Your Zope instance is configured through a file, either found by
+default::
- You will be asked to provide a user name and password for an
- administrator's account during 'mkzopeinstance'. Command-line
- options to 'mkzopeinstance' are available, and can be investigated
- by running 'mkzopeinstance.py --help'.
+ $ /path/to/zope/instance/bin/zopectl show
+ ...
+ Config file: /path/to/zope/instance/etc/zope.conf
-Starting Zope
+or passed explicitly on the commandline::
- Once an instance home has been created, the Zope server can now be
- started using this command:
+ $ /path/to/zope/instance/bin/zopectl -c /tmp/other.conf show
+ ...
+ Config file: /tmp/other.conf
- /location/of/zope/instance/bin/zopectl start
+When starting Zope, if you see errors indicating that an address is in
+use, then you will have to supply arguments to runzope to change the ports
+used for HTTP or FTP. The default HTTP and FTP ports used by Zope are
+8080 and 8021 respectively. You can change the ports used by
+editing ./etc/zope.conf apropriately.
- During start, zope emits log messages into ./log/event.log
- You can examine it with the usual tools (cat, more, tail)
- and see if there are any errors preventing zope from starting.
+The section in the configuration file looks like this::
- /location/of/zope/instance/bin/zopectl fg
-
- can be used to instead output these messages to the console. This
- way zope does not detach from terminal.
-
- If you get errors indicating that addresses are in use, then you
- will have to supply arguments to runzope to change the ports used
- for HTTP or FTP. The default HTTP and FTP ports used by Zope are
- 8080 and 8021 respectively. You can change the ports used by
- editing ./etc/zope.conf apropriately.
-
- The section usually is like this:
-
<http-server>
# valid keys are "address" and "force-connection-close"
address 8080
# force-connection-close on
</http-server>
- address can just be a port number as shown, but also a host:port
- pair to bind to a specific interface only.
+The address can just be a port number as shown, or a host:port
+pair to bind only to a specific interface.
- zopectl can be linked as rc-script in the usual start directories
- on linux or other system V unix variants.
- You can use zopectl interactively as a command shell by just
- calling it w/o any arguments. Try help there and help <command>
- to find out about additionally commands of zopectl. These commands
- work also on command line.
+Integrating with System Startup
+-------------------------------
- By default, 'zopectl start' will start a background process that
- manages Zope and 'zopectl stop' will stop the background process.
+zopectl can be linked as rc-script in the usual start directories
+on linux or other System V unix variants.
+You can use ``zopectl`` interactively as a command shell by just
+calling it without any arguments. Try ``help`` there and ``help <command>``
+to find out about additionally commands of zopectl. These commands
+also work at the command line.
+
+
Logging In To Zope
+------------------
- Once you've started Zope, you can then connect to the Zope webserver
- by directing your browser to::
+Once you've started Zope, you can then connect to the Zope webserver
+by directing your browser to::
- http://yourhost:8080/manage
+ http://yourhost:8080/manage
- .. where 'yourhost' is the DNS name or IP address of the machine
- running Zope. If you changed the HTTP port as described, use a port
- number of 8080 + the port-base value.
+.. where 'yourhost' is the DNS name or IP address of the machine
+running Zope. If you changed the HTTP port as described, use the port
+you configured.
- You will be prompted for a user name and password. Use the user name
- and password you provided in response to the prompts issued during
- the "make instance" process.
+You will be prompted for a user name and password. Use the user name
+and password you provided in response to the prompts issued during
+the "make instance" process.
- Now you're off and running! You should be looking at the Zope
- management screen which is divided into two frames. On the left you
- can navigate between Zope objects and on the right you can edit them
- by selecting different management functions with the tabs at the top
- of the frame.
+Now you're off and running! You should be looking at the Zope
+management screen which is divided into two frames. On the left you
+can navigate between Zope objects and on the right you can edit them
+by selecting different management functions with the tabs at the top
+of the frame.
- If you haven't used Zope before, you should head to the Zope web
- site and read some documentation. The Zope Book is a good place to
- start. You can access the Zope Book at:
+If you haven't used Zope before, you should head to the Zope web
+site and read some documentation. The Zope Book is a good place to
+start. You can access the Zope Book at:
- http://www.zope.org/Documentation/Books/ZopeBook
+http://www.zope.org/Documentation/Books/ZopeBook
Integrating Zope With An Existing Webserver
+--------------------------------------------
- Zope doesn't require any existing webserver to run, but you can
- integrate it with other webservers as necessary. See the
- WEBSERVER.txt file for more information about configuring Zope with
- an existing web server. There is also information about integrating
- Zope with existing webservers on the Zope.org website.
+Zope doesn't require any existing webserver to run, but you can
+integrate it with other webservers as necessary. See the
+``doc/WEBSERVER.txt`` file for more information about configuring Zope
+with an existing web server. There is also information about integrating
+Zope with existing webservers on the Zope.org website.
Troubleshooting
+---------------
- - This version of Zope requires Python 2.4.1 or better.
+- This version of Zope requires Python 2.4.4 or better, including
+ 2.5.x. It may run with Python 2.6.x, although this configuration
+ is not supported in this version of Zope. It will *not* run with
+ Python 3.x.
- - The Python you run Zope with *must* have threads compiled in,
- which is the case for a vanilla build. Warning: Zope will not run
- with a Python version that uses libpth. You *must* use
- libpthread.
+- The Python you run Zope with *must* have threads compiled in,
+ which is the case for a vanilla build. 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 (or python-dev) package installed too. If
- you built Python from source all the configuration information
- should already be available.
+- 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 (or python-dev) package installed too. If
+ you built Python from source all the configuration information
+ should already be available.
- - See CHANGES.txt for important notes on this version of Zope.
-
-
+- See ``doc/CHANGES.txt`` for important notes on this version of Zope.
_______________________________________________
Zope-Checkins maillist - Zope-Checkins@zope.org
http://mail.zope.org/mailman/listinfo/zope-checkins
