========================================================================
This is the README for the s11n "library bundle", a set of source
tarballs which make up the all-inclusive set of libraries required by
libs11n. This document describes how to install the library bundle.
The dependencies between the libs are described in
README.dependencies. For a short description of each library see
doxygen/index.txt.



Contact: s11n-devel@lists.sourceforge.net
Home page: http://s11n.net

========================================================================
BEFORE WE BEGIN:

For simplicity all examples in these instructions assume that the
distribution tarballs are gzipped (i.e., they have an extention of
.tar.gz). They may be compressed with bzip2 (i.e., an extension of
.tar.bz2). in which case you will need to change the tar decompression
options - these are tar-version dependent. Alternately, they may be in
ZIP format (extension .zip), in which case use the 'unzip' tool to
unpack them.




========================================================================
INSTALLATION "PREFIX"

All of the libraries are installed under a "prefix". Anyone familiar
with conventional configure scripts will understand what the "prefix"
is, but here is a summary:

- The prefix defines the "root" under which all installed files go.
- Installed headers go under PREFIX/include/...
- Installed binaries go under PREFIX/bin
- Installed libraries go under PREFIX/lib
- Installed documentation normally goes under PREFIX/share/doc/...

The prefix normally defaults to /usr or /usr/local, but only the root
user can install under those paths, so if you want to install these
libs under, e.g., your home directory, use a prefix of $HOME. (Tip:
this is what s11n's maintainer always uses.)

For simplicity you will normally use the same prefix for all of these
libs, but that is not a strict requirement.

========================================================================
BUILD & INSTALLATION INSTRUCTIONS: EASY WAY

        ./build_all.sh PREFIX

Examples:

        ./build_all.sh $HOME
or:
        ./build_all.sh /usr
or:
        ./build_all.sh /usr/local

If that process works then great - you can now skip down to the
POST-INSTALLATION section of this doc.


========================================================================
BUILD & INSTALLATION INSTRUCTIONS: STANDARD WAY

Note: while these instructions look a bit long, the whole process
should take less than 5 minutes on most machines.

First install the header-only libraries:

    cd libphoenix++-VERSION
    make install prefix=/installation/prefix

    cd ../libname_type++-VERSION
    make install prefix=/installation/prefix

    cd ../libtostring++-VERSION
    make install prefix=/installation/prefix

    cd ../libs11n_sigslot-VERSION
    make install prefix=/installation/prefix

    cd ../libs11n_lex_t++-VERSION
    make install prefix=/installation/prefix


The remaining libraries use a conventional 'configure' script, and
should be built in (approximately) the following order:

    1) libs11n_stringutil
    2) libs11n_zfstream
    3) libs11n_acme
    4) libs11n_class_loader
    5) libs11n


Each one should be built AND INSTALLED before the next one is
configured/built. Normally the only configure argument which "should"
be passed to each one is --prefix=/installation/prefix. Each tree may
support other arguments, which you can see by passing --help to their
configure scripts.

All of the above libs have the same build instructions:

    cd LIBNAME-VERSION
    ./configure --prefix=/installation/prefix
    make
    make install

That's normally all you need to, but read on for some tips and
sometimes-useful tricks...

As a shortcut, you may set the shell variable 'prefix', and that will
be used by the configure scripts if you do not set one (this does not
apply to the header-only libs). For example, when using the bash shell:

    export prefix=$HOME

The configure scripts will then use that prefix by default.

When installing you may optionally supply a "destination root", which
allows you to install to a "virtual root directory", like so:

    make install DESTDIR=/path/to/new/root

If you do this then all files are installed under:

     DESTDIR/PREFIX/...

The DESTDIR option works for all of the included libs, and is provided
mainly for compatibility with GNU Autotools.


========================================================================
POST-INSTALLATION

In order for applications to use the libraries the libraries must be
installed somewhere where the system's dynamic linker can find
them. How exactly this is done is system-dependent, but on Linux-like
systems there are at least 2 options:

    1) Add PREFIX/lib to the environment variable LD_LIBRARY_PATH.

    2) Add PREFIX/lib to /etc/ld.so.conf and run 'ldconfig'. This
       requires root access, and is not really recommended.

If you've never done this before, i recommended installing all libraries
with a PREFIX of $HOME, and in your login scripts add:
        export LD_LIBRARY_PATH=${HOME}/lib:${LD_LIBRARY_PATH}
(or the equivalent for your shell)

========================================================================
INSTALLING API DOCUMENTATION

If your machine has doxygen installed you may build the API
documentation by simply doing the following AFTER installing
the above libraries:

        cd doxygen
        make

Optionally, use 'make install' to install the docs under
PREFIX/share/doc/s11n/... (PREFIX, in this context, is the same one
used to build libs11n - the installer gets the info from
libs11n-config.)

Note that only the docs for *installed* libraries will be built, and
they will only be built completely if all libraries are installed
with the same PREFIX as libs11n (it uses libs11n-config to find
their location).

========================================================================
COMPILING/LINKING CLIENT SOFTWARE

If you would like to compile client software against these libraries
you can use the scripts named PREFIX/bin/LIBNAME-config to get the
compiler/linker options which client software needs in order to build
against these.  The config scripts are installed to PREFIX/bin during
'make install' and are called:

    libs11n_zfstream-config
    libs11n_stringutil-config
    libs11n_acme-config
    libs11n_class_loader-config
    libs11n-config

Note the header-only libs (phoenix & name_type) do not have config
scripts: simply add -IPREFIX to your INCLUDES when compiling.

When building libs11n clients, the only one of the above scripts you
need to run is libs11n-config, as it contains the information necessary
for compiling/linking against the others. Run it like this:

Linker options:
    libs11n-config --libs

INCLUDES path(s):
    libs11n-config --includes

To see more options use:
    libs11n-config --help


If your site has the pkg-config utility and PREFIX/lib/pkgconfig is in
your PKG_CONFIG_PATH then you can also use pkg-config to get information
about the libraries.

========================================================================
SAMPLE S11N CLIENT CODE

The libs11n tree comes with a couple sample client snippets, but they
are not built by default. To build them:

cd libs11n-VERSION/src/client/sample
make

Note that they need to link against libs11n and the other libraries,
so you may need to adjust your LD_LIBRARY_PATH, as explained above.
========================================================================

