213 lines
8.4 KiB
Text
213 lines
8.4 KiB
Text
|
|
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'
|
|
--test_setup_script='cros_pkg/test_setup.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'
|
|
--test_setup_script='sysroot_wrapper/test_setup.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
|
|
|
|
3) 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.
|
|
|
|
a) 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>
|
|
|
|
b) Cleanup:
|
|
The user must clean up all built images and the populated object files.
|
|
|
|
c) 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
|
|
|
|
d) Additional Documentation:
|
|
See ./android/README.android for full documentation of Android object file
|
|
bisecting.
|
|
|
|
e) Examples:
|
|
i) Basic interactive test android bisection, where the android source is
|
|
at ~/android_src:
|
|
./bisect.py android ~/android_src
|
|
|
|
ii) 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.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
|
|
|