Python Spread Module 1.0
------------------------

Copyright (c) 2001-2002 Python Software Foundation.  All rights reserved.

This code is released under the standard PSF license.
See the file LICENSE.

This package contains a simple Python wrapper module for the Spread
toolkit.

Spread (www.spread.org) is a group communications package.  You'll
need to download and install it separately.  The Python API has been
built and tested against Spread 3.16, including a patch available from
the Web page.  More recently (Dec 19, 2001) also against Spread
3.16.1, without extra patches.

Minimal user documentation for the Python programmer is in doc.txt.

Build instructions for Spread are way down in the Spread Readme.txt
file; search for "INSTALL".  On Linux, it's as simple as:

    cp LINUX_makefile Makefile
    patch Makefile <(this README file)
    make

The Spread makefiles do an odd install, putting things in
/var/tmp/testinstall by default.  It does *not* install header files,
the patch below fixes that.  The only header files you need are sp.h,
sp_events.h, and sp_func.h.  You can force the Makefile to install in
/usr/local by saying

    make BASEDIR=/usr/local install

and that's what I recommend.  As long as you apply the patch below,
this will also take care of the header files.

The distutils setup.py script needs to be told where the spread code
is installed.  I still don't know the preferred way to do that, so
you'll need to edit the SPREAD_DIR constant in the right branch.  The
setup script assumes you've installed the header files.  Assuming you
followed the recipe above, including the "make install" part, the
SPREAD_DIR constant is already set up right and you can do this to
build the Python wrapper for Spread:

    python setup.py build

The man pages installed by Spread (and available at www.spread.org)
are fairly helpful, although obscure at times.  There is no
documentation for the Python wrapper yet.

To run the testspread.py unit tests, you'll need to manually set your
Python path to the build directory.  Again, I don't know if distutils
provides a good way to do this.  (I wish it did.)  The following works
for me:

    PYTHONPATH=build/lib.linux-i686-2.2
    export PYTHONPATH
    python testspread.py

----------------------------------------------------------------------
Here's the patch for the Makefile to install the header files:

*** LINUX_makefile	Wed Aug 22 17:33:39 2001
--- Makefile	Wed Dec 19 09:42:28 2001
***************
*** 50,56 ****
  run_spread : run_spread.o
  	$(CC) -o run_spread run_spread.o
  
! install: install_bin install_lib install_man
  
  install_bin:
  	$(INSTALL) -m 0755 -d ${BASEDIR}/bin
--- 50,56 ----
  run_spread : run_spread.o
  	$(CC) -o run_spread run_spread.o
  
! install: install_bin install_lib install_man install_include
  
  install_bin:
  	$(INSTALL) -m 0755 -d ${BASEDIR}/bin
***************
*** 76,81 ****
--- 76,86 ----
  			$(INSTALL) -m 644 $$CMD $$MAN_DIR; \
                  done; \
          done
+ 
+ install_include:
+ 	$(INSTALL) -m 0644 sp.h $(BASEDIR)/include
+ 	$(INSTALL) -m 0644 sp_events.h $(BASEDIR)/include
+ 	$(INSTALL) -m 0644 sp_func.h $(BASEDIR)/include
  
  s : s.o alarm.o data_link.o events.o memory.o
  	$(CC) -o s s.o alarm.o data_link.o events.o memory.o


Windows
=======
The Spread 3.16.1 spread.exe distributed in spread.org's binary distro
doesn't work at all on Win98 (attempts to connect crash the spread daemon
every time), and is flaky on Win2K (*sometimes* attempts to connect
crash the daemon there).

This is a mystery we don't want to take time to solve.  When I build
Spread from source under MSVC 6, the debug mode spread.exe works fine
on Win98; the release mode spread.exe does not.  I haven't tried either
on Win2K.  Since the Spread source distro doesn't contain any Windows
build material, I made my own MSCV project by looking at the Linux makefile.

spreadit.dsw is the MSVC 6 workspace.  The only project therein is spread.dsp,
which only builds spread.exe (the other Spread components distributed by
spread.org seem to work on Windows).

Copy those two files into the root of a Spread source distro, open
spreadit.dsw, select the Debug configuration, and build.  There shouldn't
be any errors, but you'll get pages of warning msgs.  Debug\spread.exe
is the result.  Move it to wherever you like (and do the usual spread.conf
dance, etc).

Note:  the .dsp and .dsw files probably need to have \r\n line endings.
If you get mysterious errors when opening spreadit.dsw, check that first.

Postscript: While working more with Spread on Windows, we discovered
more problems.  In particular, because the code is not at all
Windows-aware, socket file descriptors are never closed, causing file
descriptors to leak until both the daemon and the client library fail.
While we have fixed some of these problems in our copy, we do not have
the time to maintain these changes.  We will make them available to
the Spread developers for incorporation in the Spread sources though.
