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