Daniel Malea | 094881f | 2011-12-14 17:39:16 -0500 | [diff] [blame] | 1 | |
| 2 | Summary |
| 3 | ======= |
| 4 | This directory contains integration tests for debug information in libbcc. |
| 5 | |
| 6 | The tests come in two flavours: host and target. Host tests are run on the |
| 7 | build machine (currently, only Linux has been tested extensively) and target |
| 8 | tests run on a live Android system (emulator or device.) |
| 9 | |
| 10 | Host tests use clang to build bytecode (bc) files, which are then executed |
| 11 | by the libbcc driver utility (bcc) on the host through GDB. The debugger |
| 12 | output is verified against expected output by the llvm tool FileCheck. |
| 13 | Both the debugger commands and the expected output are embedded in the |
| 14 | original sources as comments of the form "DEBUGGER: " and "CHECK: ". |
| 15 | |
| 16 | Target tests are similar, but instead of using clang, they use ant and |
| 17 | llvm-rs-cc from the Android SDK to build a test binary package (apk) |
| 18 | that is uploaded to the device (or emulator) and run with GDB attached. |
| 19 | The output is verified in the same way as host side tests, and the format |
| 20 | of the tests is the same. |
| 21 | |
| 22 | *** If you are running target-side tests, you must disable parallel |
| 23 | *** execution with the "-j1" flag to llvm-lit |
| 24 | |
| 25 | |
| 26 | Prerequisites |
| 27 | ============= |
| 28 | To run the tests, you must have built the android source tree and have |
| 29 | the build environment variables set (i.e. ANDROID_BUILD_TOP) |
| 30 | |
| 31 | You need the following tools (not built by the android build system) on |
| 32 | your PATH: |
| 33 | - gdb (Tested with gdb 7.3 from Ubuntu 11.10) |
| 34 | |
| 35 | In addition, you need a build of gdbserver available in the prebuilt directory. |
| 36 | |
| 37 | Customizing |
| 38 | =========== |
| 39 | By default, llvm-lit will use the clang and bcc driver built in the android |
| 40 | output directory. If you wish to use different versions of these tools, |
| 41 | set the following environment variables: |
| 42 | CLANG - path to clang |
| 43 | BCC_DRIVER - path to bcc |
| 44 | FILECHECK - path to FileCheck |
| 45 | GDB - path to GDB |
| 46 | |
| 47 | Further customization is possible by modifying the lit.cfg file. |
| 48 | |
| 49 | |
| 50 | Running |
| 51 | ======= |
| 52 | To execute all the tests from this directory, use the llvm-lit tool: |
| 53 | $ ./llvm-lit host-tests |
| 54 | $ ./llvm-lit target-tests -j 1 |
| 55 | |
| 56 | The tool can be run from any directory. |
| 57 | -j controls the number of tests to run in parallel |
| 58 | -v enables additional verbosity (useful when examining unexpected failures) |
| 59 | |
| 60 | Adding new tests |
| 61 | ================ |
| 62 | To add new tests, just add a .c, .cpp, or .rs file to a test directory with |
| 63 | similar RUN/DEBUGGER/CHECK directives in comments as the existing tests. |