1# NDK Bisection tool 2 3This is an example bisection for an NDK build system. This example specifically 4bisects the sample NDK Teapot app. All steps (setup and otherwise) for bisection 5can be found in `DO_BISECTION.sh`. This shell script is meant to show the 6process required to bisect a compiler problem in an arbitrary NDK app build 7system. 8 9There are three necessary setup steps to run this example: 10 111. Install the NDK (known to work with r12b) 12 13 1. See here for NDK: https://developer.android.com/ndk/index.html 14 2. Go here for older NDK downloads: https://github.com/android-ndk/ndk/wiki 15 161. Install the compiler wrapper provided with this repo. See 17 compiler_wrapper.py for more details. 18 19 1. Essentially you must go into the NDK source (or where you build system 20 stores its toolchain), rename your compilers to <compiler>.real, and 21 create a symlink pointing to compiler_wrapper.py named <compiler> 22 (where your compiler used to be). 23 24 2. If you're using the toolchains that come with the NDK they live at: 25 `<ndk_path>/toolchains/<arch>/prebuilt/<host>/bin` 26 example: 27 `<ndk_path>/toolchains/llvm/prebuilt/linux-x86_64/bin/clang` 28 291. Plug in an Arm7 compatible Android device with usb debugging enabled. 30 31 1. This bisection example was tested with a Nexus 5X 32 33 2. It should be relatively simple to change the example to work with other 34 types of devices. Just change the scripts, and change PATCH1 to use a 35 different build flavor (like x86). See below for more details. 36 37This example contains two patches: 38 39`PATCH1` - This is the necessary changes to the build system to make the 40bisection easier. More specifically, it adds an arm7 build flavor to gradle. 41By default, this project will build objects for all possible architectures and 42package them into one big apk. These object files meant for another 43architecture just sit there and don't actually execute. By adding a build 44flavor for arm7, our compiler wrapper won't try to bisect object files meant 45for another device. 46 47`PATCH2` - This patch is what inserts the "compiler error". This is a simple 48nullptr error in one of the source files, but it is meant to mimic bad code 49generation. The result of the error is the app simply crashes immediately 50after starting. 51 52## Using another device architecture 53 54If we want to bisect for an x86-64 device we first need to provide a arch 55specific build flavor in our app/build.gradle file: 56 57``` 58create("x86-64") { 59 ndk.abiFilters.add("x86_64") 60} 61``` 62 63We want to add this under the same "productFlavors" section that our arm7 64build flavor is in (see PATCH1). Now we should have the "installx86-64Debug" 65task in our build system. We can use this to build and install an x86-64 66version of our app. 67 68Now we want to change our `test_setup.sh` script to run our new gradle task: 69``` 70./gradlew installx86-64Debug 71``` 72 73Keep in mind, these specific build flavors are not required. If your build 74system makes these device specific builds difficult to implement, the 75bisection tool will function perfectly fine without them. However, the 76downside of not having targetting a single architecture is the bisection will 77take longer (as it will need to search across more object files). 78 79## Additional Documentation 80 81These are internal Google documents, if you are a developer external to 82Google please ask whoever gave you this sample for access or copies to the 83documentation. If you cannot gain access, the various READMEs paired with the 84bisector should help you. 85 86* Ahmad's original presentation: https://goto.google.com/zxdfyi 87* Bisection tool update design doc: https://goto.google.com/zcwei 88* Bisection tool webpage: https://goto.google.com/ruwpyi 89* Compiler wrapper webpage: https://goto.google.com/xossn 90