Installation instructions for GWXLIBS
=====================================

GWXLIBS attempts to be as self-contained as possible. As much as it can,
GWXLIBS ensures that only the libraries build by GWXLIBS itself are used
by the various builds. On OSR5 and UW7, the builds will use the real
cross environment for doing the builds.

The file build/SOURCES.gwx contains a full list of all of the libraries
contained in GWXLIBS, and the order in which they should be built. That
file contains fairly verbose comments at the top, which you should read
if you want to add new components to GWXLIBS.

The file build/procgwx.c is a small file that is built with the local
host compiler to process the contents of SOURCES.gwx. Its primary purpose
is to produce the build script, and to produce release notes. The first
step to building GWXLIBS is to compile this program. To generate the actual
build script, you need to pass this program arguments that point to the
top level source directory, and the name of the OS you are building for.
Currently, the only OS names supported are 'osr5', 'uw7' and 'generic'.
The file build/OSNAME.sh is used to set the parameters for the given OS.

The only supported way of building GWXLIBS is to build in a directory
other than the source directory. This ensures that the sources remain
untouched (and they can in fact reside on read-only media). During the
build process, as each library is built, it is installed in two ways.
The first is installed into what is called (for historical reasons), the
cross-environment directory, or xenv directory. This is the directory
which each build looks in for other dependant libraries, and which other
programs outside of GWXLIBS will look for libraries and binaries provided
by GWXLIBS as they build. The second place that each GWXLIBS component
is installed is into its packaging or product integration directory.
This is the directory which is used to produce the archives that the PI
scripts will use for creating installable packages.

To perform all of these steps correctly, there is a top level build
script called GWXBUILD that can be used. This script takes, as its
mandatory five arguments, the name of the OS to build for (osr5, uw7
or generic), the path to the top level of the source, the path to where
the build will be done, the path to where the xenv installs will be
rooted, and the path to the directory where the PI installs will be
rooted. For example:

  GWXBUILD osr5 /u/opensrc/gwxlibs /u/gwx/bld /u/gwx/xenv /u/gwx/pi
  GWXBUILD uw7 /u/opensrc/gwxlibs /u/gwx/bld /u/gwx/xenv /u/gwx/pi

Note this will create the actual build script in /u/gwx/bld, called
simply BUILD, and run it, after compiling procgwx. It will create
a cpio archive suitable for handoff to the commonpi scripts in /u/gwx/pi
called gwxlibs-OSNAME.cpio.bz2.
