Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
aepconf(5)		      File Formats Manual		    aepconf(5)

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

	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	com-
	mands in unintended ways.  There are two main sources of these prob-
	lems: file names and architecture names.  In order to have shell spe-
	cial 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 ar-
	chitecture 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	copy-
	ing 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 informa-
	tion 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	addi-
		tional 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 con-
		sulted (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 develop-
		ment 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 be-
			fore 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	avail-
			able) this field will be ignored.  If the host system
			does not have symbolic links, this field will be ig-
			nored.

			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 sub-
			stitution 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 sym-
			bolic links are	available)) this field will be ig-
			nored.

			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 ref-
			erence 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 de-
			rived files.  This allows work areas to	take advantage
			of "precompiled" object	files (etc) in the base-
			line(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 in-
			stead and avoid	hard links.  Alternatively, set	de-
			rived_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 de-
			rived files.  This allows work areas to	take advantage
			of "precompiled" object	files (etc) in the base-
			line(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 sub-
			stitution instead and avoid symbolic links.  Alterna-
			tively,	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, occasion-
			ally 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 base-
			line(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	sym-
			bolic links are	available)) this field will be ig-
			nored.

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

			See also the integrate_begin_exceptions	and sym-
			link_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 il-
			lusion 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 in-
			tegrate	begin (aeib) command.

		derived_at_start_only =	boolean;
			This field controls whether the	above fields control-
			ling 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 de-
		velopment 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).

		The development	directory style	is applied after the develop_-
		begin_command hook is run.

	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	rele-
		vant.  That field controls how the baseline is cloned to form
		the integration	directory.  This field operates	after that op-
		eration.

	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 mod-
		ification 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 diffi-
		cult. 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-compila-
		tion 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 sym-
		bolic 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 (un-
		less 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 de-
		scribed	by aesub(5) are	available; in addition,

		${File_List}
			Space separated	list of	files named.

		Executed as: the developer.  Current directory:	the develop-
		ment 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 -Re-
		Move_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 develop-
		ment directory of the change.  Exit status: ignored.

	new_file_command = string;
		Executed whenever the aegis -new_file command is run success-
		fully.	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 develop-
		ment directory of the change.  Exit status: ignored.

	new_test_command = string;
		Executed whenever the aegis -new_test command is run success-
		fully.	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 develop-
		ment directory of the change.  Exit status: ignored.

	copy_file_command = string;
		Executed whenever the aegis -copy_file command is run success-
		fully.	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 develop-
		ment directory of the change.  Exit status: ignored.

	remove_file_command = string;
		Executed whenever the aegis -remove_file command is run	suc-
		cessfully.  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 develop-
		ment directory of the change.  Exit status: ignored.

	new_file_undo_command =	string;
		Executed whenever the aegis -new_file_undo command is run suc-
		cessfully.  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 develop-
		ment directory of the change.  Exit status: ignored.

	new_test_undo_command =	string;
		Executed whenever the aegis -new_test_undo command is run suc-
		cessfully.  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.  De-
		faults 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 develop-
		ment 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_early_command = string;
		This field contains a command to be executed at	the beginning
		of a 'aegis -Develop_Begin' command, immediately after the de-
		velopment directory has	been created.  If this field is	ab-
		sent, 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 develop-
		ment directory of the change.  Exit status: ignored.

		Note: This command is run from inside the lock,	so running any
		Aegis command that modifies the	change state will cause	a
		deadlock.

	develop_begin_command =	string;
		This field contains a command to be executed whenever a	'aegis
		-Develop_Begin'	command	is successful.	If this	field is ab-
		sent, 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 develop-
		ment 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 ab-
		sent, 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	inte-
		gration	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	re-
		building them; if this is not done the baseline	will be	cor-
		rupted.	 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 direc-
		tory.  Used by the aeib(1) command.  This field	only applies
		to derived files, it does not apply to source files.  The pat-
		terns 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 substitu-
			tions 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).

		Note: For projects created Aegis 4.26 or later,	it is possible
		to change the history tool used	by the project simply changing
		the various history_*_command documented in this man page.  It
		is also	possible to change the history tool for	projects cre-
		ated with aeimport 4.26	or later, however the original tool
		must be	available to access older file's revisions.

	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 ae-
		sub(5) are available; in addition,

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

		${Edit}
			The edit number	to be extracted.  It may be an arbi-
			trary 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 substitu-
			tions 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 transac-
		tion 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 com-
		mand 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 substitu-
			tions 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	exe-
			cuted from aeipass(1) this value is the	same as	${Ver-
			sion}, which may need to be reworked with the ${Subst}
			substitutions to yield a string	suitable for the his-
			tory 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 en-
		couraged.  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 neces-
		sary to	execute	10,000 history_label_commands, to add informa-
		tion 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 modi-
		    fied 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, bi-
	nary_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	con-
			tain 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 exam-
		ined for conformance to	this limitation.  If there is a	prob-
		lem, the file is encoded in either quoted printable for
		MIME64,	whichever is smaller, before being given to the	his-
		tory tool.  This encoding is transparent, the file in the
		baseline is unchanged.

		On extract (the	history_get_command field) the encoding	is re-
		versed,	using information attached to the change file informa-
		tion.  This is because each put	could use a different encoding
		(although in practice, file contents rarely change that	dra-
		matically, 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 di-
			rectory.

		${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 in-
		tegration directory (for integration diffs), or	the develop-
		ment directory (for development	diffs).	 Exit status: zero in-
		dicates	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 dif-
		ference	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 di-
		rectory	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 tempo-
			rary file.

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

		${Input}
			The absolute path of the file in the development di-
			rectory.  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 his-
		tory.)

		Executed as: the project owner (for integration	diffs),	or the
		developer (for development diffs).  Current directory: the in-
		tegration directory (for integration diffs), or	the develop-
		ment directory (for development	diffs).	 Exit status: zero in-
		dicates	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 de-
		velopers.  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 di-
			rectory.

		${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 in-
		tegration directory (for integration diffs), or	the develop-
		ment directory (for development	diffs).	 Exit status: zero in-
		dicates	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, be-
		cause it's aimed at aeannotate(1), not at humans.)  The	com-
		mand is	always executed	by developers.	Used by	the aeanno-
		tate(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 ef-
		fect 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 op-
		tions which would alter	the number of lines, such as - -ig-
		nore-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 di-
			rectory.

		${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 in-
		tegration directory (for integration diffs), or	the develop-
		ment directory (for development	diffs).	 Exit status: zero in-
		dicates	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 neces-
		sary 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 in-
		volved with the	change.

		Executed as: the current reviewer.  Current directory: the de-
		velopment 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 re-
		quires further development.

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

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

		There are some common validations available in the aede-pol-
		icy(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 develop-
		ment 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 devel-
			oped 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 ae-
			sub(5) substitution.)

		${Search_Path_Executable}
			Colon separated	list of	directories to search for exe-
			cutable	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 com-
			mand line, suitably quoted to protect special charac-
			ter 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 exe-
		cute 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 di-
		rectory	(for integration tests), the development directory
		(for development tests), the project baseline (for -bl tests),
		or the current directory (for -independent tests).  Exit sta-
		tus: 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 dif-
		ferently 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 ae-
			sub(5) substitution.)

		${Search_Path_Executable}
			Colon separated	list of	directories to search for exe-
			cutable	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 com-
			mand line, suitably quoted to protect special charac-
			ter 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 exe-
		cute bit set.

		Executed as: the developer.  Current directory:	the develop-
		ment directory (for development	tests),	the project baseline
		(for -bl tests).  Exit status: zero indicates success, one in-
		dicates	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 develop-
		ment_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 ae-
			sub(5) substitution.)

		${Search_Path_Executable}
			Colon separated	list of	directories to search for exe-
			cutable	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 com-
			mand line, suitably quoted to protect special charac-
			ter 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 exe-
		cute 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 di-
		rectory	(for integration tests), the development directory
		(for development tests), the project baseline (for -bl tests),
		or the current directory (for -independent tests).  Exit sta-
		tus: 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 exe-
		cuted 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 develop-
		ment 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 architec-
			ture, 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 archi-
				tectures 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 di-
			rectory.  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: ig-
			nored.

		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 in-
		duce 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 di-
			rectory.  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 cre-
			ated.

		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 de-
		velop 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	implementa-
		tions of IEEE Std 1003.1-1988, it shall	consist	only of	al-
		phanumeric characters, dot, hyphen or underscore.  Hyphen
		shall not be used as the first character of a portable file-
		name.

		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	con-
		form 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 re-
		place them.

	windows_filename_required = boolean;
		This field may be used to limit	file names so that they	con-
		form to	the Windows98 and WindowsNT filename limits and	char-
		acter 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 re-
		place 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 con-
		sidered	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 fil-
		ters.  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 configura-
		tion.  And even	then, substitutions which expect a space sepa-
		rated 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 fil-
		ters.  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 unaccept-
		able file names.  The patterns are matched against each	file-
		name 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 file-
		name_pattern_accept and	filename_pattern_reject	fields con-
		flict, 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.	 De-
		faults 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 in-
			serted.	 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 Tro-
		jan horse attacks.  This will be different for different
		projects, so you will need to update this yourself.  The pat-
		terns 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	infor-
		mation).  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 list-
			ings, 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 ap-
		pear 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.

		ae-repo-ci:commit-message
			See ae-repo-ci(1) for more information.

		aede-policy
			See aede-policy(1) for more information.

		aede-policy:version-info:library
			See aede-policy(1) for more information.

		aeget:inventory:hide
			See aeget(1) for more information.

		aemakegen:debian:build-depends
			See aemakegen(1) for more information.

		aemakegen:debian:copyright
			See aemakegen(1) for more information.

		aemakegen:debian:depends
			See aemakegen(1) for more information.

		aemakegen:debian:description:name
			See aemakegen(1) for more information.

		aemakegen:debian:extended-description:name
			See aemakegen(1) for more information.

		aemakegen:debian:homepage
			See aemakegen(1) for more information.

		aemakegen:debian:maintainer
			See aemakegen(1) for more information.

		aemakegen:debian:priority
			See aemakegen(1) for more information.

		aemakegen:debian:section
			See aemakegen(1) for more information.

		aemakegen:pkg-config:cflags
			See aemakegen(1) for more information.

		aemakegen:pkg-config:conflicts
			See aemakegen(1) for more information.

		aemakegen:pkg-config:libs
			See aemakegen(1) for more information.

		aemakegen:pkg-config:libs.private
			See aemakegen(1) for more information.

		aemakegen:pkg-config:requires
			See aemakegen(1) for more information.

		aemakegen:version-info
			See aemakegen(1) for more information.

		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.

		copyright-owner
			This string is available via the ${copyright-owner}
			substitution, and is the one checked by	the aede-pol-
			icy(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.

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

		html:meta
			This attribute is used by the aeget(1) command to cus-
			tomize generated web pages.  See aeget(1) for more in-
			formation.

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

		svn:password
			See ae-repo-ci for more	information.

		svn:username
			See ae-repo-ci for more	information.

		When commands are executed by Aegis, it	ensures	that the
		AEGIS_PROJECT, AEGIS_CHANGE, AEGIS_ARCH, LINES and COLS	envi-
		ronment	variables are set appropriately.  The project configu-
		ration file's project_specific field is	also consulted,	look-
		ing 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 re-
		spect 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 alle-
		viate the vast majority	of file	modification time inconsisten-
		cies 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 en-
			sue 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 de-
		scription.  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_re-
		leases/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_ex-
		ceptions 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:feedti-
		tle 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:feed-
		language 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 al-
		ways 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 di-
			rectory.

		${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 in-
		tegration directory (for integration diffs), or	the develop-
		ment directory (for development	diffs).	 Exit status: zero in-
		dicates	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 al-
		most 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 de-
		velopment directory to the baseline for	all files in the base-
		line not in the	development directory immediately before a de-
		velopment_build_command	is issued.  Usually used to trick dumb
		DMTs into believing the	development directory contains an en-
		tire 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 in-
		tegration directory to the ancestral baseline for all files in
		the ancestral not in the integration directory immediately be-
		fore a build_command is	issued.	 Usually used to trick dumb
		DMTs into believing the	integration directory contains an en-
		tire 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 imme-
		diately	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 di-
		rectory	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.

CHANGING HISTORY TOOL
	Since version Aegis 4.26 it is possible	to change the history tool, if
	needed.	 Note, however,	that the old tool is still required to re-
	trieve file's revisions	saved before the switch	to the new tool.  As
	an example it is not advisable to uninstall the	fhist package if a
	project	switched to aesvt, since fhist will be required	to retrieve
	file's revisions pre-dating the	switch.

	The aeipass(1) command stores the history_get_command as the
	aegis:history_get_command user defined change's	attribute, that	com-
	mand will be used later	to retrieve files altered by the change.

	In any project created using Aegis v. 4.26 (or later) it is possible
	to use a different history tool	simply editing the appropriate aep-
	conf(5)	fields.

	It is possible to change the history tool of projects created with a
	older Aegis version, but it's required to properly set the aegis:his-
	tory_get_command user defined attribute	for each change	integrated be-
	fore the switch.

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.25.D510
	Copyright (C) 1991, 1992, 1993,	1994, 1995, 1996, 1997,	1998, 1999,
	2000, 2001, 2002, 2003,	2004, 2005, 2006, 2007,	2008, 2009, 2010,
	2011, 2012 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:	 pmiller@opensource.org.au
	/\/\*		  WWW:	 http://miller.emu.id.au/pmiller/

Reference Manual		     Aegis			    aepconf(5)

NAME | SYNOPSIS | DESCRIPTION | CONTENTS | RSS FEEDS | OBSOLETE FIELDS | CHANGING HISTORY TOOL | SEE ALSO | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=aepconf&sektion=5&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help