AcademySoftwareFoundation · OlafRocket · Sep 2, 2026
diff --git a/cmake/macros.cmake b/cmake/macros.cmake
@@ -105,7 +105,10 @@ macro(default_options_local name)
 		set_target_properties(${name}
 			PROPERTIES
 			LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/xSTUDIO.app/Contents/Frameworks"
+			INSTALL_NAME_DIR "@rpath"
+			BUILD_WITH_INSTALL_NAME_DIR TRUE
 			INSTALL_RPATH "@executable_path/../Frameworks"
+			BUILD_RPATH   "@executable_path/../Frameworks"
 			INSTALL_RPATH_USE_LINK_PATH TRUE
 		)
 	elseif(UNIX)

diff --git a/docs/reference/build_guides/macos.md b/docs/reference/build_guides/macos.md
@@ -73,3 +73,19 @@ When this has finished, you can build xSTUDIO with:
 RelWithDebInfo and Debug variants are also available — see [CMakePresets.json](../../../CMakePresets.json) for the full list.
 
 If the build is successful, you should have an application bundle in the 'build' folder called 'xSTUDIO.app'. This can be drag & dropped into your applications folder, desktop and dock as for any other application.
+
+### Fast iteration on source changes
+
+The `install` target above runs `macdeployqt` and copies documentation, preferences, and Python dependencies into the bundle. On a warm bundle this takes several minutes even when nothing has changed. Once you have done it at least once, incremental rebuilds do not need to repeat it, because the compiled binaries are linked directly into `build/xSTUDIO.app/Contents/`.
+
+For iteration on C++ / QML source changes, use:
+
+    cmake --build build
+
+and re-launch `build/xSTUDIO.app`. A single-file relink completes in seconds instead of minutes.
+
+You should re-run `cmake --build build --target install` when:
+
+- files under `share/docs`, `share/preference`, `share/snippets`, or `share/fonts` change,
+- a new dynamic library or plugin is added that `macdeployqt` needs to discover,
+- the Qt SDK is upgraded and the copied frameworks in the bundle need refreshing.
diff --git a/src/global/src/CMakeLists.txt b/src/global/src/CMakeLists.txt
@@ -57,12 +57,4 @@ if(UNIX AND NOT APPLE)
     target_link_libraries(${PROJECT_NAME} PRIVATE asound)  # Link against asound on Linux
 endif()
 
-if(APPLE)
-    set_target_properties(${PROJECT_NAME} PROPERTIES
-        LINK_DEPENDS_NO_SHARED true
-        INSTALL_RPATH "@executable_path/../Frameworks"
-        BUILD_WITH_INSTALL_RPATH TRUE
-    )
-else()
-    set_target_properties(${PROJECT_NAME} PROPERTIES LINK_DEPENDS_NO_SHARED true)
-endif()
+set_target_properties(${PROJECT_NAME} PROPERTIES LINK_DEPENDS_NO_SHARED true)
diff --git a/src/launch/xstudio/src/CMakeLists.txt b/src/launch/xstudio/src/CMakeLists.txt
@@ -125,6 +125,8 @@ elseif(APPLE)
 		RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/xSTUDIO.app/Contents/MacOS"
 		OUTPUT_NAME "${PROJECT_NAME}.bin"
 		LINK_DEPENDS_NO_SHARED true
+		INSTALL_RPATH "@executable_path/../Frameworks"
+		BUILD_RPATH   "@executable_path/../Frameworks"
 	)
 
 	add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
@@ -150,12 +152,6 @@ elseif(APPLE)
         configure_file(macdeploy.cmake.in ${CMAKE_CURRENT_BINARY_DIR}/macdeploy.cmake @ONLY)
     install(SCRIPT ${CMAKE_CURRENT_BINARY_DIR}/macdeploy.cmake)
 
-    # Add custom command to fix library paths after build
-    add_custom_command(TARGET ${PROJECT_NAME} POST_BUILD
-        COMMAND ${CMAKE_COMMAND} -DAPP_BUNDLE_DIR=${CMAKE_BINARY_DIR}/xSTUDIO.app
-            -P ${CMAKE_CURRENT_SOURCE_DIR}/fixup_macos_bundle.cmake
-    )
-
 else()
 
 	set_target_properties(${PROJECT_NAME}

diff --git a/src/launch/xstudio/src/fixup_macos_bundle.cmake b/src/launch/xstudio/src/fixup_macos_bundle.cmake
diff --git a/src/launch/xstudio/src/macdeploy.cmake.in b/src/launch/xstudio/src/macdeploy.cmake.in
@@ -2,25 +2,10 @@
 # This command manipulates the rpath in ffmpeg so it can find the ffmpeg libs in the Frameworks
 # folder in the app bundle
 execute_process(COMMAND install_name_tool ${CMAKE_BINARY_DIR}/xSTUDIO.app/Contents/MacOS/ffmpeg -rpath @loader_path/../../lib @loader_path/../Frameworks WORKING_DIRECTORY "${CMAKE_INSTALL_PREFIX}")
-    
+
 # macdeployqt finds xSTUDIO's library dependencies and adds them to the app bundle, as well as
-# making necessary rpath manipulations
-message("Running @macdeployqt_exe@ with args: ${CMAKE_BINARY_DIR}/xSTUDIO.app -qmldir=@CMAKE_SOURCE_DIR@/ui")
-execute_process(COMMAND "@macdeployqt_exe@" ${CMAKE_BINARY_DIR}/xSTUDIO.app -qmldir=@CMAKE_SOURCE_DIR@/ui
+# making necessary rpath manipulations. -always-overwrite forces a fresh deploy so that a
+# stale bundle from a prior install cannot leave frameworks unsigned.
+message("Running @macdeployqt_exe@ with args: ${CMAKE_BINARY_DIR}/xSTUDIO.app -qmldir=@CMAKE_SOURCE_DIR@/ui -always-overwrite")
+execute_process(COMMAND "@macdeployqt_exe@" ${CMAKE_BINARY_DIR}/xSTUDIO.app -qmldir=@CMAKE_SOURCE_DIR@/ui -always-overwrite
     WORKING_DIRECTORY "${CMAKE_INSTALL_PREFIX}")
-
-# Fix library paths to ensure they're relative to the bundle
-execute_process(
-    COMMAND
-    install_name_tool -id
-    "@rpath/libglobal.dylib"
-    ${CMAKE_BINARY_DIR}/xSTUDIO.app/Contents/Frameworks/libglobal.dylib
-)
-execute_process(
-    COMMAND
-    install_name_tool
-    -change
-    "@rpath/libglobal.dylib"
-    "@executable_path/../Frameworks/libglobal.dylib"
-    ${CMAKE_BINARY_DIR}/xSTUDIO.app/Contents/MacOS/xstudio.bin
-)