OpenSS7 STREAMS Utilities -- read me first file.  2007-06-24
$Id$
Copyright (c) 2001-2007  OpenSS7 Corporation. <http://www.openss7.com/>
Copyright (c) 1997-2000  Brian Bidulock <bidulock@openss7.org>
See the end for copying conditions (for this file).

 OpenSS7 STREAMS Utilities
==========================

Package strutil-0.9.2.6 was released under GPLv2 2007-06-24.

The `OpenSS7 STREAMS Utilities' package provides "STREAMS" modules and
drivers, programs and daemons for administration and handling of the
"STREAMS" subsystem.

     The `strutil' package is currently incomplete.  The purpose of the
     package was to move "STREAMS" utility programs and modules outside
     of the "STREAMS" release package so as to allow them to be used
     with both `LiS' and `Linux Fast-STREAMS'.  As `Linux Fast-STREAMS'
     has already shown superior to `LiS' in terms of both performance
     and conformance, it is no longer necessary to keep these packages
     separate and they can be combined once again with `Linux
     Fast-STREAMS'.

The `OpenSS7 STREAMS Utilities' package includes kernel modules, `SVR
4.2' "STREAMS" drivers, modules, libraries, utilities, test programs,
daemons, and development environment for the development and execution
of "STREAMS" modules and drivers.  This package contains primarily
user-space utilities and test programs.

This distribution is only currently applicable to `Linux' 2.4 and 2.6
kernels and was targeted at `ix86', `x86_64', `ppc' and `ppc64'
architectures, but should build and install for other architectures as
well.

 Release
--------

This is the `strutil-0.9.2.6' package, released 2007-06-24.  This
`0.9.2.6' release, and the latest version, can be obtained from the
download area (http://www.openss7.org/download.html) of The OpenSS7
Project website using a command such as:

     $> wget http://www.openss7.org/tarballs/strutil-0.9.2.6.tar.bz2

The release is available as an `autoconf(1)' tarball, `src.rpm' or
`dsc', or as a set of binary `rpm's or `deb's.  See the download page
(http://www.openss7.org/download.html) for the `autoconf(1)' tarballs,
`src.rpm's or `dsc's.  See the `strutil' package page
(http://www.openss7.org/strutil_pkg.html) for tarballs, source and
binary packages.

Please see the `NEWS' file for release notes and history of user
visible changes for the current version, and the `ChangeLog' file for a
more detailed history of implementation changes.  The `TODO' file lists
features not yet implemented and other outstanding items.

Please see the `INSTALL', `INSTALL-strutil' and `README-make', files (or
see `Installation', in the manual) for installation instructions.

When working from `cvs(1)' or `git(1)', please see the `README-cvs',
file (or see `Downloading from CVS', in the manual).  An abbreviated
installation procedure that works for most applications appears below.

This release of the package is published strictly under Version 2 of
the `GNU Public License' which can be found in the file `COPYING'.
Package specific licensing terms (if any) can be found in the file
`LICENSES'.  Please respect these licensing arrangements.  If you are
interested in different licensing terms, please contact the copyright
holder, or OpenSS7 Corporation <sales@openss7.com>.

See `README-alpha' (if it exists) for alpha release information.

 Prerequisites
--------------

The quickest and easiest way to ensure that all prerequisites are met
is to download and install this package from within the `OpenSS7 Master
Package', `openss7-0.9.2.F', instead of separately.

Prerequisites for the OpenSS7 STREAMS Utilities package are as follows:

  1. `Linux' distribution, somewhat `Linux Standards Base' compliant,
     with a 2.4 or 2.6 kernel and the appropriate tool chain for
     compiling out-of-tree kernel modules.  Most recent `Linux'
     distributions are usable out of the box, but some development
     packages must be installed.  For more information, see
     `Compatibility', in the manual.

         - A fairly LSB compliant GNU/Linux distribution.(1)
         - Linux 2.4 kernel (2.4.10 - 2.4.27), or
         - Linux 2.6 kernel (2.6.3 - 2.6.21);
         - glibc2 or better.
         - GNU info (for info files).
         - GNU groff (for man pages).(2)

(Note: If you acquired `strutil' a part of the `OpenSS7 Master
Package', then the dependencies listed below will already have been met
by unpacking the master package.)

  2. `OpenSS7 Linux Fast-STREAMS', streams-0.9.2.3
     (http://www.openss7.org/tarballs/streams-0.9.2.3.tar.bz2).  (3)

  3. `OpenSS7 STREAMS Compatibility Modules',
     strcompat-0.9.2.6
     (http://www.openss7.org/tarballs/strcompat-0.9.2.6.tar.bz2).

When configuring and building multiple `OpenSS7 Project' release
packages, place all of the source packages (unpacked tarballs) at the
same directory level and all build directories at the same directory
level (e.g. all source packages under `/usr/src').

When installing packages that install as kernel modules, it is
necessary to have the correct kernel development package installed.
For the following distributions, use the following commands:

     Ubuntu:  $> apt-get install linux-headers
     Debian:  $> apt-get install kernel-headers
     Fedora:  $> yum install kernel-devel

You also need the same version of `gcc(1)' compiler with which the
kernel was built.  If it is not the default, add `CC=kgcc' on the line
after `./configure', for example:

     $> ../strutil-0.9.2.6/configure CC='gcc-3.4'

 Installation
-------------

The following commands will download, configure, build, check, install,
validate, uninstall and remove the package:

     $> wget http://www.openss7.org/tarballs/strutil-0.9.2.6.tar.bz2
     $> tar -xjvf strutil-0.9.2.6.tar.bz2
     $> mkdir build
     $> pushd build
     $> ../strutil-0.9.2.6/configure --enable-autotest
     $> make
     $> make check
     $> sudo make install
     $> sudo make installcheck
     $> sudo make uninstall
     $> popd
     $> sudo rm -rf build
     $> rm -rf strutil-0.9.2.6
     $> rm -f strutil-0.9.2.6.tar.bz2

If you have problems, try building with the logging targets instead.
If the make of a logging target fails, an automatic problem report will
be generated that can be mailed to The OpenSS7 Project
<bugs@openss7.org>.(4) Installation steps using the logging targets
proceed as follows:

     $> wget http://www.openss7.org/tarballs/strutil-0.9.2.6.tar.bz2
     $> tar -xjvf strutil-0.9.2.6.tar.bz2
     $> mkdir build
     $> pushd build
     $> ../strutil-0.9.2.6/configure --enable-autotest
     $> make compile.log
     $> make check.log
     $> sudo make install.log
     $> sudo make installcheck.log
     $> sudo make uninstall.log
     $> popd
     $> sudo rm -rf build
     $> rm -rf strutil-0.9.2.6
     $> rm -f strutil-0.9.2.6.tar.bz2

See `README-make' for additional specialized make targets.

For custom applications, see the `INSTALL' and `INSTALL-strutil' files
or the see `Installation', in the manual, as listed below.  If you
encounter troubles, see `Troubleshooting', in the manual, before
issuing a bug report.

 Brief Installation Instructions
--------------------------------

The OpenSS7 STREAMS Utilities package is available from the downloads
area of The OpenSS7 Project website
(http://www.openss7.org/download.html) using a command such as:

     $> wget http://www.openss7.org/tarballs/strutil-0.9.2.6.tar.bz2

Unpack the tarball using a command such as:

     $> tar -xjvf strutil-0.9.2.6.tar.bz2

The tarball will unpack into the relative subdirectory named after the
package name: strutil-0.9.2.6.

The package builds using the GNU `autoconf' utilities and the
`configure' script.  To build the package, we recommend using a
separate `build' directory as follows:

     $> mkdir build
     $> cd build
     $> ../strutil-0.9.2.6/configure

In general, the package configures and builds without adding any
special options to the `configure' script.  For general options to the
`configure' script, see the GNU `INSTALL' file in the distribution:

     $> less ../strutil-0.9.2.6/INSTALL

For specific options to the `configure' script, see the
`INSTALL-strutil' file in the distribution, or simply execute the
configure script with the `--help' option like so:

     $> ../strutil-0.9.2.6/configure --help

After configuring the package, the package can be compiled simply by
issuing the `make' command:

     $> make

Some specialized makefile targets exists, see the `README-make' file in
the distribution or simply invoke the `help' target like so:

     $> make help | less

After successfully building the package, the package can be checked by
invoking the `check' make target like so:

     $> make check

After successfully checking the package, the package can be installed
by invoking the `install' make target (as root) like so:

     $> sudo make install

The test suites that ship with the package can be invoked after the
package has been installed by invoking the `installcheck' target.  This
target can either be invoked as root, or as a normal user, like so:

     $> make installcheck

(Note: you must add the `--enable-autotest' flag to `configure', above
for the test suites to be invoked with `make installcheck'.)

The package can be cleanly removed by invoking the `uninstall' target
(as root):

     $> sudo make uninstall

Then the build directory and tarball can be simply removed:

     $> cd ..
     $> rm -rf build
     $> rm -rf strutil-0.9.2.6
     $> rm -f strutil-0.9.2.6.tar.bz2

 Detailed Installation Instructions
-----------------------------------

More detailed installation instructions can be found in the
`Installation', in the manual, contained in the distribution in `text',
`info', `html' and `pdf' formats:

     $> cd ../strutil-0.9.2.6
     $> less doc/manual/strutil.txt
     $> lynx doc/manual/strutil.html
     $> info doc/manual/strutil.info
     $> xpdf doc/manual/strutil.pdf

The `text' version of the manual is always available in the `MANUAL'
file in the release.

The current manual is also always available online from `The OpenSS7
Project' website at:

     $> lynx http://www.openss7.org/strutil_manual.html

---------- Footnotes ----------

(1) See `GNU/Linux Distributions', in the manual, for more information.

(2) If you are using a Debian release, please make sure to install the
groff extension package (`groff_ext'), as it contains the `refer' or
`grefer' commands necessary for including references in the manual
pages.

(3) Although, at one time, this package supported `LiS', `LiS' is now
deprecated and unsupported.

(4) Please see `Problem Reports', in the manual, or the file `PROBLEMS'
in the release directory for more information on filing a proper
"Problem Report".

-----

=========================================================================

 Copyright (c) 2001-2007  OpenSS7 Corporation  <http://www.openss7.com/>
 Copyright (c) 1997-2000  Brian Bidulock  <bidulock@openss7.org>

 All Rights Reserved.

 Permission is granted to make and distribute verbatim copies of this
 manual provided the copyright notice and this permission notice are
 preserved on all copies.

 Permission is granted to copy and distribute modified versions of this
 manual under the conditions for verbatim copying, provided that the
 entire resulting derived work is distributed under the terms of a
 permission notice identical to this one

 Since the Linux kernel and libraries are constantly changing, this
 manual page may be incorrect or out-of-date.  The author(s) assume no
 responsibility for errors or omissions, or for damages resulting from
 the use of the information contained herein.  The author(s) may not
 have taken the same level of care in the production of this manual,
 which is licensed free of charge, as they might when working
 professionally.

 Formatted or processed versions of this manual, if unaccompanied by the
 source, must acknowledge the copyright and authors of this work.

-------------------------------------------------------------------------

 U.S. GOVERNMENT RESTRICTED RIGHTS.  If you are licensing this Software
 on behalf of the U.S. Government ("Government"), the following
 provisions apply to you.  If the Software is supplied by the Department
 of Defense ("DoD"), it is classified as "Commercial Computer Software"
 under paragraph 252.227-7014 of the DoD Supplement to the Federal
 Acquisition Regulations ("DFARS") (or any successor regulations) and
 the Government is acquiring only the license rights granted herein (the
 license rights customarily provided to non-Government users).  If the
 Software is supplied to any unit or agency of the Government other than
 DoD, it is classified as "Restricted Computer Software" and the
 Government's rights in the Software are defined in paragraph 52.227-19
 of the Federal Acquisition Regulations ("FAR") (or any successor
 regulations) or, in the cases of NASA, in paragraph 18.52.227-86 of the
 NASA Supplement to the FAR (or any successor regulations).

=========================================================================

 Commercial licensing and support of this software is available from
 OpenSS7 Corporation at a fee.  See http://www.openss7.com/

=========================================================================
vim: ft=README tw=72 nocindent nosmartindent formatoptions+=tcqlorn
