Make the installed CMake package reusable

.gitattributes

@@ -1,2 +1,3 @@
 # Declare txt file must remain as provided (unchanged carriage return)
 *.txt binary
+CMakeLists.txt -binary text diff merge

.github/workflows/build-and-test-pixi.yml

@@ -36,3 +36,6 @@ jobs:
 
       - name: Test
         run: pixi run test
+
+      - name: Test installed CMake package
+        run: pixi run test-consumer

CMakeLists.txt

@@ -56,6 +56,7 @@ project(vrs
   DESCRIPTION "Meta VRS File Format Project"
   LANGUAGES CXX
 )
+include(GNUInstallDirs)
 message(STATUS "CMAKE_CXX_COMPILER: ${CMAKE_CXX_COMPILER}")
 message(STATUS "CMAKE_CXX_COMPILER_VERSION: ${CMAKE_CXX_COMPILER_VERSION}")
 

cmake/FindOcean.cmake

@@ -20,6 +20,21 @@ if(Ocean_FOUND)
   return()
 endif()
 
+# Reuse the Ocean targets installed alongside VRS when this module is loaded
+# from vrslibConfig.cmake. This avoids fetching and rebuilding Ocean in every
+# downstream project.
+set(_Ocean_INSTALLED_TARGETS "${CMAKE_CURRENT_LIST_DIR}/../../Ocean/FindOceanTargets.cmake")
+if(EXISTS "${_Ocean_INSTALLED_TARGETS}")
+  include("${_Ocean_INSTALLED_TARGETS}")
+  if(TARGET Ocean::Ocean)
+    set(Ocean_LIBRARIES Ocean::Ocean)
+    set(Ocean_FOUND TRUE)
+    unset(_Ocean_INSTALLED_TARGETS)
+    return()
+  endif()
+endif()
+unset(_Ocean_INSTALLED_TARGETS)
+
 # --------------------------
 # 0) Standard install dirs
 include(GNUInstallDirs)
@@ -82,6 +97,7 @@ target_link_libraries(ocean INTERFACE
   ocean_math
 )
 add_library(Ocean::Ocean ALIAS ocean)
+set_target_properties(ocean PROPERTIES EXPORT_NAME Ocean)
 
 # --------------------------
 # 4) Installation

cmake/FindRapidjsonLib.cmake

@@ -12,8 +12,47 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# The package version of rapidjson provided by apt on Linux or brew on Mac date from August 2016,
-# despite being the last official version (v1.1.0), and don't include important fixes.
+if(TARGET rapidjson::rapidjson)
+  return()
+endif()
+
+# Package managers can opt into a maintained RapidJSON package. Keep VRS'
+# pinned source fallback as the default because the official v1.1.0 release is
+# too old for VRS.
+if(VRS_USE_SYSTEM_RAPIDJSON OR VRS_CONFIG_USE_SYSTEM_RAPIDJSON)
+  unset(_RAPIDJSON_TARGET)
+  find_package(RapidJSON CONFIG QUIET)
+
+  if(TARGET RapidJSON::rapidjson)
+    set(_RAPIDJSON_TARGET RapidJSON::rapidjson)
+  elseif(TARGET RapidJSON)
+    set(_RAPIDJSON_TARGET RapidJSON)
+  elseif(TARGET rapidjson)
+    set(_RAPIDJSON_TARGET rapidjson)
+  else()
+    find_path(RAPIDJSON_INCLUDE_DIR NAMES rapidjson/rapidjson.h)
+    if(NOT RAPIDJSON_INCLUDE_DIR)
+      message(FATAL_ERROR "VRS_USE_SYSTEM_RAPIDJSON is enabled, but RapidJSON was not found")
+    endif()
+  endif()
+
+  add_library(rapidjson::rapidjson INTERFACE IMPORTED)
+  if(_RAPIDJSON_TARGET)
+    set_target_properties(rapidjson::rapidjson PROPERTIES
+      INTERFACE_LINK_LIBRARIES "${_RAPIDJSON_TARGET}"
+    )
+  else()
+    set_target_properties(rapidjson::rapidjson PROPERTIES
+      INTERFACE_INCLUDE_DIRECTORIES "${RAPIDJSON_INCLUDE_DIR}"
+    )
+  endif()
+
+  unset(_RAPIDJSON_TARGET)
+  return()
+endif()
+
+# The package version of rapidjson provided by apt on Linux or brew on Mac dates from August 2016,
+# despite being the last official version (v1.1.0), and does not include important fixes.
 # So we get the code from GitHub at a known working state.
 
 # Try to find rapidjson in fbsource third-party (for fbsource builds)
@@ -36,6 +75,9 @@ if (RAPIDJSON_INCLUDE_DIR)
   set(RAPIDJSON_FOUND TRUE)
 else()
   # Fall back to downloading from GitHub (OSS behavior)
+  if ("${EXTERNAL_DEPENDENCIES_DIR}" STREQUAL "")
+    set(EXTERNAL_DEPENDENCIES_DIR "${CMAKE_BINARY_DIR}/external")
+  endif()
   set(RAPIDJSON_DIR "${EXTERNAL_DEPENDENCIES_DIR}/rapidjson")
   set(RAPIDJSON_INCLUDE_DIR "${RAPIDJSON_DIR}/include")
   set(RAPIDJSON_INCLUDE_FILE "${RAPIDJSON_INCLUDE_DIR}/rapidjson/rapidjson.h")

cmake/LibrariesSetup.cmake

@@ -33,8 +33,10 @@ find_package(TurboJpeg REQUIRED)
 find_package(Opus)
 find_package(Ocean)
 
-# Optional dependencies for XPRS decoding: only on Unix-like platforms (Linux & macOS)
-if (BUILD_WITH_XPRS AND (TARGET_LINUX OR TARGET_MACOS))
+# Optional dependencies for XPRS decoding: only on Unix-like platforms (Linux & macOS).
+# VRS_CONFIG_WITH_XPRS records whether an installed VRS package contains XPRS.
+if ((BUILD_WITH_XPRS OR VRS_CONFIG_WITH_XPRS) AND
+    (CMAKE_SYSTEM_NAME STREQUAL "Linux" OR CMAKE_SYSTEM_NAME STREQUAL "Darwin"))
   find_package(FFmpeg)
 endif()
 

cmake/Options.cmake

@@ -18,3 +18,9 @@ endif()
 set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release")
 
 set(UNIT_TESTS ON CACHE BOOL "Disable unit tests.")
+
+option(
+  VRS_USE_SYSTEM_RAPIDJSON
+  "Use an installed RapidJSON package instead of downloading VRS' pinned revision."
+  OFF
+)

pixi.toml

@@ -27,17 +27,23 @@ version = "1.1.0"
 # Note: extra CLI argument after `pixi run TASK` are passed to the task cmd.
 clean = { cmd = "rm -rf build" }
 print-env = { cmd = "echo $PATH" }
-prepare = "cmake -G 'Ninja' -B build -S . -DBUILD_WITH_XPRS:BOOL=ON -DFFmpeg_ROOT=$CONDA_PREFIX -DCMAKE_BUILD_TYPE=Release"
+prepare = "cmake -G 'Ninja' -B build -S . -DBUILD_WITH_XPRS:BOOL=ON -DVRS_USE_SYSTEM_RAPIDJSON:BOOL=ON -DFFmpeg_ROOT=$CONDA_PREFIX -DCMAKE_INSTALL_PREFIX=$PIXI_PROJECT_ROOT/build/install -DCMAKE_INSTALL_LIBDIR=lib -DCMAKE_BUILD_TYPE=Release"
 build = { cmd = "cmake --build build --config Release --target all", depends-on = ["prepare"] }
 test = { cmd = "ctest -j --rerun-failed --output-on-failure ", cwd = "build", depends-on = ["build"]}
+install = { cmd = "cmake --install build --config Release", depends-on = ["build"] }
+prepare-consumer = { cmd = "cmake -S sample_project -B build/sample_project -Dvrslib_DIR=$PIXI_PROJECT_ROOT/build/install/lib/cmake/vrslib", depends-on = ["install"] }
+test-consumer = { cmd = "cmake --build build/sample_project --config Release", depends-on = ["prepare-consumer"] }
 vrs = { cmd = "build/tools/vrs/vrs", depends-on = ["build"]}
 
 [target.win-64.tasks] # Deal with windows specifics (prepare and build)
 cmake-generator = "cmake --help"
-prepare = "cmake -B build -S . -DCMAKE_BUILD_TYPE=Release"
+prepare = "cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -DVRS_USE_SYSTEM_RAPIDJSON:BOOL=ON -DCMAKE_INSTALL_PREFIX=$PIXI_PROJECT_ROOT/build/install"
 build = { cmd = "cmake --build build --config Release  -- /m", depends-on = [
     "prepare",
 ] }
+prepare-consumer = { cmd = "cmake -S sample_project -B build/sample_project -Dvrslib_DIR=$PIXI_PROJECT_ROOT/build/install/lib/cmake/vrslib", depends-on = [
+    "install",
+] }
 vrs = { cmd = "build/tools/vrs/Release/vrs", depends-on = ["build"]}
 
 [build-dependencies]
@@ -58,3 +64,11 @@ zlib = "1.2.*"
 eigen = "3.4.*"
 libopus = "1.4*" # optional dependency
 ffmpeg = { version = "*", build = "*lgpl*" }
+# Keep this build compatible with the cxx-compiler 1.6 toolchain pinned above.
+rapidjson = { version = "==1.1.0.post20240409", build = "*_0" }
+
+[target.osx-64.dependencies]
+libcxx = { version = "==16.0.6", build = "*_0" }
+
+[target.osx-arm64.dependencies]
+libcxx = { version = "==16.0.6", build = "*_0" }

tools/vrs/CMakeLists.txt

@@ -36,7 +36,7 @@ target_link_libraries(vrs
 
 
 install(TARGETS vrs EXPORT VRSLibTargets
-  RUNTIME DESTINATION bin
+  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
 )
 
 if (UNIT_TESTS)

tools/vrsplayer/CMakeLists.txt

@@ -48,7 +48,7 @@ if (QT_FOUND)
   endif()
 
   install(TARGETS vrsplayer EXPORT VRSLibTargets
-    RUNTIME DESTINATION bin
+    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
   )
 
   set(CMAKE_AUTOMOC OFF)

vrs/CMakeLists.txt

@@ -22,7 +22,7 @@ add_library(vrslib ${VRS_SRCS})
 target_include_directories(vrslib
   PUBLIC
     $<BUILD_INTERFACE:${VRS_SOURCE_DIR}>
-    $<INSTALL_INTERFACE:include>
+    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
 )
 target_link_libraries(vrslib
   PUBLIC
@@ -41,23 +41,23 @@ target_link_libraries(vrslib
 target_link_libraries (vrslib PUBLIC $<$<PLATFORM_ID:Linux>:rt>)
 
 install(TARGETS vrslib EXPORT VRSLibTargets
-  LIBRARY DESTINATION lib
-  ARCHIVE DESTINATION lib
-  RUNTIME DESTINATION bin
-  INCLUDES DESTINATION include
+  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+  INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
 )
 
 install(EXPORT VRSLibTargets
   NAMESPACE vrs::
   FILE vrslibTargets.cmake
-  DESTINATION lib/cmake/vrslib
+  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/vrslib
 )
 
 include(CMakePackageConfigHelpers)
 
 configure_package_config_file(vrslibConfig.cmake.in
   ${CMAKE_CURRENT_BINARY_DIR}/vrslibConfig.cmake
-  INSTALL_DESTINATION ${LIB_INSTALL_DIR}/vrslib/cmake
+  INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/vrslib
 )
 
 write_basic_package_version_file(
@@ -68,21 +68,21 @@ write_basic_package_version_file(
 
 install(
   DIRECTORY .
-  DESTINATION include/vrs
+  DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/vrs
   COMPONENT headers
-  FILES_MATCHING PATTERN "*.hpp" PATTERN "*.h"
+  FILES_MATCHING PATTERN "*.hpp" PATTERN "*.h" PATTERN "*.inc"
 )
 
 install(
   DIRECTORY ../cmake
-  DESTINATION lib/cmake/vrslib
+  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/vrslib
   FILES_MATCHING PATTERN "*.cmake"
 )
 
 install(FILES
   "${CMAKE_CURRENT_BINARY_DIR}/vrslibConfig.cmake"
   "${CMAKE_CURRENT_BINARY_DIR}/vrslibConfigVersion.cmake"
-  DESTINATION lib/cmake/vrslib
+  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/vrslib
 )
 
 if (UNIT_TESTS)

vrs/helpers/CMakeLists.txt

@@ -16,7 +16,7 @@ add_library(vrs_helpers_strings INTERFACE)
 target_include_directories(vrs_helpers_strings
   INTERFACE
     $<BUILD_INTERFACE:${VRS_SOURCE_DIR}>
-    $<INSTALL_INTERFACE:include>
+    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
 )
 
 file(GLOB VRS_HELPERS_SRCS *.cpp *.h *.hpp)
@@ -33,14 +33,14 @@ target_link_libraries(vrs_helpers
 target_include_directories(vrs_helpers
   PUBLIC
     $<BUILD_INTERFACE:${VRS_SOURCE_DIR}>
-    $<INSTALL_INTERFACE:include>
+    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
 )
 
 install(TARGETS vrs_helpers vrs_helpers_strings EXPORT VRSLibTargets
-  LIBRARY DESTINATION lib
-  ARCHIVE DESTINATION lib
-  RUNTIME DESTINATION bin
-  INCLUDES DESTINATION include
+  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+  INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
 )
 
 if (UNIT_TESTS)

vrs/os/CMakeLists.txt

@@ -23,7 +23,7 @@ add_library(vrs_os ${VRS_OS_SRCS})
 target_include_directories(vrs_os
   PUBLIC
     $<BUILD_INTERFACE:${VRS_SOURCE_DIR}>
-    $<INSTALL_INTERFACE:include>
+    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
 )
 
 target_link_libraries(vrs_os
@@ -38,16 +38,16 @@ add_library(vrs_platform INTERFACE)
 target_include_directories(vrs_platform
   INTERFACE
     $<BUILD_INTERFACE:${VRS_SOURCE_DIR}>
-    $<INSTALL_INTERFACE:include>
+    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
 )
 # When building with cmake, always enable OSS build mode
 target_compile_definitions(vrs_platform INTERFACE OSS_BUILD_MODE)
 
 install(TARGETS vrs_os vrs_platform EXPORT VRSLibTargets
-  LIBRARY DESTINATION lib
-  ARCHIVE DESTINATION lib
-  RUNTIME DESTINATION bin
-  INCLUDES DESTINATION include
+  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+  INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
 )
 
 if (UNIT_TESTS)