Support external manifest repositories

Author: AnastaZIuk

.github/workflows/smoke.yml

@@ -8,7 +8,7 @@ on:
 
 jobs:
   smoke:
-    name: ${{ matrix.os }} / ${{ matrix.link_mode }}
+    name: ${{ matrix.os }} / ${{ matrix.manifest_source }} / ${{ matrix.link_mode }}
     runs-on: ${{ matrix.os }}
     timeout-minutes: 20
     strategy:
@@ -21,6 +21,9 @@ jobs:
           - symlink
           - hardlink
           - copy
+        manifest_source:
+          - internal
+          - external
         include:
           - os: ubuntu-latest
             native_build_arg: -j1
@@ -34,22 +37,39 @@ jobs:
     steps:
       - uses: actions/checkout@v6
 
+      - name: Checkout external manifests
+        if: matrix.manifest_source == 'external'
+        uses: actions/checkout@v6
+        with:
+          repository: AnastaZIuk/nam-smoke-manifests
+          path: external-manifests
+
       - name: Restore NAM cache
         uses: actions/cache@v5
         with:
           path: ${{ env.NAM_CACHE_ROOT }}
-          key: nam-cache-${{ runner.os }}-${{ hashFiles('media/**/*.dvc') }}
+          key: nam-cache-${{ runner.os }}-${{ matrix.manifest_source }}-${{ hashFiles('media/**/*.dvc', 'external-manifests/media/**/*.dvc') }}
           restore-keys: |
+            nam-cache-${{ runner.os }}-${{ matrix.manifest_source }}-
             nam-cache-${{ runner.os }}-
 
       - name: Configure smoke
         shell: pwsh
         run: |
           cmake -E rm -rf $env:SMOKE_BUILD_DIR
           cmake -E make_directory $env:NAM_CACHE_ROOT
-          cmake -S smoke -B $env:SMOKE_BUILD_DIR `
-            -DNAM_SMOKE_CACHE_ROOT="$env:NAM_CACHE_ROOT" `
-            -DNAM_SMOKE_LINK_MODE=${{ matrix.link_mode }}
+          $cmakeArgs = @(
+            '-S', 'smoke',
+            '-B', $env:SMOKE_BUILD_DIR,
+            "-DNAM_SMOKE_CACHE_ROOT=$env:NAM_CACHE_ROOT",
+            "-DNAM_SMOKE_LINK_MODE=${{ matrix.link_mode }}"
+          )
+          if ('${{ matrix.manifest_source }}' -eq 'external') {
+            $cmakeArgs += "-DNAM_SMOKE_MANIFEST_ROOT=$env:GITHUB_WORKSPACE/external-manifests"
+            $cmakeArgs += '-DNAM_SMOKE_REPO=AnastaZIuk/nam-smoke-manifests'
+            $cmakeArgs += '-DNAM_SMOKE_TAG=media'
+          }
+          & cmake @cmakeArgs
 
       - name: Build smoke
         shell: pwsh

README.md

@@ -43,6 +43,11 @@ At a high level this follows the same pattern used by mature package and artifac
 - `binaryTarget(url:, checksum:)` in `SwiftPM`
 - content-addressed external test data in `CMake ExternalData`, used by projects such as `VTK`
 
+The same consumer module is also meant to stay reusable beyond Nabla itself.
+This repository is the first-party Nabla registry, but consumers can point the
+module at a different manifest checkout and a different `GitHub Release`
+channel without changing the build-graph model.
+
 ## Evidence
 
 ### Git History Pressure

cmake/NablaAssetManifests.cmake

@@ -1,4 +1,4 @@
-# Consumer module for the Nabla-Asset-Manifests repository.
+# Consumer module with Nabla-Asset-Manifests defaults.
 #
 # Maintainer-side source of truth:
 # - physical layout under channel roots such as `media/`
@@ -167,17 +167,30 @@ function(_nam_resolve_cache_root OUT_VAR)
     set(${OUT_VAR} "${_root}" PARENT_SCOPE)
 endfunction()
 
+function(_nam_resolve_manifest_root OUT_VAR)
+    set(options)
+    set(oneValueArgs MANIFEST_ROOT)
+    cmake_parse_arguments(NAM "${options}" "${oneValueArgs}" "" ${ARGN})
+
+    if (DEFINED NAM_MANIFEST_ROOT AND NOT "${NAM_MANIFEST_ROOT}" STREQUAL "")
+        file(TO_CMAKE_PATH "${NAM_MANIFEST_ROOT}" _root)
+    else()
+        nam_get_repo_root(_root)
+    endif()
+    set(${OUT_VAR} "${_root}" PARENT_SCOPE)
+endfunction()
+
 function(_nam_get_channel_root OUT_VAR)
     set(options)
-    set(oneValueArgs CHANNEL)
+    set(oneValueArgs CHANNEL MANIFEST_ROOT)
     cmake_parse_arguments(NAM "${options}" "${oneValueArgs}" "" ${ARGN})
 
     if (NOT DEFINED NAM_CHANNEL OR "${NAM_CHANNEL}" STREQUAL "")
         set(NAM_CHANNEL "media")
     endif()
 
-    nam_get_repo_root(_repo_root)
-    set(_channel_root "${_repo_root}/${NAM_CHANNEL}")
+    _nam_resolve_manifest_root(_manifest_root MANIFEST_ROOT "${NAM_MANIFEST_ROOT}")
+    set(_channel_root "${_manifest_root}/${NAM_CHANNEL}")
     if (NOT EXISTS "${_channel_root}")
         message(FATAL_ERROR "NablaAssetManifests: channel root `${_channel_root}` does not exist")
     endif()
@@ -186,14 +199,14 @@ endfunction()
 
 function(_nam_parse_dvc_file)
     set(options)
-    set(oneValueArgs DVC_FILE CHANNEL OUT_RELATIVE_PATH OUT_RELEASE_ASSET OUT_KEY)
+    set(oneValueArgs DVC_FILE CHANNEL MANIFEST_ROOT OUT_RELATIVE_PATH OUT_RELEASE_ASSET OUT_KEY)
     cmake_parse_arguments(NAM "${options}" "${oneValueArgs}" "" ${ARGN})
 
     if (NOT NAM_DVC_FILE)
         message(FATAL_ERROR "NablaAssetManifests: DVC_FILE is required")
     endif()
 
-    _nam_get_channel_root(_channel_root CHANNEL "${NAM_CHANNEL}")
+    _nam_get_channel_root(_channel_root CHANNEL "${NAM_CHANNEL}" MANIFEST_ROOT "${NAM_MANIFEST_ROOT}")
     file(STRINGS "${NAM_DVC_FILE}" _lines)
 
     set(_path "")
@@ -230,14 +243,14 @@ endfunction()
 
 function(nam_get_channel_asset_keys OUT_VAR)
     set(options)
-    set(oneValueArgs CHANNEL)
+    set(oneValueArgs CHANNEL MANIFEST_ROOT)
     cmake_parse_arguments(NAM "${options}" "${oneValueArgs}" "" ${ARGN})
 
     if (NOT DEFINED NAM_CHANNEL OR "${NAM_CHANNEL}" STREQUAL "")
         set(NAM_CHANNEL "media")
     endif()
 
-    _nam_get_channel_root(_channel_root CHANNEL "${NAM_CHANNEL}")
+    _nam_get_channel_root(_channel_root CHANNEL "${NAM_CHANNEL}" MANIFEST_ROOT "${NAM_MANIFEST_ROOT}")
     file(GLOB_RECURSE _dvc_files "${_channel_root}/*.dvc")
     list(SORT _dvc_files)
 
@@ -246,6 +259,7 @@ function(nam_get_channel_asset_keys OUT_VAR)
         _nam_parse_dvc_file(
             DVC_FILE "${_dvc}"
             CHANNEL "${NAM_CHANNEL}"
+            MANIFEST_ROOT "${NAM_MANIFEST_ROOT}"
             OUT_RELATIVE_PATH _relative_path
             OUT_RELEASE_ASSET _release_asset
             OUT_KEY _key
@@ -257,7 +271,7 @@ endfunction()
 
 function(_nam_find_channel_asset)
     set(options)
-    set(oneValueArgs CHANNEL ASSET OUT_RELATIVE_PATH OUT_RELEASE_ASSET OUT_KEY)
+    set(oneValueArgs CHANNEL MANIFEST_ROOT ASSET OUT_RELATIVE_PATH OUT_RELEASE_ASSET OUT_KEY)
     cmake_parse_arguments(NAM "${options}" "${oneValueArgs}" "" ${ARGN})
 
     if (NOT DEFINED NAM_CHANNEL OR "${NAM_CHANNEL}" STREQUAL "")
@@ -267,7 +281,7 @@ function(_nam_find_channel_asset)
         message(FATAL_ERROR "NablaAssetManifests: ASSET is required")
     endif()
 
-    _nam_get_channel_root(_channel_root CHANNEL "${NAM_CHANNEL}")
+    _nam_get_channel_root(_channel_root CHANNEL "${NAM_CHANNEL}" MANIFEST_ROOT "${NAM_MANIFEST_ROOT}")
     file(GLOB_RECURSE _dvc_files "${_channel_root}/*.dvc")
     list(SORT _dvc_files)
 
@@ -276,6 +290,7 @@ function(_nam_find_channel_asset)
         _nam_parse_dvc_file(
             DVC_FILE "${_dvc}"
             CHANNEL "${NAM_CHANNEL}"
+            MANIFEST_ROOT "${NAM_MANIFEST_ROOT}"
             OUT_RELATIVE_PATH _relative_path
             OUT_RELEASE_ASSET _release_asset
             OUT_KEY _key
@@ -427,7 +442,7 @@ endfunction()
 
 function(nam_add_channel_target)
     set(options NO_SYMLINKS VERBOSE)
-    set(oneValueArgs TARGET CHANNEL REPO TAG CACHE_ROOT DESTINATION_ROOT SHOW_PROGRESS)
+    set(oneValueArgs TARGET CHANNEL MANIFEST_ROOT REPO TAG CACHE_ROOT DESTINATION_ROOT SHOW_PROGRESS)
     set(multiValueArgs ITEMS)
     cmake_parse_arguments(NAM "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
 
@@ -450,17 +465,19 @@ function(nam_add_channel_target)
         set(NAM_SHOW_PROGRESS ON)
     endif()
 
+    _nam_resolve_manifest_root(_manifest_root MANIFEST_ROOT "${NAM_MANIFEST_ROOT}")
+
     if (NAM_ITEMS)
         set(_items ${NAM_ITEMS})
     else()
-        nam_get_channel_asset_keys(_items CHANNEL "${NAM_CHANNEL}")
+        nam_get_channel_asset_keys(_items CHANNEL "${NAM_CHANNEL}" MANIFEST_ROOT "${_manifest_root}")
     endif()
 
     list(LENGTH _items _item_count)
     _nam_get_backend_kind(_backend_kind)
     _nam_resolve_cache_root(_cache_root CACHE_ROOT "${NAM_CACHE_ROOT}")
     _nam_include_externaldata(_externaldata_provider)
-    _nam_summary("configure channel target `${NAM_TARGET}`: channel=`${NAM_CHANNEL}`, repo=`${NAM_REPO}`, tag=`${NAM_TAG}`, backend=`${_backend_kind}`, externaldata=`${_externaldata_provider}`, cache_root=`${_cache_root}`, total=${_item_count}")
+    _nam_summary("configure channel target `${NAM_TARGET}`: channel=`${NAM_CHANNEL}`, manifest_root=`${_manifest_root}`, repo=`${NAM_REPO}`, tag=`${NAM_TAG}`, backend=`${_backend_kind}`, externaldata=`${_externaldata_provider}`, cache_root=`${_cache_root}`, total=${_item_count}")
 
     _nam_get_github_release_index_file(_index_file REPO "${NAM_REPO}" TAG "${NAM_TAG}" CACHE_ROOT "${NAM_CACHE_ROOT}")
 
@@ -495,6 +512,7 @@ function(nam_add_channel_target)
     foreach(_asset IN LISTS _items)
         _nam_find_channel_asset(
             CHANNEL "${NAM_CHANNEL}"
+            MANIFEST_ROOT "${_manifest_root}"
             ASSET "${_asset}"
             OUT_RELATIVE_PATH _relative_path
             OUT_RELEASE_ASSET _release_asset

cmake/README.md

@@ -41,6 +41,7 @@ include("${asset_manifests_repo}/nam.cmake")
 nam_add_channel_target(
     TARGET media
     CHANNEL media
+    MANIFEST_ROOT "${asset_manifests_repo}"
     REPO Devsh-Graphics-Programming/Nabla-Asset-Manifests
     TAG media
     DESTINATION_ROOT "${CMAKE_CURRENT_BINARY_DIR}"
@@ -54,6 +55,7 @@ nam_add_channel_target(
 ## Default arguments
 
 - `CHANNEL = media`
+- `MANIFEST_ROOT = <root of the repository that provides nam.cmake>`
 - `REPO = Devsh-Graphics-Programming/Nabla-Asset-Manifests`
 - `TAG = media`
 - `DESTINATION_ROOT = ${CMAKE_CURRENT_BINARY_DIR}`
@@ -63,6 +65,42 @@ nam_add_channel_target(
 - `NO_SYMLINKS = OFF`
 - `VERBOSE = OFF`
 
+## Custom manifest repository
+
+The consumer module can also read manifests from a different local checkout
+while still reusing the same public `nam_add_channel_target(...)` entrypoint.
+
+Typical setup:
+
+- add this repository as a submodule or vendor it some other way so
+  `nam.cmake` stays available locally
+- checkout a second repository that contains a compatible channel tree with
+  `.dvc` files
+- publish the corresponding payloads from that second repository as a
+  `GitHub Release`
+
+Example:
+
+```cmake
+include("${nam_module_repo}/nam.cmake")
+
+nam_add_channel_target(
+    TARGET custom_media
+    MANIFEST_ROOT "${custom_manifest_repo}"
+    CHANNEL media
+    REPO my-user/my-manifests
+    TAG media
+    DESTINATION_ROOT "${CMAKE_CURRENT_BINARY_DIR}"
+)
+```
+
+Current scope stays intentionally small:
+
+- manifest discovery can come from a different local repository via
+  `MANIFEST_ROOT`
+- remote payload resolution still uses `GitHub Release assets` only
+- the built-in Nabla defaults remain unchanged when `MANIFEST_ROOT` is omitted
+
 `<ENTRY>` resolves per platform:
 
 - Windows: `%LOCALAPPDATA%`
@@ -195,6 +233,10 @@ Its local options are:
 
 - `NAM_SMOKE_LINK_MODE = auto|symlink|hardlink|copy`
 - `NAM_SMOKE_CACHE_ROOT = <path>`
+- `NAM_SMOKE_MANIFEST_ROOT = <path>`
+- `NAM_SMOKE_REPO = <owner>/<repo>`
+- `NAM_SMOKE_TAG = <release-tag>`
+- `NAM_SMOKE_CHANNEL = <channel>`
 - `NAM_SMOKE_NO_SYMLINKS = ON|OFF`
 
 Those options are for smoke verification only. They are not part of the public

smoke/CMakeLists.txt

@@ -7,6 +7,10 @@ option(NAM_SMOKE_NO_SYMLINKS "Force copy materialization in the smoke consumer."
 set(NAM_SMOKE_LINK_MODE "auto" CACHE STRING "Smoke materialization mode override.")
 set_property(CACHE NAM_SMOKE_LINK_MODE PROPERTY STRINGS auto symlink hardlink copy)
 set(NAM_SMOKE_CACHE_ROOT "" CACHE PATH "Shared cache root for smoke runs.")
+set(NAM_SMOKE_MANIFEST_ROOT "" CACHE PATH "Manifest root override for smoke runs.")
+set(NAM_SMOKE_REPO "" CACHE STRING "GitHub repository override for smoke runs.")
+set(NAM_SMOKE_TAG "" CACHE STRING "Release tag override for smoke runs.")
+set(NAM_SMOKE_CHANNEL "media" CACHE STRING "Channel override for smoke runs.")
 
 string(TOLOWER "${NAM_SMOKE_LINK_MODE}" _nam_smoke_link_mode)
 if (
@@ -30,6 +34,18 @@ set(_nam_extra_args)
 if (NAM_SMOKE_CACHE_ROOT)
     list(APPEND _nam_extra_args CACHE_ROOT "${NAM_SMOKE_CACHE_ROOT}")
 endif()
+if (NAM_SMOKE_MANIFEST_ROOT)
+    list(APPEND _nam_extra_args MANIFEST_ROOT "${NAM_SMOKE_MANIFEST_ROOT}")
+endif()
+if (NAM_SMOKE_REPO)
+    list(APPEND _nam_extra_args REPO "${NAM_SMOKE_REPO}")
+endif()
+if (NAM_SMOKE_TAG)
+    list(APPEND _nam_extra_args TAG "${NAM_SMOKE_TAG}")
+endif()
+if (NAM_SMOKE_CHANNEL)
+    list(APPEND _nam_extra_args CHANNEL "${NAM_SMOKE_CHANNEL}")
+endif()
 
 unset(NAM_INTERNAL_FORCE_FILE_LINK_MODE)
 if (_nam_smoke_link_mode STREQUAL "copy" OR NAM_SMOKE_NO_SYMLINKS)