Cassidy Burden | a9d7077 | 2016-06-29 10:28:44 -0700 | [diff] [blame] | 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' |
Cassidy Burden | a5e3929 | 2016-08-08 10:27:34 -0700 | [diff] [blame] | 41 | --test_setup_script='cros_pkg/test_setup.sh' |
Cassidy Burden | a9d7077 | 2016-06-29 10:28:44 -0700 | [diff] [blame] | 42 | --test_script='cros_pkg/interactive_test.sh' |
Cassidy Burden | d5113fb | 2016-06-29 13:51:20 -0700 | [diff] [blame] | 43 | --incremental |
Cassidy Burden | a9d7077 | 2016-06-29 10:28:44 -0700 | [diff] [blame] | 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: |
Cassidy Burden | d5113fb | 2016-06-29 13:51:20 -0700 | [diff] [blame] | 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 |
Cassidy Burden | 39c0c21 | 2016-07-01 15:53:49 -0700 | [diff] [blame] | 79 | export BISECT_DIR="/path/to/where/you/want/to/store/builds/" |
Cassidy Burden | d5113fb | 2016-06-29 13:51:20 -0700 | [diff] [blame] | 80 | |
Cassidy Burden | 39c0c21 | 2016-07-01 15:53:49 -0700 | [diff] [blame] | 81 | export BISECT_STAGE="POPULATE_GOOD" |
Cassidy Burden | d5113fb | 2016-06-29 13:51:20 -0700 | [diff] [blame] | 82 | ./switch_to_good_compiler.sh |
| 83 | emerge-${board} -C ${package_to_bisect} |
| 84 | emerge-${board} ${package_to_bisect} |
| 85 | |
Cassidy Burden | 39c0c21 | 2016-07-01 15:53:49 -0700 | [diff] [blame] | 86 | export BISECT_STAGE="POPULATE_BAD" |
Cassidy Burden | d5113fb | 2016-06-29 13:51:20 -0700 | [diff] [blame] | 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' |
Cassidy Burden | a5e3929 | 2016-08-08 10:27:34 -0700 | [diff] [blame] | 98 | --test_setup_script='sysroot_wrapper/test_setup.sh' |
Cassidy Burden | d5113fb | 2016-06-29 13:51:20 -0700 | [diff] [blame] | 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 |
Cassidy Burden | a9d7077 | 2016-06-29 10:28:44 -0700 | [diff] [blame] | 117 | |
Cassidy Burden | 711a224 | 2016-07-27 15:21:57 -0700 | [diff] [blame] | 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' |
Cassidy Burden | a5e3929 | 2016-08-08 10:27:34 -0700 | [diff] [blame] | 169 | --test_setup_script='android/test_setup.sh' |
Cassidy Burden | 711a224 | 2016-07-27 15:21:57 -0700 | [diff] [blame] | 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 | |
Cassidy Burden | a9d7077 | 2016-06-29 10:28:44 -0700 | [diff] [blame] | 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 | |
Cassidy Burden | 0f07f97 | 2016-07-18 15:59:46 -0700 | [diff] [blame] | 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): |
Cassidy Burden | a9d7077 | 2016-06-29 10:28:44 -0700 | [diff] [blame] | 207 | ./bisect.py package daisy 172.17.211.182 \ |
Cassidy Burden | a5e3929 | 2016-08-08 10:27:34 -0700 | [diff] [blame] | 208 | --test_script=common/hash_test.sh --test_setup_script="" |
Cassidy Burden | a9d7077 | 2016-06-29 10:28:44 -0700 | [diff] [blame] | 209 | |
Cassidy Burden | b1d0c4e | 2016-08-03 09:46:20 -0700 | [diff] [blame] | 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 |
Cassidy Burden | a9d7077 | 2016-06-29 10:28:44 -0700 | [diff] [blame] | 213 | |