From 0fc0fd68b3cd25978f5065193182fb0ca6b3061a Mon Sep 17 00:00:00 2001 From: Julian Gonzalez Calderon Date: Mon, 19 Aug 2024 16:22:49 -0300 Subject: [PATCH] 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 --------- Co-authored-by: Esteve Soler Arderiu Co-authored-by: Edgar Co-authored-by: Pedro Fontana --- README.md | 36 ++++++++++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a83d47d87..60c03eef4 100644 --- a/README.md +++ b/README.md @@ -907,15 +907,43 @@ 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::() + .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: @@ -923,7 +951,7 @@ Enable logging to see the compilation process: 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):