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