How to debug a tool such as quantum-opt?

[rturrado]

I'm asking this here but if you think another place (PennyLane discussion forums, Catalyst GitHub issue...) would be more appropriate, please let me know.

• I have followed these installation instructions.
• I am using CLion as IDE to navigate the source code, build, and run tools such as quantum-opt.
• However, I haven't managed to debug this app, which would be really helpful at some point if I want to contribute to the code. If I set a breakpoint and I try to debug the app, it just doesn't stop at the breakpoint. That sounds like I'm not debugging a debug binary.

How do you debug Catalyst C++ code?
Do you build with extra flags?

Thanks!

[sengthai]

Hi, @rturrado. Thanks for raising this up.

Do you build with extra flags?

You can build Catalyst with debug mode, such as make all BUILD_TYPE=Debug. If you implement an MLIR pass in Catalyst, I would recommend make dialects BUILD_TYPE=Debug.

[dime10]

make all BUILD_TYPE=Debug

Don't run this unless you have a 100 gigs and a lot of time 😅

[sengthai]

Right! 😅

[dime10]

Thanks for asking the question @rturrado! Generally my workflow will depend on what kind of code I'm debugging, and what kind of example I'm running.

• I think debugging Python code launched from a Python example is pretty self explanatory, since Python makes this quite easy on us, and it should also integrate straight forwardly with IDEs (I cannot speak to jetbrain tools though since I use vs code myself).

• Debugging C++ code from a C++ binary (like the quantum-opt tool) is also relatively straightforward.

  The first step is building the relevant code in DEBUG mode. So for example using our make targets you can do make dialects BUILD_TYPE=Debug, or make runtime BUILD_TYPE=Debug. Note that you don't have to build all dependencies in debug mode, as that can be very expensive (especially llvm). So if don't build llvm/mlir in debug mode for example you won't able to step in or break on llvm code, but can still do so on Catalyst code.

  You should be able to create launch configurations that target the executable you built in debug mode, and then set breakpoints in your source code (at least in VS Code, but I imagine it should work somewhat analogously for clion). For instance, I have the following launch configuration targeting the currently active .mlir editor window:

        {
            "name": "(lldb) quantum-opt with...",
            "type": "cppdbg",
            "request": "launch",
            "program": "/Users/user/catalyst/mlir/build/bin/quantum-opt",
            "args": [
                "--commute-clifford-t-ppr",
                "${file}"
            ],
            "stopAtEntry": false,
            "cwd": "${fileDirname}",
            "environment": [],
            "externalConsole": false,
            "MIMode": "lldb"
        },
  

  Alternatively, you can of course use a debugger from the command line directly, like lldb quantum-opt.

• Next you might want to consider debugging C++ code from a Python example, this is a bit more difficult because of the different languages and processes involved.

  For the debugging runtime and device code, I use the following launch config:

        {
            "name": "(lldb) Python File",
            "type": "cppdbg",
            "request": "launch",
            "program": "/usr/local/bin/python",
            "args": [
                "${file}"
            ],
            "stopAtEntry": false,
            "cwd": "${fileDirname}",
            "environment": [],
            "externalConsole": false,
            "MIMode": "lldb"
        },
  

  This works well with IDE breakpoints in the (runtime) c++ code, but of course won't pick up any Python breakpoints.
  The alternative from the command line is to run the debugger on the Python executable (lldb python), and then provide the python script containing the Catalyst example.

  For compiler code, it gets more complicated, because the Catalyst Python frontend launches the compiler in a separate process. @mlxd actually has a neat PR regarding this, that will instruct the compiler process to wait upon spawn, giving you time to attach a debugger to it. You can then run a Python example (with or without the PDB debugger), and transition into the C++ debugger and stopping on a breakpoint in the compiler. I use the following config for this:

        {
            "name": "(lldb) Attach To Running Process",
            "type": "cppdbg",
            "request": "attach",
            "program": "/bin/echo", // arbitrary program, just needs to exist
            "processId": "${command:pickProcess}",
            "MIMode": "lldb",
        }
  

[rturrado]

Wow. Thanks so much for the detailed answer, @dime10 . And thanks @sengthai too for the quick response!

My scenario, for the time being, is to be able to debug something like quantum-opt, yes, which I've seen you use for your compiler passes. The make dialects BUILD_TYPE=Debug should suffice.

Regarding the last point, I suppose the old dirty trick of adding a line of code that waits on a file to be created could be used as a workaround: you launch your Python code, then the C++ binary is called, and early on waits for you to manually create a tmp/blah or something. At that point you attach your debugger, create the file, and start debugging.

By the way, I have a question related to this one. I can ask it in a separate post for logging purposes, if you want. How do you do, for example, if you want to build dialects without running the tests? Do you fiddle directly with the Makefile or CMakeLists.txt files? Working yesterday on the P(pi/2) commuting issue, some decomposition tests were killing my machine when trying to decompose pi/2 gates. So every time I was building, I had to kill the session and a couple of zombie quantum-opt binaries. In this situation you may want to first build and then separately debug a faulty binary.

[dime10]

By the way, I have a question related to this one. I can ask it in a separate post for logging purposes, if you want. How do you do, for example, if you want to build dialects without running the tests? Do you fiddle directly with the Makefile or CMakeLists.txt files? Working yesterday on the P(pi/2) commuting issue, some decomposition tests were killing my machine when trying to decompose pi/2 gates. So every time I was building, I had to kill the session and a couple of zombie quantum-opt binaries. In this situation you may want to first build and then separately debug a faulty binary.

Good point 😅 The check-dialects CMake target is the main target we use to build the catalyst compiler code, and it does always run the lit tests, that's true. Typically I might see failing tests during development, but don't get any adverse effects from it.

Can you try the following? Running a different CMake target should be pretty straight forward, for example

cmake --build mlir/build --target quantum-opt

[rturrado]

Beautiful. Many thanks for the guiding! This will get me going for the moment:

1. Add a dialects-debug target to the top level Makefile.

dialects:
	$(MAKE) -C mlir dialects

dialects-debug:
	$(MAKE) -C mlir dialects-debug

2. Add a dialects-debug entry to the mlir/Makefile too, just changing:

• build type to Debug, i.e., -DCMAKE_BUILD_TYPE=Debug, and
• CMake build target to quantum-opt, i.e., cmake --build $(DIALECTS_BUILD_DIR) --target quantum-opt.

.PHONY: help
help:
	@echo "Please use \`make <target>' where <target> is one of"
	@echo "  all                to build MLIR, MLIR-HLO and custom Catalyst dialects"
	@echo "  llvm               to build MLIR enabling Python bindings"
	@echo "  mhlo               to build MLIR-HLO"
	@echo "  enzyme             to build Enzyme"
	@echo "  dialects           to build custom Catalyst MLIR dialects"
	@echo "  dialects-debug     to build custom Catalyst MLIR dialects in Debug mode"
        ...

.PHONY: dialects-debug
dialects-debug:

	@echo "build quantum-lsp and dialects"
	cmake -G Ninja -S . -B $(DIALECTS_BUILD_DIR) \
		-DCMAKE_BUILD_TYPE=Debug \
		-DLLVM_ENABLE_ASSERTIONS=ON \
		-DQUANTUM_ENABLE_BINDINGS_PYTHON=ON \
		-DPython3_EXECUTABLE=$(PYTHON) \
		-DPython3_NumPy_INCLUDE_DIRS=$(shell $(PYTHON) -c "import numpy as np; print(np.get_include())") \
		-DEnzyme_DIR=$(ENZYME_BUILD_DIR) \
		-DENZYME_SRC_DIR=$(MK_DIR)/Enzyme \
		-DMLIR_DIR=$(LLVM_BUILD_DIR)/lib/cmake/mlir \
		-DMHLO_DIR=$(MHLO_BUILD_DIR)/lib/cmake/mlir-hlo \
		-DMHLO_BINARY_DIR=$(MHLO_BUILD_DIR)/bin \
		-DRUNTIME_LIB_DIR=$(RT_BUILD_DIR)/lib \
		-DMLIR_LIB_DIR=$(LLVM_BUILD_DIR)/lib \
		-DCMAKE_C_COMPILER=$(C_COMPILER) \
		-DCMAKE_CXX_COMPILER=$(CXX_COMPILER) \
		-DCMAKE_C_COMPILER_LAUNCHER=$(COMPILER_LAUNCHER) \
		-DCMAKE_CXX_COMPILER_LAUNCHER=$(COMPILER_LAUNCHER) \
		-DLLVM_USE_SANITIZER=$(USE_SANITIZER_NAMES) \
		-DLLVM_ENABLE_LLD=$(ENABLE_LLD) \
		-DLLVM_ENABLE_ZLIB=$(ENABLE_ZLIB) \
		-DLLVM_ENABLE_ZSTD=$(ENABLE_ZSTD) \
		-DCATALYST_ENABLE_WARNINGS=$(STRICT_WARNINGS)

	cmake --build $(DIALECTS_BUILD_DIR) --target quantum-opt