From bce3dc9891f30b1a212acda46b177ded65fbe72b Mon Sep 17 00:00:00 2001
From: Sambhav Jain <sambhav.jain@getcruise.com>
Date: Tue, 16 Jan 2024 13:45:53 -0800
Subject: [PATCH] debugging guide

---
 .bazelrc          |  7 ++++++
 README.md         | 62 +++++++++++++++++++++++++++++++++++++++++++++++
 docker/Dockerfile |  3 ++-
 3 files changed, 71 insertions(+), 1 deletion(-)

diff --git a/.bazelrc b/.bazelrc
index d55cecc9..3ef07fa2 100644
--- a/.bazelrc
+++ b/.bazelrc
@@ -34,3 +34,10 @@ build:clang_linux --linkopt=-fuse-ld=lld --host_linkopt=-fuse-ld=lld
 build:clang_linux --config=generic_clang
 
 build:clang_osx --config=generic_clang
+
+# Other compilation modes
+build:opt --compilation_mode=opt
+build:dbg --compilation_mode=dbg
+
+# GDB builds in dbg mode
+build:gdb --config=dbg
diff --git a/README.md b/README.md
index 174590f7..958d80fb 100644
--- a/README.md
+++ b/README.md
@@ -52,3 +52,65 @@ The following CI workflows are automatically triggered anytime upstream dependen
 - [![Bazel Build and Test (llvm-project)](https://github.com/cruise-automation/mlir-tcp/actions/workflows/bazelBuildAndTestLlvm.yml/badge.svg)](https://github.com/cruise-automation/mlir-tcp/actions/workflows/bazelBuildAndTestLlvm.yml)
 - [![Bazel Build and Test (torch-mlir)](https://github.com/cruise-automation/mlir-tcp/actions/workflows/bazelBuildAndTestTorchmlir.yml/badge.svg)](https://github.com/cruise-automation/mlir-tcp/actions/workflows/bazelBuildAndTestTorchmlir.yml)
 - [![Bazel Build and Test (stablehlo)](https://github.com/cruise-automation/mlir-tcp/actions/workflows/bazelBuildAndTestStablehlo.yml/badge.svg)](https://github.com/cruise-automation/mlir-tcp/actions/workflows/bazelBuildAndTestStablehlo.yml)
+
+
+## Debugging Guide
+
+Below are some standard techniques for debugging your compilation process, assuming you've reduced it to a form that can be reproduced with `tcp-opt`. For MLIR-specific debugging tips, refer [here](https://mlir.llvm.org/getting_started/Debugging/).
+
+### `printf` debugging
+
+Printing to stdout/stderr works as usual:
+```C++
+op.emitWarning() << "HERE: " << myVariable;      // preferred for op/loc diagnostics
+
+llvm::errs() << "HERE: " << myVariable << "\n";  // alternative
+```
+
+You can also hook into the [LLVM_DEBUG](https://llvm.org/docs/ProgrammersManual.html#the-llvm-debug-macro-and-debug-option) macro:
+```C++
+#include "llvm/Support/Debug.h"
+
+#define DEBUG_TYPE "foo"
+LLVM_DEBUG(llvm::dbgs() << "This only shows up when -debug or -debug-only=foo is provided.\n");
+#undef DEBUG_TYPE
+
+#define DEBUG_TYPE "bar"
+LLVM_DEBUG(llvm::dbgs() << "This only shows up when -debug or -debug-only=bar is provided.\n");
+#undef DEBUG_TYPE
+```
+
+Then run with the `-debug-only=foo,bar` flag to cuts out messages that aren't associated with the passed `DEBUG_TYPE`s.
+```shell
+bazel run --config=clang_linux //:tcp-opt -- --some-pass `pwd`/test.mlir -debug-only=foo,bar
+```
+
+### `gdb` debugging
+
+To debug `tcp-opt` with [gdb](https://www.sourceware.org/gdb/):
+```shell
+bazel build --config=clang_linux --config=gdb //:tcp-opt
+
+gdb --args bazel-bin/tcp-opt -h
+```
+
+For help with gdb commands please refer to [gdb cheat sheet](https://gist.github.com/rkubik/b96c23bd8ed58333de37f2b8cd052c30).
+
+### Enable `llvm-symbolizer`
+
+If you get a stack dump without any symbol names:
+```shell
+Stack dump without symbol names (ensure you have llvm-symbolizer in your PATH or set the environment var `LLVM_SYMBOLIZER_PATH` to point to it):
+0  tcp-opt   0x000055ac1c9c0c1d
+1  tcp-opt   0x000055ac1c9c110b
+2  tcp-opt   0x000055ac1c9be846
+3  tcp-opt   0x000055ac1c9c1855
+4  libc.so.6 0x00007f7011c6a520
+...
+```
+
+Do this and re-run:
+```shell
+bazel build --config=clang_linux @llvm-project//llvm:llvm-symbolizer
+export LLVM_SYMBOLIZER_PATH=`pwd`/bazel-bin/external/llvm-project/llvm/llvm-symbolizer
+```
diff --git a/docker/Dockerfile b/docker/Dockerfile
index a13d65f6..632545da 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -12,7 +12,8 @@ RUN apt-get update && \
     wget \
     lld \
     clang \
-    clang-format
+    clang-format \
+    gdb
 
 # Install bazel
 ARG ARCH="x86_64"