'\" t
.\"	aegis - project change supervisor
.\"	Copyright (C) 1994-1996, 1998-2001 Peter Miller;
.\"	All rights reserved.
.\"
.\"	This program is free software; you can redistribute it and/or modify
.\"	it under the terms of the GNU General Public License as published by
.\"	the Free Software Foundation; either version 2 of the License, or
.\"	(at your option) any later version.
.\"
.\"	This program is distributed in the hope that it will be useful,
.\"	but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"	GNU General Public License for more details.
.\"
.\"	You should have received a copy of the GNU General Public License
.\"	along with this program; if not, write to the Free Software
.\"	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
.\"
.\" MANIFEST: description of aegis project config file format
.\"
.so z_name.so
.TH aepconf 5 \*(N) "Reference Manual"
.SH NAME
aepconf - \*(n) project configuration file
.XX "aepconf(5)" "project configuration file format"
.SH SYNOPSIS
\fIproject\fP\f(CW/baseline/config\fP
.SH 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.
.PP
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: filenames
and architecture names.  In order to have shell special characters
in filenames, you must set the \fIshell_\%safe_\%filenames\fP field
(see below) to \fIfalse\fP.  If you do this, you will need to use the
\f(CWquote\fP substitution (see \fIaesub\fP(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.
.SH CONTENTS
This file contains the following fields:
.TP 8n
build_command = string;
.RS
This field describes how to build the project
(actually, how to do an integration build).
This field is mandatory.
Used by the
.IR aeb (1)
command.
All of the substitutions described by
.IR aesub (5)
are available.
.PP
Executed as: the intgerator (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 succes, non-zero is a failure
and a subsequent successful (exit zero) build will be required.
.RE
.TP 8n
development_build_command = string;
.RS
This field describes how to do a development build.
If this field is absent, it defaults to the above.
Used by the
.IR aeb (1)
command.
All of the substitutions described by
.IR aesub (5)
are available.
.PP
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.
.RE
.TP 8n
build_time_adjust_notify_command = string;
.RS
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.
.PP
Executed as: the project owner.
Current directory: the project baseline.
Exit status: ignored.
.RE
.TP 8n
build_covers_all_architectures = boolean;
.RS
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 techiniques, or
Cook's ability to nominate hosts on which to execute each build rule.
.RE
.TP 8n
create_symlinks_before_build = boolean;
.RS
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.
.PP
Defaults to false if not set.
.RE
.TP 8n
create_symlinks_before_integration_build = boolean;
.RS
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.
.PP
Defaults to the same value as \fIcreate_\%symlinks_\%before_\%build\fP
if not set.
.RE
.TP 8n
remove_symlinks_after_build = boolean;
.RS
This flag is true if Aegis should remove symlinks which point from the
development directory to the baseline directory immediately after a
\fPdevelopment_\%build_\%command\fP is issued.  Only consulted if the
\fIcreate_\%symlinks_\%before_\%build\fP field is true, for the purpose
of reversing the actions of the \fIcreate_\%symlinks_\%before_\%build\fP
field.
.PP
Defaults to false if not set.
.RE
.TP 8n
remove_symlinks_after_integration_build = boolean;
.RS
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 \fIcreate_\%symlinks_\%before_\%integration_\%build\fP
field is true, for the purpose of reversing the actions of the
\fIcreate_\%symlinks_\%before_\%integration_\%build\fP field.
.PP
Defaults to \fBtrue\fP 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, \fIcaveat emptor\fP.
.RE
.TP 8n
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 \fInot\fP work
(unless the pattern starts with ``\f[CW]*\fP'').
.TP 8n
change_file_command = string;
.RS 8n
This field contains a command to be executed whenever a
'\*(n) -CoPy_file',
'\*(n) -New_File'
'\*(n) -New_Test'
'\*(n) -MoVe_file'
or
'\*(n) -ReMove_file'
command is successful.
If this field is absent, nothing is done.
Used by the
.IR aecp (1),
.IR aenv (1),
.IR aenf (1),
.IR aerm (1),
and
.IR aemv (1)
commands.
All of the substitutions described by
.IR aesub (5)
are available;
in addition,
.TP 8n
${File_List}
.br
Space separated list of files named.
.PP
Executed as: the developer.
Current directory: the development directory of the change.
Exit status: ignored.
.RE
.TP 8n
change_file_undo_command = string;
.RS 8n
This field contains a command to be executed whenever a
'\*(n) -CoPy_file_Undo',
'\*(n) -MoVe_file_Undo'
'\*(n) -New_File_Undo',
'\*(n) -New_Test_Undo',
or
'\*(n) -ReMove_file_Undo'
command is successful.
Default to \fIchange_\%file_\%command\fP if absent.
If both fields are absent, nothing is done.
Used by the
.IR aecpu (1),
.IR aemvu (1),
.IR aenfu (1),
.IR aentu (1)
or
.IR aermu (1),
commands.
All of the substitutions described by
.IR aesub (5)
are available;
in addition,
.TP 8n
${File_List}
.br
Space separated list of files named.
.PP
Executed as: the developer.
Current directory: the development directory of the change.
Exit status: ignored.
.RE
.TP 8n
project_file_command = string;
.RS
This field contains a command to be executed
during a development build
before the
.I "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
.IR aeb (1)
command.
All of the substitutions described by
.IR aesub (5)
are available.
.TP 8n
develop_begin_command = string;
This field contains a command to be executed whenever
a '\*(n) -Develop_Begin'
command is successful.
If this field is absent, nothing is done.
Used by the
.IR aedb (1)
command.
All of the substitutions described by
.IR aesub (5)
are available.
.PP
Executed as: the developer.
Current directory: the development directory of the change.
Exit status: ignored.
.RE
.TP 8n
.RS
integrate_begin_command = string;
This field contains a command to be executed whenever
a '\*(n) -Integrate_Begin'
command is successful.
If this field is absent, nothing is done.
Used by the
.IR aeib (1)
command.
All of the substitutions described by
.IR aesub (5)
are available.
.PP
Executed as: the project owner.
Current directory: the integration directory.
Exit status: ignored.
.RE
.TP 8n
link_integration_directory = boolean;
.br
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.
.I Howto.cook
or
.IR Makefile ,
etc)
must unlink targets before rebuilding them;
if this is not done the baseline will be corrupted.
Used by the
.IR aeib (1)
command.
.TP 8n
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
.IR aeib (1)
command.
This field only applies to derived files,
it does \fInot\fP apply to source files.
The patterns are matched against the whole filename;
naming only the last filename path element will \fInot\fP work
(unless the pattern starts with ``\f[CW]*\fP'').
.TP 8n
history_create_command = string;
.RS 8n
This field is used to create a new history.
The command is always executed as the project owner.
Used by the
.IR aeipass (1)
command.
.PP
It is strongly recommended that the \fIhistory_\%create_\%command\fP
and \fIhistory_\%put_\%command\fP fields are identical.  If not set,
the \fIhistory_\%create_\%command\fP field defaults to the same value
as the \fIhistory_\%put_\%command\fP field.
.PP
All of the substitutions described by
.IR aesub (5)
are available;
in addition,
.TP 8n
${Input}
.br
Absolute path of the source file.
.TP 8n
${History}
.br
Absolute path of the history file.
This may need to be reworked with the
.I Dirname
and
.I Basename
substitutions to yield a string suitable for the history tool in question.
.PP
See also the
.I history_put_trashes_file
field, below.
.PP
Executed as: the project owner.
Current directory: the base of the history tree.
Exit status: zero indicates succes, all non-zero exits indicate failure
(the integrate pass will fail).
.RE
.TP 8n
history_get_command = string;
.RS 8n
This field is used to get a file from history.
The command may be executed by developers.
Used by the
.IR aeipass (1)
and
.IR aecp (1)
commands.
All of the substitutions described by
.IR aesub (5)
are available;
in addition,
.TP 8n
${History}
.br
The absolute path of the history file.
This may need to be reworked with the
.I Dirname
and
.I Basename
substitutions to yield a string suitable for the history tool in question.
.TP 8n
${Edit}
.br
The edit number to be extracted.
It may be an arbitrary string,
varying on the particular history tool.
.TP 8n
${Output}
.br
The absolute path of the destination file.
.PP
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 succes, all non-zero exits indicate failure
(the \fIaecp\fP will fail).
.RE
.TP 8n
history_put_command = string;
.RS
This field is used to add a new change to the history.
The command is always executed as the project owner.
Used by the
.IR aeipass (1)
command.
.PP
It is strongly recommended that the \fIhistory_\%put_\%command\fP and
\fIhistory_\%create__\%command\fP fields are identical.  If not set,
the \fIhistory_\%put_\%command\fP field defaults to the same value as
the \fIhistory_\%create_\%command\fP field.
.PP
All of the substitutions described by
.IR aesub (5)
are available;
in addition,
.TP 8n
${Input}
.br
The absolute path of the source file.
.TP 8n
${History}
.br
The absolute path of the history file.
This may need to be reworked with the
.I Dirname
and
.I Basename
substitutions to yield a string suitable for the history tool in question.
.PP
See also the
.I history_put_trashes_file
field, below.
.PP
Executed as: the project owner.
Current directory: the base of the history tree.
Exit status: zero indicates succes, all non-zero exits indicate failure
(the integrate pass will fail).
.RE
.TP 8n
history_query_command = string;
.RS 8n
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
.IR aeipass (1)
and
.IR aecp (1)
commands.
All of the substitutions described by
.IR aesub (5)
are available;
in addition,
.TP 8n
${History}
.br
The absolute path of the history file.
This may need to be reworked with the
.I Dirname
and
.I Basename
substitutions to yield a string suitable for the history tool in question.
.PP
Executed as: the project owner.
Current directory: the base of the history tree.
Exit status: zero indicates succes, all non-zero exits indicate failure
(the integrate pass will fail).
.RE
.TP 8n
history_put_trashes_file = (fatal, warn, ignore);
.RS
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.
.TP 4n
fatal
Emit a fatal error if one or more source files are modified by a
.I history_put_command
or
.IR history_create_command .
This is the default.
.TP 4n
warn
Emit a warning if a source file is modified.
.TP 4n
ignore
Ignore a source file changing.
You sure better hope it was only in a comment!
.RE
.TP 8n
history_content_limitation = (ascii_text, international_text, binary_capable);
.RS
This field describes the content style which the history tool is
capable of working with.
.TP 8n
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.
.TP 8n
international_text
The history tool can only cope with files which do not contain
the NUL character.  The file must end with a newline.
.TP 8n
binary_capable
The history tool can cope with all files without any limitation on
the form of the contents.
.PP
When a file is added to the history (by either the
\fIhistory_\%create_\%command\fP or the \fIhistory_\%put_\%command\fP
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.
.PP
On extract (the \fIhistory_get_command\fP 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).
.RE
.TP 8n
diff_command = string;
.RS
This field is used to difference of 2 files.
The command is always executed by developers.
Used by the
.IR aed (1)
command.
All of the substitutions described by
.IR aesub (5)
are available;
in addition,
.TP 8n
${ORiginal}
.br
The absolute path of the original
file copied into the change.
Usually in the baseline,
but not always.
.TP 8n
${Input}
.br
The absolute path of the file in the development directory.
.TP 8n
${Output}
.br
The absolute path of the file in which to write the difference listing.
.PP
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 succes, all non-zero exits indicate failure
(the aed will fail).
.RE
.TP 8n
merge_command = string;
.RS 8n
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
.IR aed (1)
command.
All of the substitutions described by
.IR aesub (5)
are available;
in addition,
.TP 8n
${ORiginal}
.br
The absolute path of the original
file copied into the change.
Usually not in the baseline, often a temporary file.
.TP 8n
${Most_Recent}
.br
The absolute path of the competing edit,
usually in the baseline.
.TP 8n
${Input}
.br
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.
.TP 8n
${Output}
.br
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.
.PP
It is important that this command does not move files around.
(See the obsolete \fIdiff3_command\fP field, below, for some history.)
.PP
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 succes, all non-zero exits indicate failure
(the aed will fail).
.RE
.TP 8n
patch_diff_command = string;
.RS
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 \fIaepatch\fP(1) command.
.PP
Defaults to \f[CW]"set +e; diff -c $original $input > $output;
text $? -le 1"\fP if not set.
.PP
All of the substitutions described by
.IR aesub (5)
are available;
in addition,
.TP 8n
${ORiginal}
.br
The absolute path of the original
file copied into the change.
Usually in the baseline,
but not always.
.TP 8n
${Input}
.br
The absolute path of the file in the development directory.
.TP 8n
${Output}
.br
The absolute path of the file in which to write the difference listing.
.PP
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 succes, all non-zero exits indicate failure
(the aed will fail).
.RE
.TP 8n
test_command = string;
.RS
This field is used to set the command to be executed by the
.IR aet (1)
command.
Defaults to "$shell $file_name" if not set.
.PP
All of the substitutions described in
.IR aesub (5)
are available.
In addition:
.TP 8n
${File_Name}
.br
The absolute path of the test to be executed.
.TP 8n
${Search_Path}
.br
Colon separated list of directories to search for tests and test support
files.  (This is a normal \fIaesub\fP(5) substitution.)
.TP 8n
${Search_Path_Executable}
.br
Colon separated list of directories to search for executable files and
executable support files.  Usually it is the same as the above,
\fIexcept\fP during an ``aet -bl'' command.
.PP
Note that tests are source files,
and thus never have the execute bit set.
.PP
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
-indenpendent tests).
Exit status: zero indicates succes, one indicates failure, anything
else indicates "no result".
.RE
.\" ------------------------------------------------------------------------
.TP 8n
development_test_command = string;
.RS
This field is used to set the command to be executed by the
.IR aet (1)
command when a change is in the
.I "being developed"
state.
Defaults to be the same as the
.I test_command
field if not set.
.PP
.B "Note:"
It is a significantly bad idea to
make tests behave differently in
.I "being development"
and
.I "being integrated"
states;
avoid this at all costs.
.PP
All of the substitutions described in
.IR aesub (5)
are available.
In addition:
.TP 8n
${File_Name}
.br
The absolute path of the test to be executed.
.TP 8n
${File_Name}
.br
The absolute path of the test to be executed.
.TP 8n
${Search_Path}
.br
Colon separated list of directories to search for tests and test support
files.  (This is a normal \fIaesub\fP(5) substitution.)
.TP 8n
${Search_Path_Executable}
.br
Colon separated list of directories to search for executable files and
executable support files.  Usually it is the same as the above,
\fIexcept\fP during an ``aet -bl'' command.
.PP
Note that tests are source files,
and thus never have the execute bit set.
.PP
Executed as: the developer.
Current directory: the development directory (for development tests),
the project baseline (for -bl tests).
Exit status: zero indicates succes, one indicates failure, anything
else indicates "no result".
.RE
.\" ------------------------------------------------------------------------
.TP 8n
batch_test_command = string;
.RS
This field is used to set the command to be executed by the
.IR aet (1)
command, in preference to the \fItest_command\fP or
\fIdevelopment_test_command\fP, if set.  It is capable of running more
than one test at once.
.PP
All of the substitutions described in
.IR aesub (5)
are available.
In addition:
.TP
${Output}
This is the name of the file to be generated to hold the test results.
See \fIaetest\fP(5) for the format of this file.
.br
A space separated list of absolute paths of the tests to be executed.
.TP
${File_Names}
.br
The absolute path of the tests to be executed.
.TP 8n
${File_Name}
.br
The absolute path of the test to be executed.
.TP 8n
${Search_Path}
.br
Colon separated list of directories to search for tests and test support
files.  (This is a normal \fIaesub\fP(5) substitution.)
.TP 8n
${Search_Path_Executable}
.br
Colon separated list of directories to search for executable files and
executable support files.  Usually it is the same as the above,
\fIexcept\fP during an ``aet -bl'' command.
.PP
Note that tests are source files,
and thus never have the execute bit set.
.PP
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.
.PP
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
-indenpendent tests).
Exit status: zero indicates succes, one indicates failure, anything
else indicates "no result".
.RE
.\" ------------------------------------------------------------------------
.TP 8n
architecture = [{ ... }];
.br
.RS
This field is a list of
system and machine architectures on which each change
must successfully build and test.
The structures listed have fields as follows:
.TP 8n
name = string;
.br
The name of the architecture.
This name is available in the
.I ${ARCHitecture}
substitution (see
.IR 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.
.TP 8n
pattern = string;
.br
.RS
The system and machine architecture are determined by using the
.IR uname (2)
system call.
The 
.IR uname (2)
return value is assembled into a string of the
form "\fIsysname\fB-\fIrelease\fB-\fIversion\fB-\fImachine\fR".
.PP
The pattern field must match this uname result string.
The first match found is used.
The pattern is a shell file name pattern,
see
.IR sh (1)
for more information.
.PP
For example, the pattern
.I SunOS-4.1*-*-sun4*
matches a machine the author commonly uses,
which returns
.I "SunOS-4.1.3-8-sun4m"
from the
.IR uname (2)
system call.
.RE
.TP 8n
mode = (required, optional, forbidden);
.br
.RS
The \fImode\fP field is used to control how the architecture information
is used.
.TP 8n
required
Architectures of thus mode will be copied into changes as their required
architectures when the change is created.  This is the default.
.TP 8n
optional
Architectures of thus mode will \fInot\fP be copied into changes as
their required architectures when the change is created.  However,
if you add them subsequently, they become required \fIfor that change\fP.
.TP 8n
forbidden
Aegis will refuse to build or test on architectures of this mode.
.PP
When a change is created, the \fIrequired\fP 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.
.RE
.PP
If the architecture field is not set,
it defaults to
.RS
.nf
.ft CW
architecture =
[
	{
		name = "unspecified";
		pattern = "*";
		mode = required;
	}
];
.ft R
.fi
.RE
.RE
.TP 8n
file_template = [ { ... } ];
.br
The file template is consulted whenever a new file is created,
by one of the
.IR aenf (1)
or
.IR aent (1)
commands.
Each list item has the form:
.RS
.TP 8n
pattern = [ string ];
The name of the file,
relative to the development directory.
Each string is a shell file name pattern;
see
.IR sh (1)
for more information.
The patterns are matched against the whole filename;
naming only the last filename path element will \fInot\fP work
(unless the pattern starts with ``\f[CW]*\fP'').
.TP 8n
body_command = string;
.RS
Command to run to initialize the body of the file.
.br
Executed as: the developer.
Current directory: the development directory of the change.
Exit status: ignored.
.RE
.TP 8n
body = string;
What to initialize the body of the file to.
.PP
All of the substitutions described in
.IR aesub (5)
are available for the \fIbody\fP and \fIbody_command\fP strings.
(Only specify one of them.)
In addition:
.TP 8n
${File_Name}
.br
will be replaced by the name of the new file.
.RE
.TP 8n
whiteout_template = [ { ... } ];
.br
The file template is consulted whenever a file is removed, by one of
the \fIaerm\fP(1) or \fIaemv\fP(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:
.RS
.TP 8n
pattern = [ string ];
The name of the file,
relative to the development directory.
Each string is a shell file name pattern;
see
.IR sh (1)
for more information.
The patterns are matched against the whole filename;
naming only the last filename path element will \fInot\fP work
(unless the pattern starts with ``\f[CW]*\fP'').
.TP 8n
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.
.PP
All of the substitutions described in
.IR aesub (5)
are available for the body string.
In addition:
.TP 8n
${File_Name}
.br
will be replaced by the name of the removed file.
.PP
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.
.RE
.TP 8n
maximum_filename_length = integer;
.RS
This field is used to limit the length of filenames.
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.
.PP
The file name lengths of project files will be checked
at develop end
if the project
.I config
file is in the change.
See
.I aede (1)
for more information.
.RE
.TP 8n
posix_filename_charset = boolean;
.RS
This field may be used to limit the characters allowed
in filenames to only those explicitly allowed by POSIX.
Defaults to false if not set.
.PP
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.
.PP
If this field is false,
all characters are allowed
except non-printing characters, space characters and leading hyphens.
.RE
.TP
dos_filename_required = boolean;
.br
This field may be used to limit filenames so that they conform to
the DOS 8+3 filename limits and to the DOS filename character set.
Also denies filenames which look like devices (AUX, \fIetc\fP).
Defaults to false if not set.
This field is used in combination with the other filename fields,
it does not replace them.
.TP
windows_filename_required = boolean;
.br
This field may be used to limit filenames so that they conform to the
Windows98 and WindowsNT filename limits and character set.  Also denies
filenames which look like devices (AUX, \fIetc\fP).  Defaults to false
if not set.  This field is used in combination with the other filename
fields, it does not replace them.
.TP
shell_safe_filenames = boolean;
.br
This field may be used to limit filenames 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 filenames in commands,
or risk unexpected errors.  This field defaults to true if not set.
.TP
filename_pattern_accept = [ string ];
.br
This field is used to specify a list of patterns of acceptable filenames.
The patterns are matched against each filename path element.
The patterns are constructed from the usual shell filename wildcards.
Defaults to "*" if not set.
.TP
filename_pattern_reject = [ string ];
.br
This field is used to specify a list of patterns of unacceptable filenames.
The patterns are matched against each filename path element.
The patterns are constructed from the usual shell filename wildcards.
Defaults to "*,D" if not set.
The pattern "*,D" is always appended.
Where the
.I filename_pattern_accept
and
filename_pattern_reject
fields conflict,
the reject takes precedence.
.TP 8n
new_test_filename = string;
.RS
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.
.PP
All of the substitutions defined in
.IR aesub (5)
are available.
The following three substitutions are also available:
.TP 8n
$Hundred
The test number divided by 100, optional
.TP
$Number
The test number, mandatory
.TP
$Type
The test type: "automatic" or "manual", optional
.RE
.TP 8n
development_directory_template = string;
.RS
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:
.TP 8n
Default_Development_Directory
The directory within which the development directory is
to be created.
.TP 8n
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.
.PP
If not set, defaults to
"\f(CW$ddd/${left $p ${expr ${namemax $ddd} - ${length .$magic$c}}}.$magic$c\fP".
.PP
For DOS compatibility (8+3 filenames), a useful setting is
"\f(CW$ddd/${downcase ${left ${id $p} 8}.$magic${right 0$c 2}}\fP".
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.
.RE
.TP 8n
metrics_filename_pattern = string;
.RS
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:
.TP 8n
File_Name
The absolute pathname of the source file.
.PP
Defaults to "$filename,S" if not set.
.RE
.TP 8n
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 youself.
The patterns are matched against the whole filename;
naming only the last filename path element will \fInot\fP work
(unless the pattern starts with ``\f[CW]*\fP'').
.TP 8n
project_specific = [ { ... } ];
.RS
This is a list of name and value pairs for use within the
${project-specific} substitution (see \fIaesub\fP(5) for more information).
The sub-fields are
.TP 8n
name = string;
The name of the value.
.TP 8n
value = string;
The value to be substituted.
.PP
There are almost no limitations on the strings which may appear in either
of these fields.
.RE
.SH OBSOLETE FIELDS
There are some obsolete fields in the file.
They are provided for backwards compatibility only, and should not be used.
.TP 8n
diff3_command = string;
.RS 8n
This field is used to difference 3 files.
The command is always executed by developers.
Used by the
.IR aed (1)
command.
All of the substitutions described by
.IR aesub (5)
are available;
in addition,
.TP 8n
${ORiginal}
.br
The absolute path of the original
file copied into the change.
Usually not in the baseline.
.TP 8n
${Most_Recent}
.br
The absolute path of the competing edit,
usually in the baseline.
.TP 8n
${Input}
.br
The absolute path of the file in the development directory.
.TP 8n
${Output}
.br
The absolute path of the file in which to write the difference listing.
.PP
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 succes, all non-zero exits indicate failure
(the aed will fail).
.PP
The problem with this field was that the default usage placed the merged
source in a strange place.  And subsequent \fIaed\fP(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.
.RE
.SH SEE ALSO
.TP 8n
.IR aeb (1)
build a change
.TP 8n
.IR aecp (1)
copy a file into a change
.TP 8n
.IR aecpu (1)
reverse action of aecp
.TP 8n
.IR aed (1)
find differences between a change and the baseline
.TP 8n
.IR aede (1)
end development of a change
.TP 8n
.IR aeib (1)
begin integration of a change
.TP 8n
.IR aeipass (1)
pass integration of a change
.TP 8n
.IR aemv (1)
rename a file as part of a change
.TP 8n
.IR aenf (1)
add new files to be created by a change
.TP 8n
.IR aenfu (1)
remove new files from a change
.TP 8n
.IR aent (1)
add a new test to be created by a change
.TP 8n
.IR aentu (1)
remove new tests from a change
.TP 8n
.IR aet (1)
run tests
.TP 8n
.IR aegis (5)
\*(n) file format syntax
.TP 8n
.IR aesub (5)
available command substitutions
.TP 8n
.IR aetest (5)
batch test results file
.so ../man1/z_cr.so