Adding MacOS Instructions

[github-felipe-caputo]

I have recently started following this (excellent) tutorial on Vulkan, but at first I really got kind of stuck setting up everything to run on my macbook. I am also a relatively new dev on mac, so I had to learn some stuff as I went.

I got the setup to work on Xcode and I decided to add that information on the instructions. Everything seems to be running fine over here, inclusing the demos, so I think these instructions should be fine.

Suggestions are definitely welcome, not only on phrasing and all that, but on the actual instructions (if maybe I forgot something that would break on more advanced applications or something like that).

Cheers!

[github-felipe-caputo]

Oh, the one thing that I ended up changing on the example was that I changed #define GLFW_INCLUDE_VULKAN to #include <vulkan/vulkan.h>. I just could not make the code build successfully with the glfw define, so instead I decided to simply include the vulkan headers (the rest of the example works just fine).

[Overv]

Very nice work, thank you for your contribution. I will review this as soon as possible. In the meanwhile, could you remove the .DS_Store file?

[github-felipe-caputo]

Oops, forgot that one. Done!

[Overv]

The introduction contains

All of the tools we'll use, with the exception of the compiler, are compatible with both Windows and Linux, but the steps for installing them differ a bit, which is why they're described separately here.

That should mention MacOS as well.

This is a library that maps Vulkan to Apple's Metal graphics framework

I'd add a sentence making it explicit that there is no native support for Vulkan on MacOS, and that it can only be used through the translation layer offered by MoltenVK. Perhaps mention some limitations of this and things to consider.

all the projects should open on Xcode

in Xcode

avoid the horrors of X11

MacOS does not use X11, but rather APIs like Cocoa (this is in the GLFW section)

change the code on the generated main.cpp

"in the generated main.cpp" Also make clear that it's okay for the user to not understand the code and that it's only there for testing (see the other sections for reference)

the folder you clonned the MoltenVK project

cloned

Homebrew install libraries

installs libraries

It should look like so (obviously, paths will be different depending on where you placed on your files):

Could you upload a higher resolution screenshot and add a thumbnail in the chapter itself?

Now, on the General tab, on Linked Frameworks and Libraries

Now, in the General tab, in Linked Frameworks and Libraries

will need to add the following frameworks:

It would be nice to briefly cover why these are needed (e.g. UI frameworks)

remembering to setting

remembering to set

keep #include <vulkan/vulkan.h> instead of #define GLFW_INCLUDE_VULKAN

I think this may be the cause of how GLFW and the Vulkan SDK are setup on MacOS. Could you check with glfw/glfw#870 if there is a way to get GLFW_INCLUDE_VULKAN to work? Furthermore, is there a reason that you only include MoltenVK and not the full LunarG package for MacOS?

[github-felipe-caputo]

About some of your points:

It would be nice to briefly cover why these are needed (e.g. UI frameworks)

Honestly, I do not know the details myself. The list I made was based on GLFW docs (just not mentioning the OpenGL framework because that one is not necessary for this case) and the MoltenVK docs. I can definitely rewrite this part to mention this, but I myself do not know why certain frameworks are required (and the docs don't really hel much either).

I think this may be the cause of how GLFW and the Vulkan SDK are setup on MacOS. Could you check with glfw/glfw#870 if there is a way to get GLFW_INCLUDE_VULKAN to work? Furthermore, is there a reason that you only include MoltenVK and not the full LunarG package for MacOS?

There was actually no specific reason, I just sort of picked one and used it. But now, reading the documentation, it seems that maybe changing it do the LunarG would be better not only for the extra stuff the SDK includes, but also because it seems even easier to set it up on Xcode. And then maybe it will get GLFW_INCLUDE_VULKAN to work too, so it's worth a try.

I'll have some more time by the end of the week to check that stuff, and you other comments too.

[Overv]

Honestly, I do not know the details myself. The list I made was based on GLFW docs (just not mentioning the OpenGL framework because that one is not necessary for this case) and the MoltenVK docs. I can definitely rewrite this part to mention this, but I myself do not know why certain frameworks are required (and the docs don't really hel much either).

Sure, you don't have to cover all of them. Just summarizing as "IOSurface.framework, QuartzCore.framework and IOKit.framework handle the window UI and Metal.framework the interfacing with the Metal framework" would be fine.

I'll have some more time by the end of the week to check that stuff, and you other comments too.

Cool, there's no rush :)

[github-felipe-caputo]

Alright @Overv, finally had some thing to redo this thing.

I was able to get the whole LunarG SDK to work, instead of just using the MoltenVk package. In fact I believe using it made some things easier, less frameworks to set up. I changed a bit the way to do it, now I am using dynamic libs instead of static libs, which makes the whole setup easier.

I also changed how to get glfw for mac, the link you posted before was really helpful. The reason #define GLFW_INCLUDE_VULKAN was not working was because the most recent stable version of glfw still doesn't fully support macos so you have to install the latest version.

I think overall the instructions got a bit easier (or maybe I am just thinking that because after reading these documentations to get this thing to work I am much more familiar with Xcode now haha).

I have also updated some pictures. Check it out, tell me what you think.

[Overv]

Nice work, I'll look at it tomorrow :)

[Overv]

It's looking very good, just a few more comments. If you fix these, then I'll merge it 👍

as a layer that translate Vulkan API calls to Apple's Metal

translates

Run the cube executable and you will see the following:

You forgot the explanation mark to turn it into the image. It's just a link right now.

this is where Homebrew install headers

installs, same for the bullet point after that

[github-felipe-caputo]

Done.

[Overv]

It is now live, thanks for the awesome work!

[Overv]

@fvcaputo Could you look into this comment and see if some extra instructions could/should be added? https://vulkan-tutorial.com/Drawing_a_triangle/Graphics_pipeline_basics/Shader_modules#comment-4210582247