# Installing 4Suite™ on UNIX

This version:
  Revision 0.4 (2005-03-03)
Principal author:
  Shatin Rai (Fourthought, Inc.)
Add'l contributors:
  Uche Ogbuji (Fourthought, Inc.)
  Mike Brown (Fourthought, Inc.)

This document can be freely translated and distributed. It's released under the LDP License.

## Abstract

4Suite™ is a platform for XML and RDF application development. This document gives step-by step instructions for installing 4Suite on a UNIX-like system such as Linux, FreeBSD, or Mac OS X.

# 1 Introduction and Conventions

These instructions were originally written for Red Hat 7.1 Linux, but should work for most Linux distributions and other UNIX variants with few, if any, modifications.

Ordinarily, the installation will occur in directories under /usr/local and /var/local. Ideally, you should perform these steps as a user who has write access in these directories.

Some instructions require the user to modify their shell environment. If multiple users will be running and accessing the repository servers, you'll want to be careful to ensure the environment is set up correctly for each user.

In command-line examples, "$" is used to represent the shell's command prompt. The actual prompt will vary from system to system. The part you are supposed to type is to the right of the "$".

Sometimes there will be a great deal of output from an instruction. If there is nothing of particular interest in the output, it will be omitted and replaced with the text "SNIP".

There are useful third-party resources mentioned in this document. Those that are necessary to follow instructions are directly linked from the text. Others are marked as endnotes and the links are available in the Resources section.

# 2 Quick Installation Steps

The Detailed Installation Guide sections that follow this section will further explain these steps.

1. Install Python 2.2.1 or newer

   Python comes pre-installed on many operating systems now, but on some systems, the 'python' user binary is linked to an outdated version of Python (happens on many Linux distros) or Python was built without PyExpat (as happened on FreeBSD for a while).

   While it is OK to install/upgrade Python via your operating system's native package or ports system (RPMs, BSD packages/ports collection, etc.), if you run into any problems, the 4Suite developers prefer that you install Python from source, if you can. Just get the appropriate Python tarball from python.org, build and install via the usual "untar; configure; make" procedure.

2. Install 4Suite

   Download the latest tarball, which at the time of this writing was 4Suite-1.0b1.tar.gz, from ftp://ftp.4suite.org/pub/4Suite/. The same files are also available in a .tar.bz2 (compressed with bzip2 rather than gzip) archive, if you prefer.

   Untar the source, then build and install via the usual procedure for installing a python application: invoke "python setup.py install" in the top-level source directory.

3. If you want to use Triclops, the RDF graph visualization tool that comes with 4Suite, then install GraphViz.

   GraphViz tarball - http://www.research.att.com/sw/tools/graphviz/download.html. It is not really necessary to do this before installing 4Suite, though.

# 3 CVS: bleeding-edge 4Suite

If you need up-to-the-minute features or fixes for 4Suite, then you can install the latest version from the developers' CVS repository. It should be considered an unstable work-in-progress preview of the next official release; it is not recommended for ordinary users.

1. 4Suite CVS snapshots

   CVS snapshots are a way to get bug fixes and experimental new features between full releases of the software. They are tarballs and zipfiles generated from Fourthought's internal CVS repository nightly.

2. 4Suite anonymous CVS

   If you want to keep closer track of the 4Suite development, you can use anonymous CVS (pserver). The main advantage of this approach is that you can get fixes quite easily when checked in by the developers, and keeping up-to-date afterward is easy. The main disadvantage is that you can also pick up bugs that the developers sometimes accidentally check in.

   For more information about 4Suite CVS, refer to the Obtaining 4Suite with CVS documentation.

# 4 Detailed Installation Guide

## 4.1 Python

4Suite is written mostly in Python: a mature, robust, efficient programming language well-suited to object-oriented programming, functional programming, and procedural tasks of any complexity. In the few cases where Python is not sufficiently speedy, certain 4Suite components are implemented in C. Therefore, you need both an appropriate version of Python and an ANSI C compiler installed if you want to be able to use 4Suite. C compilers are standard on most UNIX systems, but Python is not always available.

Specifically, Python 2.2.1 or higher is required for 4Suite. For best results, use Python 2.3 or 2.4. Your system might not have Python at all, or it might only have an older version, or it may have more than one version installed — some Linux distributions install Python 2.x as "python2", for example. You can have other versions of Python installed alongside the one you need for 4Suite, as long as when you use 4Suite's Python API, you be sure to load the modules with the interpreter that they were built for, and as long as the directory containing the correct python executable comes first in your executable path. Test that you have a good version of python in your path by issuing this command in your command shell: python -V (that's a capital V).

The installation of Python is not covered in this guide.

### 4.1.1 PyExpat and Expat

One of the optional features of 4Suite depends on the availability of PyExpat, which is a Python wrapper for the C-based XML parser Expat. Expat libraries are on most POSIX systems these days. If they were available on the system when Python was built, then PyExpat was probably built and installed, as well. The simple command-line test python -c 'import pyexpat' will reveal if pyexpat is installed. The command will produce an ImportError traceback if pyexpat is not found. This test does not ensure pyexpat actually works or that it wraps a good version of Expat, however.

The feature that uses PyExpat is the CatalogReader, which allows you to use XML or TR9401 SGML Catalogs (files that map public and system IDs to URIs for resolving entity references during XML parsing). This isn't something that most people need, so it is OK if you don't have PyExpat installed.

If PyExpat is not available, or if the underlying version of Expat is the very buggy 1.95.5 version, then the recommended procedure is to install the latest version of PyXML, which will make a safe version of PyExpat available for use in Python applications. Installing PyXML will also make a validating XML parser available for use in 4Suite, and will install other useful XML processing tools. PyXML is available from http://pyxml.sourceforge.net/. If you don't install PyXML, it is possible to install PyExpat separately, but this is sometimes a bit of an ordeal.

## 4.2 4Suite

Download the latest tarball, which at the time of this writing was 4Suite-1.0a1.tar.gz, from ftp://ftp.4suite.org/pub/4Suite/. The same files are also available in a .tar.bz2 (compressed with bzip2 rather than gzip) archive, if you prefer.

Untar the source, then build and install via the usual procedure for installing a python application: invoke setup.py install in the top-level source directory.

4Suite will be installed in your python site-packages directory, the actual location of which will vary from system to system, but is usually in either /usr/lib/python2.x/site-packages or /usr/local/lib/python2.x/site-packages. It is possible to customize the installation locations by running setup.py config with certain arguments prior to running setup.py install; see the 4Suite Installation Locations documentation for details.

An example of an installation session follows.

    $ cd /usr/local/src
    $ tar xzvf 4Suite-1.0a3.tar.gz; cd 4Suite-1.0a3
    SNIP

    $ python setup.py install
    SNIP

## 4.3 Final Step

Now you can perform a quick test to make sure everything is installed correctly. First, open up a command prompt. From any directory outside of the 4Suite source or installation directories, run the following (you enter 'python and then the text to the right of the '>>> prompts):

    $ python
    Python 2.2.1 (#1, Jul  1 2002, 19:51:59)
    [GCC 2.96 20000731 (Red Hat Linux 7.1 2.96-98)] on linux2
    Type "help", "copyright", "credits" or "license" for more information.
    >>> from Ft.Xml import Domlette
    >>> from Ft.Xml.Xslt import Processor
    >>> print Processor
    <module 'Ft.Xml.Xslt.Processor' from '/usr/local/lib/python2.2/site-packages/Ft/Xml/Xslt/Processor.pyc'>
    >>>

The imports and the print should complete without error. Report any problems to the 4Suite mailing list.

## 4.4 Tests and Further Setup

If all you wish to use in 4Suite are the basic command-line tools and Python libraries, then you are done with installation and can proceed to use them. To make sure things are working, try running a few of the command-line tools with the -h option to get usage information.

    $ 4xml -h
    SNIP
    $ 4xslt -h
    SNIP
    $ 4xpath -h
    SNIP
    $ 4rdf -h
    SNIP

More thorough regression test suites for the 4Suite Python libraries are included with 4Suite, and you are welcome to try them out. Ideally, in a regular release version of 4Suite, they should all run to completion without errors. Warnings are OK. In alpha and beta versions or CVS snapshots, some errors are to be expected, and do not need to be reported unless the tests cannot even run to completion.

    $ cd /usr/local/lib/4Suite/tests
    $ cat README
    SNIP
    $ python test.py -v
    SNIP

Be prepared for a lot of output. Omit the -v if you want somewhat less detail. You can also specify certain tests by appending the relative path to a subdirectory or .py file.

If you want to use the XML/RDF repository and server features of 4Suite, then you will need to customize and install a configuration file, initialize a repository, and do some further tests. These topics are covered in the Quick Start documentation.

# 5 Resources

## 5.1 4Suite @ SourceForge

4Suite Project Page - Bug Reports, Feature Requests, Patches

## 5.2 Additional Links

4suite.org - Documentation, Downloads, News, CVS, Developer Resources

4Suite Users Mailing List - Peer & Developer Support

4Suite Announcement Mailing List - Infrequent Announcements about 4Suite

Fourthought, Inc. - Commercial Development, Consulting & Support

# 6 Appendix A: Notes on PyXML and 4Suite

PyXML is a collection of XML processing libraries for Python. 4Suite and PyXML are complementary projects developed in tandem. There is minimal overlap in functionality. For example, where PyXML has a compliant, pure Python implementation of DOM Level 1, 4Suite has a lightweight, "Domlette" optimized for XPath processing and implemented mostly in C.

Prior to the 4Suite 0.12.0a1 release, PyXML was required to use 4Suite. This is no longer the case with modern versions of 4Suite; PyXML is not needed at all. As noted above, however, the absence of Expat and PyExpat on some systems can affect the usability of certain parts of 4Suite, and the absence of xmlproc, the validating parser that comes with PyXML, will mean that 4Suite cannot do validation when parsing XML... so the installation of PyXML can still be advantageous if you need those features.

If you decide to install PyXML, you must install PyXML 0.8 or higher (try to install the most recent version) for compatibility with 4Suite. Avoid PyXML 0.8.1 — that specific version integrates a buggy version of Expat (1.95.5), which leads to core dumps in some situations. When installing PyXML, it is recommended that you use the --without-xpath --without-xslt options for setup.py install in order to ensure that the very old, deprecated XPath and XSLT implementations included with PyXML will not be installed. These implementations are ported from 4Suite 0.11.1 and using them alongside newer versions of 4Suite may be problematic.