


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 Peter Miller; All rights reserved.

        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 defence.

SSPPAACCEE RREEQQUUIIRREEMMEENNTTSS
        You will need up to 15MB to unpack and build the _a_e_g_i_s
        program.  (This is the worst case seen so far, most
        systems have binaries about 60% as big as this, 10MB 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.

   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 the compression library
        and functions.  If your system does not have them, it is
        worth fetching and installing GGNNUU zzlliibb compression
        library before you run the _c_o_n_f_i_g_u_r_e script.  (See
        http://www.cdrom.com/pub/infozip/zlib/ for download.)
        This is essential, becaise Aegis will not build.  without
        it.  (NNoottee:: tthhiiss iiss nnoott tthhee ssaammee tthhiinngg aass zlibcc wwhhiicchh
        ddooeess ssoommeetthhiinngg ccoommpplleetteellyy ddiiffffeerreenntt..))

        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.)

   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
                _._._._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
                _._._._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,
                % ./configure --quiet
                %

        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.

        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.

        --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.

        _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
                _._._._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CF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
                _._._._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 _/_u_s_r_/_l_o_c_a_l.
        Watch the output... it should now find your installed
        packages correctly.

   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.

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, _f_i_n_d___s_i_z_e_s 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fiinndd__ssiizzeess
                The _f_i_n_d___s_i_z_e_s 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.

        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.

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.

        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.

        RCS     This is a source control package, and is
                available from any of the GNU archives.  The
                tests use RCS as the history mechanism, so it is
                necessary to have RCS for most of the tests to
                pass.  (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.)

        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 not been installed.

        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.cdrom.com/pub/infozip/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

        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edd, _f_i_n_d, _m_a_k_e, the _R_C_S package, 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
        The tests assume that the RCS commands "ci", "co", "rlog"
        and "rcs" are somewhere in the command search PATH.

        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.
                # 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.  (This may be in a different place, if you
        specified a --prefix option.)

        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.

        If you have a Web server, and the aegis.cgi was
        installed, you can set its _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 do this by creating a
        _/_u_s_r_/_l_o_c_a_l_/_l_i_b_/_a_e_g_i_s_._c_g_i_._c_o_n_f file (there isn't one, by
        default) and setting the _A_E_G_I_S___P_A_T_H environment variable
        in it.  This is a fragment of Bourne shell script, not
        just the name.

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 _3_._2_8
                _._._.
                %
        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 gave groff, there should be a PostScript copy
        at the archive site.  It is a known flaw that the User
        Guide is incomplete, it is something the author is
        working on "at this moment".

        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 Miller   E-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_-_3_._2_8_._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                             1

















































