Add Debugging Guide (cruise-automation#29)

Co-Contributors: @AaronStGeorge

.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

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
+```

docker/Dockerfile

@@ -12,7 +12,8 @@ RUN apt-get update && \
     wget \
     lld \
     clang \
-    clang-format
+    clang-format \
+    gdb
 
 # Install bazel
 ARG ARCH="x86_64"