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)

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

home | help