README.bisect revision 39c0c2109ad3b7e89a2a51e0c567b94103415d69 
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
118Resuming:
119  bisect.py and binary_search_state.py offer the ability to resume a bisection
120  in case it was interrupted by a SIGINT, power failure, etc. Every time the
121  tool completes a bisection iteration its state is saved to disk (usually to
122  the file "./bisect.py.state"). If passed the --resume option, the tool
123  it will automatically detect the state file and resume from the last
124  completed iteration.
125
126Overriding:
127  You can run ./bisect.py --help or ./binary_search_state.py --help for a full
128  list of arguments that can be overriden. Here are a couple of examples:
129
130  Example 1 (do boot test instead of interactive test):
131  ./bisect.py package daisy 172.17.211.182 --test_script=cros_pkg/boot_test.sh
132
133  Example 2 (do package bisector system test instead of interactive test):
134  ./bisect.py package daisy 172.17.211.182 \
135    --test_script=cros_pkg/testing_test.sh --install_script=""
136
137  Example 3 (enable verbose mode and disable pruning):
138  ./bisect.py package daisy 172.17.211.182 --verbose --noprune
139
140