Build system improvements: OTIO vcpkg overlay migration, general fixes, cross-platform docs (#246)

* Build system improvements: OTIO vcpkg migration, Windows fixes, cross-platform docs

Core build system
-----------------
- Migrate OpenTimelineIO from git submodule to vcpkg overlay port
  (cmake/vcpkg_overlay_ports/opentimelineio/). Removes extern/otio,
  .gitmodules, cmake/otio_patch.diff, and the OTIO_SUBMODULE option.
- OTIO portfile: on Windows, move .dll files from lib/ to bin/ (vcpkg
  convention for applocal.ps1 discovery) and rewrite generated
  Targets-*.cmake files so IMPORTED_LOCATION resolves correctly.
- Pin python3 to 3.11.11 in vcpkg.json.
- Lower CMake minimum from 3.28 to 3.26 for broader distro compatibility.
- Work around Qt 6.5/6.8 FindWrapOpenGL.cmake AGL bug on macOS by
  pre-creating WrapOpenGL::WrapOpenGL so Qt's find-module early-returns.
  Fixed upstream in Qt 6.9+; workaround can be removed once minimum
  supported Qt >= 6.9.

CMakePresets
------------
- Remove hardcoded Qt6_DIR from the default preset. Users now supply it
  via the Qt6_DIR environment variable, a CMakeUserPresets.json, or a
  one-off -D flag (documented in each build guide).
- Add VCPKG_OVERLAY_PORTS path so the new OTIO overlay is picked up.
- Add Ninja generator presets for macOS (arm / intel) and Linux — Release,
  RelWithDebInfo and Debug variants. Aligns with existing Windows Ninja
  presets.
- Un-hide WinDebug preset.
- Add VCPKG_OVERLAY_TRIPLETS to the Linux base preset.

Windows build fixes
-------------------
- Fix scripts/qt_install to use install(SCRIPT) + configure_file instead
  of install(CODE), so ${CMAKE_INSTALL_PREFIX} resolves at install time.
  Previously the configure-time prefix was baked in, which broke the
  CPack package target because CPack uses a different (staging) prefix.
- Remove the redundant early windeployqt call in src/launch/xstudio/src.
  The late call in scripts/qt_install now covers everything and runs
  after all other install rules have populated the install tree.
- In cmake/macros.cmake (default_options_qt), add RUNTIME_OUTPUT_DIRECTORY
  alongside LIBRARY_OUTPUT_DIRECTORY so *_qml.dll files land in build/bin
  on Windows (Windows uses RUNTIME for .dll, not LIBRARY).
- Fix Windows python install path mismatch in python/CMakeLists.txt:
  the build produces lib/python3.11/site-packages (Unix layout, because
  vcpkg's Python uses that layout on Windows), not Lib/site-packages.

Dev workflow
------------
- Generate build/run_xstudio.bat — a dev launcher that puts Qt's bin
  directory on PATH and forwards arguments to xstudio.exe, so xstudio
  can be run straight from the build tree without a windeployqt pass.

Documentation
-------------
- downloading_qt.md: add aqtinstall instructions (command-line, no Qt
  account required) as a recommended alternative to the GUI installer.
  Covers Linux, macOS and Windows.
- index.rst: add "Choosing a guide" section explaining the split between
  vcpkg-based guides (recommended) and distro-native guides (advanced).
- linux_generic.md: restructured around the new Qt6_DIR / user-preset
  workflow, removed submodule instructions, added optional Ninja section.
- macos.md: minor updates to reflect current dependency list and Qt
  workaround now handled in CMakeLists.txt.
- windows.md: full rewrite — unified "Set up the build environment"
  section using Enter-VsDevShell with -SkipAutomaticLocation, separate
  build sections for Visual Studio and Ninja generators, corrected Qt
  path example (C:/Qt not C:/Qt6), user-preset examples for both
  generators, note on run_xstudio.bat dev launcher.

Signed-off-by: Olaf Razzoli <olaf.razzoli@gmail.com>

* docs: simplify build guides and pin vcpkg

- Require Ninja as the CMake generator on all platforms; remove the
  "Faster builds with Ninja (optional)" sections and the Visual Studio
  generator option on Windows.
- Pin vcpkg to commit c2aeddd80357b17592e59ad965d2adf65a19b22f in all
  three guides for reproducible dependency builds.
- Document CMakeUserPresets.json as the single way to point CMake at
  the local Qt 6.5.3 install; drop the Qt6_DIR env-var and one-off
  -DQt6_DIR command-line paths.
- Note that --target package on Windows is slow and recommend a plain
  cmake --build build for dev iteration.
- Remove docs/reference/build_guides/developer_tips.md and the link
  to it from windows.md.

Signed-off-by: Olaf Razzoli <olaf.razzoli@gmail.com>

---------

Signed-off-by: Olaf Razzoli <olaf.razzoli@gmail.com>
Signed-off-by: Ted Waine <ted.waine@gmail.com>

Author: OlafRocket

.gitignore

@@ -14,9 +14,7 @@ python/src/xstudio/version.py
 /build/
 xstudio_install/
 **/qml/*_qml_export.h
-<<<<<<< HEAD
 CMakeUserPresets.json
-=======
 __build
 __build_debug
->>>>>>> c808bb352 (WIP)
+aqtinstall.log

.gitmodules

@@ -1,5 +1,7 @@
-cmake_minimum_required(VERSION 3.28 FATAL_ERROR)
-cmake_policy(VERSION 3.28)
+cmake_minimum_required(VERSION 3.26 FATAL_ERROR)
+cmake_policy(VERSION 3.26)
+#cmake_minimum_required(VERSION 3.28 FATAL_ERROR)
+#cmake_policy(VERSION 3.28)
 
 set(XSTUDIO_GLOBAL_VERSION "1.2.0" CACHE STRING "Version string")
 set(XSTUDIO_GLOBAL_NAME xStudio)
@@ -8,6 +10,17 @@ set(XSTUDIO_GLOBAL_NAME xStudio)
 
 project(${XSTUDIO_GLOBAL_NAME} VERSION ${XSTUDIO_GLOBAL_VERSION} LANGUAGES CXX)
 
+# Work around Qt bug: FindWrapOpenGL.cmake links -framework AGL, which was
+# removed from the macOS SDK in 10.14. Fixed upstream in Qt 6.9+ but not
+# backported to 6.5/6.8 LTS (see https://codereview.qt-project.org/c/qt/qtbase/+/652022).
+# Pre-create the target so Qt's FindWrapOpenGL early-returns and never hits the
+# broken AGL block. Can be removed once the minimum supported Qt is >= 6.9.
+if(APPLE AND NOT TARGET WrapOpenGL::WrapOpenGL)
+    find_package(OpenGL REQUIRED)
+    add_library(WrapOpenGL::WrapOpenGL INTERFACE IMPORTED)
+    target_link_libraries(WrapOpenGL::WrapOpenGL INTERFACE OpenGL::GL)
+endif()
+
 option(BUILD_TESTING "Build tests" OFF)
 option(INSTALL_PYTHON_MODULE "Install python module" ON)
 option(INSTALL_XSTUDIO "Install xstudio" ON)
@@ -16,7 +29,6 @@ option(ENABLE_CLANG_TIDY "Enable clang-tidy, ninja clang-tidy." OFF)
 option(ENABLE_CLANG_FORMAT "Enable clang format, ninja clangformat." OFF)
 option(FORCE_COLORED_OUTPUT "Always produce ANSI-colored output (GNU/Clang only)." TRUE)
 option(OPTIMIZE_FOR_NATIVE "Build with -march=native" OFF)
-option(OTIO_SUBMODULE "Automatically build OpenTimelineIO as a submodule" OFF)
 option(USE_VCPKG "Use Vcpkg for package management" OFF)
 option(BUILD_PYSIDE_WIDGETS "Build xstudio player as PySide widget" OFF)
 option(OPENIMAGEIO_PLUGIN "Include the OpenImageIO PLugin" ON)
@@ -188,10 +200,6 @@ endif()
 
 if (USE_VCPKG)
 
-  # When building with VCPKG, we will use OTIO submodule
-  set(OTIO_SUBMODULE true)
-  add_subdirectory("extern/otio")
-
   set(VCPKG_INTEGRATION ON)
 
   # Install pip and sphinx
@@ -218,14 +226,12 @@ if (USE_VCPKG)
 
 else()
   list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules")
-  if(${OTIO_SUBMODULE})
-	  add_subdirectory("extern/otio")
-  endif()
  	find_package(PkgConfig REQUIRED)
 endif()
 
 # Add the necessary libraries from Vcpkg if Vcpkg integration is enabled
 
+find_package(OpenTimelineIO CONFIG REQUIRED)
 find_package(nlohmann_json CONFIG REQUIRED)
 include(CTest)
 

CMakeLists.txt

@@ -7,13 +7,13 @@
       "binaryDir": "${sourceDir}/build",
       "cacheVariables": {
         "CMAKE_TOOLCHAIN_FILE": "${sourceDir}/../vcpkg/scripts/buildsystems/vcpkg.cmake",
-        "Qt6_DIR": "/Users/tedwaine/Qt6/6.5.3/macos/lib/cmake/Qt6",
         "CMAKE_INSTALL_PREFIX": "xstudio_install",
         "X_VCPKG_APPLOCAL_DEPS_INSTALL": "ON",
         "BUILD_DOCS": "OFF",
         "USE_VCPKG": "ON",
         "STUDIO_PLUGINS": "",
-        "BMD_DECKLINK_PLUGIN": "OFF"
+        "BMD_DECKLINK_PLUGIN": "OFF",
+        "VCPKG_OVERLAY_PORTS": "${sourceDir}/cmake/vcpkg_overlay_ports"
       }
     },
     { 
@@ -44,7 +44,6 @@
     },
     {
       "name": "WinDebug",
-      "hidden":  true,
       "inherits": ["windows-base"],
       "cacheVariables": {
         "CMAKE_BUILD_TYPE": "Debug",
@@ -151,10 +150,67 @@
         "USE_SANITIZER": "address"
       }
     },
-    { 
+    {
+      "name": "macos-ninja-base-arm",
+      "inherits": "macos-base-arm",
+      "generator": "Ninja"
+    },
+    {
+      "name": "macos-ninja-base-intel",
+      "inherits": "macos-base-intel",
+      "generator": "Ninja"
+    },
+    {
+      "name": "MacOSNinjaRelease",
+      "inherits": ["macos-ninja-base-arm"],
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release"
+      }
+    },
+    {
+      "name": "MacOSNinjaRelWithDebInfo",
+      "inherits": ["macos-ninja-base-arm"],
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+        "USE_SANITIZER": "address"
+      }
+    },
+    {
+      "name": "MacOSNinjaDebug",
+      "inherits": ["macos-ninja-base-arm"],
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "USE_SANITIZER": "address"
+      }
+    },
+    {
+      "name": "MacOSIntelNinjaRelease",
+      "inherits": ["macos-ninja-base-intel"],
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release"
+      }
+    },
+    {
+      "name": "MacOSIntelNinjaRelWithDebInfo",
+      "inherits": ["macos-ninja-base-intel"],
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+        "USE_SANITIZER": "address"
+      }
+    },
+    {
+      "name": "MacOSIntelNinjaDebug",
+      "inherits": ["macos-ninja-base-intel"],
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "USE_SANITIZER": "address"
+      }
+    },
+    {
       "name": "linux-base",
       "inherits": "default",
       "cacheVariables": {
+        "VCPKG_OVERLAY_TRIPLETS": "${sourceDir}/cmake/vcpkg_triplets",
         "VCPKG_TARGET_TRIPLET": "x64-xstudio-linux"
       }
     },
@@ -180,6 +236,34 @@
         "CMAKE_BUILD_TYPE": "Debug",
         "USE_SANITIZER": "address"
       }
+    },
+    {
+      "name": "linux-ninja-base",
+      "inherits": "linux-base",
+      "generator": "Ninja"
+    },
+    {
+      "name": "LinuxNinjaRelease",
+      "inherits": ["linux-ninja-base"],
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release"
+      }
+    },
+    {
+      "name": "LinuxNinjaRelWithDebInfo",
+      "inherits": ["linux-ninja-base"],
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "RelWithDebInfo",
+        "USE_SANITIZER": "address"
+      }
+    },
+    {
+      "name": "LinuxNinjaDebug",
+      "inherits": ["linux-ninja-base"],
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Debug",
+        "USE_SANITIZER": "address"
+      }
     }
   ]
 }

CMakePresets.json

@@ -308,6 +308,7 @@ macro(default_options_qt name)
 		set_target_properties(${name}
 	    	PROPERTIES
 	    	LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin/lib"
+	    	RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin"
 		)
 		install(TARGETS ${name} EXPORT xstudio
         	LIBRARY DESTINATION share/xstudio/lib)

cmake/macros.cmake

@@ -0,0 +1,12 @@
+diff --git a/CMakeLists.txt b/CMakeLists.txt
+--- a/CMakeLists.txt
++++ b/CMakeLists.txt
+@@ -245,7 +245,7 @@
+ endif()
+
+ # set up the internally hosted dependencies
+-add_subdirectory(src/deps)
++# add_subdirectory(src/deps)
+
+ set (OTIO_IMATH_TARGETS
+     # For OpenEXR/Imath 3.x:

cmake/otio_patch.diff

@@ -0,0 +1,81 @@
+vcpkg_from_github(
+    OUT_SOURCE_PATH SOURCE_PATH
+    REPO AcademySoftwareFoundation/OpenTimelineIO
+    REF v${VERSION}
+    SHA512 305d63730446c3b4c368cadd9d7a66de96dafee2168d589ae88a0320319f40cde4a739c9939eb088b635185cb1aabd051360ed432fde3ce11ef145e18c25dd21
+    HEAD_REF main
+    PATCHES
+        0001-disable-src-deps-subdir.patch
+)
+
+vcpkg_from_github(
+    OUT_SOURCE_PATH RAPIDJSON_SOURCE_PATH
+    REPO Tencent/rapidjson
+    REF 06d58b9e848c650114556a23294d0b6440078c61
+    SHA512 f0a7df46234e5b3244a801ddf1daefd26aac7ae5b2c470b8c3898f65c65591f6c9cabac0421800588826da9d3bcccba1f98e1c0c8c15184b3843cf6f3ffbdcad
+    HEAD_REF master
+)
+
+file(COPY "${RAPIDJSON_SOURCE_PATH}/include"
+     DESTINATION "${SOURCE_PATH}/src/deps/rapidjson")
+
+string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "dynamic" OTIO_SHARED)
+
+vcpkg_cmake_configure(
+    SOURCE_PATH "${SOURCE_PATH}"
+    OPTIONS
+        -DOTIO_SHARED_LIBS=${OTIO_SHARED}
+        -DOTIO_PYTHON_INSTALL=OFF
+        -DOTIO_DEPENDENCIES_INSTALL=OFF
+        -DOTIO_FIND_IMATH=ON
+        -DOTIO_CXX_INSTALL=ON
+        -DOTIO_AUTOMATIC_SUBMODULES=OFF
+        -DOTIO_INSTALL_COMMANDLINE_TOOLS=OFF
+)
+
+vcpkg_cmake_install()
+
+vcpkg_cmake_config_fixup(
+    PACKAGE_NAME opentimelineio
+    CONFIG_PATH share/opentimelineio
+)
+vcpkg_cmake_config_fixup(
+    PACKAGE_NAME opentime
+    CONFIG_PATH share/opentime
+)
+
+file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")
+
+# OTIO's upstream CMake installs shared libraries (.dll) into lib/ on Windows,
+# but vcpkg's convention (and applocal.ps1's search path) expects DLLs in bin/.
+# Move them so they get picked up by dependency deployment, and fix up the
+# generated CMake targets files so IMPORTED_LOCATION still resolves.
+if(VCPKG_TARGET_IS_WINDOWS AND VCPKG_LIBRARY_LINKAGE STREQUAL "dynamic")
+    file(MAKE_DIRECTORY "${CURRENT_PACKAGES_DIR}/bin")
+    file(MAKE_DIRECTORY "${CURRENT_PACKAGES_DIR}/debug/bin")
+    file(GLOB _otio_release_dlls "${CURRENT_PACKAGES_DIR}/lib/*.dll")
+    foreach(_dll ${_otio_release_dlls})
+        get_filename_component(_name "${_dll}" NAME)
+        file(RENAME "${_dll}" "${CURRENT_PACKAGES_DIR}/bin/${_name}")
+    endforeach()
+    file(GLOB _otio_debug_dlls "${CURRENT_PACKAGES_DIR}/debug/lib/*.dll")
+    foreach(_dll ${_otio_debug_dlls})
+        get_filename_component(_name "${_dll}" NAME)
+        file(RENAME "${_dll}" "${CURRENT_PACKAGES_DIR}/debug/bin/${_name}")
+    endforeach()
+
+    # Rewrite the generated Targets-*.cmake files to reference the new DLL
+    # locations. Only the .dll paths are changed; .lib (import library) paths
+    # stay in lib/ where they belong.
+    file(GLOB _otio_targets_files
+        "${CURRENT_PACKAGES_DIR}/share/opentime/OpenTimeTargets-*.cmake"
+        "${CURRENT_PACKAGES_DIR}/share/opentimelineio/OpenTimelineIOTargets-*.cmake"
+    )
+    foreach(_file ${_otio_targets_files})
+        file(READ "${_file}" _content)
+        string(REGEX REPLACE "/lib/([^/\"]*\\.dll)" "/bin/\\1" _content "${_content}")
+        file(WRITE "${_file}" "${_content}")
+    endforeach()
+endif()
+
+vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE.txt")

cmake/vcpkg_overlay_ports/opentimelineio/0001-disable-src-deps-subdir.patch

@@ -0,0 +1,18 @@
+{
+  "name": "opentimelineio",
+  "version": "0.17.0",
+  "description": "A file format and API for describing editorial timelines",
+  "homepage": "https://opentimeline.io",
+  "license": "Apache-2.0",
+  "dependencies": [
+    "imath",
+    {
+      "name": "vcpkg-cmake",
+      "host": true
+    },
+    {
+      "name": "vcpkg-cmake-config",
+      "host": true
+    }
+  ]
+}