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
|
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).
** NOTE **
All commands, examples, scripts, etc. are to be run from your chroot unless
stated otherwise.
Bisection Methods:
1) 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.
a) 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
b) 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/
c) 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'
--install_script='cros_pkg/install.sh'
--test_script='cros_pkg/interactive_test.sh'
--incremental
--prune
--file_args
d) Additional Documentation:
See ./cros_pkg/README.cros_pkg_triage for full documentation of ChromeOS
package bisection.
e) Examples:
i) Basic interactive test package bisection, on daisy board:
./bisect.py package daisy 172.17.211.184
ii) Basic boot test package bisection, on daisy board:
./bisect.py package daisy 172.17.211.184 -t cros_pkg/boot_test.sh
2) 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.
a) 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}
b) Cleanup:
The user must clean up all built images and the populated object files.
c) 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'
--install_script='sysroot_wrapper/install.sh'
--test_script='sysroot_wrapper/interactive_test.sh'
--noincremental
--prune
--file_args
d) Additional Documentation:
See ./sysroot_wrapper/README for full documentation of ChromeOS object file
bisecting.
e) Examples:
i) Basic interactive test object bisection, on daisy board for
cryptohome package:
./bisect.py object daisy 172.17.211.184 cryptohome
ii) 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
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.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 --install_script=""
Example 3 (enable verbose mode and disable pruning):
./bisect.py package daisy 172.17.211.182 --verbose --noprune
|
