rudy-db 0.0.1

A user-friendly library for interacting with debugging information of Rust compiled artifacts using DWARF
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

# <img src=".github/assets/logo-256.png" alt="Rudy Logo" width="48" align="left" style="margin-right: 10px"> Rudy

<br clear="left"/>

[![Crates.io](https://img.shields.io/crates/v/rudy-db.svg)](https://crates.io/crates/rudy-db)
[![Documentation](https://docs.rs/rudy-db/badge.svg)](https://docs.rs/rudy-db)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A user-friendly library for interacting with debugging information of Rust compiled artifacts using DWARF.

⚠️ **Experimental Status**: This library is in early development (0.0.x). The API is unstable and subject to breaking changes. We welcome early adopters who are willing to provide feedback!

## Features

- 🚀 **Lazy evaluation** - Parse only what you need, when you need it
- ♻️ **Incremental recomputation** - Powered by [salsa](https://github.com/salsa-rs/salsa) for efficient caching
- 🔍 **Type resolution** - Resolve types from memory addresses
- 📊 **Structured output** - Walk fields and pretty-print complex data structures
- 🦀 **Rust-focused** - Optimized for Rust's specific debug information patterns

## Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
rudy-db = "0.0.1"
```

## Basic Usage

Here's a simple example of loading a binary and resolving type information from a memory address:

```rust
use rudy_db::{DebugDatabase, TypeInfo};
use anyhow::Result;

fn main() -> Result<()> {
    // Create a new database
    let mut db = DebugDatabase::new()?;
    
    // Load a Rust binary with debug information
    let binary = db.analyze_file("path/to/your/rust/binary")?;
    
    // Resolve type information at a specific address
    let address = 0x12345678;
    if let Some(type_info) = db.resolve_type_at_address(binary, address)? {
        println!("Type at {:#x}: {}", address, type_info.name());
        
        // Walk through fields for structured types
        for field in type_info.fields() {
            println!("  Field '{}': {}", field.name, field.type_name);
        }
    }
    
    Ok(())
}
```

## Memory Address Pretty-Printer Example

For a more complete example showing how to build a memory address pretty-printer, see the [examples/pretty_printer.rs](examples/pretty_printer.rs) file.

## Architecture

This library is designed for use in long-running processes like debuggers:

1. **Efficient caching**: Parse debug information once and reuse it across multiple queries
2. **Lazy parsing**: Only parse the compilation units and DIEs you actually need
3. **Incremental updates**: When binaries change, only recompute affected queries

## Supported Platforms

- **Architectures**: x86_64, aarch64
- **Operating Systems**: macOS, Linux
- **Debug Formats**: DWARF (primary focus)

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/samscott89/rudy
cd rudy

# Run tests
cargo test

# Run with examples
cargo run --example pretty_printer
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built on top of [gimli](https://github.com/gimli-rs/gimli) for DWARF parsing
- Uses [salsa](https://github.com/salsa-rs/salsa) for incremental computation
- Inspired by the needs of Rust debugging tools

---

**Note**: This is an experimental project. Please report any issues or feature requests on our [GitHub issue tracker](https://github.com/samscott89/rudy/issues).