Add instructions to allow breakpoint debugging despite fast compile options in the Bevy setup guide

[kfjustis]

Overview

Breakpoint debugging is a common developer tool for inspecting values at runtime and checking programmer logic against code execution order. However, the current Bevy setup guide can lead to some pitfalls in enabling breakpoint debugging in editors like VS Code and Zed.

I will caveat what I found by saying some of this is a bit specific to VS Code, but I think some degree of this information should be integrated into the Quick Start page. The steps I gathered were spread out between reddit, Stack Overflow, and Discord, so I think it would be beneficial to at least lead developers down the right path from the official docs even if these steps can't be applied to every single environment.

This information is also specific to Linux and Mac. I'm not sure if breakpoints work out of the box on Windows as I don't have a Windows machine to test with.

Pain Points

On the Bevy Quickstart page, under Getting Started > Setup > Compile with Performance Optimizations, there is a series of steps that provide excellent results on how to enable optimal debug builds for fast compilation times and improved runtime performance. The major stumbles are:

• Dynamic Linking: This section caused the first problem. Since Bevy gets built as a dynamic library, the debugger needs to be made aware of where to find symbols that aren't directly available in the user's app binary.

• Cranelift: This section caused the second problem. Even when symbols can be resolved, cranelift can over optimize the binary--even in debug--to the point where a debugger can't find the correct symbol information. This one is the most frustrating because the app can run without any apparent issues, but breakpoints will be completely ignored.

• opt-level in Cargo.toml: This one is the smallest issue to fix as it's more intuitive than the others, but since the guide recommends an opt-level = 1 under [profile.dev], breakpoints that do get hit will show a call stack with missing symbol names (since some optimization was performed).

Solutions

• Dynamic Linking: On Linux, the user must be sure to set LD_LIBRARY_PATH to the location of the stdlib.so for their version of Rust (either Stable or Nightly). On macOS, the variable to set is called DYLD_LIBRARY_PATH.

• Cranelift: On Linux, enabling the cranelift settings as the current guide mentions actually works fine. It was macOS (arm) that caused the over optimizations to occur, so I found no other workaround than to disable Cranelift.

• opt-level in Cargo.toml: To guarantee symbols have all of their information, the user has to set opt-level = 1 to opt-level = 0 (for no optimizations) instead.

VS Code Specifics

Even after the above fixes, running the debugger seemed to expect the assets folder to be located along side the binary in .../target/debug. To avoid this, the user can set the "CARGO_MANIFEST_DIR": "${workspaceFolder}", option in the env tag for their launch.json configuration.

Note: Breakpoint debugging in VS Code requires the CodeLLDB extension to be installed.

Below is my full launch.json file that works for both Linux and macOS (arm):

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lldb",
            "request": "launch",
            "name": "Debug",
            "program": "${workspaceFolder}/target/debug/MyBevyAppName",
            "args": [],
            "cwd": "${workspaceFolder}",
            "env": {
                "CARGO_MANIFEST_DIR": "${workspaceFolder}",
                "LD_LIBRARY_PATH": "${workspaceFolder}/target/debug/deps:${env:HOME}/.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib",
                "DYLD_LIBRARY_PATH": "${workspaceFolder}/target/debug/deps:${env:HOME}/.rustup/toolchains/nightly-aarch64-apple-darwin/lib/rustlib/aarch64-apple-darwin/lib"
            },
        }
    ]
}

Credits & Bonus Info

I found information on this across several sources:

• The Bevy Cheatbook covers most of this debugging setup already, but did not have specifics on the problem of breakpoints getting skipped. Their page is here: https://bevy-cheatbook.github.io/setup/editor/vscode.html
• This reddit post concerns the issue of debugging with dynamic linking: https://www.reddit.com/r/bevy/comments/zoz80w/how_to_debug_a_bevy_game_with_the_dynamic_feature/
• If you don't know where your libstd dylib or .so is located, you can run: rustup toolchain list -v to get a starting point.
• Zed accepts a VS Code launch.json as input for its debugging environment, so if you have a working launch.json you can use the same environment in both editors.