Add lldb tutorial (#760)

* Simplify debug utils. * Add auto breakpoint. * Fix stuff. * Add fallback libfunc location name if missing * llvm debug * works * prog * progress * progress * move to own module * progress * add arrays * wip prog * fix * reset2 * only relate to sierra * fix * make prettier * cleanup * remove unused code * remove debug trap * fixes * docs * fix * fix doct test * fixes * add docu * docs * Add lldb tutorial * Fix typo * Apply suggestions from code review Co-authored-by: Pedro Fontana <[email protected]> --------- Co-authored-by: Esteve Soler Arderiu <[email protected]> Co-authored-by: Edgar <[email protected]> Co-authored-by: Pedro Fontana <[email protected]>
lambdaclass · Aug 19, 2024 · 0fc0fd6 · 0fc0fd6
1 parent 51d2a42
commit 0fc0fd6
Showing 1 changed file with 32 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -907,23 +907,51 @@ Do note that the MLIR with locations is in pretty form and thus not suitable to
 export NATIVE_DEBUG_DUMP=1
 ```
 
-Add a debugger breakpoint trap at the given sierra statement:
+### Debugging with LLDB
 
-The trap instruction may not end up exactly where the statement is.
+To debug with LLDB (or another debugger), we must compile the binary with the `with-debug-utils` feature.
+```bash
+cargo build --bin cairo-native-run --features with-debug-utils
+```
 
+Then, we can add the a debugger breakpoint trap. To add it at a given sierra statement, we can set the following env var:
 ```bash
 export NATIVE_DEBUG_TRAP_AT_STMT=10
 ```
+The trap instruction may not end up exactly where the statement is.
+
+If we want to manually set the breakpoint (for example, when executing a particular libfunc), then we can use the `DebugUtils` metadata in the code.
+```rust
+#[cfg(feature = "with-debug-utils")]
+{
+    metadata.get_mut::<DebugUtils>()
+        .unwrap()
+        .debug_breakpoint_trap(block, location)?;
+}
+```
+
+Now, we need to execute `cairo-native-run` from our debugger (LLDB). If we want to see the source locations, we also need to set the `NATIVE_DEBUG_DUMP` env var and execute the program with AOT.
+
+```bash
+lldb -- target/debug/cairo-native-run -s programs/recursion.cairo --available-gas 99999999 --run-mode aot
+```
+
+Some usefull lldb commands:
+- `process launch`: starts the program
+- `frame select`: shows the current line information
+- `thread step-in`: makes a source level single step
+- `thread continue`: continues execution of the current process
+- `disassemble --frame --mixed`: shows assembly instructions mixed with source level code
 
-Note: The debugger will only show source locations when using AOT. Also you need enable the cairo-native feature `with-debug-utils` and have the env var `NATIVE_DEBUG_DUMP` set.
+### Logging
 
 Enable logging to see the compilation process:
 
 ```bash
 export RUST_LOG="cairo_native=trace"
 ```
 
-Other tips:
+### Other tips
 
 - Try to find the minimal program to reproduce an issue, the more isolated the easier to test.
 - Use the `debug_utils` print utilities, more info [here](https://lambdaclass.github.io/cairo_native/cairo_native/metadata/debug_utils/struct.DebugUtils.html):