From c6d333446af1f2e9815ddc7c24a2096d30ba6c58 Mon Sep 17 00:00:00 2001
From: Edgar <git@edgarluque.com>
Date: Tue, 16 Apr 2024 14:35:51 +0200
Subject: [PATCH] improve readme

---
 README.md      | 38 ++++++++++++++++++++++++++++++++++++++
 src/context.rs | 35 +++++++++++++++++++++++++++--------
 2 files changed, 65 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 18eec309d..71105f17d 100644
--- a/README.md
+++ b/README.md
@@ -801,3 +801,41 @@ cairo-native-test ./cairo-tests/
 ```
 
 This will run all the tests (functions marked with the `#[test]` attribute).
+
+## Debugging Tips
+
+### Useful environment variables
+
+These 2 env vars will dump the generated MLIR code from any compilation on the current working directory as:
+
+- `dump.mlir`: The MLIR code after passes without locations.
+- `dump-debug.mlir`: The MLIR code after passes with locations.
+- `dump-prepass.mlir`: The MLIR code before without locations.
+- `dump-prepass-debug.mlir`: The MLIR code before passes with locations.
+
+Do note that the MLIR with locations is in pretty form and thus not suitable to pass to `mlir-opt`.
+
+```bash
+export NATIVE_DEBUG_DUMP_PREPASS=1
+export NATIVE_DEBUG_DUMP=1
+```
+
+Enable logging to see the compilation process:
+
+```bash
+export RUST_LOG="cairo_native=trace"
+```
+
+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):
+
+```rust
+#[cfg(feature = "with-debug-utils")]
+{
+    metadata.get_mut::<DebugUtils>()
+        .unwrap()
+        .print_pointer(context, helper, entry, ptr, location)?;
+}
+```
diff --git a/src/context.rs b/src/context.rs
index d19bcabfd..15089710d 100644
--- a/src/context.rs
+++ b/src/context.rs
@@ -129,17 +129,36 @@ impl NativeContext {
             debug_locations.as_ref(),
         )?;
 
-        std::fs::write(
-            "out.mlir",
-            module
-                .as_operation()
-                .to_string_with_flags(OperationPrintingFlags::new().enable_debug_info(true, false))
-                .unwrap(),
-        )
-        .unwrap();
+        if let Ok(x) = std::env::var("NATIVE_DEBUG_DUMP_PREPASS") {
+            if x == "1" || x == "true" {
+                std::fs::write("dump-prepass.mlir", module.as_operation().to_string())
+                    .expect("should work");
+                std::fs::write(
+                    "dump-prepass-debug.mlir",
+                    module.as_operation().to_string_with_flags(
+                        OperationPrintingFlags::new().enable_debug_info(true, true),
+                    )?,
+                )
+                .expect("should work");
+            }
+        }
 
         run_pass_manager(&self.context, &mut module)?;
 
+        if let Ok(x) = std::env::var("NATIVE_DEBUG_DUMP") {
+            if x == "1" || x == "true" {
+                std::fs::write("dump.mlir", module.as_operation().to_string())
+                    .expect("should work");
+                std::fs::write(
+                    "dump-debug.mlir",
+                    module.as_operation().to_string_with_flags(
+                        OperationPrintingFlags::new().enable_debug_info(true, true),
+                    )?,
+                )
+                .expect("should work");
+            }
+        }
+
         // The func to llvm pass has a bug where it sets the data layout string to ""
         // This works around it by setting it again.
         {