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