debuginfo test suite needs more documentation

The docs for the debuginfo test suite are quite brief, consisting basically just of a single example. Even that example leasves me more confused than enlightened:

For example, the following will build the test, start the debugger, set a breakpoint, launch the program, inspect a value, and check what the debugger prints:

The #break comment is below the other comments in the file. So apparently something is going on here with the execution order of these comments that makes them not just top-to-bottom in the file?

Also, #break is not the only directive that can start with #. Apparently there's also #locN:

rust/tests/debuginfo/macro-stepping.rs

Line 111 in 70320c1

foo!(); // #loc1

No idea what that does.

Also, keep in mind that whoever hits a test failure in a debuginfo test may have never used gdb or a tool like it. The documentation should either give them some chance to fix the test, or tell them whom to ping for help.

Judging from

rust/src/tools/compiletest/src/runtest/debugger.rs

Lines 35 to 39 in 72fe2ff

    
           // Breakpoints appear on lines with actual code, typically at the end of the line. 
        
           if line.contains("#break") { 
        
               breakpoint_lines.push(counter); 
        
               continue; 
        
           }

#locN isn't actually magic. It's just something this test does, maybe? So part of the problem might be the test itself not having sufficient comments.

I'm curious what parts exactly led to the confusion?

Would it have helped in the docs to say after "launch the program" to say "and then run the debugger commands in order, which in this case is run, print foo, and then checks that the debugger emits the string $0 = 123"?

Does the line describing #break need to more clearly say "all breakpoints are set before the program starts"?

Based on the test I looked at, with these #loc annotations, I was under the impression that there is an entire DSL of # annotations, and the docs only mentioned #break. But it seems like #break is truly the only annotation, and the test using #loc is an ad-hoc marker, nothing systematic?

I think generally what I am missing is reference-level docs for these kinds of tests: a list of the relevant directives, and what they do.

Yea, the #loc looks like someone's attempt to create some unique text. There's essentially just three things:

#break — sets a breakpoint on the line
// $DEBUGGER-command: — runs a command
// $DEBUGGER-check: — checks the output of the debugger

I'm not sure, but it's possible I didn't include that in the directive listing because they only apply to this one suite, and I thought its description was clear on what was possible.

Also, it would be good to explain how I can run the test suite with gdb vs lldb. Those seem to use separate annotations in the tests, so everything needs to be tested with both debuggers -- at least that's what it seems like to me.

EDIT: Ah, that is actually explained in the docs. Takes a while to get there when all you see is the CI error, but it's at least theoretically possible.

EDIT: Ah, that is actually explained in the docs. Takes a while to get there when all you see is the CI error, but it's at least theoretically possible.

Ah, that was premature... ./x test debuginfo -- --debugger lldb runs zero tests, so it doesn't actually let me test my lldb annotations.

$ ./x test debuginfo --  --debugger lldb
Building bootstrap
    Finished `dev` profile [unoptimized] target(s) in 0.02s
/home/r/src/rust/rustc.2/build/x86_64-unknown-linux-gnu/ci-llvm/bin/llvm-strip does not exist; skipping copy
Building stage1 compiler artifacts (stage0 -> stage1, x86_64-unknown-linux-gnu)
    Finished `release` profile [optimized + debuginfo] target(s) in 0.12s
Creating a sysroot for stage1 compiler (use `rustup toolchain link 'name' build/host/stage1`)
Building stage1 lld-wrapper (stage0 -> stage1, x86_64-unknown-linux-gnu)
    Finished `release` profile [optimized + debuginfo] target(s) in 0.06s
Building stage1 library artifacts (stage1 -> stage1, x86_64-unknown-linux-gnu)
    Finished `release` profile [optimized + debuginfo] target(s) in 0.02s
Building stage1 compiletest (stage0 -> stage1, x86_64-unknown-linux-gnu)
    Finished `release` profile [optimized + debuginfo] target(s) in 0.07s
Testing stage1 with compiletest suite=debuginfo mode=debuginfo (x86_64-unknown-linux-gnu)

running 0 tests


test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 10.70µs

Build completed successfully in 0:00:00

This might be related to the fact that apparently I don't have lldb installed. 😂 But, maybe there could be an error message or so...?

Navigation Menu

Repository navigation

debuginfo test suite needs more documentation #148288

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	// Breakpoints appear on lines with actual code, typically at the end of the line.
	if line.contains("#break") {
	breakpoint_lines.push(counter);
	continue;
	}

debuginfo test suite needs more documentation #148288

Description

Activity

RalfJung commented on Oct 30, 2025

ehuss commented on Oct 30, 2025

RalfJung commented on Oct 30, 2025

ehuss commented on Oct 30, 2025

RalfJung commented on Dec 1, 2025

RalfJung commented on Dec 1, 2025

RalfJung commented on Dec 1, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions