Build(Aegis)                                                      Build(Aegis)



NNAAMMEE
        aegis - project change supervisor
        Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
        2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Peter
        Miller

        The _a_e_g_i_s program is distributed under the terms of the GNU General
        Public License.  See the LICENSE section, below, for more details.

        aaeeggiiss (ee.j.iz) _n_._, a protection, a defense.

SSPPAACCEE RREEQQUUIIRREEMMEENNTTSS
        You will need up to 250MB to unpack and build the _a_e_g_i_s package.
        (This is the worst case seen so far, most systems have binaries
        smaller than this, 200MB is more typical.)  Your mileage may vary.

SSIITTEE CCOONNFFIIGGUURRAATTIIOONN
        The aaeeggiiss package is configured using the _c_o_n_f_i_g_u_r_e shell script
        included in this distribution.

        The _c_o_n_f_i_g_u_r_e shell script attempts to guess correct values for
        various system-dependent variables used during compilation, and
        creates the _M_a_k_e_f_i_l_e and _c_o_m_m_o_n_/_c_o_n_f_i_g_._h files.  It also creates a
        shell script _c_o_n_f_i_g_._s_t_a_t_u_s that you can run in the future to recreate
        the current configuration.

   UUppggrraaddiinngg
        The ./configure script will look for an existing install of Aegis and
        use the existing configuration settings.  This works best if the
        version you are upgrading is 4.11 or later.

        To disable looking for an existing installation (maybe because you
        want to change the prefix), use the ./configure --with-no-aegis-
        configured option.

        To change the AEGIS_UID and AEGIS_GID values (these control the
        ownership of Aegis' system files) you need to set environment
        variables of these names bbeeffoorree running the _._/_c_o_n_f_i_g_u_r_e script.  You
        almost never need to do this, so if you have no idea what this is
        about, don't try to change them.

   BBeeffoorree YYoouu SSttaarrtt
        Before you start configuring, it is worth reading the _O_T_H_E_R _U_S_E_F_U_L
        _S_O_F_T_W_A_R_E section, below.

        The _c_o_n_f_i_g_u_r_e script checks for the internationalization library and
        functions.  If your system does not have them, it is worth fetching
        and installing GGNNUU GGeetttteexxtt before you run the _c_o_n_f_i_g_u_r_e script.  Make
        sure that the _m_s_g_f_m_t command from GNU Gettext appears earlier in your
        command search PATH than the existing system ones, if any (this is
        very important for SunOS and Solaris).  You must do the GNU gettext
        install _b_e_f_o_r_e running the _c_o_n_f_i_g_u_r_e script, or the error messages,
        even for English speakers, will be terse and uninformative.  Remember
        to use the GNU gettext configure _-_-_w_i_t_h_-_g_n_u_-_g_e_t_t_e_x_t option if your
        system has native gettext tools.

        The _c_o_n_f_i_g_u_r_e script checks for compression libraries and functions.
        If your system does not have them, you must download and install the
        GGNNUU zzlliibb compression library (see http://www.gzip.org/zlib/ for
        download) and the bbzziipp22 compression library (see http://www.bzip.org/
        for download) before you run the _c_o_n_f_i_g_u_r_e script.  These libraries
        are essential, Aegis will not build without them.  (NNoottee:: zlib is not
        the same thing as zlibcc which does something completely different.)

        The _c_o_n_f_i_g_u_r_e script checks for the regular expression library and
        functions.  If your system does not have them, it is worth fetching
        and installing GGNNUU rrxx compression library before you run the _c_o_n_f_i_g_u_r_e
        script.  (Note: test 81 will fail if the POSIX regular expression
        functions are not available.)

        The GNOME libxml2 library (http://xmlsoft.org/) is used to parse XML,
        you will need version 1.8.17 or later.  You do not have to install the
        rest of GNOME as this library is able to be used by itself.  This
        package is nnoott optional, you need it to successfully build Aegis.

        The libcurl library (http://curl.haxx.se/) is used to fetch remote
        files.  This library is optional, but some functionality, particularly
        _a_e_d_i_s_t _-_r_e_p_l_a_y_, _w_i_l_l _n_o_t _w_o_r_k _w_i_t_h_o_u_t _i_t_.  _I_f _y_o_u _a_r_e _u_s_i_n_g _a _p_a_c_k_a_g_e
        _b_a_s_e_d _i_n_s_t_a_l_l_, _y_o_u _w_i_l_l _n_e_e_d _t_h_e _l_i_b_c_u_r_l_-_d_e_v _o_r _l_i_b_c_u_r_l_-_d_e_v_e_l _p_a_c_k_a_g_e
        _a_s _w_e_l_l_.

   RRuunnnniinngg CCoonnffiigguurree
        Normally, you just _c_d to the directory containing _a_e_g_i_s' source code
        and type
                % ..//ccoonnffiigguurree ----ssyyssccoonnffddiirr==//eettcc
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                %
        If you're using _c_s_h on an old version of System V, you might need to
        type
                % sshh ccoonnffiigguurree ----ssyyssccoonnffddiirr==//eettcc
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                %
        instead to prevent _c_s_h from trying to execute _c_o_n_f_i_g_u_r_e itself.

        Running _c_o_n_f_i_g_u_r_e takes a minute or two.  While it is running, it
        prints some messages that tell what it is doing.  If you don't want to
        see the messages, run _c_o_n_f_i_g_u_r_e with its standard output redirected to
        _/_d_e_v_/_n_u_l_l; for example,
                % ..//ccoonnffiigguurree  ----ssyyssccoonnffddiirr==//eettcc ----qquuiieett
                %

        There is a known problem with GCC 2.8.3 and HP/UX.  You will need to
        set CFLAGS = -O in the generated Makefile.  (The configure script sets
        it to CFLAGS = -O2.)  This is because the code optimization breaks the
        fingerprints.  If test 32 fails (see below) this is probably the
        reason.

        There is a known problem with IRIX builds.  You need to use the
        following configuration
                # systune ncargs 0x8000
        to increase the length of command lines.

        For mips IRIX and IRIX64 using the MipsPro compiler up to at least
        version 7.3 you must specify the flag to allow -I for loop
        initializations. You may give either of:
                CXXFLAGS='LANG:ansi-for-init-scope=ON'
                CXXFLAGS='LANG:std'
        Also required is _-_l_C_i_o but configure will test for that. Even using
        that library there remains a link failure due to:
                Unresolved text symbol
                "std::_List_base<undo_item*,std::allocator<undo_item*> >::clear(void)"
        on several of the binaries. A work around for this problem is not
        known at this time.

        By default, _c_o_n_f_i_g_u_r_e will arrange for the _m_a_k_e _i_n_s_t_a_l_l command to
        install the aaeeggiiss package's files in _/_u_s_r_/_l_o_c_a_l_/_b_i_n,
        _/_u_s_r_/_l_o_c_a_l_/_c_o_m_/_a_e_g_i_s, _/_u_s_r_/_l_o_c_a_l_/_l_i_b_/_a_e_g_i_s, _/_u_s_r_/_l_o_c_a_l_/_m_a_n and
        _/_u_s_r_/_l_o_c_a_l_/_s_h_a_r_e_/_a_e_g_i_s.  There are a number of options which allow you
        to control the placement of these files.

        --prefix=_P_A_T_H
                This specifies the path prefix to be used in the installation.
                Defaults to _/_u_s_r_/_l_o_c_a_l unless otherwise specified.  The rest
                of these building instructions assume you are using the
                default _/_u_s_r_/_l_o_c_a_l as the install prefix.

        --exec-prefix=_P_A_T_H
                You can specify separate installation prefixes for
                architecture-specific files and architecture-independent
                files.  Defaults to _$_{_p_r_e_f_i_x_} unless otherwise specified.

        --bindir=_P_A_T_H
                This directory contains executable programs.  On a network,
                this directory may be shared between machines with identical
                hardware and operating systems; it may be mounted read-only.
                Defaults to _$_{_e_x_e_c___p_r_e_f_i_x_}_/_b_i_n unless otherwise specified.

        --datadir=_P_A_T_H
                This directory contains installed data, such as the
                documentation, reports and shell scripts distributed with
                Aegis.  On a network, this directory may be shared between all
                machines; it may be mounted read-only.  Defaults to
                _$_{_p_r_e_f_i_x_}_/_s_h_a_r_e_/_a_e_g_i_s unless otherwise specified.  An "aegis"
                directory will be appended if there is none in the specified
                path.

        --libdir=_P_A_T_H
                This directory contains installed data, such as the error
                message catalogues.  On a network, this directory may be
                shared between machines with identical hardware and operating
                systems; it may be mounted read-only.  Defaults to
                _$_{_e_x_e_c___p_r_e_f_i_x_}_/_l_i_b_/_a_e_g_i_s unless otherwise specified.  An
                "aegis" directory will be appended if there is none in the
                specified path.

        --mandir=_P_A_T_H
                This directory contains the on-line manual entries.  On a
                network, this directory may be shared between all machines; it
                may be mounted read-only.  Defaults to _$_{_p_r_e_f_i_x_}_/_m_a_n unless
                otherwise specified.

        --sharedstatedir=_P_A_T_H
                This directory contains share state information, such as the
                Aegis lock file, and information on the location of the
                various Aegis projects.  On a network, this directory may be
                shared between all machines; it MUST be mounted READ-WRITE.
                Defaults to _$_{_p_r_e_f_i_x_}_/_c_o_m_/_a_e_g_i_s unless otherwise specified.
                An "aegis" directory will be appended if there is none in the
                specified path.

        --sysconfdir=_P_A_T_H
                Location of system configuration files.  You should almost
                always use the _/_e_t_c directory.

        _c_o_n_f_i_g_u_r_e ignores any other arguments that you give it.

        On systems that require unusual options for compilation or linking
        that the _a_e_g_i_s package's _c_o_n_f_i_g_u_r_e script does not know about, you can
        give _c_o_n_f_i_g_u_r_e initial values for variables by setting them in the
        environment.  In Bourne-compatible shells, you can do that on the
        command line like this:
                $ CCCC==''ggcccc --ttrraaddiittiioonnaall'' LLIIBBSS==--llppoossiixx \
                  ..//ccoonnffiigguurree ----ssyyssccoonnffddiirr==//eettcc
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                $
        Here are the _m_a_k_e variables that you might want to override with
        environment variables when running _c_o_n_f_i_g_u_r_e.

        Variable: CC
                C compiler program.  The default is _c_c.

        Variable: INSTALL
                Program to use to install files.  The default is _i_n_s_t_a_l_l if
                you have it, _c_p otherwise.

        Variable: LIBS
                Libraries to link with, in the form -l_f_o_o -l_b_a_r.  The
                _c_o_n_f_i_g_u_r_e script will append to this, rather than replace it.

        If you need to do unusual things to compile the package, the author
        encourages you to figure out how _c_o_n_f_i_g_u_r_e could check whether to do
        them, and mail diffs or instructions to the author so that they can be
        included in the next release.

   CCoommmmoonn PPrroobblleemm
        It is very common that other packages, such as _g_e_t_t_e_x_t, _r_x and _z_l_i_b
        are installed using _/_u_s_r_/_l_o_c_a_l as the prefix.  However, the configure
        script can't work this out, even when it, too, is using _/_u_s_r_/_l_o_c_a_l as
        the prefix.

        To cope with this, you need to say
                $ CCPPPPFFLLAAGGSS==--II//uussrr//llooccaall//iinncclluuddee LLDDFFLLAAGGSS==--LL//uussrr//llooccaall//lliibb \
                  ..//ccoonnffiigguurree ----ssyyssccoonnffddiirr==//eettcc
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                $
        when running configure.  Substitute the appropriate prefix if you are
        using something other than the default _/_u_s_r_/_l_o_c_a_l prefix.  Watch the
        output... it should now find your installed packages correctly.

   GGCCCC VVeerrssiioonn 33..**
        On some operating systems, notabley MacOsX Jaguar and Panther, g++
        versions 3.* will produce link-time errors complaining of missing
        typeinfo symbols.  The only known fix for this problem is to use GCC
        version 2.95, 2.96 or 4.*.  This means MacOsX Tiger does not have the
        problem.

   AAIIXX CCoommmmaanndd LLiinnee LLeennggtthhss
        For some reason, AIX has a very short command line length limit by
        default.  You can extend this by using the command
                $ ssyyssttuunnee nnccaarrggss 00xx88000000
                $
        You will need to do this to build Aegis.  It has some very long link
        lines.

   PPRRIIVVIILLEEGGEESS
        There are a number of items in the generated _M_a_k_e_f_i_l_e and
        _c_o_m_m_o_n_/_c_o_n_f_i_g_._h file which affect the way _a_e_g_i_s works.  If they are
        altered too far, _a_e_g_i_s will not be able to function correctly.

        AEGIS_MIN_UID
                This specifies the minimum unprivileged uid on your system.
                UIDs less than this may not own projects, or play any other
                role in an aegis project.  The default value is 100.

        AEGIS_MIN_GID
                This specifies the minimum unprivileged GID on your system.
                GIDs less than this may not own projects, or play any other
                role in an aegis project.  The default value is 10.

        AEGIS_USER_UID
                This is the owner of files used by _a_e_g_i_s to record pointers to
                your projects.  It is _n_o_t used to own projects (i.e. it must
                be less than AEGIS_MIN_UID).  If possible, the _c_o_n_f_i_g_u_r_e
                script tries to work out what value was used previously, but
                you must specify the --prefix option correctly for this to
                work.  Because of operating system inconsistencies, this is
                specified numerically so that _a_e_g_i_s will work across NFS.  The
                default value is 3.

        AEGIS_USER_GID
                This is the group of files used by _a_e_g_i_s to record pointers to
                your projects.  It is _n_o_t used as the group for projects (i.e.
                it must be less than AEGIS_MIN_GID).  If possible, the
                _c_o_n_f_i_g_u_r_e script tries to work out what value was used
                previously, but you must specify the --prefix option correctly
                for this to work.  Because of operating system
                inconsistencies, this is specified numerically so that _a_e_g_i_s
                will work across NFS.  The default value is 3.

        DEFAULT_UMASK
                When _a_e_g_i_s runs commands for you, or creates files or
                directories for you, it will use the defined project umask.
                This is a project attribute, and may be altered using the
                _a_e_p_a(1) command.  The DEFAULT_UMASK is the umask initially
                given to all new projects created by the _a_e_n_p_r(1) command.
                The default value of DEFAULT_UMASK is 026.  See the comments
                in the _c_o_m_m_o_n_/_c_o_n_f_i_g_._h file for an explanation of the
                alternatives.

        It is required that _a_e_g_i_s run set-uid-root for all of its
        functionality to be available.  It is NOT possible to create an
        "aegis" account and make _a_e_g_i_s run set-uid-aegis.  This is because
        _a_e_g_i_s does things as various different user IDs, sometimes as many as
        3 in the one command.  This allows _a_e_g_i_s to use UNIX security rather
        than inventing its own, and also allows _a_e_g_i_s to work across NFS.  To
        be able to do these things, _a_e_g_i_s must be set-uid-root.  Appendix D of
        the _A_e_g_i_s _U_s_e_r _G_u_i_d_e explains why _a_e_g_i_s must run set-uid-root; please
        read it if you have concerns.

   RReemmeemmbbeerr YYoouurr SSeettttiinnggss
        It is important to remember your configuration settings.  This way, it
        will be a simple matter when it comes time to upgrade Aegis.

BBUUIILLDDIINNGG AAEEGGIISS
        All you should need to do is use the
                % mmaakkee
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                %
        command and wait.  When this finishes you should see a directory
        called _b_i_n containing several files: _a_e_g_i_s, _a_e_r_e_p_o_r_t, _a_e_f_i_n_d, _a_e_f_p,
        and _f_m_t_g_e_n.

        aaeeggiiss   The _a_e_g_i_s program is a project change supervisor.

        aaeeffpp    The _a_e_f_p program may be used to "fingerprint" files.  It is
                used to test Aegis (see the testing section, below) but it
                isn't installed.

        aereport
                The _a_e_r_e_p_o_r_t program is used to query Aegis' database.

        aefind  The _a_e_f_i_n_d program is used to find files.

        ffmmttggeenn  The _f_m_t_g_e_n program is a utility used to build the _a_e_g_i_s
                package; it is not intended for general use and should not be
                installed.

        You can remove the program binaries and object files from the source
        directory by using the
                % mmaakkee cclleeaann
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                %
        command.  To remove all of the above files, and also remove the
        _M_a_k_e_f_i_l_e and _c_o_m_m_o_n_/_c_o_n_f_i_g_._h and _c_o_n_f_i_g_._s_t_a_t_u_s files, use the
                % mmaakkee ddiissttcclleeaann
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                %
        command.

        The file _a_u_x_/_c_o_n_f_i_g_u_r_e_._i_n is used to create _c_o_n_f_i_g_u_r_e by a GNU program
        called _a_u_t_o_c_o_n_f.  You only need to know this if you want to regenerate
        _c_o_n_f_i_g_u_r_e using a newer version of _a_u_t_o_c_o_n_f.

   UUppggrraaddiinngg
        When upgrading from one release to a newer one, it is important that
        all of the machines on your network are running the same release of
        Aegis.  This minimizes the possibility of database incompatibilities.
        In general, Aegis is backwards compatible with earlier releases, but
        not forwards compatible in the face of new capabilities.

OOTTHHEERR UUSSEEFFUULL SSOOFFTTWWAARREE
        Before describing how to test _a_e_g_i_s, you may need to grab some other
        free software, because the tests require it in some cases, and because
        it is generally useful in others.

        GNOME libxml2
                The GNOME libxml2 library (http://xmlsoft.org/) is used to
                parse XML.  Version 1.8.17 or later.  You do not have to
                install the rest of GNOME as this library is able to be used
                by itself.  This package is nnoott optional, you need it to
                successfully build Aegis.

        ccooookk    This is a dependency maintenance tool (DMT).  An example of a
                well-known DMT is _m_a_k_e(1), however this old faithful is mostly
                not sufficiently capable to meet the demands placed on it by
                the _a_e_g_i_s program, but _c_o_o_k certainly is.  The _c_o_o_k package is
                written by the same author as _a_e_g_i_s.  The _c_o_o_k package is
                necessary if test 11 is to be meaningful.  It is also used in
                the documentation.  The _c_o_o_k program may be found at the same
                archive site as the _a_e_g_i_s program.  The _c_o_o_k program is
                available under the terms of the GNU General Public License.

        GNU diff
                If the _d_i_f_f(1) utility supplied by your flavor of Unix does
                not have the --cc option, you will need GNU diff for _a_e_p_a_t_c_h(1)
                to work (and the _a_e_p_a_t_c_h(1) tests to pass).  Context
                differences are also helpful for reviewing changes.  GNU diff
                is essential for Solaris, because the Solaris diff has bugs
                that Aegis' tests uncover.

        GNU patch
                For best results with the _a_e_p_a_t_c_h(1) and _a_e_d_i_s_t_(_1_) _w_h_e_n
                _r_e_c_e_i_v_i_n_g _c_h_a_n_g_e _s_e_t_s_, _y_o_u _n_e_e_d _t_h_e _G_N_U _p_a_t_c_h _u_t_i_l_i_t_y_.

        _R_C_S     This is a source control package, and is available from any of
                the GNU archives.  (It is best to compile and install RCS
                _a_f_t_e_r GNU diff.  This is because the RCS configuration hard-
                codes the pathnames of the GNU diff utilities it needs into
                the RCS executables.)  This package isn't essential as Aegis
                comes with its own _a_e_s_v_t(1) history tool - although you are
                free to use any history tool you like.

        GNU Gettext
                Many systems do not yet supply the _g_e_t_t_e_x_t(3) function.  Aegis
                uses this function to internationalize its error messages.  If
                your system does not have this function, you should fetch and
                install GNU Gettext _b_e_f_o_r_e running the _c_o_n_f_i_g_u_r_e script.  If
                you do not, Aegis will still work, but the error messages will
                be rather terse, even for English speakers.  (You will be able
                to tell if your system has the internationalization library
                and functions, because the _c_o_n_f_i_g_u_r_e script will report
                finding -lintl and _(_C_W_l_i_b_i_n_t_l_._h and msgfmt in its running
                commentary.)  Please note that the GNU Gettext implementation
                is likely to be superior to the one supplied with your system,
                if any.  Remember to use the GNU gettext configure _-_-_w_i_t_h_-_g_n_u_-
                _g_e_t_t_e_x_t option if your system has native gettext tools.

                Please note: if you install GNU gettext package into
                _/_u_s_r_/_l_o_c_a_l (for example) you must ensure that the Aegis
                _._/_c_o_n_f_i_g_u_r_e script is told to also look in _/_u_s_r_/_l_o_c_a_l_/_i_n_c_l_u_d_e
                for include files (CFLAGS), and _/_u_s_r_/_l_o_c_a_l_/_l_i_b for library
                files (LDFLAGS).  Otherwise the _._/_c_o_n_f_i_g_u_r_e script will
                incorrectly conclude that GNU Gettext has not been installed.

                GNU Gettext version 0.11.1 or later is recommended.

        GNU Groff
                This GNU software replaces the documentation tools which
                (sometimes) come with UNIX.  They produce superior error
                messages, and support a wider range of functionality and
                fonts.  The _A_e_g_i_s User Guide was prepared with GNU Groff.  You
                need GNU Groff 1.14 or later.

        bison   This GNU software is a replacement for _y_a_c_c(1).  Some systems
                have very sick yaccs, and _b_i_s_o_n may be necessary if your
                system include files disagree strongly with your system's
                yacc.  The generated _M_a_k_e_f_i_l_e will use bison if you have it.

        fhist   This software, available under the terms of the GNU General
                Public License, is a set of file history and comparison
                utilities.  It was originally written by David I. Bell, and is
                based on the minimal difference algorithm by Eugene W. Myers.
                This copy is enhanced and maintained by the same author as
                _A_e_g_i_s, and may be found at the same archive site, in the same
                directory.

        rx      This library provides POSIX regular expressions, for systems
                which don't have them.  (Note: test 81 will fail if the POSIX
                regular expression functions are not available.)

        zlib    This library provides access to the GNU Zip (de)compression
                algorithm(s).  It is essential to have this installed before
                you build Aegis.  The home page may be found at
                http://www.gzip.org/zlib/ if you need to download it.  Note:
                this is not the same as zzlliibbcc which is Linux specific.

        tkdiff  This program shows the difference between two text files,
                nicely highlighted in color.  This is used by the _t_k_a_e_r and
                _a_e_c_o_m_p scripts (and probably others as they are contributed).
                By John M. Klassa, http://www.ede.com/free/tkdiff

        libmagic
                If _l_i_b_m_a_g_i_c(3) is present, the _a_e_g_e_t(1) CGI handler will use
                it to determine the MIME type of files.  This is installed by
                ffiillee version 4.0 and later (ftp://ftp.astron.com/pub/file/),
                and uses the same database as the _f_i_l_e(1) command.  If this
                library is not present when Aegis is built, a much less
                accurate method will be used.

        The tests also depend on the presence of a number of common UNIX
        programs, including but not limited to: _c_c, _c_m_p, _d_i_f_f, _e_d, _f_i_n_d, _m_a_k_e,
        etc.  Depending on your version of UNIX, some or all of these programs
        may be in optional packages.  (This is especially true of Linux.)  You
        need to ensure that these programs are correctly installed before you
        run the tests.

TTEESSTTIINNGG AAEEGGIISS
        The _A_e_g_i_s program comes with a test suite.  To run this test suite,
        use the command
                % mmaakkee ssuurree
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                Passed All Tests
                %

        The tests take a minute or two each, with a few very fast, and a
        couple very slow, but it varies greatly depending on your CPU.

   KKnnoowwnn PPrroobblleemmss
        In order to get the long form of the error messages on Solaris, it is
        necessary to install GNU Gettext before running ./configure, and once
        ./configure has been run you need to edit the Makefile to statically
        link the executables.

        The _t_e_s_t_/_0_0_/_t_0_0_1_1_a_._s_h file assumes the _c_o_o_k(1) command by the author
        is somewhere in the command search path.  This test reproduces the
        example used in Chapter 3 of the User Guide.  If the _c_o_o_k(1) command
        is not available, this test gives a pass result without testing
        anything.

        If you are using HPUX and GCC, test 32 fails if you use -O2.  You need
        to edit the Makefile to only optimize at -O, delete the objects and
        rebuild.

        If you are using Solaris' diff, test 133 will report "no result".  You
        need to install GNU diff, because the Solaris diff has bugs.

        If you are using Sun's _t_m_p_f_s file system as your _/_t_m_p directory, the
        tests will fail.  This is because the _t_m_p_f_s file system does not
        support file locking.  Set the _A_E_G_I_S___T_M_P environment variable to
        somewhere else before running the tests.  Something like
                % sseetteennvv AAEEGGIISS__TTMMPP //uussrr//ttmmpp
                %
        is usually sufficient if you are using C shell, or
                $ AAEEGGIISS__TTMMPP==//uussrr//ttmmpp
                $ eexxppoorrtt AAEEGGIISS__TTMMPP
                $
        if you are using Bourne shell.  Remember, this must be done before
        running the tests.

        If the tests fail due to errors complaining of "user too privileged"
        you will need to adjust the _A_E_G_I_S___M_I_N___U_I_D defined in the
        _c_o_m_m_o_n_/_c_o_n_f_i_g_._h file.  Similarly for "group too privileged", although
        this is rarer.  This error message will also occur if you run the
        tests as root: the tests must be run as a mortal each time.

        If the POSIX regular expression functions are not available, test 81
        will fail.  The GNU rx library provides these.  Installing it and re-
        configuring and re-building Aegis will solve the problem.

TTEESSTTIINNGG SSEETT--UUIIDD--RROOOOTT
        If the _A_e_g_i_s program is not set-uid-root then it runs in "test" mode
        which gives you some confidence that _A_e_g_i_s is working before being
        tested again when it is set-uid-root.  Two pass testing like this
        means that you need not trust your system to a set-uid-root program
        which is not known to work.

        You will need to do a little of the install, to create the directory
        which will contain _A_e_g_i_s' lock file.  (Note that these building
        instructions assume you are using the default _/_u_s_r_/_l_o_c_a_l as the
        install prefix.  You will need to substitute as appropriate if you are
        using some other prefix.)
                # mmaakkee iinnssttaallll--lliibbddiirr
                mkdir /usr/local/lib/aegis
                chown 3 /usr/local/lib/aegis
                chgrp 3 /usr/local/lib/aegis
                chmod 0755 /usr/local/lib/aegis
                mkdir /usr/local/com/aegis
                chown 3 /usr/local/com/aegis
                chgrp 3 /usr/local/com/aegis
                chmod 0755 /usr/local/com/aegis
                chown root bin/aegis
                chmod 4755 bin/aegis
                #
        As you can see, the previous command also changed _A_e_g_i_s to be set-uid-
        root.  Once this has been done, _A_e_g_i_s should be tested again, in the
        same manner as before.
                % mmaakkee ssuurree
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                Passed All Tests
                %

        You should test _A_e_g_i_s as a mortal in both passes, rather than as root,
        to be sure the set-uid-root functionality is working correctly.

        It is required that _A_e_g_i_s run set-uid-root for all of its
        functionality to be available.  It is NOT possible to create an
        "aegis" account and make _A_e_g_i_s run set-uid-aegis.  This is because
        _A_e_g_i_s does things as various different user IDs, sometimes as many as
        3 in the one command.  This allows _A_e_g_i_s to use UNIX security rather
        than inventing its own, and also allows _A_e_g_i_s to work across NFS.  To
        be able to do these things, _A_e_g_i_s must be set-uid-root.  Appendix D of
        the _A_e_g_i_s _U_s_e_r _G_u_i_d_e explains why _A_e_g_i_s must run set-uid-root; please
        read it if you have concerns.

IINNSSTTAALLLLIINNGG AAEEGGIISS
        As explained in the _S_I_T_E _C_O_N_F_I_G_U_R_A_T_I_O_N section, above, the _A_e_g_i_s
        package is installed under the _/_u_s_r_/_l_o_c_a_l tree by default.  Use the
        --prefix=_P_A_T_H option to _c_o_n_f_i_g_u_r_e if you want some other path.

        All that is required to install the _A_e_g_i_s package is to use the
                % mmaakkee iinnssttaallll
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                %
        command.  Control of the directories used may be found in the first
        few lines of the _M_a_k_e_f_i_l_e file if you want to bypass the _c_o_n_f_i_g_u_r_e
        script.

        The above procedure assumes that the _s_o_e_l_i_m(1) command is somewhere in
        the command search _P_A_T_H.  The _s_o_e_l_i_m(1) command is available as part
        of the _G_N_U _G_r_o_f_f package, mentioned below in the _P_R_I_N_T_E_D _M_A_N_U_A_L_S
        section.  If you don't have it, but you do have the _c_o_o_k package, then
        a link from _r_o_f_f_p_p to _s_o_e_l_i_m will also work.

        The above procedure also assumes that the _$_(_p_r_e_f_i_x_)_/_m_a_n_/_m_a_n_1 and
        _$_(_p_r_e_f_i_x_)_/_m_a_n_/_m_a_n_5 directories already exist.  If they do not, you
        will need to _m_k_d_i_r them manually.

UUSSEERR CCOONNFFIIGGUURRAATTIIOONN
        The _A_e_g_i_s command is assumed to be in a generally accessible place,
        otherwise users will need to add the relevant directory to their PATH.
        Users should add
                source /usr/local/lib/aegis/cshrc
        to the end of their _._c_s_h_r_c file for the recommended aliases.  (Note
        that these building instructions assume you are using the default
        _/_u_s_r_/_l_o_c_a_l as the install prefix.  You will need to substitute as
        appropriate if you are using some other prefix.)

        There is also a _p_r_o_f_i_l_e for users of the Bourne shell (it assumes you
        have a version of the Bourne shell which has functions).  Users should
        add
                . /usr/local/share/aegis/profile
        to the end of their _._p_r_o_f_i_l_e file for the recommended aliases.  (This
        _p_r_o_f_i_l_e assumes that users are using a Bourne shell which understands
        functions.)

        The _/_u_s_r_/_l_o_c_a_l_/_c_o_m_/_a_e_g_i_s_/_s_t_a_t_e file contains pointers to "system"
        projects.  Users may add their own project pointers (to their own
        projects) by putting a search path into the _A_E_G_I_S___P_A_T_H environment
        variable.  The system part is always automatically appended by _A_e_g_i_s.
        The default, already set by the _/_u_s_r_/_l_o_c_a_l_/_l_i_b_/_a_e_g_i_s_/_c_s_h_r_c file, is
        _$_H_O_M_E_/_l_i_b_/_a_e_g_i_s.  Do not create this directory, _A_e_g_i_s is finicky and
        wants to do this itself.

        Where projects reside is completely flexible, be they system projects
        or user projects.  They are not kept under the _/_u_s_r_/_l_o_c_a_l_/_c_o_m_/_a_e_g_i_s
        directory, this directory only contains pointers.  (Note that these
        building instructions assume you are using the default _/_u_s_r_/_l_o_c_a_l as
        the install prefix.  You will need to substitute as appropriate if you
        are using some other prefix.)

   WWeebb IInntteerrffaaccee
        If you have a Web server, you may like to install the Aegis web
        interface.  You do this by copying the _a_e_g_e_t script from
        _/_u_s_r_/_l_o_c_a_l_/_b_i_n_/_a_e_g_e_t into your web server's _c_g_i_-_b_i_n directory.  There
        is a _a_e_g_e_t_._i_n_s_t_a_l helper script, if you don't know where your web
        server's _c_g_i_-_b_i_n directory is.

        You may prefer to use a symbolic link, as this will be more stable
        across Aegis upgrades.  However, this requires a corresponding _f_o_l_l_o_w_-
        _s_y_m_l_i_n_k_s setting in your web server's configuration file.  (Use the
        _a_e_g_e_t_._i_n_s_t_a_l _-_s option.)

        You may need to wrap _a_e_g_e_t with a script which sets the _A_E_G_I_S___P_A_T_H
        environment variable, if you want it to be able to see more projects
        than just the global projects.  You may also need to set the _P_A_T_H
        environment variable, if you don't have the Aegis install path in the
        default path.

        (Note that these building instructions assume you are using the
        default _/_u_s_r_/_l_o_c_a_l as the install prefix.  You will need to substitute
        as appropriate if you are using some other prefix.)

PPRRIINNTTEEDD MMAANNUUAALLSS
        This distribution contains the sources to all of the documentation for
        _A_e_g_i_s, however the simplest way to get the documentation is by
        anonymous FTP; PostScript files of the User Guide and Reference Manual
        are available from the FTP sites listed in the README file.

        The Reference Manual contains the README and BUILDING files, as well
        as all of the section 1 and section 5 manual pages.  The Reference
        Manual is about 200 pages long.

        The User Guide contains information about how to use Aegis, including
        a fully worked example.  The User Guide is about 100 pages long.

TTIIMMEE SSYYNNCCHHRROONNIIZZAATTIIOONN
        The _A_e_g_i_s program uses time stamps to remember whether various events
        have happened and when.  If you are using _A_e_g_i_s in a networked
        environment, typically a server and data-less workstations, you need
        to make absolutely sure that all of the machines agree about the time.

        If possible, use the time daemon.  Otherwise, use _r_d_a_t_e(8) via _c_r_o_n(8)
        every hour or less.

GGEETTTTIINNGG HHEELLPP
        If you need assistance with _A_e_g_i_s, please do not hesitate to contact
        the author at
                Peter Miller <millerp@canb.auug.org.au>
        Any and all feedback is welcome.

        When reporting problems, please include the version number given by
        the
                % aaeeggiiss --vveerrssiioonn
                aegis version _4_._2_4_._2_._D_0_0_1
                _._._.
                %
        command.  Please run this command to get the exact number, do not send
        the text of this example.

   RRuunnttiimmee CChheecckkiinngg
        In the _c_o_m_m_o_n_/_m_a_i_n_._h file, there is a define of _D_E_B_U_G in comments.  If
        the comments are removed, extensive debugging is turned on.  This
        causes some performance loss, but performs much run-time checking and
        adds the --TTRRAAccee command line option.

        When the --TTRRAAccee command line option is followed by one or more file
        names, it turns on execution traces in those source files.  It is
        usually best to place this on the end of the command line so that
        names of the files to be traced are not confused with other file names
        or strings on the command line.

   PPrroobblleemm RReeppoorrttss
        If you send email to the author, please include the following
        information:

        1. The type of UNIX
                The author will need to know the brand and version of UNIX you
                are using, or if it is not UNIX but something else.  The
                output of "uname -sr" is usually sufficient (but not all
                systems have it).

        2. The Version Number
                In any information you send, please include the version number
                reported in the _c_o_m_m_o_n_/_p_a_t_c_h_l_e_v_e_l_._h file, or `aegis -vers` if
                you can get it to compile.

        3. The Archive Site
                When and where you obtained this version of _A_e_g_i_s.  If you
                tell me nothing else, tell me this (and, hopefully, why you
                did nothing else).

        4. Unpacking
                Did you have problems unpacking _A_e_g_i_s?  This probably isn't a
                problem with the .tar.Z distribution, but you could have
                obtained a shar format copy.

        5. Building
                Did you have problems building _A_e_g_i_s?  This could have been
                the instructions included, it could have been the configure
                script, it could have been the Makefile, or anything else.

        6. Testing, Non-Set-Uid
                Did you have problems with the tests?  You could have had
                problems running them, or some of them could have failed.  If
                some tests fail but not others, please let me know _w_h_i_c_h ones
                failed, and include the fact that _A_e_g_i_s was nnoott set-uid-root
                at the time.  The -k option to _m_a_k_e can be useful if some
                tests fail but not others.

        7. Testing, Set-Uid-Root
                Did you have problems with the tests when _A_e_g_i_s was set-uid-
                root?  You could have had problems running them, or some of
                them could have failed.  If some tests fail but not others,
                please let me know _w_h_i_c_h ones failed, and include the fact
                that _A_e_g_i_s was set-uid-root at the time.

        8. Installation
                Did you have problems installing _A_e_g_i_s?  This could have been
                the instructions, or anything else.

        At this point it would probably be a very good idea to print out the
        manual entries and read them carefully.  You will also want to print a
        copy of the User Guide; if you don't have groff, there should be a
        PostScript copy at the archive site.  It is a known flaw that the User
        Guide is incomplete, contributions are most welcome.

        9. The Example Project
                After reading the User Guide, it is often useful to manually
                run through the example in chapter 3.  You will need to do
                more than one change, hopefully several; the first change is
                not representative of the system.  Did you manually do the
                example?  Did you find flaws in the User Guide or manual
                entries?

        10. Using Aegis
                Did you have problems using _A_e_g_i_s?  This is a whole can of
                worms.  If possible, include a shell script similar to the
                tests which accompany _A_e_g_i_s, which reproduces the bug.  Exit
                code 1 on failure (bug), exit code 0 on success (for when bug
                is fixed).

        11. The Source Code
                Did you read the code?  Did you write some code?  If you read
                the code and found problems, fixed them, or extended _A_e_g_i_s,
                these contributions are most welcome.  I reserve the right to
                modify or reject such contributions.

        The above list is inclusive, not exclusive.  Any and all feedback is
        greatly appreciated, as is the effort and interest required to produce
        it.

LLIICCEENNSSEE
        The _A_e_g_i_s program is free software; you can redistribute it and/or
        modify it under the terms of the GNU General Public License as
        published by the Free Software Foundation; either version 2 of the
        License, or (at your option) any later version.

        The _A_e_g_i_s program is distributed in the hope that it will be useful,
        but WITHOUT ANY WARRANTY; without even the implied warranty of
        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
        General Public License for more details.

        It should be in the _L_I_C_E_N_S_E file included in this distribution.

AAUUTTHHOORR
        Peter MillerE-Mail:   millerp@canb.auug.org.au
        /\/\*                                     WWW:   http://www.canb.auug.org.au/~millerp/

WWIINNDDOOWWSS--NNTT
        It is possible to build Aegis for Windows-NT.  I have only done this
        using the Cygnus freeware CygWin32 system, though it may be possible
        with other Unix porting layers also.

   CCaavveeaatt
        This document only describes a ssiinnggllee uusseerr port of Aegis to Windows
        NT.

        Aegis depends on the underlying security provided by the operating
        system (rather than re-invent yet another security mechanism).
        However, in order to do this, Aegis uses the POSIX _s_e_t_e_u_i_d(2) system
        call, which has no direct equivalent on Windows NT.  This makes
        porting difficult.  SSiinnggllee uusseerr ports are possible (_e_._g_. using Cygwin
        (http://www.cygwin.com/), but are not usually what folks want.

        Compounding this is the fact that many sites want to develop their
        software for both Unix and Windows NT simultaneously.  This means that
        the security of the repository needs to be guaranteed to be handled in
        the same way by both operating systems, otherwise one can act as a
        "back door" into the repository.  Many sites do not have the same
        users and permissions (sourced from the same network register of
        users) on both Unix and Windows NT, making the mapping almost
        impossible even if the security models did actually correspond.

        Most sites using Aegis and Windows NT together do so by running Aegis
        on the Unix systems, but building and testing on the NT systems.  The
        work areas and repository are accessed via Samba or NFS.

   TThhee SSoouurrccee
        You need to FTP the Cygwin system from RedHat.  It can be found at
                http://www.cygwin.com/
        and then follow the links.  The original version used was B20.1, but
        more recently 1.1.7 has been used.

        It is _a_b_s_o_l_u_t_e_l_y _e_s_s_e_n_t_i_a_l to run the _m_k_p_a_s_s_w_d and _m_k_g_r_o_u_p commands,
        otherwise Aegis will give fatal errors about unknown users and groups.
        See the Cygwin README for instructions.

   MMoouunnttiinngg TThhiinnggss
        You need to mount a directory onto /tmp, or lots of things, and
        especially _b_a_s_h(1), don't work.  If you are in a heavily networked
        environment, like me, you need to know that using a networked drive
        for /tmp just doesn't work.  I have no idea why.  Use
                mount C:/temp /tmp
        instead.  (Or some other local drive.)

        Just a tip for all of you who, like me, know Unix much better than you
        know Windows-NT: the left-hand mount argument needs to be specified
        with a drive letter (_e_._g_. C:_) _r_a_t_h_e_r _t_h_a_n _w_i_t_h _a _d_o_u_b_l_e _s_l_a_s_h _(_e_._g_.
        _n_o_t //C_) _u_n_l_e_s_s _i_t_s _W_i_n_d_o_w_s_-_N_T _n_a_m_e _s_t_a_r_t_s _w_i_t_h _\_\_.

        You need to follow the install instructions about _/_b_i_n_/_s_h, otherwise
        shell scripts that start with #!/bin/sh don't work, among other
        things.  This includes the ./configure script, and the scripts it
        writes (_e_._g_. config.status).

        You will want to mount your various network drives onto the same
        places they appear on your Unix hosts.  This way you don't need to
        learn two names for all your files.

        Mounts persist across Cygwin sessions.  They are stored in a registry
        file somewhere.  You will not need to do all this every time!

   TToooo MMuucchh AAddmmiinniissttrraattoorr
        If you have administrator privilege on your Windows NT box, you need
        to get rid of it.  (Have a second admin account instead.)  This is
        because Windows NT will make the files belong to the wrong user for
        files on _s_o_m_e partitions, like _/_t_m_p.  (This took me days to work out!)
        This confuses both Aegis _a_n_d RCS.

        If you get weird "Permission denied" errors from amazingly unlikely
        causes, this is probably why.

   BBeeffoorree YYoouu SSttaarrtt
        There are several pieces of software you need before you can build
        Aegis on Cygwin.

        I'm going to keep mentioning "your local GNU mirror".  You can find
                GNU at http://www.gnu.org, however you are better off using a
                local mirror, and these are scattered around the globe.
                Follow the "mirrors" link on their front page to find your
                closest mirror.  Also, it's often a good idea to configure
                these packages with the "--with-gnu-gettext" option to their
                ./configure commands.

        DDoo nnoott uussee WWiinnZZiipp to unpack the tarball.  It has a nasty habit of
                turning all of the newlines into CRLFs.  This will confuse
                _l_o_t_s of utilities, especially GNU Groff.  Use the "_t_a_r _x_z_f
                _a_e_g_i_s_-_4_._2_4_._2_._t_a_r_._g_z" command from within Cygwin.

        Make sure the Cygwin you are using has GNU Groff 1.15 or later
                (use a "groff -v" command).  Grab and install the latest from
                your local GNU mirror, if it isn't.

        util-linux
                You need to get GNU rx, but to make it work you have to find a
                _t_s_o_r_t command, so that GNU rx's _._/_c_o_n_f_i_g_u_r_e script works.  Try
                the latest copy of system/misc/util-linux-?.?.tar.gz from the
                metalab.unc.edu Linux archive (or a mirror).  Simply build and
                install _m_i_s_c_-_u_t_i_l_s_/_t_s_o_r_t_._c by hand.

        GNU rx  Once you have _t_s_o_r_t installed, you will be able to get GNU rx
                configured.  Get a copy from your local GNU mirror.

        zlib    You need to grab a copy of _z_l_i_b; the same source as works for
                Unix will work for Cygwin.  It will install as a static
                library.

        GNU diffutils
                You need GNU diffults, because when you come to configure GNU
                RCS (next) it would otherwise complain about a stupid _d_i_f_f and
                a missing _d_i_f_f_3 command.  The _i_n_s_t_a_l_l_-_s_h script is broken, so
                you'll need to do the final step in the install by hand.

        GNU RCS All of Aegis' tests assume RCS is present.  Also, you are
                going to need _s_o_m_e_t_h_i_n_g for a history tool.  The _i_n_s_t_a_l_l_-_s_h
                script is broken, so you'll need to do the final step in the
                install by hand.

   CCoonnffiigguurree
        The configure and build step should be the same as for Unix, as
        described above.  All the problems I encountered were to do with
        getting the mounts just right.  (But expect it to be dog slow compared
        to Linux or FreeBSD on the same box.)

        Sharutils
                You need the _u_u_d_e_c_o_d_e command for several of the tests, and
                this may be found in the GNU Sharutils package.  You can get a
                copy from your local GNU mirror.

        The configure step is almost the same as for Unix.  I know you are
        itching to get typing, but read through to the install section before
        you configure anything.
                bbaasshh$$ ./configure
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                bbaasshh$$

   BBuuiilldd
        The build step is exactly the same as for Unix, and you shouldn't
        notice any difference...
                bbaasshh$$ make
                bbaasshh$$

   TTeesstt
        The tests are run in the same way as the Unix tests, but you don't
        need to run the set-uid-root variants, because no such thing exists
        under Windows NT.
                bbaasshh$$ make sure
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                PPaasssseedd AAllll TTeessttss
                bbaasshh$$

        Unfortunately, it isn't that simple.  There are a number of things you
        will see go wrong...

        +o Several tests fail because _e_d isn't there.

        +o Several tests fail because _c_i (RCS 5.7) dumps core much too often
          for my liking.

        +o A couple of tests fail because they don't expect the ".exe"
          extension on executable files.

        +o A couple of tests (notably, the _a_e_d_i_s_t tests) fail because of the
          CRLF _v_s NL dichotomy.  This means that the expected results don't
          match, not that it isn't working.

        Despite all the bad news, the vast majority of tests pass, and the
        others have good excuses.

   IInnssttaallll
        Installing the software works as usual, though you need to make some
        choices right at the start (I told you to read this all the way
        through first).  If you want to use the "_/_u_s_r_/_l_o_c_a_l" prefix (or any
        other install prefix) you mount it right at the start.  For anything
        other than the "_/_u_s_r_/_l_o_c_a_l" default prefix, you also needed to give a
        "----pprreeffiixx==_b_l_a_h_b_l_a_h_" _a_r_g_u_m_e_n_t _t_o _t_h_e _c_o_n_f_i_g_u_r_e _s_c_r_i_p_t_, _r_i_g_h_t _a_t _t_h_e
        _s_t_a_r_t_.
                bbaasshh$$ _m_a_k_e _i_n_s_t_a_l_l
                _._._._l_o_t_s _o_f _o_u_t_p_u_t_._._.
                bbaasshh$$



Reference Manual                     Aegis                        Build(Aegis)
