build(macos): make gz SITL work out-of-box after homebrew 4.5

The px4-sim / px4-sim-gazebo Homebrew meta-formulae can no longer
pull their Gazebo dependency chain because Homebrew 4.5+ stopped
auto-resolving cross-tap deps. PX4/homebrew-px4#104 already
deprecated px4-dev into a no-op; #111 does the same for the sim
formulae. This PR is the PX4-side counterpart: move the sim install
into Tools/setup/macos.sh with an explicit package list and tap
registration, mirroring the pattern already used for the toolchain
block. Adds xquartz install on --sim-tools.

Beyond install, three runtime and configure gaps kept make px4_sitl
gz_x500 from working on a clean macOS:

- gz-gui8 (pulled in by gz-sim8) links against Qt5, but Homebrew's
  qt@5 is keg-only so CMake cannot find it. Add a POSIX-scoped hint
  in platforms/posix/cmake/px4_impl_os.cmake that resolves
  brew --prefix qt@5 and appends it to CMAKE_PREFIX_PATH. No-ops on
  non-APPLE builds and respects a user-set Qt5_DIR.

- On macOS, dyld does not search /opt/homebrew/lib by default.
  gobject-introspection typelibs reference libs by bare basename,
  causing gst-plugin-scanner to fail to load plugins and adding
  ~90s of timeout to Gazebo's cold start. Set
  DYLD_FALLBACK_LIBRARY_PATH to the Homebrew prefix lib dir in
  gz_env.sh so the bridge launch inherits it. Darwin-scoped, no
  effect on Linux or CI.

- configure_file on gz_env.sh.in now uses @ONLY so shell ${VAR}
  references pass through untouched.

Verified locally on macOS 26.4 / arm64 / Homebrew 5.1.7: configure
clean, 1119/1119 targets compile and link, vehicle spawns in
Gazebo Harmonic 8.11.0 with a single "Waiting for Gazebo world"
wait (was ~18 before the dyld fix).

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

Tools/setup/macos.sh

@@ -6,11 +6,11 @@
 ## Installs:
 ##	- Common dependencies and tools for building PX4
 ##	- Cross compilers for building hardware targets using NuttX
-##	- Can also install the default simulation provided by the px4-sim homebrew
-##		Formula
+##	- With --sim-tools: Gazebo Harmonic and jMAVSim simulation stack
 ##
-## For more information regarding the Homebrew Formulas see:
-##		https://github.com/PX4/homebrew-px4/
+## Homebrew 4.5+ no longer auto-resolves cross-tap dependencies, so
+## every tap and package is listed explicitly here rather than hidden
+## behind meta-formulae. See PX4/homebrew-px4#104 for background.
 ##
 
 # script directory
@@ -97,10 +97,37 @@ fi
 
 # Optional, but recommended additional simulation tools:
 if [[ $INSTALL_SIM == "--sim-tools" ]]; then
-	if ! brew ls --versions px4-sim > /dev/null; then
-		brew install px4-sim
-	elif [[ $REINSTALL_FORMULAS == "--reinstall" ]]; then
-		brew reinstall px4-sim
+	# Simulation packages. This replaces the px4-sim / px4-sim-gazebo
+	# meta-formulae, which declared cross-tap dependencies that
+	# Homebrew 4.5+ no longer auto-resolves. Same migration pattern as
+	# the toolchain block above. See PX4/homebrew-px4#104 for the
+	# px4-dev precedent.
+	#
+	# osrf/simulation: gz-harmonic (Gazebo Harmonic meta-formula)
+	brew tap osrf/simulation
+
+	PX4_SIM_BREW_PACKAGES=(
+		exiftool
+		glog
+		graphviz
+		gstreamer
+		opencv
+		osrf/simulation/gz-harmonic
+		protobuf
+	)
+
+	if [[ $REINSTALL_FORMULAS == "--reinstall" ]]; then
+		echo "[macos.sh] Re-installing PX4 simulation dependencies"
+		brew reinstall "${PX4_SIM_BREW_PACKAGES[@]}"
+	else
+		echo "[macos.sh] Installing PX4 simulation dependencies"
+		brew install "${PX4_SIM_BREW_PACKAGES[@]}"
+	fi
+
+	# XQuartz is required for Gazebo GUI display on macOS.
+	if ! brew list --cask xquartz &> /dev/null; then
+		echo "[macos.sh] Installing XQuartz (required for Gazebo display)"
+		brew install --cask xquartz
 	fi
 
 	# jMAVSim requires a JDK (Java 17 LTS recommended)

platforms/posix/cmake/px4_impl_os.cmake

@@ -31,6 +31,24 @@
 #
 ############################################################################
 
+# Homebrew's qt@5 is keg-only on macOS. gz-gui8 (pulled in by gz-sim8
+# from the Gazebo simulation modules) links against Qt5 and CMake
+# cannot locate it without a prefix hint. This file is included early
+# from the root CMakeLists.txt, before any add_subdirectory descends
+# into find_package(gz-sim8). Only runs when the user has not already
+# set Qt5_DIR.
+if(APPLE AND NOT DEFINED Qt5_DIR)
+	execute_process(
+		COMMAND brew --prefix qt@5
+		OUTPUT_VARIABLE _brew_qt5_prefix
+		OUTPUT_STRIP_TRAILING_WHITESPACE
+		ERROR_QUIET
+	)
+	if(_brew_qt5_prefix AND EXISTS "${_brew_qt5_prefix}/lib/cmake/Qt5")
+		list(APPEND CMAKE_PREFIX_PATH "${_brew_qt5_prefix}")
+	endif()
+endif()
+
 #=============================================================================
 #
 #	Defined functions in this file

src/modules/simulation/gz_bridge/CMakeLists.txt

@@ -121,7 +121,9 @@ if (gz-transport_FOUND)
 	endforeach()
 
 	# Setup the environment variables: PX4_GZ_MODELS, PX4_GZ_WORLDS, GZ_SIM_RESOURCE_PATH
-	configure_file(gz_env.sh.in ${PX4_BINARY_DIR}/rootfs/gz_env.sh)
+	# @ONLY disables ${VAR} substitution so that shell $VAR references in the
+	# template are passed through untouched.
+	configure_file(gz_env.sh.in ${PX4_BINARY_DIR}/rootfs/gz_env.sh @ONLY)
 
 else()
 	# Create fallback targets that provide helpful error messages when Gazebo dependencies are missing

src/modules/simulation/gz_bridge/gz_env.sh.in

@@ -19,3 +19,15 @@ export PX4_GZ_SERVER_CONFIG=@PX4_SOURCE_DIR@/src/modules/simulation/gz_bridge/se
 export GZ_SIM_RESOURCE_PATH=$GZ_SIM_RESOURCE_PATH:$PX4_GZ_MODELS:$PX4_GZ_WORLDS
 export GZ_SIM_SYSTEM_PLUGIN_PATH=$GZ_SIM_SYSTEM_PLUGIN_PATH:$PX4_GZ_PLUGINS
 export GZ_SIM_SERVER_CONFIG_PATH=$PX4_GZ_SERVER_CONFIG
+
+# macOS: dyld does not search /opt/homebrew/lib by default. Many
+# gobject-introspection typelibs reference libs by bare basename,
+# which fails to resolve unless we add Homebrew's lib dir to the
+# fallback search path. Prepend so it beats any system-placed libs,
+# and preserve any existing value the user has set.
+if [ "$(uname)" = "Darwin" ]; then
+	HOMEBREW_PREFIX=${HOMEBREW_PREFIX:-$(brew --prefix 2>/dev/null)}
+	if [ -n "$HOMEBREW_PREFIX" ]; then
+		export DYLD_FALLBACK_LIBRARY_PATH="$HOMEBREW_PREFIX/lib:${DYLD_FALLBACK_LIBRARY_PATH}"
+	fi
+fi