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