xref: /aosp_15_r20/external/toolchain-utils/binary_search_tool/README.bisect.md (revision 760c253c1ed00ce9abd48f8546f08516e57485fe) 
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* use_flags: (Optional) Use flags for emerge. For example: "-thinlto -cfi".
80* noreboot: (Optional) Do not reboot after updating the package.
81* dir: (Optional) the directory for your good/bad build trees. Defaults to
82       $BISECT_DIR or /tmp/sysroot_bisect. This value will set $BISECT_DIR
83       for all bisecting scripts.
84
85By default the ChromeOS object method will do a simple interactive test that
86pings the machine and prompts the user if the machine is good.
87
881.  Setup: The ChromeOS package method requires that you populate your good and
89    bad set of objects. `sysroot_wrapper` will automatically detect the
90    `BISECT_STAGE` variable and use this to populate emerged objects. Here is an
91    example:
92
93    ```
94    # Defaults to /tmp/sysroot_bisect
95    export BISECT_DIR="/path/to/where/you/want/to/store/builds/"
96
97    export BISECT_STAGE="POPULATE_GOOD"
98    ./switch_to_good_compiler.sh
99    emerge-${board} -C ${package_to_bisect}
100    emerge-${board} ${package_to_bisect}
101
102    export BISECT_STAGE="POPULATE_BAD"
103    ./switch_to_bad_compiler.sh
104    emerge-${board} -C {package_to_bisect}
105    emerge-${board} ${package_to_bisect}
106    ```
107
1081.  Cleanup: The user must clean up all built images and the populated object
109    files.
110
1111.  Default Arguments:
112
113    ```
114    --get_initial_items='sysroot_wrapper/get_initial_items.sh'
115    --switch_to_good='sysroot_wrapper/switch_to_good.sh'
116    --switch_to_bad='sysroot_wrapper/switch_to_bad.sh'
117    --test_setup_script='sysroot_wrapper/test_setup.sh'
118    --test_script='sysroot_wrapper/interactive_test.sh'
119    --noincremental
120    --prune
121    --file_args
122    ```
123
1241.  Additional Documentation: See `./sysroot_wrapper/README` for full
125    documentation of ChromeOS object file bisecting.
126
1271.  Examples:
128
129    1.  Basic interactive test object bisection, on daisy board for cryptohome
130        package: `./run_bisect.py object daisy 172.17.211.184 cryptohome`
131
132    2.  Basic boot test package bisection, on daisy board for cryptohome
133        package: `./run_bisect.py object daisy 172.17.211.184 cryptohome
134        --test_script=sysroot_wrapper/boot_test.sh`
135
136### Android object
137
138NOTE: Because this isn't a ChromeOS bisection tool, the concept of a
139      chroot doesn't exist. Just run this tool from a normal shell.
140
141This method will bisect across all objects in the Android source tree and
142find the offending objects (according to your test script). This method takes
143the following arguments:
144
145*   `android_src`: The location of your android source tree
146
147*   `num_jobs`: (Optional) The number of jobs to pass to make. This is dependent
148    on how many cores your machine has. A good number is probably somewhere
149    around 5 to 10.
150
151*   `device_id`: (Optional) The serial code for the device you are testing on.
152    This is used to determine which device should be used in case multiple
153    devices are plugged into your computer. You can get serial code for your
154    device by running "adb devices".
155
156*   `dir`: (Optional) the directory for your good/bad build trees. Defaults to
157    `$BISECT_DIR` or `~/ANDROID_BISECT/`. This value will set `$BISECT_DIR` for
158    all bisecting scripts.
159
160  By default the Android object method will do a simple interactive test that
161  pings the machine and prompts the user if the machine is good.
162
1631.  Setup: The Android object method requires that you populate your good and
164    bad set of objects. The Android compiler wrapper will automatically detect
165    the `BISECT_STAGE` variable and use this to populate emerged objects. Here
166    is an example:
167
168    ```
169    # Defaults to ~/ANDROID_BISECT/
170    export BISECT_DIR="/path/to/where/you/want/to/store/builds/"
171
172    export BISECT_STAGE="POPULATE_GOOD"
173    # Install the "good" compiler
174    ./switch_to_good_compiler.sh
175    make clean
176    make -j <your_preferred_number_of_jobs>
177
178    export BISECT_STAGE="POPULATE_BAD"
179    # Install the "bad" compiler
180    ./switch_to_bad_compiler.sh
181    make clean
182    make -j <your_preferred_number_of_jobs>
183    ```
184
1851.  Cleanup: The user must clean up all built images and the populated object
186    files.
187
1881.  Default Arguments:
189
190    ```
191    --get_initial_items='android/get_initial_items.sh'
192    --switch_to_good='android/switch_to_good.sh'
193    --switch_to_bad='android/switch_to_bad.sh'
194    --test_setup_script='android/test_setup.sh'
195    --test_script='android/interactive_test.sh'
196    --incremental
197    --prune
198    --file_args
199    ```
200
2011.  Additional Documentation: See `./android/README.android` for full
202    documentation of Android object file bisecting.
203
2041.  Examples:
205
206    1.  Basic interactive test android bisection, where the android source is at
207        ~/android_src: `./run_bisect.py android ~/android_src`
208
209    2. Basic boot test android bisection, where the android source is at
210       `~/android_src`, and 10 jobs will be used to build android:
211       `./run_bisect.py
212       android ~/android_src --num_jobs=10
213       --test_script=sysroot_wrapper/boot_test.sh`
214
215### Resuming
216
217`run_bisect.py` and `binary_search_state.py` offer the
218ability to resume a bisection in case it was interrupted by a
219SIGINT, power failure, etc. Every time the tool completes a
220bisection iteration its state is saved to disk (usually to the file
221`./bisect_driver.py.state`). If passed the --resume option, the tool
222it will automatically detect the state file and resume from the last
223completed iteration.
224
225### Overriding
226
227You can run `./run_bisect.py --help` or `./binary_search_state.py
228--help` for a full list of arguments that can be overriden. Here are
229a couple of examples:
230
231Example 1 (do boot test instead of interactive test):
232
233```
234./run_bisect.py package daisy 172.17.211.182 --test_script=cros_pkg/boot_test.sh
235```
236
237Example 2 (do package bisector system test instead of interactive test, this
238           is used to test the bisecting tool itself -- see comments in
239           hash_test.sh for more details):
240
241```
242./run_bisect.py package daisy 172.17.211.182 \
243    --test_script=common/hash_test.sh --test_setup_script=""
244```
245
246Example 3 (enable verbose mode, disable pruning, and disable verification):
247
248```
249./run_bisect.py package daisy 172.17.211.182
250      --verbose --prune=False --verify=False
251```
252