LLDB Debug Symbol Test Framework

English | 中文

This project provides a test framework for verifying compiler debug symbol implementations using LLDB. It allows you to validate variable values during program execution, which is crucial for ensuring the correctness of debug information generated by compilers.

Tests

• Clang

Features

• Automatic breakpoint setting and variable value verification
• Support for testing individual variables and all variables in scope
• Verbose output option for detailed test results
• Interactive mode for debugging failed tests
• Integration with LLDB for powerful debugging capabilities
• Suitable for testing debug symbol implementations of various programming languages supported by LLDB

Quick Example

#include <stdio.h>

int main() {
    int x = 5;
    int y = 10;
    // Expected:
    //   x: 5
    //   y: 10
    //   all variables: x y
    printf("x = %d, y = %d\n", x, y);
    return 0;
}

Compile and run the test:

$ clang -g -o test_program test_program.c

$ python runtest.py ./test_program test_program.c -v
(lldb) command script import ./test.py
(lldb) script test.run_tests_with_result('./test_program', ['test_program.c',], True, False, 'test_result.json')
Running tests for test_program.c with ./test_program
Found 1 test cases

Setting breakpoint at test_program.c:9

Test case: test_program.c:6-9 in function 'main'
✓ Line 7, x: Pass
✓ Line 8, y: Pass
✓ Line 9, all variables: Pass
    Variables: x, y

Test results:
  Total tests: 3
  Passed tests: 3
  Failed tests: 0
All tests passed!
0
(lldb) quit

Requirements

• LLDB (version 18 or later recommended for DWARF 5 support)
• Appropriate compiler for your target language (e.g., Clang for C/C++, Go compiler for Go)

Installation

1. Clone this repository:

   git clone https://github.com/cpunion/lldb-test.git
   cd lldb-test
   

2. Ensure you have LLDB installed and accessible in your PATH.

Usage

1. Prepare your program with inline test comments.

2. Compile your program using an appropriate compiler with debug symbols enabled.

3. Run the tests:

   python runtest.py path/to/your/compiled/program path/to/your/source/files...
   

   For verbose output, use:

   python runtest.py -v path/to/your/compiled/program path/to/your/source/files...
   

   For interactive mode on test failure, use:

   python runtest.py -i path/to/your/compiled/program path/to/your/source/files...
   

Supported Languages

This framework can be used to test debug symbol implementations for any programming language that LLDB supports. Some examples include, but are not limited to:

• C/C++
• Objective-C/Objective-C++
• Swift
• Rust
• Go
• Assembly

Ensure you use the appropriate compiler and compilation flags for your target language, including debug symbol generation. The framework's flexibility allows it to work with any language that LLDB can debug, making it a versatile tool for testing debug symbol implementations across various programming environments.

Example: Testing C Compiler Debug Symbol Implementation

Here's a detailed example of how to write and run tests for C compiler debug symbol implementation:

1. Write your C program with inline test comments:

   #include <stdio.h>
   
   int main() {
       int x = 5;
       int y = 10;
       // Expected:
       //   x: 5
       //   y: 10
       //   all variables: x y
       printf("x = %d, y = %d\n", x, y);
       return 0;
   }

2. Compile your program with debug symbols:

   clang -g -o test_program test_program.c
   

3. Run the tests as described in the Usage section:

   python runtest.py ./test_program test_program.c -v
   

Writing Inline Tests for Debug Symbol Verification

• Use // Expected: comments to define test cases
• Each subsequent line should be in the format // variable_name: expected_value
• Use // all variables: var1 var2 ... to test for the presence of specific variables in scope
• These inline tests verify the correctness of debug symbol implementation by checking variable values and scope at specific points in the program execution

Troubleshooting

If you encounter an "Unable to import 'lldb'" error when running the tests:

1. Ensure LLDB is correctly installed and in your PATH.
2. If using a virtual environment, make sure it's activated and the LLDB Python module is accessible within it.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.