Home | History | Annotate | Download | only in binary_search_tool 
      1 
      2 bisect.py is a wrapper around the general purpose binary_search_state.py. It
      3 provides a user friendly interface for bisecting various compilation errors.
      4 The 2 currently provided methods of bisecting are ChromeOS package and object
      5 bisection. Each method defines a default set of options to pass to
      6 binary_search_state.py and allow the user to override these defaults (see
      7 the "Overriding" section).
      8 
      9 ** NOTE **
     10 All commands, examples, scripts, etc. are to be run from your chroot unless
     11 stated otherwise.
     12 
     13 Bisection Methods:
     14 
     15 1) ChromeOS Package:
     16   This method will bisect across all packages in a ChromeOS repository and find
     17   the offending packages (according to your test script). This method takes the
     18   following arguments:
     19 
     20     board: The board to bisect on. For example: daisy, falco, etc.
     21     remote: The IP address of the physical machine you're using to test with.
     22 
     23   By default the ChromeOS package method will do a simple interactive test that
     24   pings the machine and prompts the user if the machine is good.
     25 
     26   a) Setup:
     27     The ChromeOS package method requires that you have three build trees:
     28 
     29       /build/${board}.bad  - The build tree for your "bad" build
     30       /build/${board}.good - The build tree for your "good" build
     31       /build/${board}.work - A full copy of /build/${board}.bad
     32 
     33   b) Cleanup:
     34     bisect.py does most cleanup for you, the only thing required by the user is
     35     to cleanup all built images and the three build trees made in /build/
     36 
     37   c) Default Arguments:
     38     --get_initial_items='cros_pkg/get_initial_items.sh'
     39     --switch_to_good='cros_pkg/switch_to_good.sh'
     40     --switch_to_bad='cros_pkg/switch_to_bad.sh'
     41     --test_setup_script='cros_pkg/test_setup.sh'
     42     --test_script='cros_pkg/interactive_test.sh'
     43     --incremental
     44     --prune
     45     --file_args
     46 
     47   d) Additional Documentation:
     48     See ./cros_pkg/README.cros_pkg_triage for full documentation of ChromeOS
     49     package bisection.
     50 
     51   e) Examples:
     52     i)  Basic interactive test package bisection, on daisy board:
     53         ./bisect.py package daisy 172.17.211.184
     54 
     55     ii) Basic boot test package bisection, on daisy board:
     56         ./bisect.py package daisy 172.17.211.184 -t cros_pkg/boot_test.sh
     57 
     58 2) ChromeOS Object:
     59   This method will bisect across all objects in a ChromeOS package and find
     60   the offending objects (according to your test script). This method takes the
     61   following arguments:
     62 
     63     board: The board to bisect on. For example: daisy, falco, etc.
     64     remote: The IP address of the physical machine you're using to test with.
     65     package: The package to bisect with. For example: chromeos-chrome
     66     dir: (Optional) the directory for your good/bad build trees. Defaults to
     67          $BISECT_DIR or /tmp/sysroot_bisect. This value will set $BISECT_DIR
     68          for all bisecting scripts.
     69 
     70   By default the ChromeOS object method will do a simple interactive test that
     71   pings the machine and prompts the user if the machine is good.
     72 
     73   a) Setup:
     74     The ChromeOS package method requires that you populate your good and bad set
     75     of objects. sysroot_wrapper will automatically detect the BISECT_STAGE
     76     variable and use this to populate emerged objects. Here is an example:
     77 
     78       # Defaults to /tmp/sysroot_bisect
     79       export BISECT_DIR="/path/to/where/you/want/to/store/builds/"
     80 
     81       export BISECT_STAGE="POPULATE_GOOD"
     82       ./switch_to_good_compiler.sh
     83       emerge-${board} -C ${package_to_bisect}
     84       emerge-${board} ${package_to_bisect}
     85 
     86       export BISECT_STAGE="POPULATE_BAD"
     87       ./switch_to_bad_compiler.sh
     88       emerge-${board} -C {package_to_bisect}
     89       emerge-${board} ${package_to_bisect}
     90 
     91   b) Cleanup:
     92     The user must clean up all built images and the populated object files.
     93 
     94   c) Default Arguments:
     95     --get_initial_items='sysroot_wrapper/get_initial_items.sh'
     96     --switch_to_good='sysroot_wrapper/switch_to_good.sh'
     97     --switch_to_bad='sysroot_wrapper/switch_to_bad.sh'
     98     --test_setup_script='sysroot_wrapper/test_setup.sh'
     99     --test_script='sysroot_wrapper/interactive_test.sh'
    100     --noincremental
    101     --prune
    102     --file_args
    103 
    104   d) Additional Documentation:
    105     See ./sysroot_wrapper/README for full documentation of ChromeOS object file
    106     bisecting.
    107 
    108   e) Examples:
    109     i)  Basic interactive test object bisection, on daisy board for
    110         cryptohome package:
    111         ./bisect.py object daisy 172.17.211.184 cryptohome
    112 
    113     ii) Basic boot test package bisection, on daisy board for cryptohome
    114         package:
    115         ./bisect.py object daisy 172.17.211.184 cryptohome \
    116         --test_script=sysroot_wrapper/boot_test.sh
    117 
    118 3) Android object:
    119   NOTE: Because this isn't a ChromeOS bisection tool, the concept of a
    120         chroot doesn't exist. Just run this tool from a normal shell.
    121 
    122   This method will bisect across all objects in the Android source tree and
    123   find the offending objects (according to your test script). This method takes
    124   the following arguments:
    125 
    126     android_src: The location of your android source tree
    127     num_jobs: (Optional) The number of jobs to pass to make. This is dependent
    128               on how many cores your machine has. A good number is probably
    129 	      somewhere around 5 to 10.
    130     device_id: (Optional) The serial code for the device you are testing on.
    131                This is used to determine which device should be used in case
    132 	       multiple devices are plugged into your computer. You can get
    133 	       serial code for your device by running "adb devices".
    134     dir: (Optional) the directory for your good/bad build trees. Defaults to
    135          $BISECT_DIR or ~/ANDROID_BISECT/. This value will set $BISECT_DIR
    136          for all bisecting scripts.
    137 
    138   By default the Android object method will do a simple interactive test that
    139   pings the machine and prompts the user if the machine is good.
    140 
    141   a) Setup:
    142     The Android object method requires that you populate your good and bad set
    143     of objects. The Android compiler wrapper will automatically detect the
    144     BISECT_STAGE variable and use this to populate emerged objects. Here is an
    145     example:
    146 
    147       # Defaults to ~/ANDROID_BISECT/
    148       export BISECT_DIR="/path/to/where/you/want/to/store/builds/"
    149 
    150       export BISECT_STAGE="POPULATE_GOOD"
    151       # Install the "good" compiler
    152       ./switch_to_good_compiler.sh
    153       make clean
    154       make -j <your_preferred_number_of_jobs>
    155 
    156       export BISECT_STAGE="POPULATE_BAD"
    157       # Install the "bad" compiler
    158       ./switch_to_bad_compiler.sh
    159       make clean
    160       make -j <your_preferred_number_of_jobs>
    161 
    162   b) Cleanup:
    163     The user must clean up all built images and the populated object files.
    164 
    165   c) Default Arguments:
    166     --get_initial_items='android/get_initial_items.sh'
    167     --switch_to_good='android/switch_to_good.sh'
    168     --switch_to_bad='android/switch_to_bad.sh'
    169     --test_setup_script='android/test_setup.sh'
    170     --test_script='android/interactive_test.sh'
    171     --incremental
    172     --prune
    173     --file_args
    174 
    175   d) Additional Documentation:
    176     See ./android/README.android for full documentation of Android object file
    177     bisecting.
    178 
    179   e) Examples:
    180     i)  Basic interactive test android bisection, where the android source is
    181         at ~/android_src:
    182         ./bisect.py android ~/android_src
    183 
    184     ii) Basic boot test android bisection, where the android source is at
    185         ~/android_src, and 10 jobs will be used to build android:
    186         ./bisect.py android ~/android_src --num_jobs=10 \
    187         --test_script=sysroot_wrapper/boot_test.sh
    188 
    189 Resuming:
    190   bisect.py and binary_search_state.py offer the ability to resume a bisection
    191   in case it was interrupted by a SIGINT, power failure, etc. Every time the
    192   tool completes a bisection iteration its state is saved to disk (usually to
    193   the file "./bisect.py.state"). If passed the --resume option, the tool
    194   it will automatically detect the state file and resume from the last
    195   completed iteration.
    196 
    197 Overriding:
    198   You can run ./bisect.py --help or ./binary_search_state.py --help for a full
    199   list of arguments that can be overriden. Here are a couple of examples:
    200 
    201   Example 1 (do boot test instead of interactive test):
    202   ./bisect.py package daisy 172.17.211.182 --test_script=cros_pkg/boot_test.sh
    203 
    204   Example 2 (do package bisector system test instead of interactive test, this
    205              is used to test the bisecting tool itself -- see comments in
    206              hash_test.sh for more details):
    207   ./bisect.py package daisy 172.17.211.182 \
    208     --test_script=common/hash_test.sh --test_setup_script=""
    209 
    210   Example 3 (enable verbose mode, disable pruning, and disable verification):
    211   ./bisect.py package daisy 172.17.211.182 \
    212   --verbose --prune=False --verify=False
    213 
    214