Update macOS instructions

.github/workflows/macosx-ci.yml

@@ -5,7 +5,7 @@ jobs:
   # https://docs.github.com/en/actions/reference/software-installed-on-github-hosted-runners
   # we install stuff not already there
   macos-build:
-    runs-on: macOS-latest
+    runs-on: macos-latest
     steps:
       - name: Checkout sources
         uses: actions/checkout@v4
@@ -19,7 +19,7 @@ jobs:
           string(TIMESTAMP current_date "%Y-%m-%d-%H:%M:%S" UTC)
           message("timestamp=${current_date}" >> $GITHUB_OUTPUT)
       - name: Cache dependencies
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         id: cache-deps
         with:
           path: |
@@ -29,7 +29,7 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-deps-
       - name: Cache ccache dir
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         id: cache-ccache
         with:
           path: ~/Library/Caches/ccache
@@ -40,26 +40,14 @@ jobs:
         run: brew update-reset
       - name: Brew update
         run: brew update
-      - name: Install clang / LLVM 15.0.0
-        run: |
-          set -x
-          brew install --force wget
-          mkdir -p /tmp/clang
-          cd /tmp/clang
-          wget https://github.com/llvm/llvm-project/releases/download/llvmorg-15.0.0/clang+llvm-15.0.0-x86_64-apple-darwin.tar.xz -O clang-15.0.0.tar.xz
-          ls
-          tar -xvf clang-15.0.0.tar.xz -C ~
-          cd ~
-          mv clang+llvm-15.0.0-x86_64-apple-darwin clang-15.0.0
-          ~/clang-15.0.0/bin/clang++ --version
       - name: Brew install DeJaVu fonts
         run: brew install --cask font-dejavu
-      - name: Remove python's 2to3 link so that 'brew link' does not fail
-        run: rm /usr/local/bin/2to3* && rm /usr/local/bin/idle3*
       - name: Install environment helpers with homebrew
         run: brew install --force ccache
-      - name: Install dependencies with homebrew
-        run: brew install --force libepoxy freetype fontconfig harfbuzz opus opusfile qt6 libogg libpng toml11 eigen
+      - name: Install LLVM with homebrew
+        run: brew install --force llvm
+      - name: Install openage dependencies with homebrew
+        run: brew install --force cmake python3 libepoxy freetype fontconfig harfbuzz opus opusfile qt6 libogg libpng toml11 eigen
       - name: Install nyan dependencies with homebrew
         run: brew install --force flex make
       - name: Install python3 packages
@@ -68,9 +56,7 @@ jobs:
         # numpy pulls gcc as dep? and pygments doesn't work.
         run: pip3 install --upgrade --break-system-packages cython numpy mako lz4 pillow pygments setuptools toml
       - name: Configure
-        run: |
-          CLANG_PATH="$HOME/clang-15.0.0/bin/clang++"
-          ./configure --compiler="$CLANG_PATH" --mode=debug --ccache --download-nyan
+        run: ./configure --compiler="$(brew --prefix llvm)/bin/clang++" --mode=release --ccache --download-nyan
       - name: Build
         run: make -j$(sysctl -n hw.logicalcpu) VERBOSE=1
       - name: Test

.github/workflows/ubuntu-22.04.yml

@@ -16,7 +16,7 @@ jobs:
         sudo docker save openage-devenv:latest | gzip > /tmp/staging/devenv.tar.gz
       shell: bash
     - name: Publish the Docker image
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: devenv-image-compressed.tar.gz
         path: '/tmp/staging/devenv.tar.gz'
@@ -32,7 +32,7 @@ jobs:
       run: mkdir -p /tmp/image
       shell: bash
     - name: Download devenv image
-      uses: actions/download-artifact@v3
+      uses: actions/download-artifact@v4
       with:
         name: devenv-image-compressed.tar.gz
         path: '/tmp/image'
@@ -47,7 +47,7 @@ jobs:
         mkdir -p /tmp/openage
         tar -czvf /tmp/openage/openage-build.tar.gz ./build
     - name: Publish build artifacts
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: openage-build.tar.gz
         path: '/tmp/openage/openage-build.tar.gz'

.github/workflows/windows-server-2019.yml

@@ -15,7 +15,7 @@ jobs:
         vswhere -latest
       shell: pwsh
     - name: Setup Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: '3.9'
         architecture: 'x64'
@@ -78,15 +78,15 @@ jobs:
         python -m openage --add-dll-search-path $DLL_PATH --version
       shell: pwsh
     - name: Publish build artifacts
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       if: ${{ always() }}
       with:
         name: build-files
         path: './build'
         if-no-files-found: error
         retention-days: 30
     - name: Publish packaged artifacts
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       if: ${{ always() }}
       with:
         name: package-files

.github/workflows/windows-server-2022.yml

@@ -15,7 +15,7 @@ jobs:
         vswhere -latest
       shell: pwsh
     - name: Setup Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: '3.9'
         architecture: 'x64'
@@ -78,15 +78,15 @@ jobs:
         python -m openage --add-dll-search-path $DLL_PATH --version
       shell: pwsh
     - name: Publish build artifacts
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       if: ${{ always() }}
       with:
         name: build-files
         path: './build'
         if-no-files-found: error
         retention-days: 30
     - name: Publish packaged artifacts
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       if: ${{ always() }}
       with:
         name: package-files

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,32 @@ 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/
+./configure --compiler="$(brew --prefix llvm)/bin/clang"" --download-nyan
+```
+
+Afterwards, trigger the build using `make`:
+
 ```
-./configure --compiler=$(which clang++) --mode=release --download-nyan
 make -j$(sysctl -n hw.ncpu)
 ```
 
@@ -40,7 +52,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