bevy/docs/debugging.md

# 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](https://github.com/dtolnay/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](https://github.com/gfx-rs/wgpu/wiki/Debugging-wgpu-Applications#tracing-infrastructure).

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](https://github.com/gfx-rs/wgpu). Please include the wgpu revision in your bug reports. You can find the revision in the `Cargo.lock` file in your workspace.
add texture to frag shader. fix weird macro name collision bug 2020-02-19 04:26:02 +00:00			`# Debugging`

			`## Macro Debugging`

Add wgpu trace docs 2020-08-16 08:21:37 +00:00			* Print the final output of a macro using `cargo rustc --profile=check -- -Zunstable-options --pretty=expanded`
			`* Alternatively you could install and use [cargo expand](https://github.com/dtolnay/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](https://github.com/gfx-rs/wgpu/wiki/Debugging-wgpu-Applications#tracing-infrastructure).`

			`To capture a wgpu trace:`
Documenting small things here and there.. (#706) Documenting small things here and there.. 2020-10-21 22:57:03 +00:00
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. 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](https://github.com/gfx-rs/wgpu). Please include the wgpu revision in your bug reports. You can find the revision in the `Cargo.lock` file in your workspace.