                        Installing 4Suite on UNIX
                        =========================
Fourthought, Inc.
This document can be freely translated and distributed. It's released under the LDP License.

                                Abstract
                                --------

4Suite((TM)) is a collection of Python tools for
XML processing and object database management.  An integrated packaging
of components for DOM (in-memory and persistent), XPath, XSLT, RDF,
ODMG object databases, XPointer, XLink.  This document gives step-by step instructions for installing 4Suite on UNIX.  It is rather biased towards Linux.  Please send the author any material more appropriate to other flavors of UNIX for inclusion in later versions.


                      Introduction and conventions
                      ----------------------------

This introduction covers Red Hat 6.2 Linux, but should work for most Linux
distributions and other UNIX variations with some modifications.



All the installation will be to directories under
/usr/local and
/var/local.  Ideally, you should perform
these steps as a non-superuser who has access to these directories.  Some of
the instructions will change the enviroment of the user, so if you use
multiple users for running 4Suite Server you'll want to be careful about
making sure the environment is set up correctly for all relevant users.



Sometimes there will be a great deal of output from an instruction.  If there
is nothing of particular interest in the output, I'll omit it and replace it
with the text "SNIP".



There are many useful third-party resources mentioned in this document.
Those that are necessary for you to access in order to follow instructions
are directly linked from the text.  Others are marked as end notes and the
links are available in the Resources section.


                      Installing the prerequisites
                      ----------------------------


 ** Python ** 


Your system might not have Python, or might only have Python 1.5.2.
Python 2.0 is best for 4Suite, so here are directions for upgrading.
If you are installing Python 2.0 in addition to an older version, you
will have to exercise some care over executable paths, as you shall see.



I recommend downloading the Python source rather than RPM.  Get
Python-2.0.tar.bz2 from


ftp://ftp.sourceforge.net/pub/sourceforge/python/


Untar to a suitable location


[uogbuji@malatesta uogbuji]$ cd /usr/local/src
[uogbuji@malatesta src]$ tar Ixvf Python-2.0.tar.bz2 ; cd Python-2.0
SNIP


You should probably at least browse the Python README, but here's what I did



Configure Python for the build


[uogbuji@malatesta Python-2.0]$ ./configure
SNIP
[uogbuji@malatesta Python-2.0]$ cp Modules/Setup.in Modules/Setup


Next modify the file Modules/Setup to enable library modules useful on a UNIX installation.  First patch the set up file.  Copy the following into uogbuji-pysetup.patch


--- Modules/Setup.in	Mon Oct 16 15:49:33 2000
+++ Modules/Setup	Wed Jan  3 13:13:38 2001
@@ -111,7 +111,7 @@
 # modules are to be built as shared libraries (see above for more
 # detail; also note that *static* reverses this effect):
 
-#*shared*
+*shared*
 
 # GNU readline.  Unlike previous Python incarnations, GNU readline is
 # now incorporated in an optional module, configured in the Setup file
@@ -121,7 +121,7 @@
 # it, depending on your system -- see the GNU readline instructions.
 # It's okay for this to be a shared library, too.
 
-#readline readline.c -lreadline -ltermcap
+readline readline.c -lreadline -ltermcap
 
 
 # Modules that should always be present (non UNIX dependent):
@@ -164,24 +164,24 @@
 
 # The crypt module is now disabled by default because it breaks builds
 # on many systems (where -lcrypt is needed), e.g. Linux (I believe).
-#crypt cryptmodule.c # -lcrypt	# crypt(3); needs -lcrypt on some systems
+crypt cryptmodule.c  -lcrypt	# crypt(3); needs -lcrypt on some systems
 
 
 # Some more UNIX dependent modules -- off by default, since these
 # are not supported by all UNIX systems:
 
-#nis nismodule.c -lnsl	# Sun yellow pages -- not everywhere
-#termios termios.c	# Steen Lumholt's termios module
-#resource resource.c	# Jeremy Hylton's rlimit interface
+nis nismodule.c -lnsl	# Sun yellow pages -- not everywhere
+termios termios.c	# Steen Lumholt's termios module
+resource resource.c	# Jeremy Hylton's rlimit interface
 
 
 # Multimedia modules -- off by default.
 # These don't work for 64-bit platforms!!!
 # These represent audio samples or images as strings:
 
-#audioop audioop.c	# Operations on audio samples
-#imageop imageop.c	# Operations on images
-#rgbimg rgbimgmodule.c	# Read SGI RGB image files (but coded portably)
+audioop audioop.c	# Operations on audio samples
+imageop imageop.c	# Operations on images
+rgbimg rgbimgmodule.c	# Read SGI RGB image files (but coded portably)
 
 
 # The md5 module implements the RSA Data Security, Inc. MD5
@@ -255,7 +255,7 @@
 
 # Linux specific modules -- off by default:
 
-#linuxaudiodev linuxaudiodev.c
+linuxaudiodev linuxaudiodev.c
 
 
 # George Neville-Neil's timing module:
@@ -311,7 +311,7 @@
 # Lance Ellinghaus's modules:
 
 rotor rotormodule.c		# enigma-inspired encryption
-#syslog syslogmodule.c		# syslog daemon interface
+syslog syslogmodule.c		# syslog daemon interface
 
 
 # Curses support, requring the System V version of curses, often
@@ -319,7 +319,7 @@
 # instead of -lcurses; on SunOS 4.1.3, insert -I/usr/5include
 # -L/usr/5lib before -lcurses).
 
-#_curses _cursesmodule.c -lcurses -ltermcap
+_curses _cursesmodule.c -lcurses -ltermcap
 
 
 
@@ -349,7 +349,7 @@
 
 # Anthony Baxter's gdbm module.  GNU dbm(3) will require -lgdbm:
 
-#gdbm gdbmmodule.c -I/usr/local/include -L/usr/local/lib -lgdbm
+gdbm gdbmmodule.c -I/usr/local/include -L/usr/local/lib -lgdbm
 
 
 # Berkeley DB interface.
@@ -408,7 +408,7 @@
 # Andrew Kuchling's zlib module.
 # This require zlib 1.1.3 (or later).
 # See http://www.cdrom.com/pub/infozip/zlib/
-#zlib zlibmodule.c -I$(prefix)/include -L$(exec_prefix)/lib -lz
+zlib zlibmodule.c -I$(prefix)/include -L$(exec_prefix)/lib -lz
 
 # Interface to the Expat XML parser
 #


You might be wondering that I didn't enable the pyexpat module that
comes with Python 2.0.  PyXML 0.6.2, which we'll need and install later
already supplies a pyexpat module so we don't need Python's.



Apply the patch and then build Python


[uogbuji@malatesta Python-2.0]$ patch -lp0 < uogbuji-pysetup.patch
patching file `Modules/Setup'
[uogbuji@malatesta Python-2.0]$ make
SNIP
[uogbuji@malatesta Python-2.0]$ make install
SNIP


"make install" installs to /usr/local/lib/python2.0, with the python
interpreter executable at /usr/local/bin.  Remember this.  It's the key
to not mixing up Python 2.0 and Python 1.5.2.  Red Hat 6.2 has Python
2.0 at /usr/lib/python1.5 with a the exe at /usr/bin



Your system might not have all the needed prerequisites for the Python
build I suggest above.  The termcap
and readlines libraries are
needed.  Note that SuSE 7.0 puts libtermcap (from the termcap-2.0.8-231
RPM into /usr/lib/termcap/ rather than
/usr/lib. So you might have to change
the appropriate line to use
-L/usr/lib/termcap.





IMPORTANT: You will need to have Python 2.0 ahead of Python 1.5 in your
executable path.  There are many ways to do this, but the simplest is
to edit the ~/.bash_profile all users that need 4Suite and 4Suite Server.
Just append the following lines:


PATH=/usr/local/bin:$PATH
export PATH


Then log out from the relevant users and log back in.



Try the following:


[uogbuji@malatesta Python-2.0]$ python
Python 2.0 (#1, Dec 10 2000, 12:22:57) 
[GCC egcs-2.91.66 19990314/Linux (egcs-1.1.2 release)] on linux2
Type "copyright", "credits" or "license" for more information.
>>> 


If you don't get similar output, your environment is incorrect.



NOTE: If you install Python 1.5.2 rather than Python 2.0, you'll also need to install Python Distutils 1.0 or later.  You can find out more and get the package from the Distutils home page.


 ** PyXML ** 

Current 4Suite works with the Python XML-SIG 0.6.5 installation.  This is now a required prerequisite for 4suite.  You can download it from:
  

http://sourceforge.net/project/showfiles.php?group_id=6473
  
For this example, we will assume you downloaded the source package at:
  

http://prdownloads.sourceforge.net/pyxml/PyXML-0.6.5.tar.gz
  
Untar the download to a suitable location such as /usr/local/src

[root@penny src]# tar zxvf /tmp/PyXML-0.6.5.tar.gz
SNIP
  
Execute setup.py

[root@penny src]# cd PyXML-0.6.5/
[root@penny PyXML-0.6.5]# python setup.py -q install
  
Test the installation

[root@penny src]# python -c "from xml.dom.ext.reader import PyExpat"
  
 ** 4Suite ** 


Get 4Suite-0.10.2.tar.gz from


ftp://ftp.fourthought.com/pub/4Suite/

[uogbuji@malatesta uogbuji]$ cd /usr/local/src
[uogbuji@malatesta src]$ tar zxvf 4Suite-0.10.2.tar.gz ; cd 4Suite-0.10.2
SNIP
[uogbuji@malatesta 4Suite-0.10.2]$ python setup.py install
SNIP


And you're done.  It's that simple.



You can always install to a custom directory by using the "--prefix" parameter.  For example, 'python setup.py install --prefix=/opt/mycoolapps/'.  You can also installto your home directory by using the "--home" option.  For instance 'python setup.py install --home=/home/uogbuji/mycoolapps/'.  'python setup.py install --help' will display all options supported by the install command.



Now it's time to test things out.  4XSLT exercises a good deal of 4Suite, so a good test is:


[uogbuji@malatesta 4Suite-0.10.2]$ cd /usr/local/doc/4Suite-0.10.2/4XSLT/test_suite/
[uogbuji@malatesta test_suite]$ python test.py


You may get a few warnings about test files being omitted, but as long as you don't get any error messages or failure reports, All should be well.


                        Installing CVS Snapshots
                        ------------------------

4Suite CVS snapshots are a way to get bug fixes and experimental new features between full releases of the software.  They are generated from Fourthought's internal CVS nightly.  You can also access the 4Suite CVS anonymously as discussed in the next section



Once you have 4Suite all properly set up, installing CVS snapshots is pretty straightforward.



Download the latest snapshot (they are marked by date) from

ftp://ftp.fourthought.com/pub/cvs-snapshots/

Then untar it.  As an example we shall use the CVS snapshot from 20 January, 2001.  Note that untarring it creates an  directory, rather than the  directory created by the 4Suite 0.10.2 release.


[uogbuji@malatesta uogbuji]$ cd /usr/local/src
[uogbuji@malatesta src]$ tar zxvf 2001-01-20-4Suite.tgz ; cd Ft
SNIP


Nevertheless, you run setup the same way



Now comes the only tricky part.  The 4Suite installer is set up to automatically install PyXML for you.  I recommend that you get the latest CVS snapshot of PyXML for this purpose, since the 4Suite CVS version might rely on fixes and updates in the PyXML CVS version.  Note that whenever you get a prompt for a password, simply press "return".


[uogbuji@malatesta Ft]$ cvs -d:pserver:anonymous@cvs.pyxml.sourceforge.net:/cvsroot/pyxml login
[uogbuji@malatesta Ft]$ cvs -d:pserver:anonymous@cvs.pyxml.sourceforge.net:/cvsroot/pyxml export -d PyXML xml
SNIP


This will grab the latest version of PyXML.  Now you are ready to install 4Suite (and PyXML)


[uogbuji@malatesta Ft]$ python setup.py install
SNIP


And you should be updated.  Run the 4XSLT test suite again to check that all is well.


                          4Suite Anonymous CVS
                          --------------------

If daily CVS snapshots aren't close enough to the bleeding edge for you, you can use anonymous CVS (pserver).



Once you have Python all set up, you can use CVS to install 4Suite for the first time, if you're adventurous.  You can also install the CVS version over a working 4Suite installation.


[uogbuji@malatesta uogbuji]$ cd /usr/local/src
[uogbuji@malatesta src]$ cvs -d:pserver:anonymous@cvs.4suite.org:/var/local/cvsroot login
[uogbuji@malatesta src]$ cvs -z3 -d:pserver:anonymous@cvs.4suite.org:/var/local/cvsroot get Ft
SNIP
[uogbuji@malatesta src]$ cd Ft


Now retrieve the latest version of PyXML directly from CVS.


[uogbuji@malatesta Ft]$ cvs -d:pserver:anonymous@cvs.pyxml.sourceforge.net:/cvsroot/pyxml login
[uogbuji@malatesta Ft]$ cvs -d:pserver:anonymous@cvs.pyxml.sourceforge.net:/cvsroot/pyxml get -d PyXML xml
SNIP


In order to make updating CVS easier in future (i.e. not having to request updates from both the 4Suite and PyXML CVS separately), you may want to edit your file CVS/Entries in your Ft directory and add the line D/PyXML////.



Now you can fully update to the latest CVS versions of both 4Suite and PyXML quite easily:


[uogbuji@malatesta uogbuji]$ cd /usr/local/src/Ft
[uogbuji@malatesta src]$ cvs update
SNIP


At any rate, after your first checkout, or after any cvs update, you install by running setup in the familar way:


[uogbuji@malatesta Ft]$ python setup.py install
SNIP


And you should be ready to go.  Run the 4XSLT test suite again to check that all is well.


                          Quick tour of 4Suite
                          --------------------

I shall be filling out this section further soon.



For now, please peruse the documentation directory generated by the 4Suite install.  Feel free to suggest to the author areas that would be usefuol to cover in a quick tour.




                                Resources
                                ---------

Here is more information about the various packages we have introduced in
the 4Suite setup.  All excellent open-source software.

   *  PyXML is a comprehensive toolbox for XML processing in Python.  Check out the general information page, the Sourceforge project page or get more information from the Python XML-SIG mailing list.  PyXML is now bundled in 4Suite.
   *  The author has also written an introduction to 4RDF on xml.com.
   *  See the 4Suite.org home page for news, downloads, demos, links and other resources relevant to 4Suite.

