Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-09-20 06:22:01 +00:00
Code Issues Projects Releases Packages Wiki Activity
bevy/docs/debugging.md
MichiRecRoom 94d40d206e
Replace the wgpu_trace feature with a field in bevy_render::settings::WgpuSettings (#14842) 
# Objective
- Remove the `wgpu_trace` feature while still making it easy/possible to
record wgpu traces for debugging.
- Close #14725.
- Get a taste of the bevy codebase. :P

## Solution
This PR performs the above objective by removing the `wgpu_trace`
feature from all `Cargo.toml` files.

However, wgpu traces are still useful for debugging - but to record
them, you need to pass in a directory path to store the traces in. To
avoid forcing users into manually creating the renderer,
`bevy_render::settings::WgpuSettings` now has a `trace_path` field, so
that all of Bevy's automatic initialization can happen while still
allowing for tracing.

## Testing
- Did you test these changes? If so, how?
- I have tested these changes, but only via running `cargo run -p ci`. I
am hoping the Github Actions workflows will catch anything I missed.
- Are there any parts that need more testing?
  - I do not believe so.
- How can other people (reviewers) test your changes? Is there anything
specific they need to know?
- If you want to test these changes, I have updated the debugging guide
(`docs/debugging.md`) section on WGPU Tracing.
- If relevant, what platforms did you test these changes on, and are
there any important ones you can't test?
- I ran the above command on a Windows 10 64-bit (x64) machine, using
the `stable-x86_64-pc-windows-msvc` toolchain. I do not have anything
set up for other platforms or targets (though I can't imagine this needs
testing on other platforms).

---

## Migration Guide

1. The `bevy/wgpu_trace`, `bevy_render/wgpu_trace`, and
`bevy_internal/wgpu_trace` features no longer exist. Remove them from
your `Cargo.toml`, CI, tooling, and what-not.
2. Follow the instructions in the updated `docs/debugging.md` file in
the repository, under the WGPU Tracing section.

Because of the changes made, you can now generate traces to any path,
rather than the hardcoded `%WorkspaceRoot%/wgpu_trace` (where
`%WorkspaceRoot%` is... the root of your crate's workspace) folder.

(If WGPU hasn't restored tracing functionality...) Do note that WGPU has
not yet restored tracing functionality. However, once it does, the above
should be sufficient to generate new traces.

---------

Co-authored-by: TrialDragon <31419708+TrialDragon@users.noreply.github.com>
2024-08-25 14:16:11 +00:00

1.8 KiB
Raw Blame History

Debugging

Macro Debugging

  • Print the final output of a macro using cargo rustc --profile=check -- -Zunstable-options --pretty=expanded
    • Alternatively you could install and use cargo expand which adds syntax highlighting to the terminal output.
      • Additionally get pager by piping to less ( on Unix systems ): cargo expand --color always | less -R
  • Print output during macro compilation using eprintln!("hi");

WGPU Tracing

When a suspected wgpu error occurs, you should capture a wgpu trace so that Bevy and wgpu devs can debug using the wgpu player tool.

To capture a wgpu trace:

  1. Create a new folder in which to store your wgpu trace.
  2. Pass the path to the folder you created for your wgpu trace to bevy_render::RenderPlugin, using the render_creation field.
    • If you're manually creating the renderer resources, pass the path to wgpu when creating the RenderDevice and RenderQueue.
    • Otherwise, pass the path to Bevy via the trace_path field in bevy_render::settings::WgpuSettings.
  3. Add wgpu = { version = "*", features = ["trace"]} to your Cargo.toml.
    • version = "*" tells Rust that this can be any version of the wgpu crate, so it will not try to pull in a different version of wgpu than what is already pulled in by Bevy.
  4. Compile and run your application, performing any in-app actions necessary to replicate the wgpu error.

Once you've captured a wgpu trace, zip up the folder and attach it to the relevant issue. New wgpu issues should generally be created in the wgpu repository. Please include the wgpu revision in your bug reports. You can find the revision in the Cargo.lock file in your workspace.