diff options
| -rw-r--r-- | .lldbinit | 2 | ||||
| -rw-r--r-- | docs/building.md | 4 | ||||
| -rw-r--r-- | docs/debugging.md | 70 | ||||
| -rw-r--r-- | flake.nix | 14 | ||||
| -rw-r--r-- | source/core/core_lldb.py | 3 | ||||
| -rw-r--r-- | source/slang/slang_lldb.py | 3 |
6 files changed, 89 insertions, 7 deletions
diff --git a/.lldbinit b/.lldbinit new file mode 100644 index 000000000..399587061 --- /dev/null +++ b/.lldbinit @@ -0,0 +1,2 @@ +command script import source/core/core_lldb.py +command script import source/slang/slang_lldb.py diff --git a/docs/building.md b/docs/building.md index 156e2471a..b8a3429a3 100644 --- a/docs/building.md +++ b/docs/building.md @@ -143,6 +143,10 @@ build/Debug/bin/slang-test See the [documentation on testing](../tools/slang-test/README.md) for more information. +## Debugging + +See the [documentation on debugging](/docs/debugging.md). + ## More niche topics ### CMake options diff --git a/docs/debugging.md b/docs/debugging.md new file mode 100644 index 000000000..8946eeee9 --- /dev/null +++ b/docs/debugging.md @@ -0,0 +1,70 @@ +# Debugging Slang + +This document gives examples showing how to run debuggers in the Slang codebase. +Follow the [Building Slang From Source](/docs/building.md) instructions first. + +## Visual Studio + +This repo includes multiple `*.natvis` files which Visual Studio picks up +automatically; no extra configuration is required. + +## LLDB + +If you use [LLDB][], we provide a `.lldbinit` file which enables data formatters +for types in the Slang codebase. You can use this with LLDB in your terminal via +the [`--local-lldbinit`][] flag; for example: + +``` +$ cmake --build --preset debug +$ lldb --local-lldbinit build/Debug/bin/slangc -- tests/byte-code/hello.slang -dump-ir +(lldb) breakpoint set --name dumpIR +(lldb) run +``` + +LLDB can be used with either GCC or Clang, but Clang seems to behave better +about respecting breakpoint locations and not having missing variables. + +### VS Code + +If instead you prefer to debug within VS Code, you can run LLDB via the +[CodeLLDB][] extension. For example, to recreate the same debugging session as +above, create a `.vscode/tasks.json` file with these contents: + +```json +{ + "version": "2.0.0", + "tasks": [ + { + "label": "Debug build", + "type": "shell", + "command": "cmake", + "args": ["--build", "--preset", "debug"] + } + ] +} +``` + +Then create a `.vscode/launch.json` file with these contents: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "LLDB", + "preLaunchTask": "Debug build", + "type": "lldb", + "request": "launch", + "initCommands": ["command source .lldbinit"], + "program": "build/Debug/bin/slangc", + "args": ["tests/byte-code/hello.slang", "-dump-ir"] + } + ] +} +``` + +Finally, place any breakpoints you want, and hit F5. + +[`--local-lldbinit`]: https://lldb.llvm.org/man/lldb.html#cmdoption-lldb-local-lldbinit +[codelldb]: https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb +[lldb]: https://lldb.llvm.org/index.html @@ -16,12 +16,20 @@ pkgs = import nixpkgs { inherit system; }; in { - devShell = pkgs.mkShell { + # We want to use Clang instead of GCC because it seems to behave better + # with LLDB, so we use `mkShellNoCC` here instead of `mkShell` because + # the latter brings in GCC by default on Linux. + devShell = pkgs.mkShellNoCC { buildInputs = [ + # Must put `clang-tools` before `clang` for clangd to work properly. + # We use `llvmPackages_17.clang-tools` instead of just `clang-tools` + # to match the `clang-format` version used in CI. + pkgs.llvmPackages_17.clang-tools + + pkgs.clang pkgs.cmake pkgs.gersemi - pkgs.llvm - pkgs.llvmPackages_17.clang-tools + pkgs.lldb pkgs.ninja pkgs.nixfmt-rfc-style pkgs.prettier diff --git a/source/core/core_lldb.py b/source/core/core_lldb.py index 05ba0a4db..2857405fd 100644 --- a/source/core/core_lldb.py +++ b/source/core/core_lldb.py @@ -1,7 +1,6 @@ """ This python script provides LLDB formatters for Slang core types. -To use it, add the following line to your ~/.lldbinit file: -command script import /path/to/source/core/core_lldb.py +To use it, see the `docs/debugging.md` file in this repo. """ import lldb diff --git a/source/slang/slang_lldb.py b/source/slang/slang_lldb.py index c1213e830..d4cb3b6f6 100644 --- a/source/slang/slang_lldb.py +++ b/source/slang/slang_lldb.py @@ -1,7 +1,6 @@ """ This python script provides LLDB formatters for Slang IR types. -To use it, add the following line to your ~/.lldbinit file: -command script import /path/to/source/slang/slang_lldb.py +To use it, see the `docs/debugging.md` file in this repo. """ import json |