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