[docs] Update MacOS build instructions

BUILD.macOS.md

@@ -16,24 +16,28 @@ Avoid the version of cmake supplied, we need a newer one (see later).
 
 ### Qt6
 
-#### Option 1: Using Qt official sources
+#### Installing Qt 6.2.4 using aqtinstall (recommended)
 
-Install the latest stable version of Qt6 LTS (6.2.4 at the moment): <http://www.qt.io/download-open-source/>.
+Install aqtinstall and use it to download Qt 6.2.4:
 
-If it tells you that XCode 5.0.0 needs to be installed, go to XCode > Preferences > Locations and make a selection in
-the _Command Line Tools_ box.
+    brew install aqtinstall
+    aqt install-qt mac desktop 6.2.4 --outputdir ~/Qt
 
-Add Qt6 to your PATH environment variable, adding to your `.bash_profile` file the following line:
-
-    export PATH=$PATH:~/Qt/6.2.4/clang_64/bin
+This will install Qt 6.2.4 to `~/Qt/6.2.4/macos`.
 
 Adjust accordingly if you customized the Qt install directory.
 
-#### Option 2: Using Homebrew
+### CocoaPods
+
+CocoaPods is required to build the Flutter GUI
+
+    sudo gem install cocoapods
+
+You may need to update your version of Ruby first. You can do so with RVM:
 
-Install Qt6:
+    rvm install 3.1.0 && rvm --default use 3.1.0
 
-    brew install qt6
+**Important: RVM/Ruby may require OpenSSL v1, while building Multipass requires OpenSSL v3. Make sure to switch to the right version of OpenSSL as necessary with `brew link`**
 
 ### Cmake/OpenSSL
 
@@ -45,47 +49,73 @@ means to obtain these dependencies is with Homebrew <https://brew.sh/>.
 Building
 ---------------------------------------
 
-    cd <multipass>
-    git submodule update --init --recursive
+### Additional configuration
+
+If you encounter errors about missing `pkg-config` or `ninja`, install them with:
+
+    brew install pkg-config ninja
+
+This is required for CMake to find all necessary build tools and dependencies.
+
+#### Dylibbundler
+
+Dylibbundler is required to make Multipass packages:
+
+    brew install dylibbundler
+
+#### QEMU Configuration
+
+QEMU is required to build the Multipass tests:
+
+    brew install qemu
 
-To build with official Qt sources do:
+If you encounter Python errors about missing `tomli` during the QEMU build step, install it with:
 
-    cmake -Bbuild -H. -GNinja -DCMAKE_PREFIX_PATH=~/Qt/6.2.4/clang_64
+    pip3 install tomli
 
-Alternatively if using Qt6 from Homebrew, do
+This is required for Python-based build scripts.
 
-    cmake -Bbuild -H. -GNinja -DCMAKE_PREFIX_PATH=/usr/local/opt/qt6
+You may need additional libraries and packages during the configuration process:
 
-or, if on Apple silicon, brew will store the Qt binaries in a different location. Additionally, OpenSSL will be in a
-similar location; `/opt/homebrew/Cellar/openssl@3`, which can be set in the project level `CMakeLists.txt` file.
+    brew install glib pixman
 
-    cmake -Bbuild -H. -GNinja -DCMAKE_PREFIX_PATH=/opt/homebrew/opt/qt6
+#### Xcode setup
+
+After installing Xcode, you may need to configure the command line tools and complete the initial setup:
+
+    sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
+    sudo xcodebuild -runFirstLaunch
+
+The first command sets the active developer directory to your Xcode installation. This is necessary when xcodebuild is not found in the PATH or when there are multiple Xcode installations.
+
+The second command runs Xcode's first launch setup, which installs additional components and tools required for building iOS and macOS applications. This may be needed if you encounter errors about missing Xcode tools or frameworks during the build process.
+
+### Install Submodules
+
+    cd <multipass>
+    git submodule update --init --recursive
+
+### Build Multipass
+
+To build with Qt installed via aqtinstall:
+
+    cmake -Bbuild -H. -GNinja -DCMAKE_PREFIX_PATH=~/Qt/6.2.4/macos/bin
 
 Then start the build with:
 
     cd build/
-    ninja
+    cmake --build .
 
 Take care to adjust the `CMAKE_PREFIX_PATH` to the location you installed Qt above, or else cmake will complain about
 missing Qt6.
 
-Building in QtCreator
----------------------
-QtCreator will be missing all the environment adjustments made above. To get cmake to successfully configure, open the
-project and adjust the Build Environment (click the "Projects" icon of the left pane, scroll down). Then add the entries
-to the $PATH as above, and add the variables reported by `opem config env`. CMake should now succeed, and QtCreator
-allow you to edit the project files.
-
-
 Creating a Package
 ------------------
 This is as simple as running
 
-    ninja package
-
-or
+    cmake --build . --target package
 
-    cpack
+Make sure you have dylibbundler installed!
 
 Once it is complete, you will have a Multipass.pkg file in the build directory.