aebisect(1) General Commands Manual aebisect(1) NNAAMMEE aebisect - search for a delta which changed project behaviour SSYYNNOOPPSSIISS aaeebbiisseecctt [_o_p_t_i_o_n...] [-Branch _b_r_a_n_c_h_1] -DELta _d_e_l_t_a_1 [-Branch _b_r_a_n_c_h_2] -DELta _d_e_l_t_a_2 -- _c_o_m_m_a_n_d [command_args] DDEESSCCRRIIPPTTIIOONN The aaeebbiisseecctt 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, aaeebbiisseecctt sets up a development directory, builds the project, and then runs the specified _c_o_m_m_a_n_d in the development directory. By iteration, aaeebbiisseecctt finds two consecu- tive deltas where the return code of _c_o_m_m_a_n_d changed. Note: aaeebbiisseecctt can take considerable CPU effort, since it (normally) does a full build from scratch for each delta tested. OOPPTTIIOONNSS The following options are understood: --HHeellpp Show usage information. --PPrroojjeecctt _p_r_o_j_e_c_t_-_n_a_m_e specify the project (otherwise done via the AAEEGGIISS__PPRROOJJEECCTT environ- ment variable) --CChhaannggee _c_h_a_n_g_e_-_n_u_m_b_e_r specify the change to use for the processing (otherwise done via the AAEEGGIISS__CCHHAANNGGEE environment variable). The change must be in the _a_w_a_i_t_i_n_g___d_e_v_e_l_o_p_m_e_n_t state; this ensures a correct environment for building and testing. --BBrraanncchh _b_r_a_n_c_h_-_e_x_t_e_n_s_i_o_n specify the branch for one of the deltas. Defaults to the baseline branch of the project. Use --bb -- (single dash) to specify the trunk. Branch specifiers must precede the corresponding delta specifiers. --LLooggffiillee _l_o_g_f_i_l_e specify where normal output goes; defaults to _$_H_O_M_E_/_a_e_b_i_s_e_c_t_._l_o_g. --VVeerrbboossee produce more diagnostic information (both logfile and standard out- put). --KKeeeepp do not delete working files, which are in a temporary directory. Warning: these may be voluminous! --DDIIRReeccttoorryy _p_a_t_h specify a development directory to use for building and testing. --MMiinniimmuumm use the --mmiinniimmuumm option for the builds. --NNoobbuuiilldd skip the build steps. This option is useful if the test command only involves source files. (Consider using aaeeaannnnoottaattee(1) instead.) --ZZeerroo__oonnllyy treat all test result codes other than 0 as equivalent. DDIIAAGGNNOOSSTTIICCSS 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. SSIIGGNNAALLSS aaeebbiisseecctt will stop on INT, QUIT, and TERM signals, probably leaving the development directory in an uncertain state. EEXXAAMMPPLLEE Suppose a bug was introduced by development on project _f_o_o_-_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 aaeenntt(1)), called _/_w_r_k_/_t_e_s_t_/_0_0_/_t_0_0_0_7_a_._s_h, 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. BBUUGGSS aaeebbiisseecctt depends on aaeeccpp --ddeellttaa 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, aaeebbiisseecctt 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 aaeeddbbuu when done. In some situations the problem may be cured by an additional step between aaeeddbb and aaeebb. A command to be interposed may be defined via the environment variable AAEEBBIISSEECCTT__DDBB__HHOOOOKK; this command is executed after aaeeccpp, so it may be used to patch source files -- see the script source for details. CCOOPPYYRRIIGGHHTT 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)