source: trunk/doc/build-system @ 11199

This document explains how to build packages from the Athena source
tree, and then describes guidelines for designing the build system for
code we maintain in the Athena source tree.  A discussion of building
packages we get from third parties is in the file "third-party" in
this directory.

This file contains the following sections:

        Building packages from the source tree
        Building the tree
        Generic build system guidelines
        Using Autoconf
        Using a straight Makefile

Building packages from the source tree
--------------------------------------

To build a package from the Athena source tree, you should generally
first attach the source tree that you want.  You can either attach a
locker like "source-8.0" or "source-8.1" to get the sources for a
particular release, or you can attach "source" to get the current
development sources.  Releases prior to 8.1 will not build using the
procedure below.  Note that you can only build whole packages, not
arbitrary subdirectories; package names are listed in
packs/build/packages.

After attaching the correct locker, you can build a package by doing:

        set src = /mit/source           # or /mit/source-8.1, etc.
        mkdir /var/tmp/PACKGAGE-NAME
        cd /var/tmp/PACKAGE-NAME
        synctree -s $src/PATH-TO-PACKAGE -d . -a $src/.rconf
        sh $src/packs/build/do.sh prepare
        sh $src/packs/build/do.sh all

"do" accepts the following options:

        -s SRCDIR       Specifies the source hierarchy, if not default
        -d DESTDIR      Specifies the install hierarchy, if not /srvd

The default location for SRCDIR is the source locker you attached
(/mit/source, /mit/source-8.1, etc.).  "do" recognizes supports the
following build operations:

        prepare         Set up the source tree for building
        clean           Clean any files generated by the "all" operation
        all             Create automatically generated files
        check           Perform automated tests, if any
        install         Install in /srvd (or dir given by -d option)

Building the tree
-----------------

To build the entire tree by hand, you run packs/build/build.sh from
the source directory.  Building the tree has the following
requirements right now:

        * The system passwd file must have "pop" and "discuss" users.
          Athena machines should typically have these lines in them
          already, but you may have to add them on non-Athena systems.

        * The source tree must be findable in the default location
          (/mit/source for the current sources), or you must tell
          build.sh where to find the source tree using the -s option.

        * You must have a link farm of the source tree generated by
          synctree.  The default location is /build; you can specify
          an alternative location with the -b option.

        * You must have write access to a destination tree, and be
          able to chown files and make setuid root files in that tree.
          The default location is /srvd; you can specify an
          alternative location with the -d option.

        * On Solaris, you need system:authuser access to the Athena
          cell in order to build third/gcc (since it is bootstrapped
          with the sunsoft compiler).

Therefore, if you have a machine newly installed with the vendor
operating system and AFS, and you want to build the Athena source tree
for the first time, you have to do a little work beforehand:

        * Make a temporary directory to put binaries in:

                mkdir /var/tmp/bin
                set path = ($path /var/tmp/bin)

        * You need a functioning synctree.  The sources are in
          athena/etc/synctree; because they are not world-readable,
          you may need to copy the sources somewhere temporary from
          another workstation in order to get them onto the machine
          you're building on.  Once you have a copy of the sources,
          building them is relatively easy:

                set src = /afs/dev.mit.edu/source/src-current
                imake -I$src/packs/build/config -DUseInstalled
                make
                cp synctree /var/tmp/bin
                rehash

        * You need a functioning kinit.  In the worst case, you may
          need to do a complete build of third/cns.

                cd /var/tmp; mkdir cns; cd cns
                synctree -s $src/third/cns -d . -a $src/.rconf
                ./configure --site=athena
                make
                cp kuser/kinit /var/tmp/bin
                mkdir /etc/athena
                cp $src/packs/config/krb.conf /etc/athena
                cp $src/packs/config/krb.realms /etc/athena

        * You need a functioning aklog.

                cd /var/tmp; mkdir aklog; cd aklog
                synctree -s $src/athena/bin/aklog -d . -a $src/.rconf
                imake -I$src/packs/build/config -DUseInstalled
                make # or "make AFSDIR=/wherever" if AFS libs not in /usr/afsws
                cp aklog /var/tmp/bin

        * For a few packages (third/perl and some things under packs),
          /os must point to an image of the operating system.  A
          symlink from /os to / will usually service if a pristine
          operating system image is unavailable.

With these tools, you should be able to set up the build environment
as documented above.

Generic build system guidelines
-------------------------------

Here are some desirable properties of a build system for programs or
libraries, regardless of how it is implemented:

        * It should use feature tests, not platform tests.

        * Once the appropriate configuration steps (e.g. running
          configure or imake) have been done, "make all" should
          generate all automatically generated files without ever
          modifying any source files.  (For example, "make all" should
          not try to regenerate configure from configure.in, and a
          build system should not wait until "make install" time to
          generate a file which is going to be installed.)

        * "make install" should install all files appropriate for the
          target directories without modifying any files in the build
          tree.  In particular, it should not depend on the "all"
          target.

          "make install" should use the install command to install
          files, not cp or tar or shell redirection.  To install
          multiple files in the same way, use a single install command
          rather than a for loop.

        * "make clean" should clean all files generated by "make all."
          "make distclean" should also delete files generated by the
          configuration steps.

        * "make check" should run self-tests.  It should not assume
          that the program has been installed, but it should assume
          that the program has been built.  It should not modify the
          build tree in any way; in particular, it should not depend
          on the "all" target.  If there are no self-tests, "make
          check" should not generate an error.

        * In a multi-directory source tree, it should be possible to
          change to a subdirectory of the build tree and run any of
          the aforementioned make targets with the same results as
          having descended into that directory from above.  It is okay
          to assume that previous parts of the build tree have been
          built, but it is not okay to rely on make command-line
          parameters passed in from the parent directory.

Using Autoconf
--------------

For packages in the "athena" hierarchy, we use autoconf.  Autoconf is
not perfect, but it's the only reasonable package out there for doing
feature tests as opposed to platform tests.  See the Autoconf info
pages (available in the default emacs info menu) for information about
using Autoconf in general.

When we build the program for the Athena environment, we will use a
config.site file (already written; you don't need to write it or point
to it) which does the following:

        * Sets the shell variable "athena" to "true".

        * Sets the appropriate compiler (using the CC environment
          variable) as well as other compilation tools (yacc, lex) for
          the platform in question.

        * Sets the appropriate X include path and library path for use
          with AC_PATH_X.

        * Sets the appropriate with_* variables for finding Motif, AFS
          libraries, Kerberos 4, Kerberos 5, com_err, and ss.  If your
          package uses any of those libraries, copy the aclocal.m4
          file from packs/build and use the macros contained within.

        * Sets prefix to /usr/athena, datadir to '${prefix}/lib',
          sbindir to '${prefix}/etc', and sysconfdir to '/etc/athena'.
          You do not need to take these into account in configure.in;
          just put in your Makefile.in:

                prefix=@prefix@
                exec_prefix=@exec_prefix@
                datadir=@datadir@
                sbindir=@sbindir@
                sysconfdir=@sysconfdir@

        * Sets shell variables lbindir and lsbindir to /bin/athena and
          /etc/athena respectively.  If your build system needs to
          install files in /bin/athena or /etc/athena when built for
          the Athena environment, use the following in your configure.in:

                test -z "$lbindir" && lbindir='${bindir}'
                test -z "$lsbindir" && lsbindir='${sbindir}'
                AC_SUBST(lbindir)
                AC_SUBST(lsbindir)

          And then in your Makefile.in:

                prefix=@prefix@
                exec_prefix=@exec_prefix@
                bindir=@bindir@
                sbindir=@sbindir@
                lbindir=@lbindir@
                lsbindir=@lsbindir@

The build environment will ensure that the following things are true:

        * The environment variable ATHENA_SYS is set to the current
          platform's desired ATHENA_SYS value (e.g. "sun4m_54").

        * The environment variable HOSTTYPE is set to the current
          platform name (e.g. "sun").

        * The environment variable CONFIG_SITE points to the Athena
          config.site file.

Using a straight Makefile
-------------------------

For packages in the "packs" hierarchy, and in some parts of the
"third" hierarchy where we construct the build system by hand, we use
a straight Makefile, since feature tests are not necessary for the
packs hierarchy.

The build system will ensure that the same environment variables are
set as for using Autoconf.  In addition, the make variable CC will be
set to the appropriate compiler for the current platform when the
"all" target is invoked.  You should be sparing in your use of C
source code in packages using a straight Makefile, but for small,
portable C programs it's okay.

The subdirectories "platform/$HOSTTYPE" or "arch/$ATHENA_SYS" should
be used for platform or system-dependent components of a package using
a straight Makefile.

Start each Makefile with "# $Id: $" and "SHELL=/bin/sh".  The latter
is to work around a bug in the Irix make where it runs commands under
${SHELL} rather than /bin/sh.  Also necessary for Irix is using
"-mkdir -p" instead of "mkdir -p", since mkdir -p under Irix gives an
error when the directory already exists (in violation of IEEE 1003.2).