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

FreeBSD Manual Pages

  
 
  

home | help
aebisect(1)		    General Commands Manual		   aebisect(1)

NAME
	aebisect - search for a	delta which changed project behaviour

SYNOPSIS
	aebisect [option...] [-Branch branch1] -DELta delta1 [-Branch branch2]
		 -DELta	delta2 -- command [command_args]

DESCRIPTION
	The aebisect command is	used to	determine when in a project history
	some property or behavior changed. It does this	by means of a bisec-
	tion search through the	inventory of deltas. The user must specify
	starting and ending deltas, which may be in historical branches	of the
	project.

	For each delta tested in the search, aebisect sets up a	development
	directory, builds the project, and then	runs the specified command in
	the development	directory. By iteration, aebisect finds	two consecu-
	tive deltas where the return code of command changed.

	Note: aebisect can take	considerable CPU effort, since it (normally)
	does a full build from scratch for each	delta tested.

OPTIONS
	The following options are understood:

	-Help
	   Show	usage information.

	-Project project-name
	   specify the project (otherwise done via the AEGIS_PROJECT environ-
	   ment	variable)

	-Change	change-number
	   specify the change to use for the processing	(otherwise done	via
	   the AEGIS_CHANGE environment	variable). The change must be in the
	   awaiting_development	state; this ensures a correct environment for
	   building and	testing.

	-Branch	branch-extension
	   specify the branch for one of the deltas. Defaults to the baseline
	   branch of the project. Use -b - (single dash) to specify the	trunk.
	   Branch specifiers must precede the corresponding delta specifiers.

	-Logfile logfile
	   specify where normal	output goes; defaults to $HOME/aebisect.log.

	-Verbose
	   produce more	diagnostic information (both logfile and standard out-
	   put).

	-Keep
	   do not delete working files,	which are in a temporary directory.
	   Warning: these may be voluminous!

	-DIRectory path
	   specify a development directory to use for building and testing.

	-Minimum
	   use the -minimum option for the builds.

	-Nobuild
	   skip	the build steps. This option is	useful if the test command
	   only	involves source	files. (Consider using aeannotate(1) instead.)

	-Zero_only
	   treat all test result codes other than 0 as equivalent.

DIAGNOSTICS
	Normally, exit status is 0 if consecutive deltas are found to bracket
	a change in the	test command result. Exit status is 1 if errors	are
	detected in arguments. Exit status is 2	if a subordinate command fails
	(possibly leaving the development directory in an uncertain state) or
	if the test behavior is	found to be inconsistent with bisection
	search.

SIGNALS
	aebisect will stop on INT, QUIT, and TERM signals, probably leaving
	the development	directory in an	uncertain state.

EXAMPLE
	Suppose	a bug was introduced by	development on project foo-4.5,	some-
	time between version 1.2.D003 and 4.5.D006, and	you have written an
	Aegis test script for the bug (see aent(1)), called
	/wrk/test/00/t0007a.sh,	taking an argument for system architecture.
	Then the following should isolate the change which introduced the bug:

	    % aenc -p foo-4.5 -c 20 -file caf
	    % aebisect -p foo-4.5 -c 20	-b 1.2 -del 3 -b 4.5 -del 6 \
		-- sh /wrk/test/00/t0007a.sh linux-i486

	Note that the full path	for the	test script is specified, since	the
	command	is executed in a development directory.

BUGS
	aebisect depends on aecp -delta	for historical reconstructions.	This
	can be problematic.

	It is possible for a build to fail: derived files from the baseline
	may poison the build, or there may have	been changes in	the system in-
	frastructure since the old deltas were integrated. In such cases, ae-
	bisect exits. The user may then	snoop around the development direc-
	tory, fix something, rebuild, perform the test,	and use	the logfile to
	see how	to proceed. Remember to	aedbu when done.

	In some	situations the problem may be cured by an additional step be-
	tween aedb and aeb. A command to be interposed may be defined via the
	environment variable AEBISECT_DB_HOOK; this command is executed	after
	aecp, so it may	be used	to patch source	files -- see the script	source
	for details.

COPYRIGHT
	Copyright (C) 2007 Ralph Smith

	Partially derived from aeintegratq, Copyright (C) 1998-2005 Endocar-
	dial Solutions,	Inc.

	This is	free software; see the source for copying conditions. There is
	NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
	PURPOSE.

Reference Manual		     Aegis			   aebisect(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | DIAGNOSTICS | SIGNALS | EXAMPLE | BUGS | COPYRIGHT

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

home | help