Rust Debugging Cheatsheet

Source: Rust Debugging Cheatsheet | by AIAlchemist_Ab1r

Debugging Rust applications can be a challenging task, especially when dealing with complex data structures and memory-related issues. Fortunately, the Rust development team has enhanced LLDB, creating a powerful debugging tool that understands Rust's unique concepts and data structures.

What is Rust LLDB?

Rust LLDB is a modified version of the LLDB debugger that comes bundled with the Rust compiler. These modifications enable the debugger to understand Rust-specific concepts and provide enhanced debugging capabilities for Rust applications. The key features include:

• Pretty-printing for standard library types
• Understanding of Rust's ownership model
• Ability to inspect complex Rust data structures
• Support for Rust's unique memory layout

Getting Started with Rust LLDB

Prerequisites

Since Rust LLDB comes bundled with the Rust compiler, you don't need to install it separately. However, you'll need:

1. A working Rust installation (rustc and cargo)
2. Debug symbols in your binary (built with debug = true in Cargo.toml)
3. Basic understanding of LLDB commands

Building for Debugging

To ensure you can debug effectively, add the following to your Cargo.toml:

[profile.dev] debug = true opt-level = 0

Launching the Debugger

There are two main ways to start debugging your Rust program:

1. Direct LLDB launch:

rust-lldb target/debug/your_program

1. Through cargo:

cargo run --debug

Essential Rust LLDB Commands

Basic Navigation

# Set a breakpoint (lldb) b src/main.rs:10 # Run the program (lldb) r # Step over (lldb) n # Step into (lldb) s # Continue execution (lldb) c

Inspecting Variables

# Print a variable (lldb) p variable_name # Print with type information (lldb) pt variable_name # Print dereferenced value (lldb) p *variable_name

Advanced Features

Working with Rust-Specific Types

Option Types

# Inspect an Option<T> (lldb) p my_option # Check if it's Some or None (lldb) p my_option.is_some()

Result Types

# Inspect a Result<T, E> (lldb) p my_result # Check if it's Ok or Err (lldb) p my_result.is_ok()

Smart Pointers

Box

# Print the value inside a Box (lldb) p *boxed_value

Rc and Arc

# Print reference count (lldb) p rc_value.strong_count # Print inner value (lldb) p *rc_value

Working with Collections

# Print Vec contents (lldb) p vec_variable # Print HashMap entries (lldb) p hash_map_variable # Print String contents (lldb) p string_variable

Debugging Memory Issues

Examining Memory Layout

# Print memory address (lldb) p &variable # Examine memory at address (lldb) x address # Print size of type (lldb) p sizeof(Type)

Tracking Ownership

# Print ownership information (lldb) p variable._ownership # Check borrow status (lldb) p variable._borrow

Pro Tips and Best Practices

1. Use Conditional Breakpoints

# Break when condition is met (lldb) br set -f main.rs -l 10 -c "x > 5"

1. Create Custom Commands

# Create an alias for common commands (lldb) command alias pc print -c

1. Use Expression Evaluation

# Evaluate complex expressions (lldb) expr (variable + 1) * 2

Common Debugging Scenarios

Debugging Ownership Issues

When dealing with ownership problems, use these commands:

# Track variable moves (lldb) bt (lldb) frame variable # Check current scope (lldb) frame info

Debugging Threading Issues

For multi-threaded applications:

# List all threads (lldb) thread list # Switch threads (lldb) thread select 2 # Show thread backtrace (lldb) thread backtrace

Debugging Async Code

When working with async code:

# Print future state (lldb) p future_variable # Examine task status (lldb) p task_handle

Integration with IDEs

Many IDEs provide integrated debugging experiences using Rust LLDB:

1. VS Code

   • Install "rust-analyzer" extension
   • Configure launch.json for debugging
   • Use breakpoints directly in the editor

2. CLion

   • Native Rust debugging support
   • Visual debugging interface
   • Integrated variable inspection

Troubleshooting Common Issues

1. Missing Debug Symbols

   • Ensure debug = true in Cargo.toml
   • Rebuild with cargo clean && cargo build

2. Optimized Code Debugging

   • Use -C opt-level=0 for better debugging
   • Consider using #[inline(never)] on functions

3. Pretty Printer Issues

   • Update Rust toolchain
   • Check LLDB version compatibility

Conclusion

Rust LLDB is a powerful tool that makes debugging Rust applications much more manageable. By understanding its features and capabilities, you can significantly improve your debugging workflow and solve complex issues more efficiently. Remember to:

• Use the built-in pretty printers for standard library types
• Leverage Rust-specific debugging features
• Combine different debugging techniques for complex scenarios
• Keep your toolchain updated for the best experience

The more you practice with Rust LLDB, the more natural and efficient your debugging process will become. Happy debugging!

Additional Resources

1. Official Rust Documentation
2. LLDB Documentation
3. Rust Compiler Debugging Guide
4. Community Forums and Discussion Boards

Remember that debugging is both an art and a science. Don't hesitate to experiment with different commands and techniques to find what works best for your specific debugging needs.