diff options
Diffstat (limited to 'binary_search_tool/README.bisect')
| -rw-r--r-- | binary_search_tool/README.bisect | 213 |
1 files changed, 213 insertions, 0 deletions
diff --git a/binary_search_tool/README.bisect b/binary_search_tool/README.bisect new file mode 100644 index 00000000..e6185e8a --- /dev/null +++ b/binary_search_tool/README.bisect @@ -0,0 +1,213 @@ + +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 + |