doc: Update macOS build instructions.

doc/build_instructions/macos.md

@@ -6,14 +6,10 @@
 
 ```
 brew update-reset && brew update
-brew tap homebrew/cask-fonts
-brew install font-dejavu
+brew install --cask font-dejavu
 brew install cmake python3 libepoxy freetype fontconfig harfbuzz opus opusfile qt6 libogg libpng toml11 eigen
 brew install llvm
-pip3 install cython numpy mako lz4 pillow pygments toml
-
-# optional, for documentation generation
-brew install doxygen
+pip3 install --upgrade --break-system-packages cython numpy mako lz4 pillow pygments setuptools toml
 ```
 
 You will also need [nyan](https://github.com/SFTtech/nyan/blob/master/doc/building.md) and its dependencies:
@@ -22,16 +18,33 @@ You will also need [nyan](https://github.com/SFTtech/nyan/blob/master/doc/buildi
 brew install flex make
 ```
 
+Optionally, for documentation generation:
+
+```
+brew install doxygen
+```
+
 ## Clone the repository
+
 ```
 git clone https://github.com/SFTtech/openage
 cd openage
 ```
 
 ## Building
 
+We advise against using the clang version that comes with macOS (Apple Clang) as it notoriously out of date and often causes compilation errors. Use homebrew's clang if you don't want any trouble. You can pass the path of homebrew clang to the openage `configure` script which will generate the CMake files for building:
+
+```
+# on Intel macOS, llvm is by default in /usr/local/Cellar/llvm/bin/
+# on ARM macOS, llvm is by default in /opt/homebrew/Cellar/llvm/bin/
+CLANG_PATH="<homebrew llvm install path>/bin/clang++"
+./configure --compiler="$CLANG_PATH" --download-nyan
+```
+
+Afterwards, trigger the build using `make`:
+
 ```
-./configure --compiler=$(which clang++) --mode=release --download-nyan
 make -j$(sysctl -n hw.ncpu)
 ```
 
@@ -40,7 +53,7 @@ make -j$(sysctl -n hw.ncpu)
 
 
 ## Running
-`make run` or `./bin/run` launches the game. Try `./bin/run --help`!
+`make run` or `cd bin && ./run` launches the game. Try `./run --help` if you don't know what to do!
 
 
 ## To create the documentation