Man Linux: Main Page and Category List

NAME

       aepconf - aegis project configuration file

SYNOPSIS

       project/baseline/aegis.conf (default)
       project/baseline/config (obsolete)

DESCRIPTION

       A project configuration file is used to store information about a
       project.  This file is under source control, and is one of the
       project’s source files.  Developers may thus modify this file as part
       of a change.

       As of aegis.4.17, it is possible to assign any arbitrary name to the
       project configuration file or files.  See aenf(1) for more information.

       This file contains a number of commands to be executed by Aegis.  There
       are times when the substitutions in these commands may contain shell
       special characters, which would change the meaning of the commands in
       unintended ways.  There are two main sources of these problems: file
       names and architecture names.  In order to have shell special
       characters in filenames, you must set the shell_safe_filenames field
       (see below) to false.  If you do this, you will need to use the quote
       substitution (see aesub(5)) to quote them, so that the shell does not
       abuse them.  Other things which may need quoting include architecture
       names if you get creative, and edit numbers if unusual ones are
       generated by your history tool.

   Getting Started
       Because the project aegis.conf file is under source control like any
       other file, you must create the project aegis.conf file in the very
       first change of your project.  Use the
              $ aenf aegis.conf
              $
       command and then editing the file to fill in the fields.  Subsequent
       Aegis commands in that change will use that file.  Once the change is
       completed (see aeipass(1) for more information) the file will be
       present in the baseline, and be used by all users and all changes.

       If you ever need to change one of the fields of the project aegis.conf
       file, you do this the same way as for any other source file, by copying
       it into a change using the
              $ aecp aegis.conf
              $
       command and then edit the file to make the desired changes.  While it’s
       being developed your change will use it’s copy of the project
       aegis.conf file, but once the change is completed (see aeipass(1) for
       more information), it becomes the new version used by all users and
       changes.

       If you would prefer a different name for the project configuration
       file, use the aenf -config option.  For example, the
              $ aenf -config project.configuration
              $
       command would create a file called project.configuration and Aegis
       would then proceed to use it to obtain project configuration
       information for the duration of the project.  This attribute will even
       be preserved across file renames (see the aemv(1) command).

CONTENTS

       This file contains the following fields:

       configuration_directory = string;
               This field names a directory which will be searched for
               additional configuration files.  (This directive is only legal
               or meaningful in the master project aegis.conf file.)

               All source files (change source files and project source files)
               present in this directory will be read in as if they were added
               to the end of the project "aegis.conf" file.

               The usual priority of files (development directory, branch
               baseline, etc, project trunk baseline) is observed when these
               files are read.

               Please note that the physical directories are never searched,
               only the Aegis concept of the change and project files is
               consulted (i.e.  files created and modified in the usual way
               with aenf(1) and aecp(1) commands).  Placing additional files
               in the physical directories will have no effect.

               It is recommended that if you use this field at all, that your
               top level project aegis.conf file should only contain this one
               field.  This is to avoid overly-large re-reading of this file
               when it is joined to all the others.

       build_command = string;
               This field describes how to build the project (actually, how to
               do an integration build).  This field is mandatory.  Used by
               the aeb(1) command.  All of the substitutions described by
               aesub(5) are available.

               Executed as: the integrator (for integration builds) or the
               developer (for development builds).  Current directory: the
               integration directory of the change (for integration builds)
               the development directory of the change (for development
               builds).  Exit status: zero is considered success, non-zero is
               a failure and a subsequent successful (exit zero) build will be
               required.

               If this field is set to "exit 0" then no integration build will
               be required, and will not be checked for by the aeipass(1)
               command.

       development_build_command = string;
               This field describes how to do a development build.  If this
               field is absent, it defaults to the above.  Used by the aeb(1)
               command.  All of the substitutions described by aesub(5) are
               available.

               Executed as: the developer.  Current directory: the development
               directory of the change.  Exit status: zero is considered
               success, non-zero is a failure and a subsequent successful
               (exit zero) build will be required.

               If this field is set to "exit 0" then no development build will
               be required, and will not be checked for by the aede(1)
               command.

       development_directory_style = { ... };
               This field encapsulates a set of parameters controlling the
               appearance of the development directory.  It has significant
               implications for the way the DMT is used, and the directory
               appearance presented to the DMT.

               source_file_link = boolean;
                       This field is true if hard links are to be used for
                       project source files (which are not part of the change)
                       so that the work area has a complete set of source
                       files.

                       Defaults to false if not set.

                       If the host system does not have hard links, this field
                       will be ignored.

                       Maintaining the hard links can be time consuming for
                       large projects, and add quite a noticeable delay before
                       builds start doing anything.  If possible, change your
                       build system to use the $search_path substitution
                       instead and avoid links.

               source_file_symlink = boolean;
                       This field is true if symbolic links are to be used for
                       project source files (which are not part of the change)
                       so that the work area has a complete set of source
                       files.

                       Defaults to false if not set.  [If the obsolete
                       create_symlinks_before_build field is set, defaults to
                       the value of that field, with a warning.]

                       If (source_file_link == true and hard links are
                       available) this field will be ignored.  If the host
                       system does not have symbolic links, this field will be
                       ignored.

                       Maintaining the symbolic links can be time consuming
                       for large projects, and add quite a noticeable delay
                       before builds start doing anything.  If possible,
                       change your build system to use the $search_path
                       substitution instead and avoid symbolic links.

               source_file_copy = boolean;
                       This field is true if copies are to be used for project
                       source files (which are not part of the change) so that
                       the work area has a complete set of source files.  File
                       modification time attributes will be preserved.

                       Defaults to false if not set.

                       If ((source_file_link == true and hard links are
                       available) OR (source_file_symlink == true and symbolic
                       links are available)) this field will be ignored.

                       Maintaining the copies can be time consuming (and space
                       consuming) for large projects, and add quite a
                       noticeable delay before builds start doing anything.
                       If possible, change your build system to use the
                       $search_path substitution instead and avoid file
                       copies.

               source_file_whiteout = boolean;
                       The source_file_whiteout field mat be used to specify
                       the presence (true) or absence (false) of white-out
                       files, used to "cover up" files being removed by a
                       change set.  These files contain 1kB of random data,
                       intended to cause a syntax error should be build
                       reference them.

                       It is rarely necessary to explicitly set this field.
                       It defaults to false if you set any of the
                       source_file_link, source_file_symlink or
                       source_file_copy to true; it defaults to true only if
                       none of them are true.

                       Not meaningful (always false) for integration builds.

               derived_file_link = boolean;
                       This field is true if hard links are to be used for
                       non-source files which are present in the project
                       baseline(s) but which are not present in the work area,
                       so that the work area has a complete set of derived
                       files.  This allows work areas to take advantage of
                       "precompiled" object files (etc) in the baseline(s).

                       Defaults to false if not set.

                       If the host system does not have hard links, this field
                       will be ignored.

                       Maintaining the links can be time consuming for large
                       projects, and add quite a noticeable delay before
                       builds start doing anything.  If possible, change your
                       build system to use the $search_path substitution
                       instead and avoid hard links.  Alternatively, set
                       derived_at_start_only = true; and your work area will
                       get a "head start" but the derived files will not be
                       checked for every build, but this will occasionally
                       result in long build times after integrations.

                       See also the integrate_begin_exceptions and symlink_
                       exceptions fields (they apply to hard links as well as
                       symbolic links).

               derived_file_symlink = boolean;
                       This field is true if symbolic links are to be used for
                       non-source files which are present in the project
                       baseline(s) but which are not present in the work area,
                       so that the work area has a complete set of derived
                       files.  This allows work areas to take advantage of
                       "precompiled" object files (etc) in the baseline(s).

                       Defaults to false if not set.  [If the obsolete
                       create_symlinks_before_build field is set, defaults to
                       the value of that field, with a warning.]

                       If (derived_file_link == true and hard links are
                       available) this field will be ignored.  If the host
                       system does not have symbolic links, this field will be
                       ignored.

                       Maintaining the symbolic links can be time consuming
                       for large projects, and add quite a noticeable delay
                       before builds start doing anything.  If possible,
                       change your build system to use the $search_path
                       substitution instead and avoid symbolic links.
                       Alternatively, set derived_at_start_only = true; and
                       your work area will get a "head start" but the derived
                       files will not be checked for every build, occasionally
                       resulting in long build times after integrations.

                       See also the integrate_begin_exceptions and symlink_
                       exceptions fields.

               derived_file_copy = boolean;
                       This field is true if copies are to be used for non-
                       source files which are present in the project
                       baseline(s) but which are not present in the work area,
                       so that the work area has a complete set of derived
                       files.  This allows work areas to take advantage of
                       "precompiled" object files (etc) in the baseline(s).

                       Defaults to false if not set.

                       If ((derived_file_link == true and hard links are
                       available) or (derived_file_symlink == true and
                       symbolic links are available)) this field will be
                       ignored.

                       Maintaining the copies can be time consuming (and space
                       consuming) for large projects, and add quite a
                       noticeable delay before builds start doing anything.
                       If possible, change your build system to use the
                       $search_path substitution instead and avoid symbolic
                       links.  Alternatively, set derived_at_start_only =
                       true; and your work area will get a "head start" but
                       the derived files will not be checked for every build,
                       occasionally resulting in long build times after
                       integrations.

                       See also the integrate_begin_exceptions and
                       symlink_exceptions fields (they apply to copies as well
                       as symbolic links).

               during_build_only = boolean;
                       This field is set to true if you want the symbolic
                       links, hard links and/or copies removed again after
                       each build.  This allows the user to maintain the
                       illusion of using a search path, without actually doing
                       so.  This option is not especially efficient.

                       Defaults to false if not set.  [If the obsolete
                       remove_symlinks_after_build field is set, defaults to
                       the value of that field, with a warning.]

                       If this field is false, the development directory will
                       be populated by the develop begin (aedb) command, and
                       the integration directory will be populated by the
                       integrate begin (aeib) command.

               derived_at_start_only = boolean;
                       This field controls whether the above fields
                       controlling the appearance of derived files are acted
                       upon before every build (false) or only when the work
                       area is created (true).

                       Defaults to false if not set.

                       This field is ignored if the during_build_only field is
                       true.

               This field can be complex.  Here are a few examples; but much,
               much more is possible.  The first example will get you a
               development directory very similar to one presented by CVS:
                      development_directory_style =
                      {
                          source_file_copy = true;
                      };
               Note that this is hugely space inefficient, and can be quite
               slow.  The second example will get you a development directory
               very similar to one presented by Tom Lord’s arch:
                      development_directory_style =
                      {
                          source_file_link = true;
                          source_file_symlink = true;
                          source_file_copy = true;
                      };
               Ideally, however, you should use the $search_path substitution
               of the build_command field.  This is because the view path
               scales better than any other method.  On the other hand, you
               need a DMT with an excellent view path implementation (and GNU
               make doesn’t).

       integration_directory_style = { ... };
               This field encapsulates a set of parameters controlling the
               appearance of the integration directory.  It has significant
               implications for the way the DMT is used, and the directory
               appearance presented to the DMT.

               Defaults to the value of the development_directory_style field
               if not set.  Note that the obsolete create_symlinks_before_
               integration_build and remove_symlinks_after_integration_build
               fields affect this default (with a warning) but only if they
               are explicitly set.

               Note that the link_integration_directory field is still
               relevant.  That field controls how the baseline is cloned to
               form the integration directory.  This field operates after that
               operation.

       build_time_adjust_notify_command = string;
               This command is run when Aegis adjusts the last-time-modified
               time-stamp on files in the integration directory.  If the build
               tool uses additional information to supplement file
               modification times, this command gives you the opportunity to
               re-sync the associated database.

               Executed as: the project owner.

               Current directory: the integration directory.  This is what is
               about to be come the new baseline.

               Exit status: NOT ignored. Note that a failure here puts the
               change in a partial state from which recovery may be difficult.
               Best to define this command with a set+e so that errors are
               ignored at the command level.

       build_covers_all_architectures = boolean;
               This field is set to true if the build command, when executed
               on any architecture, results in all architectures being built.
               This may be accomplished, for example, by using cross-
               compilation techniques, or Cook’s ability to nominate hosts on
               which to execute each build rule.

       test_covers_all_architectures = boolean;
               This field is set to true if the test command, when executed on
               any architecture, results in all architectures being tested.
               This may be accomplished, for example, by using Cook’s ability
               to nominate hosts on which to execute each test rule.

       symlink_exceptions = [ string ];
               This field is used to list filename patterns for which symbolic
               links must not be made between the development directory and
               the baseline.  These are usually state files for various tools.
               The patterns are matched against the whole filename; naming
               only the last filename path element will not work (unless the
               pattern starts with “*”).

       change_file_command = string;
               This field contains a command to be executed whenever a ´aegis
               -CoPy_file´, ´aegis -New_File´ ´aegis -New_Test´ ´aegis
               -MoVe_file´ or ´aegis -ReMove_file´ command is successful.  See
               also command-specific overrides.  If this field is absent,
               nothing is done.  Used by the aecp(1), aenv(1), aenf(1),
               aerm(1), and aemv(1) commands.  All of the substitutions
               described by aesub(5) are available; in addition,

               ${File_List}
                       Space separated list of files named.

               Executed as: the developer.  Current directory: the development
               directory of the change.  Exit status: ignored.

       change_file_undo_command = string;
               This field contains a command to be executed whenever a ´aegis
               -CoPy_file_Undo’, ´aegis -MoVe_file_Undo’ ´aegis
               -New_File_Undo’, ´aegis -New_Test_Undo’, or ´aegis
               -ReMove_file_Undo’ command is successful.  Default to change_
               file_command if absent.  See also command-specific overrides.
               If both fields are absent, nothing is done.  Used by the
               aecpu(1), aemvu(1), aenfu(1), aentu(1) or aermu(1), commands.
               All of the substitutions described by aesub(5) are available;
               in addition,

               ${File_List}
                       Space separated list of files named.

               Executed as: the developer.  Current directory: the development
               directory of the change.  Exit status: ignored.

       new_file_command = string;
               Executed whenever the aegis -new_file command is run
               successfully.  Defaults to ‘change_file_command’ if not set.

               All of the substitutions described in aesub(5) are available.
               In addition:

               ${File_List}
                      Space separated list of files named (at times, can be
                      empty).

               Executed as: the developer.  Current directory: the development
               directory of the change.  Exit status: ignored.

       new_test_command = string;
               Executed whenever the aegis -new_test command is run
               successfully.  Defaults to ‘change_file_command’ if not set.

               All of the substitutions described in aesub(5) are available.
               In addition:

               ${File_List}
                      Space separated list of files named (at times, can be
                      empty).

               Executed as: the developer.  Current directory: the development
               directory of the change.  Exit status: ignored.

       copy_file_command = string;
               Executed whenever the aegis -copy_file command is run
               successfully.  Defaults to ‘change_file_command’ if not set.

               All of the substitutions described in aesub(5) are available.
               In addition:

               ${File_List}
                      Space separated list of files named (at times, can be
                      empty).

               Executed as: the developer.  Current directory: the development
               directory of the change.  Exit status: ignored.

       remove_file_command = string;
               Executed whenever the aegis -remove_file command is run
               successfully.  Defaults to ‘change_file_command’ if not set.

               All of the substitutions described in aesub(5) are available.
               In addition:

               ${File_List}
                      Space separated list of files named (at times, can be
                      empty).

               Executed as: the developer.  Current directory: the development
               directory of the change.  Exit status: ignored.

       new_file_undo_command = string;
               Executed whenever the aegis -new_file_undo command is run
               successfully.  Defaults to change_file_undo_command if not set.

               All of the substitutions described in aesub(5) are available.
               In addition:

               ${File_List}
                      Space separated list of files named (at times, can be
                      empty).

               Executed as: the developer.  Current directory: the development
               directory of the change.  Exit status: ignored.

       new_test_undo_command = string;
               Executed whenever the aegis -new_test_undo command is run
               successfully.  Defaults to change_file_undo_command if not set.

               All of the substitutions described in aesub(5) are available.
               In addition:

               ${File_List}
                      Space separated list of files named (at times, can be
                      empty).

               Executed as: the developer Current directory: the development
               directory of the change Exit status: ignored

       copy_file_undo_command = string;
               Executed whenever the aegis -copy_file_undo command is run
               successfully.  Defaults to change_file_undo_command if not set.

               All of the substitutions described in aesub(5) are available.
               In addition:

               ${File_List}
                      Space separated list of files named (at times, can be
                      empty).

               Executed as: the developer Current directory: the development
               directory of the change Exit status: ignored

       remove_file_undo_command = string;
               Executed whenever the aegis -remove_file_undo command is run
               successfully.  Defaults to change_file_undo_command if not set.

               All of the substitutions described in aesub(5) are available.
               In addition:

               ${File_List}
                      Space separated list of files named (at times, can be
                      empty).

               Executed as: the developer Current directory: the development
               directory of the change Exit status: ignored

       make_transparent_command = string;
               The make_transparent_command is executed whenever the aegis
               -make_transparent command is run successfully.  Defaults to
               change_file_command if not set.

               All of the substitutions described in aesub(5) are available.
               In addition:

               ${File_List}
                      Space separated list of files named (at times, can be
                      empty).

               Executed as: the developer Current directory: the development
               directory of the change Exit status: ignored

       make_transparent_undo_command = string;
               The make_transparent_undo_command is executed whenever the
               aegis -make_transparent_undo command is run successfully.
               Defaults to change_file_undo_command if not set.

               All of the substitutions described in aesub(5) are available.
               In addition:

               ${File_List}
                      Space separated list of files named (at times, can be
                      empty).

               Executed as: the developer Current directory: the development
               directory of the change Exit status: ignored

       project_file_command = string;
               This field contains a command to be executed during a
               development build before the development build command above,
               when (a) it is the first build after a develop begin, or (b)
               some other change has been integrated into the baseline since
               the last build.  If this field is absent, nothing is done.
               Used by the aeb(1) command.  All of the substitutions described
               by aesub(5) are available.

       develop_begin_command = string;
               This field contains a command to be executed whenever a ’aegis
               -Develop_Begin’ command is successful.  If this field is
               absent, nothing is done.  Used by the aedb(1) command.  All of
               the substitutions described by aesub(5) are available.

               Executed as: the developer.  Current directory: the development
               directory of the change.  Exit status: ignored.

       develop_begin_undo_command = string;
               This field contains a command to be executed whenever a ’aegis
               -Develop_Begin_Undo’ command is successful.  If this field is
               absent, nothing is done.  Used by the aedbu(1) command.  All of
               the substitutions described by aesub(5) are available.

               Executed as: the developer.  Current directory: wherever the
               command was executed from.  Exit status: ignored.

       integrate_begin_command = string;
               This field contains a command to be executed whenever a ’aegis
               -Integrate_Begin’ command is successful.  If this field is
               absent, nothing is done.  Used by the aeib(1) command.  All of
               the substitutions described by aesub(5) are available.

               Executed as: the project owner.  Current directory: the
               integration directory.  Exit status: ignored.

       link_integration_directory = boolean;
               This flag is true if Aegis should link the files from the
               baseline into the integration directory, rather than copy them
               (the default).  This has risks, as the build script (e.g.
               Howto.cook or Makefile, etc) must unlink targets before
               rebuilding them; if this is not done the baseline will be
               corrupted.  Used by the aeib(1) command.

       integrate_begin_exceptions = [ string ];
               This field may be used to specify a list of file names (and
               file name patterns) which are to be omitted from the copy
               (link) of the baseline when creating the integration directory.
               Used by the aeib(1) command.  This field only applies to
               derived files, it does not apply to source files.  The patterns
               are matched against the whole filename; naming only the last
               filename path element will not work (unless the pattern starts
               with “*”).

       history_create_command = string;
               This field is used to create a new history.  The command is
               always executed as the project owner.  Used by the aeipass(1)
               command.

               It is strongly recommended that the history_create_command and
               history_put_command fields are identical.  If not set, the
               history_create_command field defaults to the same value as the
               history_put_command field.

               All of the substitutions described by aesub(5) are available;
               in addition,

               ${Input}
                       Absolute path of the source file.

               ${History}
                       Absolute path of the history file.  This may need to be
                       reworked with the Dirname and Basename substitutions to
                       yield a string suitable for the history tool in
                       question.

               ${File_Name}
                       The base relative file name of the file for this check-
                       in.  Note that the file name can vary over the lifetime
                       of the file as it is renamed, but the history file name
                       (above) never varies.  Do not use this as the name of
                       the history file.  (Optional)

               ${UUID} The universally unique identifier of the source file.
                       This is invariant for the lifetime of the file.  Do not
                       use use this as the name of the history file.
                       (Optional)

               See also the history_put_trashes_file field, below.

               Executed as: the project owner.  Current directory: the base of
               the history tree.  Exit status: zero indicates success, all
               non-zero exits indicate failure (the integrate pass will fail).

       history_get_command = string;
               This field is used to get a file from history.  The command may
               be executed by developers.  Used by the aeipass(1) and aecp(1)
               commands.  All of the substitutions described by aesub(5) are
               available; in addition,

               ${History}
                       The absolute path of the history file.  This may need
                       to be reworked with the Dirname and Basename
                       substitutions to yield a string suitable for the
                       history tool in question.

               ${Edit}
                       The edit number to be extracted.  It may be an
                       arbitrary string, varying on the particular history
                       tool.

               ${Output}
                       The absolute path of the destination file.

               Executed as: the developer (or the executing user, in the case
               of the -independent option).  Current directory: the base of
               the history tree Exit status: zero indicates success, all non-
               zero exits indicate failure (the aecp will fail).

       history_put_command = string;
               This field is used to add a new change to the history.  The
               command is always executed as the project owner.  Used by the
               aeipass(1) command.

               It is strongly recommended that the history_put_command and
               history_create__command fields are identical.  If not set, the
               history_put_command field defaults to the same value as the
               history_create_command field.

               All of the substitutions described by aesub(5) are available;
               in addition,

               ${Input}
                       The absolute path of the source file.

               ${History}
                       The absolute path of the history file.  This may need
                       to be reworked with the Dirname and Basename
                       substitutions to yield a string suitable for the
                       history tool in question.

               ${File_Name}
                       The base relative file name of the file for this check-
                       in.  Note that the file name can vary over the lifetime
                       of the file as it is renamed, but the history file name
                       (above) never varies.  Do not use this as the name of
                       the history file.  (Optional)

               ${UUID} The universally unique identifier of the source file.
                       This is invariant for the lifetime of the file.  Do not
                       use use this as the name of the history file.
                       (Optional)

               See also the history_put_trashes_file field, below.

               Executed as: the project owner.  Current directory: the base of
               the history tree.  Exit status: zero indicates success, all
               non-zero exits indicate failure (the integrate pass will fail).

       history_transaction_begin_command = string;
               The history_transaction_begin_command field is used to specify
               a command to be run by aeipass(1) before any history create or
               history put commands are run.  The default is to do nothing.

               All of the substitutions described in aesub(5) are available.
               If you need a transaction ID, use the $version substitution.

               Executed as: the project owner.  Current directory: the base of
               the history tree.  Exit status: zero indicates success, all
               non-zero exits indicate failure (the integrate pass will fail).

       history_transaction_end_command = string;
               The history_transaction_end_command field is used to specify a
               command to be run by aeipass(1) after any history create or
               history put commands are run, but before any history query
               commands are run.  The default is to do nothing.

               All of the substitutions described in aesub(5) are available.
               If you need a transaction ID, use the $version substitution.

               Executed as: the project owner.  Current directory: the base of
               the history tree.  Exit status: zero indicates success, all
               non-zero exits indicate failure (the integrate pass will fail).

       history_transaction_abort_command = string;
               The history_transaction_abort_command field is used to specify
               a command to be run by aeipass(1) to indicate that a
               transaction has been abandoned.  The default is to do nothing.

               All of the substitutions described in aesub(5) are available.
               If you need a transaction ID, use the $version substitution.

               Executed as: the project owner.  Current directory: the base of
               the history tree.  Exit status: ignored (the integrate pass has
               already failed).

       history_query_command = string;
               This field is used to query the topmost edit of a history file.
               Result to be printed on the standard output.  This command may
               be executed by developers.  Used by the aeipass(1) and aecp(1)
               commands.  All of the substitutions described by aesub(5) are
               available; in addition,

               ${History}
                       The absolute path of the history file.  This may need
                       to be reworked with the Dirname and Basename
                       substitutions to yield a string suitable for the
                       history tool in question.

               Executed as: the project owner.  Current directory: the base of
               the history tree.  Exit status: zero indicates success, all
               non-zero exits indicate failure (the integrate pass will fail).

       history_label_command = string;
               This field contains a command to be executed whenever a
               aeipass(1) or aedn(1) command is successful.  This command is
               invoked for every file in the project.  So using it incurs a
               performance penalty.  If this field is absent, nothing is done.
               All of the substitutions described by aesub(5) are available;
               in addition,

               ${History}
                       The absolute path of the history file.

               ${Edit}
                       The edit number to be labeled.  It may be an arbitrary
                       string, varying on the particular history tool.

               ${Label}
                       The label to  be attached to the history.  When
                       executed from aeipass(1) this value is the same as
                       ${Version}, which may need to be reworked with the
                       ${Subst} substitutions to yield a string suitable for
                       the history tool in question.  When executed from
                       aedn(1) it is set to the value passed in from the
                       command line.

               Executed as: the project owner.  Current directory: the base of
               the history tree.  Exit status: zero indicates success, all
               non-zero exits indicate failure (a warning will be issued).

               Labeling does not scale, so the use of this command is not
               encouraged.  If you have a project with 10,000 files, and a
               change modified exactly one of them, only one history_put_
               command execution is required, which operates on one history
               file.  If you have labeling turned on, it will also be
               necessary to execute 10,000 history_label_commands, to add
               information Aegis will never use.

       history_put_trashes_file = (fatal, warn, ignore);
               Many history tools (e.g. RCS) can modify the contents of the
               file when it is committed.  While there are usually options to
               turn this off, they are seldom used.  The problem is: if the
               commit changes the file, the source in the repository now no
               longer matches the object file in the repository - i.e. the
               history tool has compromised the referential integrity of the
               repository.

               fatal
                   Emit a fatal error if one or more source files are modified
                   by a history_put_command or history_create_command.  This
                   is the default.

               warn
                   Emit a warning if a source file is modified.

               ignore
                   Ignore a source file changing.  You sure better hope it was
                   only in a comment!

       history_content_limitation = (ascii_text, international_text,
       binary_capable);
               This field describes the content style which the history tool
               is capable of working with.

               ascii_text
                       The history tool can only cope with files which contain
                       printable ASCII characters, plus space, tab and
                       newline.  The file must end with a newline.  This is
                       the default.

               international_text
                       The history tool can only cope with files which do not
                       contain the NUL character.  The file must end with a
                       newline.

               binary_capable
                       The history tool can cope with all files without any
                       limitation on the form of the contents.

               When a file is added to the history (by either the history_
               create_command or the history_put_command field) it is examined
               for conformance to this limitation.  If there is a problem, the
               file is encoded in either quoted printable for MIME64,
               whichever is smaller, before being given to the history tool.
               This encoding is transparent, the file in the baseline is
               unchanged.

               On extract (the history_get_command field) the encoding is
               reversed, using information attached to the change file
               information.  This is because each put could use a different
               encoding (although in practice, file contents rarely change
               that dramatically, and the same encoding is likely to be
               deduced every time).

               Please note that this field does not apply to the diff_command
               or merge_command fields.

       diff_command = string;
               This field is used to difference of 2 files.  The command is
               always executed by developers.  Used by the aed(1) command.
               All of the substitutions described by aesub(5) are available;
               in addition,

               ${ORiginal}
                       The absolute path of the original file copied into the
                       change.  Usually in the baseline, but not always.

               ${Input}
                       The absolute path of the file in the development
                       directory.

               ${Output}
                       The absolute path of the file in which to write the
                       difference listing.

               Executed as: the project owner (for integration diffs), or the
               developer (for development diffs).  Current directory: the
               integration directory (for integration diffs), or the
               development directory (for development diffs).  Exit status:
               zero indicates success, all non-zero exits indicate failure
               (the aed will fail).

               Note: It is possible to configure a project to omit the diff
               step as unnecessary, by the following setting:
                      diff_command = "exit 0";
               This disables all generation, checking and validation of
               difference file for each change source file.  The merge
               functions of the aediff(1) command are unaffected by this
               setting.

       merge_command = string;
               This field is used to merge two competing edits to a file.  The
               command is always executed by developers.  The current
               directory will be the development directory.  This field is
               used by the aed(1) command.  All of the substitutions described
               by aesub(5) are available; in addition,

               ${ORiginal}
                       The absolute path of the original file copied into the
                       change.  Usually not in the baseline, often a temporary
                       file.

               ${Most_Recent}
                       The absolute path of the competing edit, usually in the
                       baseline.

               ${Input}
                       The absolute path of the file in the development
                       directory.  This is the “preferred” edit, if the tool
                       has this concept when highlighting conflicting edits.

               ${Output}
                       The absolute path of the file in which to write the
                       merged result.  This will usually be the name if a
                       change source file in the development directory.

               It is important that this command does not move files around.
               (See the obsolete diff3_command field, below, for some
               history.)

               Executed as: the project owner (for integration diffs), or the
               developer (for development diffs).  Current directory: the
               integration directory (for integration diffs), or the
               development directory (for development diffs).  Exit status:
               zero indicates success, all non-zero exits indicate failure
               (the aed will fail).

       patch_diff_command = string;
               The difference of 2 files, to send around as a patch.  (This
               isn’t the same as diff_command, because it’s aimed at GNU
               Patch, not at humans.)  The command is always executed by
               developers.  Used by the aepatch(1) command.

               Defaults to "set +e; diff -c -L $index -L $index $original
               $input > $output; test $? -le 1" if not set.

               All of the substitutions described by aesub(5) are available;
               in addition,

               ${ORiginal}
                       The absolute path of the original file copied into the
                       change.  Usually in the baseline, but not always.

               ${Input}
                       The absolute path of the file in the development
                       directory.

               ${Output}
                       The absolute path of the file in which to write the
                       difference listing.

               ${INDex}
                       The project-relative name of the file, for use when the
                       file name is embedded in the output.  (Optional.)

               Executed as: the project owner (for integration diffs), or the
               developer (for development diffs).  Current directory: the
               integration directory (for integration diffs), or the
               development directory (for development diffs).  Exit status:
               zero indicates success, all non-zero exits indicate failure
               (the aed will fail).

       annotate_diff_command = string;
               The difference of 2 files, for the use of the aeannotate(1)
               command.  (This isn’t the same as the diff_command field,
               because it’s aimed at aeannotate(1), not at humans.)  The
               command is always executed by developers.  Used by the
               aeannotate(1) command.

               Extreme care should be taken if you are considering setting
               this field, otherwise the result reported by aeannotate(1) may
               bear little relation to reality.  The most useful option is GNU
               diff’s --ignore-all-space option, which will have the effect of
               ignoring the majority of indenting and code formatting changes.
               The --ignore-case option could also be useful for case
               insensitive languages such as FORTRAN or PL/1.  Avoid options
               which would alter the number of lines, such as - -ignore-blank-
               lines or --context as these will produce misleading results.

               Defaults to "set +e; diff $option $original $input > $output;
               test $? -le 1" if not set.

               All of the substitutions described by aesub(5) are available;
               in addition,

               ${ORiginal}
                       The absolute path of the original file copied into the
                       change.  Usually in the baseline, but not always.

               ${Input}
                       The absolute path of the file in the development
                       directory.

               ${Output}
                       The absolute path of the file in which to write the
                       difference listing.

               ${INDex}
                       The project-relative name of the file, for use when the
                       file name is embedded in the output.  (Optional.)

               ${OPTion}
                       Extra options to be passed to the diff command, as set
                       by the aeannotate(1) -diff-option command line option.
                       Use with extreme care.

               Executed as: the project owner (for integration diffs), or the
               developer (for development diffs).  Current directory: the
               integration directory (for integration diffs), or the
               development directory (for development diffs).  Exit status:
               zero indicates success, all non-zero exits indicate failure
               (the aed will fail).

       review_policy_command = string;
               This field is used to set the command to be executed by the
               aerpass(1) command.  This command is useful in cases where the
               enterprise has determined that more than one review is
               necessary or that the reviewer must be senior to the developer,
               etc.  Defaults to "exit 0" if not set.

               The exit status is examined.  An zero exit status (success)
               means that the change will proceed to the awaiting integration
               state; a non-zero exit status (failure) means that the change
               requires further review state, and the develop_end_action is
               consulted to determine the appropriate state (awaiting_review
               or being_reviewed) for the change to move to.

               All of the substitutions described by aesub(5) are available.
               Of particular interest are ${Change_Developer_List} and
               ${Change_Reviewer_List} for passing the specific staff involved
               with the change.

               Executed as: the current reviewer.  Current directory: the
               development directory.  Exit status: zero indicates success,
               non-zero indicates failure.

               For example, to have a script which is a project source file to
               be used to gate the code review process, a setting such as the
               following may be used:
                      review_policy_command =
                          "$sh ${source script/reviewpolicy.sh} "
                          "-p $project -c $change "
                          "-d ${developer_list} "
                          "-r ${reviewer_list}"
                          ;
               This is only one of many ways to implement a project specific
               review policy.

       develop_end_policy_command = string;
               This field is used to set the command to be executed by the
               aede(1) command.  This command is useful in cases where the
               enterprise has determined that additional pre-conditions must
               be met (in addition to those already imposed by the aede(1)
               command) before a change may leave the being developed state.
               Defaults to "exit 0" if not set.

               The exit status is examined.  An zero exit status (success)
               means that the change may leave to the being developed state; a
               non-zero exit status (failure) means that the change requires
               further development.

               All of the substitutions described by aesub(5) are available.

               Executed as: the developer.  Current directory: the development
               directory.  Exit status: zero indicates success, non-zero
               indicates failure.

               There are some common validations available in the aede-
               policy(1) command; you may choose all or only some of them, or
               you may choose to write a policy command specific to your
               project.

       unchanged_file_develop_end_policy = (...);
               This field may be used to control what happens when development
               of a change is ended, and the change contains files which have
               not had their contents or their attributes changed.

               ignore  Does not look for or warn about unchanged files.  This
                       the default.

               warning If the change sets contains unchanged files, a warning
                       will be issued for each one.

               error   If the change set contains unchanged files, an error
                       will be issued for each one, and develop end will not
                       complete (the change will remain in the being developed
                       state).

       unchanged_file_integrate_pass_policy = (...);
               This field may be used to control what happens when a change is
               completed, and the change contains files which have not had
               their contents or their attributes changed.

               ignore  Does not look for or warn about unchanged files.  The
                       file version will be added to the history.  This the
                       default.

               warning If the change sets contains unchanged files, a warning
                       will be issued for each one.  The file version will be
                       added to the history.

               remove  If the change set contains an unchanged file, it will
                       be silently removed from the change set.  The file
                       version will not be added to the history.  The project
                       file is unaffected.

       test_command = string;
               This field is used to set the command to be executed by the
               aet(1) command.  Defaults to "$shell $file_name" if not set.

               All of the substitutions described in aesub(5) are available.
               In addition:

               ${File_Name}
                       The absolute path of the test to be executed.

               ${Search_Path}
                       Colon separated list of directories to search for tests
                       and test support files.  (This is a normal aesub(5)
                       substitution.)

               ${Search_Path_Executable}
                       Colon separated list of directories to search for
                       executable files and executable support files.  Usually
                       it is the same as the above, except during an “aet -bl”
                       command.

               ${VARiables}
                       The text of name=value variable settings from the
                       command line, suitably quoted to protect special
                       character from the shell.  Will be appended to the end
                       of the command if not used explicitly.

               Note that tests are source files, and thus never have the
               execute bit set.

               Executed as: the project owner (for integration tests) or the
               developer (for development tests), or the executing user (for
               -independent tests).  Current directory: the integration
               directory (for integration tests), the development directory
               (for development tests), the project baseline (for -bl tests),
               or the current directory (for -independent tests).  Exit
               status: zero indicates success, one indicates failure, anything
               else indicates "no result".

       development_test_command = string;
               This field is used to set the command to be executed by the
               aet(1) command when a change is in the being developed state.
               Defaults to be the same as the test_command field if not set.

               Note: It is a significantly bad idea to make tests behave
               differently in being development and being integrated states;
               avoid this at all costs.

               All of the substitutions described in aesub(5) are available.
               In addition:

               ${File_Name}
                       The absolute path of the test to be executed.

               ${File_Name}
                       The absolute path of the test to be executed.

               ${Search_Path}
                       Colon separated list of directories to search for tests
                       and test support files.  (This is a normal aesub(5)
                       substitution.)

               ${Search_Path_Executable}
                       Colon separated list of directories to search for
                       executable files and executable support files.  Usually
                       it is the same as the above, except during an “aet -bl”
                       command.

               ${VARiables}
                       The text of name=value variable settings from the
                       command line, suitably quoted to protect special
                       character from the shell.  Will be appended to the end
                       of the command if not used explicitly.

               Note that tests are source files, and thus never have the
               execute bit set.

               Executed as: the developer.  Current directory: the development
               directory (for development tests), the project baseline (for
               -bl tests).  Exit status: zero indicates success, one indicates
               failure, anything else indicates "no result".

       batch_test_command = string;
               This field is used to set the command to be executed by the
               aet(1) command, in preference to the test_command or
               development_test_command, if set.  It is capable of running
               more than one test at once.

               All of the substitutions described in aesub(5) are available.
               In addition:

               ${Output}
                      This is the name of the file to be generated to hold the
                      test results.  See aetest(5) for the format of this
                      file.
                      A space separated list of absolute paths of the tests to
                      be executed.

               ${File_Names}
                      The absolute path of the tests to be executed.

               ${File_Name}
                       The absolute path of the test to be executed.

               ${Search_Path}
                       Colon separated list of directories to search for tests
                       and test support files.  (This is a normal aesub(5)
                       substitution.)

               ${Search_Path_Executable}
                       Colon separated list of directories to search for
                       executable files and executable support files.  Usually
                       it is the same as the above, except during an “aet -bl”
                       command.

               ${Current}
                       Number of first test in the batch.

               ${Total}
                       Total number of tests. If this is 0 then no progress
                       messages should be issued.

               ${VARiables}
                       The text of name=value variable settings from the
                       command line, suitably quoted to protect special
                       character from the shell.  Will be appended to the end
                       of the command if not used explicitly.

               Note that tests are source files, and thus never have the
               execute bit set.

               It is strongly recommended that you design your test scripts so
               that they may be executed by either batch or non-batch methods.
               This permits simple migration when your environment changes.

               Executed as: the project owner (for integration tests) or the
               developer (for development tests), or the executing user (for
               -independent tests).  Current directory: the integration
               directory (for integration tests), the development directory
               (for development tests), the project baseline (for -bl tests),
               or the current directory (for -independent tests).  Exit
               status: zero indicates success, one indicates failure, anything
               else indicates "no result".

       architecture_discriminator_command = string;
               If this field is present it is used as a command to be executed
               in order to further identify the platform architecture (see
               below).  All of the substitutions described by aesub(5) are
               available;
               Executed as: the developer.  Current directory: the development
               directory of the change.  Exit status: zero indicates success,
               all non-zero exits indicate failure.

       architecture = [{ ... }];
               This field is a list of system and machine architectures on
               which each change must successfully build and test.  May be
               assigned more than once.  The structures listed have fields as
               follows:

               name = string;
                       The name of the architecture.  This name is available
                       in the ${ARCHitecture} substitution (see aesub(5) for
                       more information), as well as being used internally by
                       Aegis.  You may use almost any name for your
                       architecture, but it is best to avoid shell special
                       characters and white space, because it may be
                       substituted into commands to be executed by Aegis.

               pattern = string;
                       The system and machine architecture are determined by
                       using the uname(2) system call.  The uname(2) return
                       value is assembled into a string of the form "sysname-
                       release-version-machine", or "sysname-release-version-
                       machine-disc" if architecture_discriminator_command is
                       used.

                       The pattern field must match this uname result string.
                       The first match found is used.  The pattern is a shell
                       file name pattern, see sh(1) for more information.

                       For example, the pattern SunOS-4.1*-*-sun4* matches a
                       machine the author commonly uses, which returns
                       SunOS-4.1.3-8-sun4m from the uname(2) system call.

               mode = (required, optional, forbidden);
                       The mode field is used to control how the architecture
                       information is used.

                       required
                               Architectures of thus mode will be copied into
                               changes as their required architectures when
                               the change is created.  This is the default.

                       optional
                               Architectures of thus mode will not be copied
                               into changes as their required architectures
                               when the change is created.  However, if you
                               add them subsequently, they become required for
                               that change.

                       forbidden
                               Aegis will refuse to build or test on
                               architectures of this mode.

                       When a change is created, the required architecture
                       names are copied into the change’s architecture list.
                       Once names are in this list, they are required for the
                       change, and the project attributes are less relevant.

               If the architecture field is not set, it defaults to
                      architecture =
                      [
                              {
                                      name = "unspecified";
                                      pattern = "*";
                                      mode = required;
                              }
                      ];

       file_template = [ { ... } ];
               The file template is consulted whenever a new file is created,
               by one of the aenf(1) or aent(1) commands.  May be assigned
               more than once.  Each list item has the form:

               pattern = [ string ];
                       The name of the file, relative to the development
                       directory.  Each string is a shell file name pattern;
                       see sh(1) for more information.  The patterns are
                       matched against the whole filename; naming only the
                       last filename path element will not work (unless the
                       pattern starts with “*”).

               body_command = string;
                       Command to run to initialize the body of the file.
                       Executed as: the developer.  Current directory: the
                       development directory of the change.  Exit status:
                       ignored.

               body = string;
                       What to initialize the body of the file to.

               All of the substitutions described in aesub(5) are available
               for the body and body_command strings.  (Only specify one of
               them.)  In addition:

               ${File_Name}
                       will be replaced by the name of the new file.

       whiteout_template = [ { ... } ];
               The file template is consulted whenever a file is removed, by
               one of the aerm(1) or aemv(1) commands.  It is used to place a
               “whiteout” entry in the development directory, in order to
               induce compile errors of the removed file is referenced during
               the build.  Each list item has the form:

               pattern = [ string ];
                       The name of the file, relative to the development
                       directory.  Each string is a shell file name pattern;
                       see sh(1) for more information.  The patterns are
                       matched against the whole filename; naming only the
                       last filename path element will not work (unless the
                       pattern starts with “*”).

               body = string;
                       What to initialize the body of the file to.  If not
                       present, no whiteout file will be created; if the empty
                       string, a zero-length whiteout file will be created.

               All of the substitutions described in aesub(5) are available
               for the body string.  In addition:

               ${File_Name}
                       will be replaced by the name of the removed file.

               If the name of the file being removed does not match any of the
               filename patterns, a file consisting of 1KB of very ugly
               garbage will be generated.  The idea is that it will produce a
               syntax error for most languages if you try to run it, compile
               it, or include it.

       maximum_filename_length = integer;
               This field is used to limit the length of file names.  All new
               files may not have path components longer than this.  Existing
               files are not affected.  The last component must also allow for
               the ",D" suffix of difference files.  Where this value is
               larger than the file system allows, the file system limit will
               be imposed.  Defaults to 255 if not set.  Legal values range
               from 9 to 255.

               The file name lengths of project files will be checked at
               develop end if the project aegis.conf file is in the change.
               See aede (1) for more information.

       posix_filename_charset = boolean;
               This field may be used to limit the characters allowed in file
               names to only those explicitly allowed by POSIX.  Defaults to
               false if not set.

               For a filename to be portable across conforming implementations
               of IEEE Std 1003.1-1988, it shall consist only of alphanumeric
               characters, dot, hyphen or underscore.  Hyphen shall not be
               used as the first character of a portable filename.

               If this field is false, all characters are allowed except non-
               printing characters, space characters and leading hyphens.

       dos_filename_required = boolean;
               This field may be used to limit file names so that they conform
               to the DOS 8+3 filename limits and to the DOS filename
               character set.  Also denies file names which look like devices
               (AUX, etc).  Defaults to false if not set.  This field is used
               in combination with the other filename fields, it does not
               replace them.

       windows_filename_required = boolean;
               This field may be used to limit file names so that they conform
               to the Windows98 and WindowsNT filename limits and character
               set.  Also denies file names which look like devices (AUX,
               etc).  Defaults to false if not set.  This field is used in
               combination with the other filename fields, it does not replace
               them.

       shell_safe_filenames = boolean;
               This field may be used to limit file names so that they may not
               contain shell special characters.  If you do not set this to
               true, you will need to use the ${quote} substitution around
               file names in commands, or risk unexpected errors.

               This field defaults to true if not set.

               The white space characters (space, tab, newline, etc) are
               considered shell special characters.

       allow_white_space_in_filenames = boolean;
               This field may be used to allow white space characters in file
               names.  This will allow the following characters to appear in
               filenames: backspace (BS, \b, 0x08), horizontal tab (HT, \t,
               0x09), new line (NL, \n, 0x0A), vertical tab (VT, \v, 0x0B),
               form feed (FF, \f, 0x0C), and carriage return (CR, \r, 0x0D).

               Defaults to false if not set.

               Note that this field does not override other file name filters.
               It will be necessary to explicitly set shell_safe_filenames =
               false as well.  It will be necessary to set dos_filename_
               required = false (the default) as well.  It will be necessary
               to set posix_filename_charset = false (the default) as well.

               The user must take great care to use the ${quote} substitution
               around all file names in commands in the project configuration.
               And even then, substitutions which expect a space separated
               list of file names will have undefined results.

       allow_non_ascii_filenames = boolean;
               This field may be used to allow file names with non-ascii-
               printable characters in them.  Usually this would mean a UTF8
               or international charset of some kind.

               Defaults to false if not set.

               Note that this field does not override other file name filters.
               It will be necessary to explicitly set shell_safe_filenames =
               false as well.  It will be necessary to set dos_filename_
               required = false (the default) as well.  It will be necessary
               to set posix_filename_charset = false (the default) as well.

       filename_pattern_accept = [ string ];
               This field is used to specify a list of patterns of acceptable
               file names.  The patterns are matched against each filename
               path element.  The patterns are constructed from the usual
               shell filename wild-cards.  Defaults to "*" if not set.

       filename_pattern_reject = [ string ];
               This field is used to specify a list of patterns of
               unacceptable file names.  The patterns are matched against each
               filename path element.  The patterns are constructed from the
               usual shell filename wild-cards.  Defaults to "*,D" if not set.
               The pattern "*,D" is always appended.  Where the
               filename_pattern_accept and filename_pattern_reject fields
               conflict, the reject takes precedence.

       new_test_filename = string;
               This field is used to form the filename of new tests, where the
               filename is not specified on the aent command line.  Defaults
               to "test/${zpad $hundred 2}/t${zpad $number 4}${left $type
               1}.sh" if not set.

               All of the substitutions defined in aesub(5) are available.
               The following three substitutions are also available:

               $Hundred
                       The test number divided by 100, optional

               $Number The test number, mandatory

               $Type   The test type: "automatic" or "manual", optional

       development_directory_template = string;
               This field is used to determine the name of the development
               directory at develop begin.  All of the substitutions defined
               in aesub(5) are available.  The following substitutions is also
               available:

               Default_Development_Directory
                       The directory within which the development directory is
                       to be created.

               Magic   A single letter, starting from “C”, which can be
                       inserted.  This must be used, as it allows Aegis to try
                       different names should there be a conflict.

               If not set, defaults to "$ddd/${left $p ${expr ${namemax $ddd}
               - ${length .$magic$c}}}.$magic$c".

               For DOS compatibility (8+3 file names), a useful setting is
               "$ddd/${downcase ${left ${id $p} 8}.$magic${right 0$c 2}}".
               This ensures that the filename is always a valid 8.3 filename,
               that it is always lowercase, and it translates any punctuation
               in the project name into underscores.

       metrics_filename_pattern = string;
               This field is used to form the name of the metrics file, given
               a source file.  All of the substitutions defined in aesub(5)
               are available.  The following substitutions is also available:

               File_Name
                       The absolute path name of the source file.

               Defaults to "$filename,S" if not set.

       trojan_horse_suspect = [ string ];
               This list of filename patterns is consulted by aedist --receive
               when it is checking for files which could be used to host
               Trojan horse attacks.  This will be different for different
               projects, so you will need to update this yourself.  The
               patterns are matched against the whole filename; naming only
               the last filename path element will not work (unless the
               pattern starts with “*”).

       project_specific = [ { ... } ];
               This is a list of name and value pairs for use within the
               ${project-specific} substitution (see aesub(5) for more
               information).  May be assigned more than once.  The sub-fields
               are

               name = string;
                       The name of the value.  By convention, names which
                       start with an upper-case letter will appear in
                       listings, and lower-case will not.  Attribute names are
                       case-insensitive.

               value = string;
                       The value to be substituted.

               There are almost no limitations on the strings which may appear
               in either of these fields.

               There are several attribute names which are known to and used
               by Aegis, these include:

               aede-policy
                       This attribute is used when no policy names are listed
                       on the aede-policy(1) command line.

               aetar:exclude
                       This attribute is used by he aetar(1) receive command
                       to exclude files in tarballs from consideration.  This
                       is a space separated list of file names.

               html:meta
                       This attribute is used by the aeget(1) command to
                       customize generated web pages.  See aeget(1) for more
                       information.

               html:body-begin
                       This attribute is used by the aeget(1) command to
                       customize generated web pages.  See aeget(1) for more
                       information.

               html:body-end
                       This attribute is used by the aeget(1) command to
                       customize generated web pages.  See aeget(1) for more
                       information.

               copyright-owner
                       This string is available via the ${copyright-owner}
                       substitution, and is the one checked by the aede-
                       policy(1) command.  Only set this attribute if your
                       project is a work-for-hire under copyright law.  It
                       defaults to the value of ${user name} if not set, this
                       is almost always correct for Open Source projects.

               When commands are executed by Aegis, it ensures that the
               AEGIS_PROJECT, AEGIS_CHANGE, AEGIS_ARCH, LINES and COLS
               environment variables are set appropriately.  The project
               configuration file’s project_specific field is also consulted,
               looking for value’s whose name starts with "setenv:" and sets
               the corresponding environment variable.  All of the
               substitutions described by aesub(5) are available.  For
               example: specifying a PATH and a SEARCH_PATH to be used for all
               commands may be set as follows:
                      project_specific =
                      [
                        {
                          name = "setenv:PATH";
                          value = "/usr/bin:/bin";
                        },
                        {
                          name = "setenv:SEARCH_PATH";
                          value = "${search_path}";
                        },
                      ];
               As many environment variables as desired may be specified in
               this way.

       build_time_adjust = (...);
               This field controls the adjustment of file modification times
               at the end of integrate-pass.  File times are adjusted so that
               development directories are, in the main, out of date with
               respect to the baseline.  The idea is that, at the very least,
               programs need to be re-linked so that aet -reg does not give
               false negatives.

               Combining this with the project_file_command (above) can
               alleviate the vast majority of file modification time
               inconsistencies experienced as a result of a project
               integration and the subsequent changes in the baseline’s file
               modification times.

               Unless you are a masochist, do not set this field.  Leave it as
               the default.

               adjust_and_sleep
                       Causes the file times to be adjusted, and if the file
                       times would extend into the future, aeipass will sleep
                       until that time has passed.  This is the default.

               adjust_only
                       Causes the file times to be adjusted.  If the file time
                       extend into the future, a warning is issued.

               dont_adjust
                       File modification times are not adjusted.  This is a
                       really bad idea.  Really.  Make sure that, at the very
                       minimum, project_file_command touches all of the
                       change’s files, otherwise the build problems which
                       ensue are going to take you weeks to track down and
                       lose you much productivity.  You have been warned.

               See also the build_time_adjust_notify_command field.

       signed_off_by = boolean;
               If this field is set each aedb(1), aechown(1), aede(1) and
               aerpass(1) will append a Signed-off-by line to the change
               description.  This field should only be set to true for open
               source projects.

               For a description of Signed-off-by see
               http://www.ussg.iu.edu/hypermail/linux/kernel/0405.2/.html
               and
               http://www.osdl.org/newsroom/press_releases/2004/2004_05_24_dco.html

       cache_project_file_list_for_each_delta = boolean;
               It is possible to have Aegis cache the list of project files
               that were present at integrate pass for each delta (integrated
               change set).  This is used to optimize all project-history-
               based operations, such as aecp -delta or aepatch(1).

               This cache will optimize many operations which would otherwise
               require time to reconstruct the project state using the roll-
               forward data available in each change set.  However, it comes
               at the cost of disk space, and not everyone can afford more and
               more disk.

               This field defaults to true if not set.

       clean_exceptions = [ string ];
               It is possible to have Aegis exclude from the clean process any
               file that match one of the pattern listed in the
               clean_exceptions list.

               This field default to an empty list if not set.

       cache_project_file_list_for_each_delta = boolean;
               It is possible to have Aegis cache the list of project files
               that were present at integrate pass for each delta (integrated
               change set).  This is used to optimize all project-history-
               based operations, such as aecp -delta or aepatch(1).

               This cache will optimize many operations which would otherwise
               require time to reconstruct the project state using the roll-
               forward data available in each change set.  However, it comes
               at the cost of disk space, and not everyone can afford more and
               more disk.

               This field defaults to true if not set.

RSS FEEDS

       Aegis has the ability to feed RSS channels when change sets transition
       states.  See the User Guide for full details.  Following is a brief
       description of the project-specific attributes used to control this
       process.

       Create / Add to a channel
               An RSS channel is specified with the rss:feedfilename
               project_specific attribute:

               project_specific =
                       [
                         {
                           name = "rss:feedfilename-<filename>";
                           value = "<space-separated list of states>";
                         }
                       ]

       Specify the Description of an RSS channel
               The description of an RSS channel is specified with the
               rss:feeddescription project_specific attribute:

               project_specific =
                       [
                         {
                           name = "rss:feeddescription-<filename>";
                           value = "<description>";
                         }
                       ]

       Specify the Title of an RSS channel
               The title of an RSS channel is specified with the rss:feedtitle
               project_specific attribute:

               project_specific =
                       [
                         {
                           name = "rss:feedtitle-<filename>";
                           value = "<title>";
                         }
                       ]

       Specify the Language of an RSS channel
               The language of an RSS channel is specified with the
               rss:feedlanguage project_specific attribute:

               project_specific =
                       [
                         {
                           name = "rss:feedlanguage-<filename>";
                           value = "<language";
                         }
                       ]

OBSOLETE FIELDS

       There are some obsolete fields in the file.  They are provided for
       backwards compatibility only, and should not be used.

       diff3_command = string;
               This field is used to difference 3 files.  The command is
               always executed by developers.  Used by the aed(1) command.
               All of the substitutions described by aesub(5) are available;
               in addition,

               ${ORiginal}
                       The absolute path of the original file copied into the
                       change.  Usually not in the baseline.

               ${Most_Recent}
                       The absolute path of the competing edit, usually in the
                       baseline.

               ${Input}
                       The absolute path of the file in the development
                       directory.

               ${Output}
                       The absolute path of the file in which to write the
                       difference listing.

               Executed as: the project owner (for integration diffs), or the
               developer (for development diffs).  Current directory: the
               integration directory (for integration diffs), or the
               development directory (for development diffs).  Exit status:
               zero indicates success, all non-zero exits indicate failure
               (the aed will fail).

               The problem with this field was that the default usage placed
               the merged source in a strange place.  And subsequent aed(1)
               commands would over-write it.  This meant that merges would be
               lost, causing a number of nasty problems.  Some sites overcame
               this by adding “mv” commands to put the output back where the
               input came from, but this meant that Aegis’ commentary was
               misleading.  Use the “merge_command” field instead.  It is
               almost identical, but Aegis will move the files around for you
               - so you get the good behavior by default (no lost merges) and
               the error message is consistent.

       create_symlinks_before_build = boolean;
               This flag is true if Aegis should create symlinks from the
               development directory to the baseline for all files in the
               baseline not in the development directory immediately before a
               development_build_command is issued.  Usually used to trick
               dumb DMTs into believing the development directory contains an
               entire copy of the project, though sometimes the DMT is smart
               enough, the tools it must work with are not.  Symlinks in the
               development directory which point to nonexistent files will be
               removed.

               Defaults to false if not set.

       create_symlinks_before_integration_build = boolean;
               This flag is true if Aegis should create symlinks from the
               integration directory to the ancestral baseline for all files
               in the ancestral not in the integration directory immediately
               before a build_command is issued.  Usually used to trick dumb
               DMTs into believing the integration directory contains an
               entire copy of the project, though sometimes the DMT is smart
               enough, the tools it must work with are not.  Symlinks in the
               integration directory which point to nonexistent files will be
               removed.

               Defaults to the same value as create_symlinks_before_build if
               not set.

       remove_symlinks_after_build = boolean;
               This flag is true if Aegis should remove symlinks which point
               from the development directory to the baseline directory
               immediately after a development_build_command is issued.  Only
               consulted if the create_symlinks_before_build field is true,
               for the purpose of reversing the actions of the create_
               symlinks_before_build field.

               Defaults to false if not set.

       remove_symlinks_after_integration_build = boolean;
               This flag is true if Aegis should remove symlinks which point
               from the integration directory to the ancestral baseline
               directory immediately after a build_command is issued.  Only
               consulted if the create_symlinks_before_integration_build field
               is true, for the purpose of reversing the actions of the
               create_symlinks_before_integration_build field.

               Defaults to true if not set.  This default is intentional.  It
               is important that there are no symlinks in the (new) baseline,
               because they could go stale between integrations.  If you set
               this field to false, caveat emptor.

SEE ALSO

       aeb(1)  build a change

       aecp(1) copy a file into a change

       aecpu(1)
               reverse action of aecp

       aed(1)  find differences between a change and the baseline

       aede(1) end development of a change aede-policy(1) check things about a
               change

       aerpass(1)
               pass a review of a change

       aeib(1) begin integration of a change

       aeipass(1)
               pass integration of a change

       aemv(1) rename a file as part of a change

       aenf(1) add new files to be created by a change

       aenfu(1)
               remove new files from a change

       aent(1) add a new test to be created by a change

       aentu(1)
               remove new tests from a change

       aet(1)  run tests

       aegis(5)
               aegis file format syntax

       aesub(5)
               available command substitutions

       aetest(5)
               batch test results file

COPYRIGHT

       aegis version 4.24.3.D001
       Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
       2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Peter
       Miller

       The aegis program comes with ABSOLUTELY NO WARRANTY; for details use
       the ’aegis -VERSion License’ command.  This is free software and you
       are welcome to redistribute it under certain conditions; for details
       use the ’aegis -VERSion License’ command.

AUTHOR

       Peter Miller   E-Mail:   millerp@canb.auug.org.au
       /\/\*             WWW:   http://www.canb.auug.org.au/~millerp/