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

FreeBSD Manual Pages

  
 
  

home | help
aegis -Integrate_Pass(1)    General Commands Manual   aegis -Integrate_Pass(1)

NAME
	aegis integrate	pass - pass a change integration

SYNOPSIS
	aegis -Integrate_Pass [	option...  ]
	aegis -Integrate_Pass -List [ option...	 ]
	aegis -Integrate_Pass -Help

DESCRIPTION
	The aegis -Integrate_Pass command is used to notify aegis that a
	change has passed integration.	The change is advanced from the	being
	integrated state to the	completed state.  boxwid = 1 down box "being"
	"integrated" arrow " integrate"	ljust "	pass" ljust box	"completed"

	This command updates the file histories, so that future	aecp(1)	com-
	mands may extract previous file	versions from history, and so that fu-
	ture aed(1) commands may merge out-of-date files.  The history is up-
	dated using the	history_create_command and history_put_command fields
	of the project configuration file (see aepconf(5) for more informa-
	tion).	The integrate pass will	abort with an error if one of these
	history	commands should	fail, e.g. by running out of disk space.  If
	this should happen, the	change will remain in the being	integrated
	state, and the integration directory is	unaltered.

	Once the history has been updated, the integration directory is	re-
	named as the baseline directory, and the old baseline directory	is
	deleted.

	Once integrate pass is complete	the change is no longer	assigned to
	the current user.

   History Tools Modify	Files
	Many history tools (e.g. RCS and SCCS) can modify the contents of the
	file when it is	committed.  This usually requires the use of specific
	"keyword" strings, and there are usually options to turn this behavior
	off, but users familiar	with version control tools (as opposed to con-
	figuration management systems) will often use these features.  The
	problem	is that	if the commit changes the file,	the source file	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.	 By default, a fatal error is emitted if the file is
	changed	by the check-in, however this can be modified to a be warning
	or even	ignored	completely; see	the history_put_trashes_file field of
	aepconf(5) for more information.

   File	Modification Times
	The modification times of all files modified since the beginning of
	integration (see aeib(1) for more information) are updated to be since
	the beginning of integrate pass.  The order of modification times will
	be preserved, however the time range will be compressed	to the great-
	est extent possible.  This ensures that	subsequent development builds
	will notice that baseline files	have changed.

	Note that if there are many new	files with all different timestamps in
	the integration	directory, and if the number of	files with different
	timestamps exceeds the number of seconds since the start of the	inte-
	grate-pass command, Aegis may have to set file modification times into
	the future.

	The build_time_adjust field of the project config file controls	Aegis'
	behavior in this case.	(See aepconf(5)	for more information.)	There
	are three settings:

	adjust_and_sleep
		This setting, which is the default, causes Aegis to sleep un-
		til the	file modification times	would no longer	be in the fu-
		ture.  This avoids both	development build problems and inte-
		gration	build problems,	both of	which which can	arise as a re-
		sult "interesting" file	modification times.

	adjust_only
		Aegis will issue a warning that	the file modification times
		extend into the	future,	but will not sleep.  This may cause
		integration build problems, particularly if you	are using
		aeintegratq(1).	 Development builds may	perform	redundant
		builds,	however	aet -reg should	not produce false negatives.

	dont_adjust
		This is	highly inadvisable.  It	is provided solely for some
		very rare circumstances.  This setting causes Aegis not	to ad-
		just the file modification times at all.  This can have	very
		unhappy	side-effects, especially of the	integration build was
		before one or more development builds; the commonest symptom
		being that development builds do not always cause a relink of
		the necessary executables, and aet -reg	may give false nega-
		tives.	It is strongly recommended that	you do not use this
		setting.

	If you use cook(1), see	the time-adjust-back flag for how to compress
	the time range even further.  This usually makes the sleep (or the
	warning	period)	significantly shorter.

   Notification
	On successful completion of this command, after	the directory rename
	has ocurred and	after the database has been updated, the integration_-
	pass_notify_command field of the project attributes is run, if set.
	See aepattr(5) and aepa(1) for more information.  This command is run
	as the project owner.

	Some compilers bury absolute path names	into object files and executa-
	bles.  The renaming of the integration directory to become the new
	baseline breaks	these paths.  The above	command	is passed an environ-
	ment variable called AEGIS_INTEGRATION_DIRECTORY so that the appropri-
	ate symlink may	be placed, if desired.

	Other commands run by this command include the history_create_command,
	history_put_command and	history_query_command fields of	the project
	config file.  See aepconf(5) for more information.

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	in-
	clude 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-ex-
	clusive) locked.

   The History Lock
	Where a	project	has a number of	branches active	simultaneously,	it is
	possible for independent integrate pass	commands for different
	branches to be issued very close together.  The	is an exclusive	his-
	tory lock taken	by integrate pass to ensure that only one branch is
	updating the file history at a time, thus preventing history file cor-
	ruption.

TEST CORRELATIONS
	The "aegis -Test -SUGgest" command may be used to have aegis suggest
	suitable regression tests for your change, based on the	source files
	in your	change.	 This automatically focuses testing effort to relevant
	tests, reducing	the number of regression tests necessary to be confi-
	dent that you have not introduced a bug.

	The test correlations are generated by the "aegis -Integrate_Pass"
	command, which associates each test in the change with each source
	file in	the change.  Thus, each	source file accumulates	a list of
	tests which have been associated with it in the	past.  This is not as
	exact as code coverage analysis, but is	a reasonable approximation in
	practice.

	The aecp(1) and	aenf(1)	commands are used to associate files with a
	change.	 While they do not actively perform the	association, these are
	the files used by aeipass(1) and aet(1)	to determine which source
	files are associated with which	tests.

   Test	Correlation Accuracy
	Assuming that the testing correlations are accurate and	that the tests
	are evenly distributed across the function space, there	will be	a less
	than 1/number chance that a relevant test has not been run by the
	"aegis -Test -SUGgest number" command.	A small	amount of noise	is
	added to the test weighting, so	that unexpected	things are sometimes
	tested,	and the	same tests are not run every time.

	Test correlation accuracy can be improved by ensuring that:

	o Each change should be	strongly focused, with no gratuitous file in-
	  clusions.  This avoids spurious correlations.

	o Each item of new functionality should	be added in an individual
	  change, rather than several together.	 This strongly correlates
	  tests	with functionality.

	o Each bug should be fixed in an individual change, rather than	sev-
	  eral together.  This strongly	correlates tests with functionality.

	o Test correlations will be lost if files are moved.  This is because
	  correlations are by name.

	The best way for tests to correlate accurately with source files is
	when a change contains a test and exactly those	files relating to the
	functionality under test.  Too many spurious files will	weaken the
	usefulness of the testing correlations.

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:

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

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

	-REAson	text
		This option may	be used	to attach a comment to the change his-
		tory generated by this command.	 You will need to use quotes
		to insulate the	spaces from the	shell.

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

	-Wait	This option may	be used	to require Aegis commands to wait for
		access locks, if they cannot be	obtained immediately.  De-
		faults 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 op-
	tional.	 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	"--op-
	tion=value" convention is also understood.

RECOMMENDED ALIAS
	The recommended	alias for this command is
	csh%	alias aeipass 'aegis -ipass \!*	-v'
	sh$	aeipass(){aegis	-ipass "$@" -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 the being integrated state.
	It is an error if there	has been no successful 'aegis -Build' command
	for the	integration.
	It is an error if there	has been no successful 'aegis -Test' command
	for the	integration.
	It is an error if there	has been no successful 'aegis -Test -BaseLine'
	command	for the	integration.

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	er-
	rors.

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
	aeib(1)	begin integration of a change

	aeifail(1)
		fail integration of a change

	aemeasure(1)
		simple file metrics

	aemetrics(5)
		metrics	values 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 -Integrate_Pass(1)

NAME | SYNOPSIS | DESCRIPTION | THE BASELINE LOCK | TEST CORRELATIONS | 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=aeipass&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help