wyvrnpm 2.10.2 → 2.12.2

package/bin/{wyvrn.js → wyvrnpm.js}

@@ -5,6 +5,7 @@
 const yargs     = require('yargs');
 const init         = require('../src/commands/init');
 const add          = require('../src/commands/add');
+const versionCmd   = require('../src/commands/version');
 const install      = require('../src/commands/install');
 const clean        = require('../src/commands/clean');
 const publish      = require('../src/commands/publish');
@@ -143,6 +144,40 @@ yargs
     (argv) => add(argv),
   )
 
+  // ── version ───────────────────────────────────────────────────────────────
+  .command(
+    'version [newVersion]',
+    'Read, set, or partially update the top-level `version` field in wyvrn.json. ' +
+    'Bare `wyvrnpm version` prints the current value on stdout (for `VER=$(...)` ' +
+    'capture). Pass a full 4-part value (1.2.3.4) or component flags (--major / ' +
+    '--minor / --patch / --build) to tweak individual parts. Designed for CI/CD — ' +
+    'pair with --format json to capture { previous, version } on stdout.',
+    (y) => {
+      y
+        .positional('newVersion', {
+          type: 'string',
+          describe: 'Full 4-part version to write verbatim (e.g. 1.2.3.4). ' +
+                    'Mutually exclusive with --major/--minor/--patch/--build.',
+        })
+        .option('major', { type: 'number', description: 'Replace the 1st component (major).' })
+        .option('minor', { type: 'number', description: 'Replace the 2nd component (minor).' })
+        .option('patch', { type: 'number', description: 'Replace the 3rd component (patch).' })
+        .option('build', { type: 'number', description: 'Replace the 4th component (build) — typical CI use.' })
+        .option('dry-run', {
+          type: 'boolean',
+          default: false,
+          description: 'Compute and print the proposed version without writing wyvrn.json.',
+        })
+        .option('format', {
+          type: 'string',
+          choices: ['text', 'json'],
+          default: 'text',
+          description: 'Output format. "json" emits { command, previous, version, ... } on stdout.',
+        });
+    },
+    (argv) => versionCmd({ ...argv, dryRun: argv['dry-run'] }),
+  )
+
   // ── install ───────────────────────────────────────────────────────────────
   .command(
     'install',
@@ -227,6 +262,15 @@ yargs
           choices: ['win_x64', 'win_x86', 'linux_x64', 'linux_x86', 'osx_x64', 'osx_arm64'],
           default: 'win_x64',
         })
+        .option('build-dir', {
+          type: 'string',
+          description:
+            'Project-relative subdir for the generated preset\'s binaryDir ' +
+            '(default: "build"). Use this when the repo has a `BUILD` ' +
+            'Bazel/Buck file at root that collides with `build/` on ' +
+            'case-insensitive filesystems (gRPC, …). For persistent ' +
+            'override, set `binaryDirRoot` in wyvrn.local.json.',
+        })
         .option('timeout', {
           type: 'number',
           description: 'HTTP timeout in seconds',
@@ -246,6 +290,7 @@ yargs
       awsProfile:   argv['aws-profile'],
       tokenEnv:     argv['token-env'],
       dryRun:       argv['dry-run'],
+      buildDir:     argv['build-dir'],
     }),
   )
 
@@ -346,6 +391,15 @@ yargs
             '--conf cmake.cache.CHROMA_ENABLE_TEST=ON. CLI --conf does NOT ' +
             'regenerate CMakePresets.json; edit wyvrn.local.json and re-run ' +
             '`wyvrnpm install` for persistent overrides. See claude/PLAN-CONF.md.',
+        })
+        .option('build-dir', {
+          type: 'string',
+          description:
+            'Project-relative subdir for the build tree (default: "build"). ' +
+            'Must match the value used at install time — the preset baked ' +
+            'in by `wyvrnpm install` is the source of truth for the ' +
+            'cmake binaryDir. For persistent override, set `binaryDirRoot` ' +
+            'in wyvrn.local.json so install + build agree without a flag.',
         });
     },
     (argv) => build({
@@ -353,6 +407,7 @@ yargs
       autoInstall:   argv['auto-install'],
       installPrefix: argv['install-prefix'],
       allConfigs:    argv['all-configs'],
+      buildDir:      argv['build-dir'],
     }),
   )
 
@@ -557,6 +612,16 @@ yargs
             'Reads recipe conf + CLI only; wyvrn.local.json is intentionally ' +
             'ignored for publish.',
         })
+        .option('build-dir', {
+          type: 'string',
+          description:
+            'Project-relative subdir to look up the install tree under ' +
+            '(default: "build"). Must match the value used at install/build ' +
+            'time so publish can find `<root>/wyvrn-<profile>/<installDir>/`. ' +
+            'For persistent override, set `binaryDirRoot` in wyvrn.local.json. ' +
+            'Reading the overlay value here is path-only — no `conf` from the ' +
+            'overlay is folded into the published artefact.',
+        })
         .option('format', {
           type: 'string',
           choices: ['text', 'json'],
@@ -570,6 +635,7 @@ yargs
       awsProfile: argv['aws-profile'],
       tokenEnv:   argv['token-env'],
       dryRun:     argv['dry-run'],
+      buildDir:   argv['build-dir'],
     }),
   )
 

package/cmake/cpp.cmake

@@ -1,9 +1,9 @@
-# Define the cpp information ( version, compilation type, thread type, exception handling )
-# Set a C++20 default only if the consumer (or wyvrnpm's toolchain) has not
-# already chosen a standard — the toolchain sets CMAKE_CXX_STANDARD from the
-# active build profile before project(), and that explicit choice must win.
-if(NOT DEFINED CMAKE_CXX_STANDARD)
-    set(CMAKE_CXX_STANDARD 20)
-    set(CMAKE_CXX_STANDARD_REQUIRED True)
-endif()
-set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API OFF)
+# Define the cpp information ( version, compilation type, thread type, exception handling )
+# Set a C++20 default only if the consumer (or wyvrnpm's toolchain) has not
+# already chosen a standard — the toolchain sets CMAKE_CXX_STANDARD from the
+# active build profile before project(), and that explicit choice must win.
+if(NOT DEFINED CMAKE_CXX_STANDARD)
+    set(CMAKE_CXX_STANDARD 20)
+    set(CMAKE_CXX_STANDARD_REQUIRED True)
+endif()
+set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API OFF)

package/cmake/functions.cmake

@@ -1,224 +1,224 @@
-# ── Internal helper ───────────────────────────────────────────────────────────
-# Collects all sources for the calling directory in three layers:
-#
-#   1. General sources  — all .cpp/.h/.hpp under CMAKE_CURRENT_SOURCE_DIR,
-#                         excluding HAL/, Platform/, and include/HAL|Platform/
-#   2. HAL common       — files sitting directly (non-recursive) in any HAL/ or
-#                         Platform/ root; these are platform-neutral shared headers
-#   3. HAL layered      — recursive sources from each applicable subdirectory,
-#                         resolved in order: family → leaf
-#
-#                         Family tiers (from variables.cmake derived vars):
-#                           microsoft  — Windows + Xbox
-#                           unix       — Linux + SteamOS + Android + Darwin + PlayStation
-#                           darwin     — macOS + iOS
-#                           playstation— PS4 + PS5
-#
-#                         Leaf dirs:
-#                           win  xbox  linux  steamos  mac  ios
-#                           android  ps4  ps5
-#
-#                         Search roots for both family and leaf dirs:
-#                           HAL/  Platform/  src/HAL/  src/Platform/
-#                           include/HAL/  include/Platform/
-#
-# Result is written to the variable named by <out_var> in the caller's scope.
-# Any additional arguments are treated as regex patterns to exclude from all source lists.
-function(_wyvrn_collect_sources out_var)
-    set(_extra_excludes ${ARGN})
-    file(GLOB_RECURSE _sources
-        "${CMAKE_CURRENT_SOURCE_DIR}/*.cpp"
-        "${CMAKE_CURRENT_SOURCE_DIR}/*.h"
-        "${CMAKE_CURRENT_SOURCE_DIR}/*.hpp"
-    )
-    list(FILTER _sources EXCLUDE REGEX ".*[/\\\\]HAL[/\\\\].*")
-    list(FILTER _sources EXCLUDE REGEX ".*[/\\\\]Platform[/\\\\].*")
-    list(FILTER _sources EXCLUDE REGEX ".*[/\\\\]tests[/\\\\].*")
-    list(FILTER _sources EXCLUDE REGEX ".*[/\\\\]vendors[/\\\\].*")
-    list(FILTER _sources EXCLUDE REGEX ".*[/\\\\]wyvrn_internal[/\\\\].*")
-    list(FILTER _sources EXCLUDE REGEX ".*[/\\\\]build[/\\\\].*")
-    list(FILTER _sources EXCLUDE REGEX ".*[/\\\\]output[/\\\\].*")
-    
-    # Shared / platform-neutral files sitting directly in any HAL/ or Platform/ root
-    file(GLOB _hal_common
-        "${CMAKE_CURRENT_SOURCE_DIR}/HAL/*.*"
-        "${CMAKE_CURRENT_SOURCE_DIR}/Platform/*.*"
-        "${CMAKE_CURRENT_SOURCE_DIR}/src/HAL/*.*"
-        "${CMAKE_CURRENT_SOURCE_DIR}/src/Platform/*.*"
-        "${CMAKE_CURRENT_SOURCE_DIR}/include/HAL/*.*"
-        "${CMAKE_CURRENT_SOURCE_DIR}/include/Platform/*.*"
-    )
-
-    # Build an ordered list of HAL subdirectory names to search: family first, then leaf.
-    # Each entry is searched under every search root listed in _hal_roots below.
-    set(_plat_dirs)
-
-    # ── Family tiers ──────────────────────────────────────────────────────────
-    if(WYVRN_PLATFORM_MICROSOFT)
-        list(APPEND _plat_dirs microsoft)
-    endif()
-    if(WYVRN_PLATFORM_UNIX)
-        list(APPEND _plat_dirs unix)
-    endif()
-    if(WYVRN_PLATFORM_DARWIN)
-        list(APPEND _plat_dirs darwin)
-    endif()
-    if(WYVRN_PLATFORM_PLAYSTATION)
-        list(APPEND _plat_dirs playstation)
-    endif()
-
-    # ── Leaf tiers ────────────────────────────────────────────────────────────
-    # Exactly one leaf is set by variables.cmake; SteamOS also gets a linux pass
-    # first (most SteamOS-targeting code lives there) then a steamos overlay pass.
-    if(WYVRN_PLATFORM_WINDOWS)
-        list(APPEND _plat_dirs win)
-    elseif(WYVRN_PLATFORM_XBOX)
-        list(APPEND _plat_dirs xbox)
-    elseif(WYVRN_PLATFORM_PS5)
-        list(APPEND _plat_dirs ps5)
-    elseif(WYVRN_PLATFORM_PS4)
-        list(APPEND _plat_dirs ps4)
-    elseif(WYVRN_PLATFORM_ANDROID)
-        list(APPEND _plat_dirs android)
-    elseif(WYVRN_PLATFORM_IOS)
-        list(APPEND _plat_dirs ios)
-    elseif(WYVRN_PLATFORM_MACOS)
-        list(APPEND _plat_dirs mac)
-    elseif(WYVRN_PLATFORM_STEAMOS)
-        list(APPEND _plat_dirs linux steamos)
-    elseif(WYVRN_PLATFORM_LINUX)
-        list(APPEND _plat_dirs linux)
-    endif()
-
-    # All directory roots that may contain HAL/<subdir>/ trees
-    set(_hal_roots
-        "${CMAKE_CURRENT_SOURCE_DIR}/HAL"
-        "${CMAKE_CURRENT_SOURCE_DIR}/Platform"
-        "${CMAKE_CURRENT_SOURCE_DIR}/src/HAL"
-        "${CMAKE_CURRENT_SOURCE_DIR}/src/Platform"
-        "${CMAKE_CURRENT_SOURCE_DIR}/include/HAL"
-        "${CMAKE_CURRENT_SOURCE_DIR}/include/Platform"
-    )
-
-    set(_hal_plat)
-    foreach(_dir IN LISTS _plat_dirs)
-        foreach(_root IN LISTS _hal_roots)
-            file(GLOB_RECURSE _tmp "${_root}/${_dir}/*.*")
-            list(APPEND _hal_plat ${_tmp})
-        endforeach()
-    endforeach()
-
-    foreach(_pat IN LISTS _extra_excludes)
-        list(FILTER _sources    EXCLUDE REGEX "${_pat}")
-        list(FILTER _hal_common EXCLUDE REGEX "${_pat}")
-        list(FILTER _hal_plat   EXCLUDE REGEX "${_pat}")
-    endforeach()
-
-    set(${out_var} ${_sources} ${_hal_common} ${_hal_plat} PARENT_SCOPE)
-endfunction()
-
-# ── Internal helper ───────────────────────────────────────────────────────────
-# Applies the standard Wyvrn compiler flags to <target>.
-function(_wyvrn_apply_compiler_flags target)
-    get_target_property(_wyvrn_target_type ${target} TYPE)
-    if(_wyvrn_target_type STREQUAL "INTERFACE_LIBRARY")
-        return()
-    endif()
-    target_compile_options(${target} PRIVATE ${WYVRN_COMPILER_FLAGS})
-    target_compile_options(${target} PRIVATE $<$<CONFIG:Debug>:${WYVRN_COMPILER_FLAGS_DEBUG}>)
-    target_compile_options(${target} PRIVATE $<$<CONFIG:Release>:${WYVRN_COMPILER_FLAGS_RELEASE}>)
-endfunction()
-
-# ── SETUP_LIBRARY(target type [EXCLUDE pat...] [extra_sources...]) ────────────
-# Creates a library target from all sources in CMAKE_CURRENT_SOURCE_DIR,
-# with platform-specific HAL sources included automatically.
-#
-# Arguments:
-#   target         CMake target name
-#   type           Library type: STATIC | SHARED | INTERFACE | OBJECT
-#   EXCLUDE        (optional) One or more regex patterns; matched files are
-#                  excluded from the auto-collected source list
-#   extra_sources  (optional) Additional source files to append (positional,
-#                  or via the SOURCES keyword)
-#
-# Side effects:
-#   - Registers aliases  chroma::<target>  and  wyvrn::<target>
-#   - Applies standard Wyvrn compiler flags
-#   - Configures source_group for IDE folder view
-#
-# Example:
-#   SETUP_LIBRARY(WyvrnLog STATIC)
-#   SETUP_LIBRARY(WyvrnRenderer SHARED ${PLATFORM_GENERATED_SOURCES})
-#   SETUP_LIBRARY(WyvrnCore STATIC EXCLUDE ".*legacy.*" ".*_old\\.cpp")
-function(SETUP_LIBRARY target type)
-    cmake_parse_arguments(_SETUP "" "" "EXCLUDE;SOURCES" ${ARGN})
-    _wyvrn_collect_sources(_sources ${_SETUP_EXCLUDE})
-    list(APPEND _sources ${_SETUP_SOURCES} ${_SETUP_UNPARSED_ARGUMENTS})
-
-    add_library(${target} ${type} ${_sources})
-    _wyvrn_apply_compiler_flags(${target})
-    set(_src_sources "")
-    set(_gen_sources "")
-    foreach(_f IN LISTS _sources)
-        cmake_path(IS_PREFIX CMAKE_CURRENT_SOURCE_DIR "${_f}" NORMALIZE _is_under_src)
-        if(_is_under_src)
-            list(APPEND _src_sources "${_f}")
-        else()
-            list(APPEND _gen_sources "${_f}")
-        endif()
-    endforeach()
-    if(_src_sources)
-        source_group(TREE ${CMAKE_CURRENT_SOURCE_DIR} FILES ${_src_sources})
-    endif()
-    if(_gen_sources)
-        source_group("Generated" FILES ${_gen_sources})
-    endif()
-
-    # chroma is a legacy alias namespace; new code should use wyvrn::, but both are provided for compatibility
-    add_library(chroma::${target} ALIAS ${target})
-    add_library(wyvrn::${target}  ALIAS ${target})
-
-    get_target_property(_wyvrn_target_type ${target} TYPE)
-    if(_wyvrn_target_type STREQUAL "INTERFACE_LIBRARY")
-        return()
-    endif()
-
-    target_include_directories(${target} 
-        PUBLIC 
-            $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/${target}>
-            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
-            $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
-    )
-
-endfunction()
-
-# ── SETUP_EXE(target [EXCLUDE pat...] [extra_sources...]) ─────────────────────
-# Creates an executable target from all sources in CMAKE_CURRENT_SOURCE_DIR,
-# with platform-specific HAL sources included automatically.
-# On Windows and Xbox the WIN32 subsystem flag is set automatically.
-#
-# Arguments:
-#   target         CMake target name
-#   EXCLUDE        (optional) One or more regex patterns; matched files are
-#                  excluded from the auto-collected source list
-#   extra_sources  (optional) Additional source files to append (positional,
-#                  or via the SOURCES keyword)
-#
-# Example:
-#   SETUP_EXE(ChromaApp)
-#   SETUP_EXE(ChromaTool ${TOOL_GENERATED_SOURCES})
-#   SETUP_EXE(ChromaTool EXCLUDE ".*test_stub.*" SOURCES ${EXTRA})
-function(SETUP_EXE target)
-    cmake_parse_arguments(_SETUP "" "" "EXCLUDE;SOURCES" ${ARGN})
-    _wyvrn_collect_sources(_sources ${_SETUP_EXCLUDE})
-    list(APPEND _sources ${_SETUP_SOURCES} ${_SETUP_UNPARSED_ARGUMENTS})
-
-    if(WYVRN_PLATFORM_WINDOWS OR WYVRN_PLATFORM_XBOX)
-        add_executable(${target} WIN32 ${_sources})
-    else()
-        add_executable(${target} ${_sources})
-    endif()
-
-    _wyvrn_apply_compiler_flags(${target})
-    source_group(TREE ${CMAKE_CURRENT_SOURCE_DIR} FILES ${_sources})
-endfunction()
+# ── Internal helper ───────────────────────────────────────────────────────────
+# Collects all sources for the calling directory in three layers:
+#
+#   1. General sources  — all .cpp/.h/.hpp under CMAKE_CURRENT_SOURCE_DIR,
+#                         excluding HAL/, Platform/, and include/HAL|Platform/
+#   2. HAL common       — files sitting directly (non-recursive) in any HAL/ or
+#                         Platform/ root; these are platform-neutral shared headers
+#   3. HAL layered      — recursive sources from each applicable subdirectory,
+#                         resolved in order: family → leaf
+#
+#                         Family tiers (from variables.cmake derived vars):
+#                           microsoft  — Windows + Xbox
+#                           unix       — Linux + SteamOS + Android + Darwin + PlayStation
+#                           darwin     — macOS + iOS
+#                           playstation— PS4 + PS5
+#
+#                         Leaf dirs:
+#                           win  xbox  linux  steamos  mac  ios
+#                           android  ps4  ps5
+#
+#                         Search roots for both family and leaf dirs:
+#                           HAL/  Platform/  src/HAL/  src/Platform/
+#                           include/HAL/  include/Platform/
+#
+# Result is written to the variable named by <out_var> in the caller's scope.
+# Any additional arguments are treated as regex patterns to exclude from all source lists.
+function(_wyvrn_collect_sources out_var)
+    set(_extra_excludes ${ARGN})
+    file(GLOB_RECURSE _sources
+        "${CMAKE_CURRENT_SOURCE_DIR}/*.cpp"
+        "${CMAKE_CURRENT_SOURCE_DIR}/*.h"
+        "${CMAKE_CURRENT_SOURCE_DIR}/*.hpp"
+    )
+    list(FILTER _sources EXCLUDE REGEX ".*[/\\\\]HAL[/\\\\].*")
+    list(FILTER _sources EXCLUDE REGEX ".*[/\\\\]Platform[/\\\\].*")
+    list(FILTER _sources EXCLUDE REGEX ".*[/\\\\]tests[/\\\\].*")
+    list(FILTER _sources EXCLUDE REGEX ".*[/\\\\]vendors[/\\\\].*")
+    list(FILTER _sources EXCLUDE REGEX ".*[/\\\\]wyvrn_internal[/\\\\].*")
+    list(FILTER _sources EXCLUDE REGEX ".*[/\\\\]build[/\\\\].*")
+    list(FILTER _sources EXCLUDE REGEX ".*[/\\\\]output[/\\\\].*")
+    
+    # Shared / platform-neutral files sitting directly in any HAL/ or Platform/ root
+    file(GLOB _hal_common
+        "${CMAKE_CURRENT_SOURCE_DIR}/HAL/*.*"
+        "${CMAKE_CURRENT_SOURCE_DIR}/Platform/*.*"
+        "${CMAKE_CURRENT_SOURCE_DIR}/src/HAL/*.*"
+        "${CMAKE_CURRENT_SOURCE_DIR}/src/Platform/*.*"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/HAL/*.*"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/Platform/*.*"
+    )
+
+    # Build an ordered list of HAL subdirectory names to search: family first, then leaf.
+    # Each entry is searched under every search root listed in _hal_roots below.
+    set(_plat_dirs)
+
+    # ── Family tiers ──────────────────────────────────────────────────────────
+    if(WYVRN_PLATFORM_MICROSOFT)
+        list(APPEND _plat_dirs microsoft)
+    endif()
+    if(WYVRN_PLATFORM_UNIX)
+        list(APPEND _plat_dirs unix)
+    endif()
+    if(WYVRN_PLATFORM_DARWIN)
+        list(APPEND _plat_dirs darwin)
+    endif()
+    if(WYVRN_PLATFORM_PLAYSTATION)
+        list(APPEND _plat_dirs playstation)
+    endif()
+
+    # ── Leaf tiers ────────────────────────────────────────────────────────────
+    # Exactly one leaf is set by variables.cmake; SteamOS also gets a linux pass
+    # first (most SteamOS-targeting code lives there) then a steamos overlay pass.
+    if(WYVRN_PLATFORM_WINDOWS)
+        list(APPEND _plat_dirs win)
+    elseif(WYVRN_PLATFORM_XBOX)
+        list(APPEND _plat_dirs xbox)
+    elseif(WYVRN_PLATFORM_PS5)
+        list(APPEND _plat_dirs ps5)
+    elseif(WYVRN_PLATFORM_PS4)
+        list(APPEND _plat_dirs ps4)
+    elseif(WYVRN_PLATFORM_ANDROID)
+        list(APPEND _plat_dirs android)
+    elseif(WYVRN_PLATFORM_IOS)
+        list(APPEND _plat_dirs ios)
+    elseif(WYVRN_PLATFORM_MACOS)
+        list(APPEND _plat_dirs mac)
+    elseif(WYVRN_PLATFORM_STEAMOS)
+        list(APPEND _plat_dirs linux steamos)
+    elseif(WYVRN_PLATFORM_LINUX)
+        list(APPEND _plat_dirs linux)
+    endif()
+
+    # All directory roots that may contain HAL/<subdir>/ trees
+    set(_hal_roots
+        "${CMAKE_CURRENT_SOURCE_DIR}/HAL"
+        "${CMAKE_CURRENT_SOURCE_DIR}/Platform"
+        "${CMAKE_CURRENT_SOURCE_DIR}/src/HAL"
+        "${CMAKE_CURRENT_SOURCE_DIR}/src/Platform"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/HAL"
+        "${CMAKE_CURRENT_SOURCE_DIR}/include/Platform"
+    )
+
+    set(_hal_plat)
+    foreach(_dir IN LISTS _plat_dirs)
+        foreach(_root IN LISTS _hal_roots)
+            file(GLOB_RECURSE _tmp "${_root}/${_dir}/*.*")
+            list(APPEND _hal_plat ${_tmp})
+        endforeach()
+    endforeach()
+
+    foreach(_pat IN LISTS _extra_excludes)
+        list(FILTER _sources    EXCLUDE REGEX "${_pat}")
+        list(FILTER _hal_common EXCLUDE REGEX "${_pat}")
+        list(FILTER _hal_plat   EXCLUDE REGEX "${_pat}")
+    endforeach()
+
+    set(${out_var} ${_sources} ${_hal_common} ${_hal_plat} PARENT_SCOPE)
+endfunction()
+
+# ── Internal helper ───────────────────────────────────────────────────────────
+# Applies the standard Wyvrn compiler flags to <target>.
+function(_wyvrn_apply_compiler_flags target)
+    get_target_property(_wyvrn_target_type ${target} TYPE)
+    if(_wyvrn_target_type STREQUAL "INTERFACE_LIBRARY")
+        return()
+    endif()
+    target_compile_options(${target} PRIVATE ${WYVRN_COMPILER_FLAGS})
+    target_compile_options(${target} PRIVATE $<$<CONFIG:Debug>:${WYVRN_COMPILER_FLAGS_DEBUG}>)
+    target_compile_options(${target} PRIVATE $<$<CONFIG:Release>:${WYVRN_COMPILER_FLAGS_RELEASE}>)
+endfunction()
+
+# ── SETUP_LIBRARY(target type [EXCLUDE pat...] [extra_sources...]) ────────────
+# Creates a library target from all sources in CMAKE_CURRENT_SOURCE_DIR,
+# with platform-specific HAL sources included automatically.
+#
+# Arguments:
+#   target         CMake target name
+#   type           Library type: STATIC | SHARED | INTERFACE | OBJECT
+#   EXCLUDE        (optional) One or more regex patterns; matched files are
+#                  excluded from the auto-collected source list
+#   extra_sources  (optional) Additional source files to append (positional,
+#                  or via the SOURCES keyword)
+#
+# Side effects:
+#   - Registers aliases  chroma::<target>  and  wyvrn::<target>
+#   - Applies standard Wyvrn compiler flags
+#   - Configures source_group for IDE folder view
+#
+# Example:
+#   SETUP_LIBRARY(WyvrnLog STATIC)
+#   SETUP_LIBRARY(WyvrnRenderer SHARED ${PLATFORM_GENERATED_SOURCES})
+#   SETUP_LIBRARY(WyvrnCore STATIC EXCLUDE ".*legacy.*" ".*_old\\.cpp")
+function(SETUP_LIBRARY target type)
+    cmake_parse_arguments(_SETUP "" "" "EXCLUDE;SOURCES" ${ARGN})
+    _wyvrn_collect_sources(_sources ${_SETUP_EXCLUDE})
+    list(APPEND _sources ${_SETUP_SOURCES} ${_SETUP_UNPARSED_ARGUMENTS})
+
+    add_library(${target} ${type} ${_sources})
+    _wyvrn_apply_compiler_flags(${target})
+    set(_src_sources "")
+    set(_gen_sources "")
+    foreach(_f IN LISTS _sources)
+        cmake_path(IS_PREFIX CMAKE_CURRENT_SOURCE_DIR "${_f}" NORMALIZE _is_under_src)
+        if(_is_under_src)
+            list(APPEND _src_sources "${_f}")
+        else()
+            list(APPEND _gen_sources "${_f}")
+        endif()
+    endforeach()
+    if(_src_sources)
+        source_group(TREE ${CMAKE_CURRENT_SOURCE_DIR} FILES ${_src_sources})
+    endif()
+    if(_gen_sources)
+        source_group("Generated" FILES ${_gen_sources})
+    endif()
+
+    # chroma is a legacy alias namespace; new code should use wyvrn::, but both are provided for compatibility
+    add_library(chroma::${target} ALIAS ${target})
+    add_library(wyvrn::${target}  ALIAS ${target})
+
+    get_target_property(_wyvrn_target_type ${target} TYPE)
+    if(_wyvrn_target_type STREQUAL "INTERFACE_LIBRARY")
+        return()
+    endif()
+
+    target_include_directories(${target} 
+        PUBLIC 
+            $<BUILD_INTERFACE:${CMAKE_BINARY_DIR}/${target}>
+            $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+            $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+    )
+
+endfunction()
+
+# ── SETUP_EXE(target [EXCLUDE pat...] [extra_sources...]) ─────────────────────
+# Creates an executable target from all sources in CMAKE_CURRENT_SOURCE_DIR,
+# with platform-specific HAL sources included automatically.
+# On Windows and Xbox the WIN32 subsystem flag is set automatically.
+#
+# Arguments:
+#   target         CMake target name
+#   EXCLUDE        (optional) One or more regex patterns; matched files are
+#                  excluded from the auto-collected source list
+#   extra_sources  (optional) Additional source files to append (positional,
+#                  or via the SOURCES keyword)
+#
+# Example:
+#   SETUP_EXE(ChromaApp)
+#   SETUP_EXE(ChromaTool ${TOOL_GENERATED_SOURCES})
+#   SETUP_EXE(ChromaTool EXCLUDE ".*test_stub.*" SOURCES ${EXTRA})
+function(SETUP_EXE target)
+    cmake_parse_arguments(_SETUP "" "" "EXCLUDE;SOURCES" ${ARGN})
+    _wyvrn_collect_sources(_sources ${_SETUP_EXCLUDE})
+    list(APPEND _sources ${_SETUP_SOURCES} ${_SETUP_UNPARSED_ARGUMENTS})
+
+    if(WYVRN_PLATFORM_WINDOWS OR WYVRN_PLATFORM_XBOX)
+        add_executable(${target} WIN32 ${_sources})
+    else()
+        add_executable(${target} ${_sources})
+    endif()
+
+    _wyvrn_apply_compiler_flags(${target})
+    source_group(TREE ${CMAKE_CURRENT_SOURCE_DIR} FILES ${_sources})
+endfunction()