From ae082551b3dbd59d40c8d11085b864fbaf2a075d Mon Sep 17 00:00:00 2001
From: robkohr <spam@robkohr.com>
Date: Fri, 14 Nov 2025 10:27:01 -0800
Subject: [PATCH] update macos compiling and distribution instructions

---
 guides/Compiling.md    | 40 ++++++++++++++++++++++++++++------------
 guides/Distribution.md |  7 +++++++
 2 files changed, 35 insertions(+), 12 deletions(-)

diff --git a/guides/Compiling.md b/guides/Compiling.md
index 1d9e7402..6838f9d3 100644
--- a/guides/Compiling.md
+++ b/guides/Compiling.md
@@ -61,30 +61,46 @@ via the command line as `lovr.exe path/to/project`.
 macOS
 ---
 
-Build using CMake, as above:
+### Installing Dependencies
+
+LÖVR on MacOS requires MoltenVK 1.3.268 or higher. You can install it using either method:
+
+**Option 1: Homebrew (Recommended)**
+    $ brew install vulkan-loader molten-vk
+
+**Option 2: Vulkan SDK**
+Install the Vulkan SDK from [LunarG](https://vulkan.lunarg.com/). Be sure to leave the "global install" checkbox enabled while installing so LÖVR is able to find the Vulkan library.
+
+Prebuilt binaries include MoltenVK in the .app bundle, so installing the Vulkan SDK is optional when using one of those builds.
+
+### Building
+
+Build using CMake:
 
     $ mkdir build
     $ cd build
     $ cmake ..
     $ cmake --build .
 
-The lovr executable should exist in `lovr/build/bin` now.  It's recommended to set up an alias or
-symlink so that this executable can be found in your PATH environment variable.  Once that's done,
-you can run a project like this:
+The lovr executable should exist in `lovr/build/bin` now.
+
+### Running
+
+If you installed Vulkan via Homebrew, you may need to set the library path:
+
+    $ export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH
+    $ ./build/bin/lovr /path/to/myGame
 
-    $ lovr /path/to/myGame
+It's recommended to set up an alias or symlink so that this executable can be found in your PATH environment variable.
 
 :::note
-You can set the `LOVR_BUILD_BUNDLE` CMake variable to `ON` to build a .app instead of a plain
-executable.
+You can set the `LOVR_BUILD_BUNDLE` CMake variable to `ON` to build a .app instead of a plain executable.
 :::
 
-LÖVR requires MoltenVK 1.3.268 or higher.  The easiest way to get MoltenVK is to install the Vulkan
-SDK from LunarG.  Be sure to leave the "global install" checkbox enabled while installing so LÖVR is
-able to find the Vulkan library.
+### Troubleshooting
 
-Prebuilt binaries include MoltenVK in the .app bundle, so installing the Vulkan SDK is optional when
-using one of those builds.
+- If LÖVR starts but no window appears, check that Vulkan/MoltenVK is properly installed and the library path is set correctly.
+- If you get "Failed to load vulkan library" errors, ensure `DYLD_LIBRARY_PATH` includes the path to your Vulkan libraries (e.g., `/opt/homebrew/lib` for Homebrew installations).
 
 Linux
 ---
diff --git a/guides/Distribution.md b/guides/Distribution.md
index c4473bf2..8c22b8ca 100644
--- a/guides/Distribution.md
+++ b/guides/Distribution.md
@@ -42,6 +42,13 @@ To create a .app on macOS, first get the stock LÖVR.app, either by downloading
 [here](https://lovr.org/download/mac) or by setting the `-DLOVR_BUILD_BUNDLE=ON` flag when building
 with CMake.
 
+:::note
+If you build your own .app bundle, you may need to bundle MoltenVK and Vulkan libraries for
+distribution. Prebuilt binaries include these libraries, but custom builds require them to be added
+manually. The libraries should be placed in `YourApp.app/Contents/Frameworks/` as `libvulkan.1.dylib`
+and `libMoltenVK.dylib`. See the `Compiling` guide for more information about Vulkan installation.
+:::
+
 Then, to get the .app to run a custom project instead of the nogame screen, put a .lovr archive in
 the `LÖVR.app/Contents/Resources` folder (right click and use "Show Package Contents" to get to the
 Contents folder).