table of contents
other versions
- jessie 4.24.3-3
aepconf(5) | File Formats Manual | aepconf(5) |
NAME¶
aepconf - aegis project configuration fileSYNOPSIS¶
project/baseline/aegis.conf (default)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 $
$ aecp aegis.conf $
$ aenf -config project.configuration $
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.
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:
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).
- 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; };
development_directory_style = { source_file_link = true; source_file_symlink = true; source_file_copy = true; };
- 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}
-
- 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}
-
- 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).
- 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).
- 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).
- 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).
- 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).
- 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).
- 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).
- 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).
- 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).
- 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).
- 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;
-
- 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}
-
- ${History}
-
- ${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)
- 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}
-
- ${Edit}
-
- ${Output}
-
- 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}
-
- ${History}
-
- ${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)
- 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}
-
- 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}
-
- ${Edit}
-
- ${Label}
-
- 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.
- 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}
-
- ${Input}
-
- ${Output}
-
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}
-
- ${Most_Recent}
-
- ${Input}
-
- ${Output}
-
- 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}
-
- ${Input}
-
- ${Output}
-
- ${INDex}
-
- 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}
-
- ${Input}
-
- ${Output}
-
- ${INDex}
-
- ${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.
- 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."$sh ${source script/reviewpolicy.sh} "
"-p $project -c $change "
"-d ${developer_list} "
"-r ${reviewer_list}"
;
- 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}
-
- ${Search_Path}
-
- ${Search_Path_Executable}
-
- ${VARiables}
-
- 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}
-
- ${File_Name}
-
- ${Search_Path}
-
- ${Search_Path_Executable}
-
- ${VARiables}
-
- 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.
- ${File_Names}
-
- ${File_Name}
-
- ${Search_Path}
-
- ${Search_Path_Executable}
-
- ${Current}
-
- ${Total}
-
- ${VARiables}
-
- 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;
-
- 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.
If the architecture field is not set, it defaults to
- 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.
architecture = [ { name = "unspecified"; pattern = "*"; mode = required; } ];
- file_template = [ { ... } ];
-
- 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.
- ${File_Name}
-
- whiteout_template = [ { ... } ];
-
- 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.
- ${File_Name}
-
- 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;
-
- windows_filename_required = boolean;
-
- 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 ];
-
- filename_pattern_reject = [ string ];
-
- 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.
- 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.
- 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
As many environment variables as desired may be specified in this way.
- 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.
- 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.
project_specific = [ { name = "setenv:PATH"; value = "/usr/bin:/bin"; }, { name = "setenv:SEARCH_PATH"; value = "${search_path}"; }, ];
- 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.
- 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/1301.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>";
}
]
{
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>";
}
]
{
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>";
}
]
{
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";
}
]
{
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}
-
- ${Most_Recent}
-
- ${Input}
-
- ${Output}
-
- 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.D001AUTHOR¶
Peter Miller | E-Mail: | millerp@canb.auug.org.au |
/\/\* | WWW: | http://www.canb.auug.org.au/~millerp/ |
Aegis | Reference Manual |