diff --git a/crates/extension_api/wit/since_v0.6.0/dap.wit b/crates/extension_api/wit/since_v0.6.0/dap.wit index a3f07435d1..693befe02f 100644 --- a/crates/extension_api/wit/since_v0.6.0/dap.wit +++ b/crates/extension_api/wit/since_v0.6.0/dap.wit @@ -33,7 +33,7 @@ interface dap { } /// Debug Config is the "highest-level" configuration for a debug session. - /// It comes from a new session modal UI; thus, it is essentially debug-adapter-agnostic. + /// It comes from a new process modal UI; thus, it is essentially debug-adapter-agnostic. /// It is expected of the extension to translate this generic configuration into something that can be debugged by the adapter (debug scenario). record debug-config { /// Name of the debug task diff --git a/crates/task/src/debug_format.rs b/crates/task/src/debug_format.rs index e336fa1fd7..f95fcf56b6 100644 --- a/crates/task/src/debug_format.rs +++ b/crates/task/src/debug_format.rs @@ -243,7 +243,7 @@ pub enum Request { Attach, } -/// This struct represent a user created debug task from the new session modal +/// This struct represent a user created debug task from the new process modal #[derive(Deserialize, Serialize, PartialEq, Eq, Clone, Debug, JsonSchema)] #[serde(rename_all = "snake_case")] pub struct ZedDebugConfig { diff --git a/docs/src/configuring-zed.md b/docs/src/configuring-zed.md index 4587a70ac1..6318851913 100644 --- a/docs/src/configuring-zed.md +++ b/docs/src/configuring-zed.md @@ -1944,17 +1944,17 @@ Example: 1. Maps to `Alt` on Linux and Windows and to `Option` on MacOS: -```jsonc +```json { - "multi_cursor_modifier": "alt", + "multi_cursor_modifier": "alt" } ``` 2. Maps `Control` on Linux and Windows and to `Command` on MacOS: -```jsonc +```json { - "multi_cursor_modifier": "cmd_or_ctrl", // alias: "cmd", "ctrl" + "multi_cursor_modifier": "cmd_or_ctrl" // alias: "cmd", "ctrl" } ``` diff --git a/docs/src/debugger.md b/docs/src/debugger.md index 47d9ffaa04..f10461a160 100644 --- a/docs/src/debugger.md +++ b/docs/src/debugger.md @@ -3,6 +3,7 @@ Zed uses the [Debug Adapter Protocol (DAP)](https://microsoft.github.io/debug-adapter-protocol/) to provide debugging functionality across multiple programming languages. DAP is a standardized protocol that defines how debuggers, editors, and IDEs communicate with each other. It allows Zed to support various debuggers without needing to implement language-specific debugging logic. +Zed implements the client side of the protocol, and various _debug adapters_ implement the server side. This protocol enables features like setting breakpoints, stepping through code, inspecting variables, and more, in a consistent manner across different programming languages and runtime environments. @@ -10,36 +11,53 @@ and more, in a consistent manner across different programming languages and runt > We currently offer onboarding support for users. We are eager to hear from you if you encounter any issues or have suggestions for improvement for our debugging experience. > You can schedule a call via [Cal.com](https://cal.com/team/zed-research/debugger) -## Supported Debug Adapters +## Supported Languages -Zed supports a variety of debug adapters for different programming languages out of the box: +To debug code written in a specific language, Zed needs to find a debug adapter for that language. Some debug adapters are provided by Zed without additional setup, and some are provided by [language extensions](./extensions/debugger-extensions.md). The following languages currently have debug adapters available: -- JavaScript ([vscode-js-debug](https://github.com/microsoft/vscode-js-debug.git)): Enables debugging of Node.js applications, including setting breakpoints, stepping through code, and inspecting variables in JavaScript. + -- Python ([debugpy](https://github.com/microsoft/debugpy.git)): Provides debugging capabilities for Python applications, supporting features like remote debugging, multi-threaded debugging, and Django/Flask application debugging. +- [C](./languages/c.md#debugging) (built-in) +- [C++](./languages/cpp.md#debugging) (built-in) +- [Go](./languages/go.md#debugging) (built-in) +- [JavaScript](./languages/javascript.md#debugging) (built-in) +- [PHP](./languages/php.md#debugging) (built-in) +- [Python](./languages/python.md#debugging) (built-in) +- [Ruby](./languages/ruby.md#debugging) (provided by extension) +- [Rust](./languages/rust.md#debugging) (built-in) +- [Swift](./languages/swift.md#debugging) (provided by extension) +- [TypeScript](./languages/typescript.md#debugging) (built-in) -- LLDB ([CodeLLDB](https://github.com/vadimcn/codelldb.git)): A powerful debugger for Rust, C, C++, and some other compiled languages, offering low-level debugging features and support for Apple platforms. +> If your language isn't listed, you can contribute by adding a debug adapter for it. Check out our [debugger extensions](./extensions/debugger-extensions.md) documentation for more information. -- GDB ([GDB](https://sourceware.org/gdb/)): The GNU Debugger, which supports debugging for multiple programming languages including C, C++, Go, and Rust, across various platforms. - -- Go ([Delve](https://github.com/go-delve/delve)): Delve, a debugger for the Go programming language, offering both local and remote debugging capabilities with full support for Go's runtime and standard library. - -- PHP ([Xdebug](https://xdebug.org/)): Provides debugging and profiling capabilities for PHP applications, including remote debugging and code coverage analysis. - -- Ruby ([rdbg](https://github.com/ruby/debug)): Provides debugging for Ruby. - -These adapters enable Zed to provide a consistent debugging experience across multiple languages while leveraging the specific features and capabilities of each debugger. - -> Is your desired debugger not listed? You can install a [Debug Adapter extension](https://zed.dev/extensions?filter=debug-adapters) to add support for your favorite debugger. -> If that's not enough, you can contribute by creating an extension yourself. Check out our [debugger extensions](extensions/debugger-extensions.md) documentation for more information. +Follow those links for language- and adapter-specific information and examples, or read on for more about Zed's general debugging features that apply to all adapters. ## Getting Started -For basic debugging, you can set up a new configuration by opening the `New Session Modal` either via the `debugger: start` (default: f4) or by clicking the plus icon at the top right of the debug panel. +For most languages, the fastest way to get started is to run {#action debugger::Start} ({#kb debugger::Start}). This opens the _new process modal_, which shows you a contextual list of preconfigured debug tasks for the current project. Debug tasks are created from tests, entry points (like a `main` function), and from other sources — consult the documentation for your language for full information about what's supported. -For more advanced use cases, you can create debug configurations by directly editing the `.zed/debug.json` file in your project root directory. +You can open the same modal by clicking the "plus" button at the top right of the debug panel. -You can then use the `New Session Modal` to select a configuration and start debugging. +For languages that don't provide preconfigured debug tasks (this includes C, C++, and some extension-supported languages), you can define debug configurations in the `.zed/debug.json` file in your project root. This file should be an array of configuration objects: + +```json +[ + { + "adapter": "CodeLLDB", + "label": "First configuration" + // ... + }, + { + "adapter": "Debugpy", + "label": "Second configuration" + // ... + } +] +``` + +Check the documentation for your language for example configurations covering typical use-cases. Once you've added configurations to `.zed/debug.json`, they'll appear in the list in the new process modal. + +Zed will also load debug configurations from `.vscode/launch.json`, and show them in the new process modal if no configurations are found in `.zed/debug.json`. ### Launching & Attaching @@ -58,7 +76,7 @@ While configuration fields are debug adapter-dependent, most adapters support th ```json [ { - // The label for the debug configuration and used to identify the debug session inside the debug panel & new session modal + // The label for the debug configuration and used to identify the debug session inside the debug panel & new process modal "label": "Example Start debugger config", // The debug adapter that Zed should use to debug the program "adapter": "Example adapter name", @@ -113,309 +131,7 @@ Build tasks can also refer to the existing tasks by unsubstituted label: ### Automatic scenario creation Given a Zed task, Zed can automatically create a scenario for you. Automatic scenario creation also powers our scenario creation from gutter. -Automatic scenario creation is currently supported for Rust, Go, and Python. JavaScript/TypeScript support is being worked on. - -### Example Configurations - -#### JavaScript - -##### Debug Active File - -```json -[ - { - "label": "Debug with node", - "adapter": "JavaScript", - "program": "$ZED_FILE", - "request": "launch", - "console": "integratedTerminal", - "type": "pwa-node" - } -] -``` - -##### Attach debugger to a server running in web browser (`npx serve`) - -Given an externally-ran web server (e.g., with `npx serve` or `npx live-server`) one can attach to it and open it with a browser. - -```json -[ - { - "label": "Inspect ", - "adapter": "JavaScript", - "type": "pwa-chrome", - "request": "launch", - "url": "http://localhost:5500", // Fill your URL here. - "program": "$ZED_FILE", - "webRoot": "${ZED_WORKTREE_ROOT}" - } -] -``` - -#### Python - -##### Debug Active File - -```json -[ - { - "label": "Python Active File", - "adapter": "Debugpy", - "program": "$ZED_FILE", - "request": "launch" - } -] -``` - -##### Flask App - -For a common Flask Application with a file structure similar to the following: - -``` -.venv/ -app/ - init.py - main.py - routes.py -templates/ - index.html -static/ - style.css -requirements.txt -``` - -…the following configuration can be used: - -```json -[ - { - "label": "Python: Flask", - "adapter": "Debugpy", - "request": "launch", - "module": "app", - "cwd": "$ZED_WORKTREE_ROOT", - "env": { - "FLASK_APP": "app", - "FLASK_DEBUG": "1" - }, - "args": [ - "run", - "--reload", // Enables Flask reloader that watches for file changes - "--debugger" // Enables Flask debugger - ], - "autoReload": { - "enable": true - }, - "jinja": true, - "justMyCode": true - } -] -``` - -#### Rust/C++/C - -> For CodeLLDB, you might want to set `sourceLanguages` in your launch configuration based on the source code language. - -##### Using pre-built binary - -```json -[ - { - "label": "Debug native binary", - "program": "$ZED_WORKTREE_ROOT/build/binary", - "request": "launch", - "adapter": "CodeLLDB" // GDB is available on non-ARM Macs as well as Linux - } -] -``` - -##### Build binary then debug - -```json -[ - { - "label": "Build & Debug native binary", - "build": { - "command": "cargo", - "args": ["build"] - }, - "program": "$ZED_WORKTREE_ROOT/target/debug/binary", - "request": "launch", - "adapter": "CodeLLDB" // GDB is available on non-ARM Macs as well as Linux - } -] -``` - -##### Automatically locate a debug target based on build command - -```json -[ - { - "label": "Build & Debug native binary", - "adapter": "CodeLLDB" // GDB is available on non-ARM Macs as well as Linux - // Zed can infer the path to a debuggee based on the build command - "build": { - "command": "cargo", - "args": ["build"] - }, - } -] -``` - -#### TypeScript - -##### Attach debugger to a server running in web browser (`npx serve`) - -Given an externally-ran web server (e.g., with `npx serve` or `npx live-server`) one can attach to it and open it with a browser. - -```json -[ - { - "label": "Launch Chrome (TypeScript)", - "adapter": "JavaScript", - "type": "pwa-chrome", - "request": "launch", - "url": "http://localhost:5500", - "program": "$ZED_FILE", - "webRoot": "${ZED_WORKTREE_ROOT}", - "sourceMaps": true, - "build": { - "command": "npx", - "args": ["tsc"] - } - } -] -``` - -#### Go - -Zed uses [delve](https://github.com/go-delve/delve?tab=readme-ov-file) to debug Go applications. -Zed will automatically create debug scenarios for `func main` in your main packages, and also -for any tests, so you can use the Play button in the gutter to debug these without configuration. - -##### Debug Go Packages - -To debug a specific package, you can do so by setting the Delve mode to "debug". In this case "program" should be set to the package name. - -```json -[ - { - "label": "Go (Delve)", - "adapter": "Delve", - "program": "$ZED_FILE", - "request": "launch", - "mode": "debug" - } -] -``` - -```json -[ - { - "label": "Run server", - "adapter": "Delve", - "request": "launch", - "mode": "debug", - // For Delve, the program can be a package name - "program": "./cmd/server" - // "args": [], - // "buildFlags": [], - } -] -``` - -##### Debug Go Tests - -To debug the tests for a package, set the Delve mode to "test". -The "program" is still the package name, and you can use the "buildFlags" to do things like set tags, and the "args" to set args on the test binary. (See `go help testflags` for more information on doing that). - -```json -[ - { - "label": "Run integration tests", - "adapter": "Delve", - "request": "launch", - "mode": "test", - "program": ".", - "buildFlags": ["-tags", "integration"] - // To filter down to just the test your cursor is in: - // "args": ["-test.run", "$ZED_SYMBOL"] - } -] -``` - -##### Build and debug separately - -If you need to build your application with a specific command, you can use the "exec" mode of Delve. In this case "program" should point to an executable, -and the "build" command should build that. - -```json -{ - "label": "Debug Prebuilt Unit Tests", - "adapter": "Delve", - "request": "launch", - "mode": "exec", - "program": "${ZED_WORKTREE_ROOT}/__debug_unit", - "args": ["-test.v", "-test.run=${ZED_SYMBOL}"], - "build": { - "command": "go", - "args": [ - "test", - "-c", - "-tags", - "unit", - "-gcflags\"all=-N -l\"", - "-o", - "__debug_unit", - "./pkg/..." - ] - } -} -``` - -##### Attaching to an existing instance of Delve - -You might find yourself needing to connect to an existing instance of Delve that's not necessarily running on your machine; in such case, you can use `tcp_arguments` to instrument Zed's connection to Delve. - -``` -{ - "adapter": "Delve", - "label": "Connect to a running Delve instance", - "program": "/Users/zed/Projects/language_repositories/golang/hello/hello", - "cwd": "/Users/zed/Projects/language_repositories/golang/hello", - "args": [], - "env": {}, - "request": "launch", - "mode": "exec", - "stopOnEntry": false, - "tcp_connection": { "host": "123.456.789.012", "port": 53412 } -} -``` - -In such case Zed won't spawn a new instance of Delve, as it opts to use an existing one. The consequence of this is that _there will be no terminal_ in Zed; you have to interact with the Delve instance directly, as it handles stdin/stdout of the debuggee. - -#### Ruby - -To run a ruby task in the debugger, you will need to configure it in the `.zed/debug.json` file in your project. We don't yet have automatic detection of ruby tasks, nor do we support connecting to an existing process. - -The configuration should look like this: - -```json -[ - { - "adapter": "Ruby", - "label": "Run CLI", - "script": "cli.rb" - // If you want to customize how the script is run (for example using bundle exec) - // use "command" instead. - // "command": "bundle exec cli.rb" - // - // "args": [] - // "env": {} - // "cwd": "" - } -] -``` +Automatic scenario creation is currently supported for Rust, Go, Python, JavaScript, and TypeScript. ## Breakpoints @@ -623,5 +339,5 @@ If you're running into problems with the debugger, please [open a GitHub issue]( There are also some features you can use to gather more information about the problem: -- When you have a session running in the debug panel, you can run the `dev: copy debug adapter arguments` action to copy a JSON blob to the clipboard that describes how Zed initialized the session. This is especially useful when the session failed to start, and is great context to add if you open a GitHub issue. -- You can also use the `dev: open debug adapter logs` action to see a trace of all of Zed's communications with debug adapters during the most recent debug sessions. +- When you have a session running in the debug panel, you can run the {#action dev::CopyDebugAdapterArguments} action to copy a JSON blob to the clipboard that describes how Zed initialized the session. This is especially useful when the session failed to start, and is great context to add if you open a GitHub issue. +- You can also use the {#action dev::OpenDebugAdapterLogs} action to see a trace of all of Zed's communications with debug adapters during the most recent debug sessions. diff --git a/docs/src/extensions/debugger-extensions.md b/docs/src/extensions/debugger-extensions.md index ad8e2c5e29..4412bf8b9a 100644 --- a/docs/src/extensions/debugger-extensions.md +++ b/docs/src/extensions/debugger-extensions.md @@ -56,7 +56,7 @@ impl zed::Extension for MyExtension { } ``` -`dap_config_to_scenario` is used when the user spawns a session via new session modal UI. At a high level, it takes a generic debug configuration (that isn't specific to any +`dap_config_to_scenario` is used when the user spawns a session via new process modal UI. At a high level, it takes a generic debug configuration (that isn't specific to any debug adapter) and tries to turn it into a concrete debug scenario for your adapter. Put another way, it is supposed to answer the question: "Given a program, a list of arguments, current working directory and environment variables, what would the configuration for spawning this debug adapter look like?". diff --git a/docs/src/languages/c.md b/docs/src/languages/c.md index ff6b180660..14a11c0d66 100644 --- a/docs/src/languages/c.md +++ b/docs/src/languages/c.md @@ -4,6 +4,7 @@ C support is available natively in Zed. - Tree-sitter: [tree-sitter/tree-sitter-c](https://github.com/tree-sitter/tree-sitter-c) - Language Server: [clangd/clangd](https://github.com/clangd/clangd) +- Debug Adapter: [CodeLLDB](https://github.com/vadimcn) (primary), [GDB](https://sourceware.org/gdb/) (secondary, not available on Apple silicon) ## Clangd: Force detect as C @@ -61,3 +62,25 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON) ``` After building your project, CMake will generate the `compile_commands.json` file in the build directory and clangd will automatically pick it up. + +## Debugging + +You can use CodeLLDB or GDB to debug native binaries. (Make sure that your build process passes `-g` to the C compiler, so that debug information is included in the resulting binary.) See below for examples of debug configurations that you can add to `.zed/debug.json`. + +### Build and Debug Binary + +```json +[ + { + "label": "Debug native binary", + "build": { + "command": "make", + "args": ["-j8"], + "cwd": "$ZED_WORKTREE_ROOT" + } + "program": "$ZED_WORKTREE_ROOT/build/prog", + "request": "launch", + "adapter": "CodeLLDB" + } +] +``` diff --git a/docs/src/languages/cpp.md b/docs/src/languages/cpp.md index ccce575af7..1273bce2ac 100644 --- a/docs/src/languages/cpp.md +++ b/docs/src/languages/cpp.md @@ -112,3 +112,25 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON) ``` After building your project, CMake will generate the `compile_commands.json` file in the build directory and clangd will automatically pick it up. + +## Debugging + +You can use CodeLLDB or GDB to debug native binaries. (Make sure that your build process passes `-g` to the C++ compiler, so that debug information is included in the resulting binary.) See below for examples of debug configurations that you can add to `.zed/debug.json`. + +### Build and Debug Binary + +```json +[ + { + "label": "Debug native binary", + "build": { + "command": "make", + "args": ["-j8"], + "cwd": "$ZED_WORKTREE_ROOT" + } + "program": "$ZED_WORKTREE_ROOT/build/prog", + "request": "launch", + "adapter": "CodeLLDB" + } +] +``` diff --git a/docs/src/languages/go.md b/docs/src/languages/go.md index 6bea4ba04c..0a12616b1c 100644 --- a/docs/src/languages/go.md +++ b/docs/src/languages/go.md @@ -4,6 +4,7 @@ Go support is available natively in Zed. - Tree-sitter: [tree-sitter/tree-sitter-go](https://github.com/tree-sitter/tree-sitter-go) - Language Server: [golang/tools/tree/master/gopls](https://github.com/golang/tools/tree/master/gopls) +- Debug Adapter: [delve](https://github.com/go-delve/delve) ## Setup @@ -72,6 +73,112 @@ to override these settings. See [gopls inlayHints documentation](https://github.com/golang/tools/blob/master/gopls/doc/inlayHints.md) for more information. +## Debugging + +Zed supports zero-configuration debugging of Go tests and entry points (`func main`). Run {#action debugger::Start} ({#kb debugger::Start}) to see a contextual list of these preconfigured debug tasks. + +For more control, you can add debug configurations to `.zed/debug.json`. See below for examples. + +### Debug Go Packages + +To debug a specific package, you can do so by setting the Delve mode to "debug". In this case "program" should be set to the package name. + +```json +[ + { + "label": "Go (Delve)", + "adapter": "Delve", + "program": "$ZED_FILE", + "request": "launch", + "mode": "debug" + }, + { + "label": "Run server", + "adapter": "Delve", + "request": "launch", + "mode": "debug", + // For Delve, the program can be a package name + "program": "./cmd/server" + // "args": [], + // "buildFlags": [], + } +] +``` + +### Debug Go Tests + +To debug the tests for a package, set the Delve mode to "test". +The "program" is still the package name, and you can use the "buildFlags" to do things like set tags, and the "args" to set args on the test binary. (See `go help testflags` for more information on doing that). + +```json +[ + { + "label": "Run integration tests", + "adapter": "Delve", + "request": "launch", + "mode": "test", + "program": ".", + "buildFlags": ["-tags", "integration"] + // To filter down to just the test your cursor is in: + // "args": ["-test.run", "$ZED_SYMBOL"] + } +] +``` + +### Build and debug separately + +If you need to build your application with a specific command, you can use the "exec" mode of Delve. In this case "program" should point to an executable, +and the "build" command should build that. + +```json +[ + { + "label": "Debug Prebuilt Unit Tests", + "adapter": "Delve", + "request": "launch", + "mode": "exec", + "program": "${ZED_WORKTREE_ROOT}/__debug_unit", + "args": ["-test.v", "-test.run=${ZED_SYMBOL}"], + "build": { + "command": "go", + "args": [ + "test", + "-c", + "-tags", + "unit", + "-gcflags\"all=-N -l\"", + "-o", + "__debug_unit", + "./pkg/..." + ] + } + } +] +``` + +### Attaching to an existing instance of Delve + +You might find yourself needing to connect to an existing instance of Delve that's not necessarily running on your machine; in such case, you can use `tcp_arguments` to instrument Zed's connection to Delve. + +```json +[ + { + "adapter": "Delve", + "label": "Connect to a running Delve instance", + "program": "/Users/zed/Projects/language_repositories/golang/hello/hello", + "cwd": "/Users/zed/Projects/language_repositories/golang/hello", + "args": [], + "env": {}, + "request": "launch", + "mode": "exec", + "stopOnEntry": false, + "tcp_connection": { "host": "123.456.789.012", "port": 53412 } + } +] +``` + +In such case Zed won't spawn a new instance of Delve, as it opts to use an existing one. The consequence of this is that _there will be no terminal_ in Zed; you have to interact with the Delve instance directly, as it handles stdin/stdout of the debuggee. + ## Go Mod - Tree-sitter: [camdencheek/tree-sitter-go-mod](https://github.com/camdencheek/tree-sitter-go-mod) diff --git a/docs/src/languages/javascript.md b/docs/src/languages/javascript.md index b42fa31922..c71071a9b3 100644 --- a/docs/src/languages/javascript.md +++ b/docs/src/languages/javascript.md @@ -4,6 +4,7 @@ JavaScript support is available natively in Zed. - Tree-sitter: [tree-sitter/tree-sitter-javascript](https://github.com/tree-sitter/tree-sitter-javascript) - Language Server: [typescript-language-server/typescript-language-server](https://github.com/typescript-language-server/typescript-language-server) +- Debug Adapter: [vscode-js-debug](https://github.com/microsoft/vscode-js-debug) ## Code formatting @@ -174,6 +175,54 @@ You can configure ESLint's `workingDirectory` setting: } ``` +## Debugging + +Zed supports debugging JavaScript code out of the box. +The following can be debugged without writing additional configuration: + +- Tasks from `package.json` +- Tests written using several popular frameworks (Jest, Mocha, Vitest, Jasmine) + +Run {#action debugger::Start} ({#kb debugger::Start}) to see a contextual list of these predefined debug tasks. + +As for all languages, configurations from `.vscode/launch.json` are also available for debugging in Zed. + +If your use-case isn't covered by any of these, you can take full control by adding debug configurations to `.zed/debug.json`. See below for example configurations. + +### Debug the current file + +```json +[ + { + "adapter": "JavaScript", + "label": "Debug JS file", + "type": "node", + "request": "launch", + "program": "$ZED_FILE", + "skipFiles": ["/**"] + } +] +``` + +This implicitly runs the current file using `node`. + +### Launch a web app in Chrome + +```json +[ + { + "adapter": "JavaScript", + "label": "Debug app in Chrome", + "type": "chrome", + "request": "launch", + "file": "$ZED_WORKTREE_ROOT/index.html", + "webRoot": "$ZED_WORKTREE_ROOT", + "console": "integratedTerminal", + "skipFiles": ["/**"] + } +] +``` + ## See also - [Yarn documentation](./yarn.md) for a walkthrough of configuring your project to use Yarn. diff --git a/docs/src/languages/python.md b/docs/src/languages/python.md index 05f1491ca7..5d90065de0 100644 --- a/docs/src/languages/python.md +++ b/docs/src/languages/python.md @@ -6,6 +6,7 @@ Python support is available natively in Zed. - Language Servers: - [microsoft/pyright](https://github.com/microsoft/pyright) - [python-lsp/python-lsp-server](https://github.com/python-lsp/python-lsp-server) (PyLSP) +- Debug Adapter: [debugpy](https://github.com/microsoft/debugpy) ## Language Servers @@ -125,3 +126,67 @@ A common tool for formatting Python code is [Ruff](https://docs.astral.sh/ruff/) TBD: Expand Python Ruff docs. TBD: Ruff pyproject.toml, ruff.toml docs. `ruff.configuration`. --> + +## Debugging + +Zed supports zero-configuration debugging of Python module entry points and pytest tests. +Run {#action debugger::Start} ({#kb debugger::Start}) to see a contextual list for the current project. +For greater control, you can add debug configurations to `.zed/debug.json`. See the examples below. + +### Debug Active File + +```json +[ + { + "label": "Python Active File", + "adapter": "Debugpy", + "program": "$ZED_FILE", + "request": "launch" + } +] +``` + +### Flask App + +For a common Flask Application with a file structure similar to the following: + +``` +.venv/ +app/ + init.py + main.py + routes.py +templates/ + index.html +static/ + style.css +requirements.txt +``` + +…the following configuration can be used: + +```json +[ + { + "label": "Python: Flask", + "adapter": "Debugpy", + "request": "launch", + "module": "app", + "cwd": "$ZED_WORKTREE_ROOT", + "env": { + "FLASK_APP": "app", + "FLASK_DEBUG": "1" + }, + "args": [ + "run", + "--reload", // Enables Flask reloader that watches for file changes + "--debugger" // Enables Flask debugger + ], + "autoReload": { + "enable": true + }, + "jinja": true, + "justMyCode": true + } +] +``` diff --git a/docs/src/languages/ruby.md b/docs/src/languages/ruby.md index 8b3094a3b7..67904e35f1 100644 --- a/docs/src/languages/ruby.md +++ b/docs/src/languages/ruby.md @@ -9,6 +9,7 @@ Ruby support is available through the [Ruby extension](https://github.com/zed-ex - [ruby-lsp](https://github.com/Shopify/ruby-lsp) - [solargraph](https://github.com/castwide/solargraph) - [rubocop](https://github.com/rubocop/rubocop) +- Debug Adapter: [`rdbg`](https://github.com/ruby/debug) The Ruby extension also provides support for ERB files. @@ -43,15 +44,15 @@ For all supported Ruby language servers (`solargraph`, `ruby-lsp`, `rubocop`, `s You can skip step 1 and force using the system executable by setting `use_bundler` to `false` in your settings: -```jsonc +```json { "lsp": { "": { "settings": { - "use_bundler": false, - }, - }, - }, + "use_bundler": false + } + } + } } ``` @@ -349,21 +350,21 @@ The Ruby extension provides a debug adapter for debugging Ruby code. Zed's name #### Debug a Ruby script -```jsonc +```json [ { "label": "Debug current file", "adapter": "rdbg", "request": "launch", "script": "$ZED_FILE", - "cwd": "$ZED_WORKTREE_ROOT", - }, + "cwd": "$ZED_WORKTREE_ROOT" + } ] ``` #### Debug Rails server -```jsonc +```json [ { "label": "Debug Rails server", @@ -373,8 +374,8 @@ The Ruby extension provides a debug adapter for debugging Ruby code. Zed's name "args": ["server"], "cwd": "$ZED_WORKTREE_ROOT", "env": { - "RUBY_DEBUG_OPEN": "true", - }, - }, + "RUBY_DEBUG_OPEN": "true" + } + } ] ``` diff --git a/docs/src/languages/rust.md b/docs/src/languages/rust.md index ea6f6912cd..1ee25a37b5 100644 --- a/docs/src/languages/rust.md +++ b/docs/src/languages/rust.md @@ -4,6 +4,7 @@ Rust support is available natively in Zed. - Tree-sitter: [tree-sitter/tree-sitter-rust](https://github.com/tree-sitter/tree-sitter-rust) - Language Server: [rust-lang/rust-analyzer](https://github.com/rust-lang/rust-analyzer) +- Debug Adapter: [CodeLLDB](https://github.com/vadimcn/codelldb) (primary), [GDB](https://sourceware.org/gdb/) (secondary, not available on Apple silicon)