This is the top level source directory for many of the open source
components delivered as part of the standard SCO OpenServer 5, OpenServer 6
and UnixWare 7 platforms. Rebuilding everything is a non-trivial matter,
and requires considerable expertise. However, this document will attempt
to distill things down to the simplest form. First, some basic principles
and assumptions.

In order to have reproducable builds, which is a requirement for any
escalations work, there needs to be fairly rigid control over the build
environment. While end users may use these build scripts to "roll their
own" versions of these packages, for internal use, the requirements
need to be rigidly met. The build environment starts with a vanilla
OSR5.0.7 machine with the latest Maintenance Pack and Build Supplement
installed. On OSR5, most of these packages require gcc, which is
delivered a part of the build supplement. For the UnixWare builds, you
need to start with a UnixWare 7.1.4 system with the latest Maintenance
Pack installed and the UnixWare Build Supplement or its equivalent.

You will require a fast machine with a lot of disk space in order to
fully build and package all of these products. If you intend to build
for OSR6, you will need two build machines: one for the OSR5.0.7 builds
and one for the UW7.1.4 builds. The PI porcess merges the two builds
when appropriate.

In order for the builds to be as reproducable as possible, the scripts
in these packages attempt to create or use the notion of a "cross
environment". This term is borrowed from the internal UnixWare build
procedure, and essentially means an environment which is rooted somewhere
other than "/". If these builds ar ever integrated with the actual UnixWare
nightly build procedure, this will point ot the actual XENV. For the
purposes of this document however, the term "XENV" is used to refer to a
staging area that is given as an argument to the various build scripts
that is a place where each package is installed, so that sunsequent packages
can find the lastest libraries / software in one central place. This
directory is used ONLY for building, not for packaging.

The GWXLIBS package must always be the first one built and provides the
basis of the XENV. For truely reproducable builds, even if you are interested
in building, for example, Apache, you should also rebuild the GWXLIBS
sources too, to create the correct build environment for building Apache.

Each package creates its own directories for PI purposes. The location of
these PI directories should be completely outside the XENV hierarchy. Each
package also needs its own build directory, which should be completely
outside of the source, XENV, and PI directory hierarchies.

Lets consider an example, using just GWXLIBS and Apache as the two open
source packages. Wherever Apache is referenced here, you can apply the
same to the other opern source components such as Extended Shells, ViM etc.
Lets say that the source directory is rooted in /u/opensrc. That is where
this file will live. Under that directory are the individual directories
for each package, namely gwxlibs and apache. If you intend to any kind of
packaging, you will also need the "commonpi" source directory:

  /u/opensrc/gwxlibs
  /u/opensrc/apache
  /u/opensrc/commonpi

Now you would chose a location in which to do the builds. For example,
lets say /u/build is where you have space for the build. You would end
up with:

  /u/build/gwxlibs
  /u/build/apache

(The commonpi package doesnt use this build directory, it does its build
inside the PI directory, discussed below).

A standard part of each build is to populate the XENV. A typical location
would be something like:

  /u/xenv

Note that this directory is shared by ALL of the open source components.
As each one is built, it installs itself into this directory, as well as
the various PI directories.

All builds assume that you will want to create installable archives
for the package you are building (even if you wont be). These PI
directories are a requirement of the build procedure. A sensible
location given all of the above would be:

  /u/pi/gwxlibs
  /u/pi/apache

The very top level build script, which builds ALL of these open source
components, will need to know the final location of where the commonpi
distribution directory will be. See the commonpi docs for details. This
is the location in which all of the archives created from the /u/pi
directories above are processed in order to actually create installable
archives. This should ideally be on a separate filesystem, especially
on OSR5. For the UW7 builds that will contribute to OSR6 packages, this
location is simply a place where the final archives as handed off to
the commonpi distribution area are stored, and from which you will copy
onto the OSR5 machine where the PI run takes place. For example, a suitable
location for the final PI distribution directory for the OSR5 builds
would be:

  /pi/dist/osr5

Note that when you finally get down to packaging and the commonpi scripts
are run, the /pi directory must be absolutely empty except for /pi/dist/*.
That directory should contains only the macros.gwxlibs file, and the
sub-directories for each OS'es handoff archives.

When building for OSR6, you would also have a /pi/dist/uw7 and /pi/dist/osr6
directory that would contain the PI archives built on UnixWare and
(in the single exceptional case of OpenSSH, OSR6).

