Missing instructions for macOS Metal

[Walther]

The instructions for getting started with gfx-rs on macOS are lacking.

The Readme instructs:

# macOS
cargo run --bin quad --features metal

These examples assume that necessary dependencies for the graphics backend are already installed. For more information about installation and usage, refer to the Getting Started guide.

The Getting Started guide only has instructions for Fedora and Ubuntu.

With the instructions provided, running on macOS 10.14.1 (18B75), with only the XCode command-line utils installed (not the full XCode IDE and everything), you bump into the following error:

cargo run --bin quad --features metal
   Compiling gfx-backend-metal v0.1.0 (file:///Users/walther/git/gfx/src/backend/metal)
   Compiling spirv_cross v0.11.2
   Compiling objc_id v0.1.1
   Compiling cocoa v0.18.1
   Compiling cocoa v0.17.0
   Compiling parking_lot_core v0.3.1
   Compiling glsl-to-spirv v0.1.7
   Compiling gfx-hal v0.1.0 (file:///Users/walther/git/gfx/src/hal)
   Compiling jpeg-decoder v0.1.15
error: failed to run custom build command for `gfx-backend-metal v0.1.0 (file:///Users/walther/git/gfx/src/backend/metal)`
process didn't exit successfully: `/Users/walther/git/gfx/target/debug/build/gfx-backend-metal-eca86b15efa6c9d1/build-script-build` (exit code: 101)
--- stdout
cargo:rerun-if-changed=/Users/walther/git/gfx/src/backend/metal/shaders
cargo:rerun-if-changed=/Users/walther/git/gfx/src/backend/metal/shaders/blit.metal

--- stderr
xcrun: error: unable to find utility "metal", not a developer tool or in PATH
thread 'main' panicked at 'shader compilation failed', src/backend/metal/build.rs:68:13
note: Run with `RUST_BACKTRACE=1` for a backtrace.

warning: build failed, waiting for other jobs to finish...
^C

After a quick googling, this seems to suggest that the relevant tools might be only available after installing the full XCode distribution.

(I'll report back when I get to a place with proper internet again so that I can download the full XCode, and see if that solves the issue. If it does, I'll gladly write a PR with the step-by-step instructions ❤️ )

[Walther]

Confirmed, after installing the full XCode from the mac AppStore, the example runs just fine.

I wonder if there would be any other way to make this runnable? Any lightweight options of installing only the metal support somehow?

Or should I just add the instructions on the Getting started doc for installing the full XCode app?

[boredstiff]

In case it helps anyone in the future, I already did have XCode installed, but it still wasn't finding metal, so running sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer got it running for me again. Thanks for fixing stuff up @Walther it helped me figure out my issue pretty quickly.

[ikamensh]

would be great to emit a human readable message with those instructions so that people don't have to search the internet!

[kvark]

@ikamensh yes, we could do something like that in the build.rs script if we detect things to fail. Would you want to make that change?

[ikamensh]

I haven't contributed to gfx so far, so I don't know anything about the code base. Could you lay out a design idea, what conditions do I need to capture, etc. and few links to relevant places in code?

[kvark]

@ikamensh actually, this particular problem shouldn't exist as of #3047