Add documentation describing how to set up Xcode debugging

[chinedufn]

I’d like to add an example of taking a Metal app that’s completely written in Rust and debugging it in Xcode.

I’ve never actually done this - but I have some thoughts on how to approach it.

On mobile so might have typos

1. Add an example that just imports one of the other examples (such as the textured quad example). So the imported example would have to expose a “run” method. Use an environment variable to make the shader compilation include debug info. (So that when people copy paste the build script for their real project they aren’t accidentally generating debug builds without realizing)

2. Our Xcode debugging example would compile to a dylib that exposed a single method to run it

3. Xcode example would have the smallest possible Xcode project that links to and runs the Rust generated dylib

4. In the README of the example we include a screenshot or two of an Xcode debug session as well as any important notes / caveats if there end up being any

The nice part would be that the Xcode project would be immediately re-usable for any application since it does nothing but run a dylib.

One reason that I can think of against adding this example is that in general Xcode tends to feel bloaty (or at least that was my experience 6 or so years ago). I think that this is mitigated by having a project that does nothing more than run a linked library.

Another question might be - does this belong in metal-rs or a separate repo?

My thinking would be that being able to debug your shaders can be such a timesaver as well as such a cool demo as well as something you might not have thought of (I can still use Xcode tools with my entirely Rust app?!?!) that it belongs alongside the core examples.

Once people know how to run Xcode tools on their Rust app this means they now also know how to profile shaders, as well as anything else you might want to lean on Xcode’s user interface for (anything you want to visualize).

So this one example would unlock all Xcode tooling for the developer.

To repeat - I’ve never actually done this so it sounds good on paper but who knows what gotchas might exist.

But that’s the point of the example. We discover the solutions to those and present it in a nice tidy little example.

Let me know your thoughts and where you agree or disagree!

[kvark]

Thank you for filing your thoughts here!

We've been using XCode extensively in gfx/wgpu land to debug Metal pure-Rust applications. There is no need to have any infrastructure to do so, or any dedicated example.
There was a nice picture showing how to set it up somewhere (cc @grovesNL). Perhaps all we need is to make a Wiki page with a few pictures describing this?

The steps are basically:

1. Create a new project with "External Build System" type and "$(HOME)/.cargo/bin/cargo" tool
2. Edit Scheme -> Info -> Executable point to the executable you build
3. Optionally set up the environment, arguments (in Arguments) and working dir (in Options)

That's it!

[chinedufn]

Woah - that’s awesome!

A wiki page describing this sounds good to me. Along with a link to it from the README.

Sweet - glad this turned out to be even easier than I originally thought

[chinedufn]

Quick update. I plan to do this whenever I need to use Metal's debugging tools.

No idea when that will be - but when it happens I'll PR a markdown file with some screenshots and maybe @kvark can take that and copy paste it into a Wiki for this repo (although I personally prefer either docs/some-markdown-files.md or an mdbook but I don't have a strong opinion here so whatever works!)

[chinedufn]

Going to leave this open until I move the docs from the markdown file to the wiki as discussed in #151 (review)

[kvark]

@chinedufn you don't have to. I just wanted to make sure that you can do that, but if you prefer the markdown in code, I'm totally fine with that too.

[chinedufn]

Oh - sweet I'm leaving it as markdown then.

Cheers!