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

FreeBSD Manual Pages

  
 
  

home | help
aegis -Build(1)						       aegis -Build(1)

NAME
	aegis build - build a change

SYNOPSIS
	aegis -Build [ option...  ][ filename...  ]
	aegis -Build -List [ option...	]
	aegis -Build -Help

DESCRIPTION
	The aegis -Build command is used to build a project.  The project con-
	figuration file	is consulted for the appropriate build command,	and
	that command is	executed (see the build_ command and integration_-
	build_command fields in	aepconf(5) for more information.)  Output of
	the command is automatically logged to the aegis.log file at the root
	of the development directory tree.  The	build command will be executed
	with its current directory being the root of the development direc-
	tory, irrespective of there the	aegis -Build command was executed.

	If the change is in the	being integrated state,	references to the
	development directory, above, should be	read as	the integration	direc-
	tory.  Integration build commands are executed with the	user and group
	set to the project's owning user and group.  That is, it is not	neces-
	sary for an integrator to log in as someone else, the project account
	for instance, in order to do an	integration.

   No Build Required
	It is possible to configure your project so that no build is required.
	To do this, set	the following
		build_command =	"exit 0";
	in the project configuration file.

   Process Side	Effects
	This command will cancel any test registrations, because building the
	project	logically invalidates them.  If	the project configuration file
	was deleted, any diff registration will	also be	canceled.

   Notification
	The actions of the command are controlled by the build_	command	and
	integration_build_command fields of the	project	config file.  See aep-
	conf(5)	for more information.

   File	Action Adjustment
	When this command runs,	it first checks	the change files against the
	projects files.	 If there are inconsistencies, the file	actions	will
	be adjusted as follows:

	create	If a file is being created, but	another	change set is inte-
		grated which also creates the file, the	file action in the
		change set still being developed will be adjusted to "modify".

	modify	If a file is being modified, but another change	set is inte-
		grated which removes the file, the file	action in the change
		set still being	developed will be adjusted to "create".

	remove	If a file is being removed, but	another	change set is inte-
		grated which removes the file, the file	will be	dropped	from
		the change set still being developed.

PARTIAL	BUILD
	If files are named on the command line,	these files are	appended to
	the build command.  This is known as a partial build.  Partial builds
	are not	legal in the being integrated state, but can often be useful
	in the being developed state.  Partial builds are not recorded in the
	change status, because builds are decoupled from aegis it is not pos-
	sible for aegis	to know	if any set of partial builds is	equivalent to
	a full build.

	Warning: no change state lock is taken for a partial build, only a
	baseline read lock.

   File	Name Interpretation
	The aegis program will attempt to determine the	project	file names
	from the file names given on the command line.	All file names are
	stored within aegis projects as	relative to the	root of	the baseline
	directory tree.	 The development directory and the integration direc-
	tory are shadows of this baseline directory, and so these relative
	names apply here, too.	Files named on the command line	are first con-
	verted to absolute paths if necessary.	They are then compared with
	the baseline path, the development directory path, and the integration
	directory path,	to determine a baseline-relative name.	It is an error
	if the file named is outside one of these directory trees.

	The -BAse_RElative option may be used to cause relative	filenames to
	be interpreted as relative to the baseline path; absolute filenames
	will still be compared with the	various	paths in order to determine a
	baseline-relative name.

	The relative_filename_preference in the	user configuration file	may be
	used to	modify this default behavior.  See aeuconf(5) for more infor-
	mation.

SYMBOLIC LINKS
	Many dependency	maintenance tools, and indeed some compilers, have
	little or no support for include file search paths, and	thus for the
	concept	of the two-level directory hierarchy employed by Aegis.	 (It
	becomes	multi-level when Aegis'	branching functionality	is used.)  To
	allow these tools to be	used, Aegis provides the ability to maintain a
	set of symbolic	links between the development directory	of a change
	and the	baseline of a project, so it appears to	these tools that all
	of the project's files are present in the development directory.

   Project Configuration
	The development_directory_style	field of the project configuration
	file controls the appearance of	the development	directory.  See	aep-
	conf(5)	for more information.

	By using a setting such	as
		development_directory_style =
		{
		    source_file_symlink	= true;
		    during_build_only =	true;
		};
	the user never sees the	symbolic links,	because	they are added purely
	for the	benefit	of the dependency maintenance tool during the execu-
	tion of	the aeb(1) command.

	By using a setting such	as
		development_directory_style =
		{
		    source_file_symlink	= true;
		};
	(the other will	default	to false) the symbolic links will be created
	at develop begin time (see aedb(1) for more information) and also
	maintained by each aeb(1) invocation.  Note that the symbolic links
	are only maintained at these times, so project integrations during the
	course of editing change sourec	files may leave	the symbolic links in
	an inconsistent	state until the	next build.

	When files are copied from the baseline	into a change, using the
	aecp(1)	command, the symbolic link pointing into the baseline, if any,
	will be	removed	before the file	is copied.

	Note: Using this functionality in either form has implications for how
	the rules file of the dependency maintenance tool is written.  Rules
	must remove their targets before creating them (usually	with an	rm -f
	command) if you	use any	of the link sub-fields (both hard links	and
	symbolic links).  This is to avoid attempting to write the result on
	the symbolic link, which will point at a read-only file	in the project
	baseline.  This	is similar to the same requirement for using the
	link_integration_directory field of the	project	configuration file.

   User	Configuration
	There is a symbolic_link_preference field in the user configuration
	file (see aeuconf(5) for more information).  This controls whether
	aeb(1) will verify the symbolic	links before the build (default) or
	whether	it will	assume they are	up-to-date.  (This field is only rele-
	vant if	development_directory__style.source_file_symlink is true.)

	For medium-to-large projects, verifying	the symbolic links can take as
	long as	the build itself.  Assuming the	symbolic links are up-to-date
	can be a large time-saving for these projects.	It may be advisable to
	review your choice of DMT in such a situation.

	The aedb(1) command does not consult this preference.  Thus, in	most
	situations, the	symbolic links will be up-to-date when the build is
	performed.  The	only Aegis function which may result in	the symbolic
	links becoming out-of-date is the integration of another change, as
	this may alter the presence or absence of files	in the baseline.  In
	this situation,	the default aeb(1) action is to	ignore the user	pref-
	erence and the verify symbolic links.

	There are two command line options which modify	aeb(1) behavior	fur-
	ther: the -Verify-Symbolic-Links option	says to	verify the symbolic
	links; and the -Assume-Symbolic-Links option says to assume the	sym-
	bolic links are	up-to-date.  In	each case the option over-rides	the
	default	and the	user preference.

	It is possible to obtain behaviour similar to Tom Lord'a Arch by using
	a setting such as:
		development_directory_style =
		{
		    source_file_link = true;
		    source_file_symlink	= true;
		};

	It is possible to obtain behaviour similar to CVS by using a setting
	such as:
		development_directory_style =
		{
		    source_file_copy = true;
		};
	There are many more possible configurations of the development_-
	directory_style, usually with helpful build side-effects.  See aep-
	conf(1)	and the	Depenedency Maintenance	Tool chapter of	the User Guide
	for more information.

	The symbolic link command line options and preferences apply equally
	to hard	links and file copies (the names have historical origins).

THE BASELINE LOCK
	The baseline lock is used to ensure that the baseline remains in a
	consistent state for the duration of commands which need to read the
	contents of files in the baseline.

	The commands which require the baseline	to be consistent (these
	include	the aeb(1), aecp(1) and	aed(1) commands) take a	baseline read
	lock.  This is a non-exclusive lock, so	the concurrent development of
	changes	is not hindered.

	The command which modifies the baseline, aeipass(1), takes a baseline
	write lock.  This is an	exclusive lock,	forcing	aeipass(1) to block
	until there are	no active baseline read	locks.

	It is possible that one	of the above development commands will block
	until an in-progress aegis -Integrate_PASS completes.  This is usually
	of short duration while	the project history is updated.	 The delay is
	essential so that these	commands receive a consistent view of the
	baseline.  No other integration	command	will cause the above develop-
	ment commands to block.

	When aegis' branch functionality is in use, a read (non-exclusive)
	lock is	taken on the branch baseline and also each of the "parent"
	baselines.  However, a baseline	write (exclusive) lock is only taken
	on the branch baseline;	the "parent" baselines are only	read
	(non-exclusive)	locked.

METRICS
	Aegis is capable of recording metrics as part of the file attributes
	of a change.  This allows various properties of	files to be recorded
	for later trend	analysis, or other uses.

	The specific metrics are not dictated by Aegis.	 It is expected	that
	the integration	build will create a metrics file for each of the
	source files the change.  These	metrics	files must be in the format
	specified by aemetrics(5).

	The name of the	metrics	file defaults to "filename,S", however it may
	be varied, by setting the metrics_filename_pattern field of the
	project	config file.  See aepconf(5) for more information.

	If such	a metrics file exists, for each	source file in a change, it
	will be	read and remembered at integrate pass time.  If	it does	not
	exist, Aegis assumes there are no relevant metrics for that file, and
	proceeds silently; it is not an	error.

OPTIONS
	The following options are understood:

	name=value
		Command	line arguments of this form are	assumed	to be variable
		assignments for	the build tool.	 They are passed through
		unchanged.  They imply a partial build.

	-BAse_RElative
		This option may	be used	to cause relative filenames to be con-
		sidered	relative to the	base of	the source tree.  See aeu-
		conf(5)	for the	corresponding user preference.

	-CUrrent_RElative
		This option may	be used	to cause relative filenames to be con-
		sidered	relative to the	current	directory.  This is usually
		the default.  See aeuconf(5) for the corresponding user	pref-
		erence.

	-Change	number
		This option may	be used	to specify a particular	change within
		a project.  See	aegis(1) for a complete	description of this
		option.

	-Help
		This option may	be used	to obtain more information about how
		to use the aegis program.

	-List
		This option may	be used	to obtain a list of suitable subjects
		for this command.  The list may	be more	general	than expected.

	-MINImum
		This option may	be used	to request a source-only development_-
		directory_style.  This is useful if you	want to	simulate some-
		thing like aeib	-minimum in the	development directory.	This
		option is only meaningful if development_directory_style is
		being used.  If	the change is in the being integrated state,
		and the	developer specified -MINImum when issuing the aegis
		-Integrate_Begin command, then this option is set by default.

	-Not_Logging
		This option may	be used	to disable the automatic logging of
		output and errors to a file.  This is often useful when	sev-
		eral aegis commands are	combined in a shell script.

	-Project name
		This option may	be used	to select the project of interest.
		When no	-Project option	is specified, the AEGIS_PROJECT	envi-
		ronment	variable is consulted.	If that	does not exist,	the
		user's $HOME/.aegisrc file is examined for a default project
		field (see aeuconf(5) for more information).  If that does not
		exist, when the	user is	only working on	changes	within a sin-
		gle project, the project name defaults to that project.	 Oth-
		erwise,	it is an error.

	-TERse
		This option may	be used	to cause listings to produce the bare
		minimum	of information.	 It is usually useful for shell
		scripts.

	-Verbose
		This option may	be used	to cause aegis to produce more output.
		By default aegis only produces output on errors.  When used
		with the -List option this option causes column	headings to be
		added.

	-Verify_Symbolic_Links
		This option may	be used	to request that	the symbolic links, or
		hard links, or file copies, in the work	area be	updated	to
		reflect	the current state of the baseline.  This is controlled
		by the development_directory_style field of the	project	con-
		figuration file.  Only files which are not involved in the
		change are updated.  See also the "symbolic_links_preference"
		field of aeuconf(5).  This option is the default, if meaning-
		ful for	your configuration.  The name is an historical acci-
		dent, hard links and file copies are included.

	-Assume_Symbolic_Links
		This option may	be used	to request that	no update of baseline
		mirror files take place.  This options is useful when you def-
		initely	know the files'	up-to-date-ness	isn't important	right
		now; incorrect use of this option may have unanticipated build
		side-effects.  See also	the "symbolic_links_preference"	field
		of aeuconf(5).	This option is the default, if not meaningful
		for your configuration.	 The name is an	historical accident,
		hard links and file copies are included.

	-Wait	This option may	be used	to require Aegis commands to wait for
		access locks, if they cannot be	obtained immediately.
		Defaults to the	user's lock_wait_preference if not specified,
		see aeuconf(5) for more	information.

	-No_Wait
		This option may	be used	to require Aegis commands to emit a
		fatal error if access locks cannot be obtained immediately.
		Defaults to the	user's lock_wait_preference if not specified,
		see aeuconf(5) for more	information.

	See also aegis(1) for options common to	all aegis commands.

	All options may	be abbreviated;	the abbreviation is documented as the
	upper case letters, all	lower case letters and underscores (_) are
	optional.  You must use	consecutive sequences of optional letters.

	All options are	case insensitive, you may type them in upper case or
	lower case or a	combination of both, case is not important.

	For example: the arguments "-project", "-PROJ" and "-p"	are all	inter-
	preted to mean the -Project option.  The argument "-prj" will not be
	understood, because consecutive	optional characters were not supplied.

	Options	and other command line arguments may be	mixed arbitrarily on
	the command line, after	the function selectors.

	The GNU	long option names are understood.  Since all option names for
	aegis are long,	this means ignoring the	extra leading '-'.  The
	"--option=value" convention is also understood.

RECOMMENDED ALIAS
	The recommended	alias for this command is
	csh%	alias aeb 'aegis -b \!*	-v'
	sh$	aeb(){aegis -b "$@" -v}

ERRORS
	It is an error if the change is	not assigned to	the current user.
	It is an error if the change is	not in one of the being	developed or
	being integrated states.
	It is an error if a partial build is requested and the change is in
	the being integrated state.

EXIT STATUS
	The aegis command will exit with a status of 1 on any error.  The
	aegis command will only	exit with a status of 0	if there are no
	errors.

ENVIRONMENT VARIABLES
	See aegis(1) for a list	of environment variables which may affect this
	command.  See aepconf(5) for the project configuration file's
	project_specific field for how to set environment variables for	all
	commands executed by Aegis.

SEE ALSO
	aedb(1)	begin development of a change

	aecp(1)	file copy also takes a baseline	read lock (non-exclusive)

	aeib(1)	begin integration of a change

	aeipass(1)
		integrate pass takes a baseline	write lock (exclusive)

	aet(1)	run tests

	aemetrics(5)
		metrics	values file format

	aepconf(5)
		project	configuration file format

	aeuconf(5)
		user configuration file	format

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		       aegis -Build(1)

NAME | SYNOPSIS | DESCRIPTION | PARTIAL BUILD | SYMBOLIC LINKS | THE BASELINE LOCK | METRICS | OPTIONS | RECOMMENDED ALIAS | ERRORS | EXIT STATUS | ENVIRONMENT VARIABLES | SEE ALSO | COPYRIGHT | AUTHOR

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

home | help