README.bisect revision b1d0c4e00ed787befa9591231ac5d04d2cf6795d 
1
2bisect.py is a wrapper around the general purpose binary_search_state.py. It
3provides a user friendly interface for bisecting various compilation errors.
4The 2 currently provided methods of bisecting are ChromeOS package and object
5bisection. Each method defines a default set of options to pass to
6binary_search_state.py and allow the user to override these defaults (see
7the "Overriding" section).
8
9** NOTE **
10All commands, examples, scripts, etc. are to be run from your chroot unless
11stated otherwise.
12
13Bisection Methods:
14
151) 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'
41    --install_script='cros_pkg/install.sh'
42    --test_script='cros_pkg/interactive_test.sh'
43    --incremental
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
582) ChromeOS Object:
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
79      export BISECT_DIR="/path/to/where/you/want/to/store/builds/"
80
81      export BISECT_STAGE="POPULATE_GOOD"
82      ./switch_to_good_compiler.sh
83      emerge-${board} -C ${package_to_bisect}
84      emerge-${board} ${package_to_bisect}
85
86      export BISECT_STAGE="POPULATE_BAD"
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'
98    --install_script='sysroot_wrapper/install.sh'
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
117
1183) 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'
169    --install_script='android/install.sh'
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
189Resuming:
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
197Overriding:
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
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):
207  ./bisect.py package daisy 172.17.211.182 \
208    --test_script=common/hash_test.sh --install_script=""
209
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
213
214