addLibrary.cmake

function(addLibrary)
    cmake_parse_arguments(arg
            "STATIC;SHARED;MULTI_LIBS;PRIMARY;EXECUTABLE"
            "NAME;PATH;VERSION;LINK;HEADER_VISIBILITY;SOURCE_VISIBILITY;MODULE_VISIBILITY;CXX_MODULES_FILE_SET;HEADERS_FILE_SET"
            "HEADERS;SOURCES;SOURCE;MODULES;LIBS;DEPENDS;USES;BASE_DIRS;CXX_BASE_DIRS"
            ${ARGN}
    )
    get_filename_component(LIB_PATH ${CMAKE_PARENT_LIST_FILE} DIRECTORY)
    get_filename_component(LIB_NAME ${LIB_PATH} NAME)

    if (NOT arg_HEADERS_FILE_SET)
        set(arg_HEADERS_FILE_SET "HEADERS")
    endif ()

    if (NOT arg_CXX_MODULES_FILE_SET)
        set(arg_CXX_MODULES_FILE_SET "CXX_MODULES")
    endif ()

    if (NOT arg_HEADER_VISIBILITY)
        set(arg_HEADER_VISIBILITY "PUBLIC")
    else ()
        string(TOUPPER ${arg_HEADER_VISIBILITY} arg_HEADER_VISIBILITY)
    endif ()

    if (NOT arg_SOURCE_VISIBILITY)
        set(arg_SOURCE_VISIBILITY "PRIVATE")
    else ()
        string(TOUPPER ${arg_SOURCE_VISIBILITY} arg_SOURCE_VISIBILITY)
    endif ()

    if (NOT arg_MODULE_VISIBILITY)
        set(arg_MODULE_VISIBILITY "PUBLIC")
    else ()
        string(TOUPPER ${arg_MODULE_VISIBILITY} arg_MODULE_VISIBILITY)
    endif ()

    if (arg_SOURCE)
        list(APPEND arg_SOURCES ${arg_SOURCE})
    endif ()

    if (arg_LIBS)
        list(APPEND arg_DEPENDS ${arg_LIBS})
    endif ()

    if (NOT arg_NAME)
        set(arg_NAME ${LIB_NAME})
    endif ()

    if (NOT arg_PATH)
        set(arg_PATH ${LIB_PATH})
    endif ()

    if (NOT arg_VERSION)
        set(arg_VERSION "1.0.0")
    endif ()

    if (NOT arg_BASE_DIRS)
        set(arg_BASE_DIRS ${HEADER_BASE_DIRS})
    endif ()

    if (NOT arg_CXX_BASE_DIRS)
        set(arg_CXX_BASE_DIRS "${CMAKE_CURRENT_SOURCE_DIR}")
    endif ()

    string(TOUPPER "${arg_USES}" arg_USES)

    if (NOT arg_EXECUTABLE)
        if (arg_LINK MATCHES SHARED)
            set(arg_SHARED ON)
            set(arg_STATIC OFF)
            set(glurg " SHARED")
        elseif (arg_LINK MATCHES STATIC)
            set(arg_SHARED OFF)
            set(arg_STATIC ON)
            set(glurg " STATIC")
        else ()
            if (arg_STATIC AND arg_SHARED)
                message(FATAL_ERROR "Only 'PLUGIN SHARED', 'SHARED', or 'STATIC' allowed")
            elseif (arg_SHARED)
                set(arg_LINK "SHARED")
                set(glurg " SHARED")
            else ()
                set(arg_LINK "STATIC")
                set(glurg " STATIC")
            endif ()
        endif ()
    else ()
        set(arg_SHARED OFF)
        set(arg_STATIC OFF)
        set(glurg "")

    endif ()

    if (arg_EXECUTABLE)
        set(PLUGIN_ENNUCIATOR "executable app")
    else ()
        set(PLUGIN_ENNUCIATOR "library")
    endif ()

    # Diagnostic logging
    string(LENGTH ${arg_NAME} THIS_LEN)
    if (NOT DEFINED LONGEST_LIBRARY_NAME_SO_FAR)
        string(LENGTH "Appearance" LONGEST_LIBRARY_NAME_SO_FAR)
        set(LONGEST_LIBRARY_NAME_SO_FAR ${LONGEST_LIBRARY_NAME_SO_FAR} CACHE STRING "")
    endif ()
    if (${THIS_LEN} GREATER ${LONGEST_LIBRARY_NAME_SO_FAR})
        set(LONGEST_LIBRARY_NAME_SO_FAR ${THIS_LEN})
        set(LONGEST_LIBRARY_NAME_SO_FAR ${LONGEST_LIBRARY_NAME_SO_FAR} CACHE STRING "" FORCE)
    endif ()
    math(EXPR NUM_SPACES_REQD "${LONGEST_LIBRARY_NAME_SO_FAR} - ${THIS_LEN}")
    if (${NUM_SPACES_REQD} LESS 0)
        set(NUM_SPACES_REQD 0)
    endif ()
    set(GAP_CHARS "                                                ")
    string(SUBSTRING "${GAP_CHARS}" 0 ${NUM_SPACES_REQD} THE_SPACES)
    message("Creating${glurg} ${PLUGIN_ENNUCIATOR} ${THE_SPACES}'${arg_NAME}' Version ${arg_VERSION}")

    string(TOLOWER ${arg_NAME} arg_NAME_LC)
    string(TOLOWER ${APP_VENDOR} arg_VENDOR_LC)

    # Create the library (maybe)
    if (NOT TARGET ${arg_NAME})
        if (arg_EXECUTABLE)
            add_executable(${arg_NAME} ${PlatformFlag})
        else ()
            add_library(${arg_NAME} ${arg_LINK})
            if (arg_PRIMARY)
                add_library(${APP_VENDOR}::${APP_NAME} ALIAS ${arg_NAME})
            endif ()
        endif ()
    endif ()

    # Add sources only to the new library
    if (arg_HEADERS)
        # Public headers from the source/include tree
        # Use generator expressions in BASE_DIRS so build-tree (source) paths do not leak into the install export
        target_sources(${arg_NAME}
                ${arg_HEADER_VISIBILITY}
                FILE_SET ${arg_HEADERS_FILE_SET} TYPE HEADERS
                BASE_DIRS ${arg_BASE_DIRS}
                FILES ${arg_HEADERS}
        )
    endif ()
    if (arg_SOURCES)
        target_sources(${arg_NAME}
                ${arg_SOURCE_VISIBILITY}
                ${arg_SOURCES}
        )
    endif ()
    if (arg_MODULES)

        target_sources(${arg_NAME}
                ${arg_MODULE_VISIBILITY}
                FILE_SET ${arg_CXX_MODULES_FILE_SET} TYPE CXX_MODULES
                BASE_DIRS ${arg_CXX_BASE_DIRS}
                FILES ${arg_MODULES}
        )

        set_source_files_properties(${arg_MODULES} PROPERTIES
                # PCH must not be applied to C++ module interface units (.ixx):
                # Clang 21 processes the global module fragment with separate include
                # state from the PCH. _LIBCPP_HIDE_FROM_ABI functions tagged with
                # [[abi_tag("ne210105")]] (new in libc++ 21) end up defined twice in
                # the same compilation unit — once from the PCH and once from the
                # module's global fragment — producing "definition with same mangled
                # name" hard errors. Disabling PCH for module files is the correct
                # fix; the wx_pch.h comment already noted this intent.
                SKIP_PRECOMPILE_HEADERS ON
                CXX_SCAN_FOR_MODULES ON
        )
    endif ()

    # Configure the library
    if (arg_EXECUTABLE)
        set(LIB_SUF ${CMAKE_EXECUTABLE_SUFFIX})
        set(LIB_OUTPUT_NAME "${arg_NAME}")
    else ()
        set(LIB_PRE ${CMAKE_${arg_LINK}_LIBRARY_PREFIX})
        set(LIB_SUF ${CMAKE_${arg_LINK}_LIBRARY_SUFFIX})
        set(LIB_OUTPUT_NAME "${arg_VENDOR_LC}_${arg_NAME_LC}")
    endif ()

    # SO_VERSION may be empty if framework.cmake ran before AppSpecific.cmake set APP_VERSION
    # (include_guard fires before per-library setup). Derive from arg_VERSION as a fallback.
    set(_hs_so_ver "${SO_VERSION}")
    if (NOT _hs_so_ver AND arg_VERSION)
        SplitAt("${arg_VERSION}" "." _hs_so_ver _hs_so_dc)
        unset(_hs_so_dc)
    endif ()

    # @formatter:off
    set_target_properties(${arg_NAME} PROPERTIES
            CXX_EXTENSIONS              OFF
            CXX_MODULE_STD              ON
            CXX_STANDARD                23
            CXX_STANDARD_REQUIRED       ON
            OUTPUT_NAME                 ${LIB_OUTPUT_NAME}
            POSITION_INDEPENDENT_CODE   ON
            PREFIX                      "${LIB_PRE}"
            SUFFIX                      "${LIB_SUF}"
    )

    # CMake's CXX_MODULE_STD support (still experimental as of 4.x) creates a
    # real "@cmake_cxx_std" STATIC_LIBRARY target (lib@cmake_cxx_std.a, BMI at
    # CMakeFiles/@cmake_cxx_std.dir/std.pcm in this CMake/generator version)
    # that builds the `std`/`std.compat` BMIs, and correctly wires
    # `-fmodule-file=std=...` (via the per-TU dyndep-generated modmap) into any
    # TU in THIS SAME CMake project that directly writes `import std;`. It
    # does NOT do this for a module consumed from an ALREADY-INSTALLED package
    # via find_package() (e.g. MyCare importing one of Core's/Gfx's modules
    # that internally uses `import std;`) -- the cross-package dependency scan
    # doesn't see into the already-built BMI to discover the std dependency,
    # so the consumer's compile fails with "failed to find module file for
    # module 'std'" for any TU that doesn't itself write `import std;` (e.g.
    # one that only does `export import Database;`). Two things are needed to
    # fix that case: (1) the explicit `-fmodule-file=std=...` flag below,
    # since CMake's own scanner never adds it for a transitively-only
    # dependency; and (2) an explicit build-order dependency on `@cmake_cxx_std`
    # itself, since the flag alone races against that target's compile of
    # std.cc/std.compat.cc -- without it, a TU whose own dyndep scan doesn't
    # request `std` (so gets no order-only edge onto the real BMI) can start
    # compiling before std.pcm exists. Harmless to add unconditionally -- a TU
    # that doesn't reference `std` simply ignores an unused -fmodule-file.
    #
    # KNOWN REMAINING ISSUE (2026-09-24): this flag/dependency only fixes the
    # ordering/existence problem. It does NOT fix module-BMI *identity*
    # mismatches: CMake's per-directory-scope std synthesis is not reproducible
    # across separate compiles of the same input (verified by hand: sha256 of
    # the "std" BMI differed across per-scope copies within a single Libs
    # build), and Clang's module deserializer crashes (ASTDeclReader::UpdateDecl,
    # SIGSEGV) rather than erroring cleanly when a consumer is hand a different
    # "std" instance than a dependency was actually compiled against. This
    # surfaces as an intermittent crash in MyCare compiling .ixx files that
    # transitively touch Core/Gfx modules (e.g. DBase.ixx importing Database).
    # See the wip/shared-std-module branch in this repo for an in-progress fix
    # (a single explicit shared "std" target instead of relying on
    # CXX_MODULE_STD's per-scope synthesis) -- not yet complete: it resolves
    # this for Core's own modules but Gfx's cross-target import of Core's
    # OTHER modules hits an analogous mismatch via a different CMake mechanism.
    #
    # Revisit once CMake's cross-package import-std propagation matures, and
    # re-verify the "@cmake_cxx_std.dir" path/target name against whatever
    # CMake version is in use -- both are internal/undocumented and have
    # already changed once across CMake versions (previously
    # "__cmake_cxx_std_23.dir", silently broken by a CMake upgrade).
    target_compile_options(${arg_NAME} PRIVATE
            "-fmodule-file=std=${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/@cmake_cxx_std.dir/std.pcm"
    )
    if (TARGET "@cmake_cxx_std")
        add_dependencies(${arg_NAME} "@cmake_cxx_std")
    endif ()

    # VERSION drives CMake's versioned-filename + symlink behavior on its own,
    # independent of SOVERSION/NO_SONAME, so it must stay off executable targets.
    if (APP_TYPE STREQUAL Executable)
        set_target_properties(${arg_NAME} PROPERTIES
            NO_SONAME                   ON)
    else ()
        set_target_properties(${arg_NAME} PROPERTIES
            VERSION                     "${arg_VERSION}"
            SOVERSION                   "${_hs_so_ver}")
    endif ()
    unset(_hs_so_ver)

    # Explicitly add the compile feature to help the exporter
    target_compile_features(${arg_NAME} PUBLIC cxx_std_23)

    # Compile and link options
    string(TOUPPER ${arg_NAME} arg_NAME_UC)
    target_compile_definitions(${arg_NAME}      PUBLIC  ${arg_NAME}_EXPORTS ${HS_DefinesList})
    target_compile_options(${arg_NAME}          PUBLIC  ${HS_CompileOptionsList})

    # Expose only install-time include paths to consumers; keep build-time includes private to avoid leaking
    target_include_directories(${arg_NAME}
            PRIVATE
            ${HS_IncludePathsList}
            PUBLIC
            $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
    )
    # Third-party/fetched package headers go in a separate SYSTEM call (the SYSTEM keyword only
    # takes effect as the first argument to target_include_directories) so -Werror and warnings
    # never fire on vendored code.
    target_include_directories(${arg_NAME} SYSTEM PRIVATE ${HS_SystemIncludePathsList})
    target_link_directories(${arg_NAME}         PRIVATE $<BUILD_INTERFACE:${HS_LibraryPathsList}>)
    target_link_libraries(${arg_NAME}           PRIVATE ${arg_DEPENDS})
    target_link_options(${arg_NAME}             PUBLIC  ${HS_LinkOptionsList})

    # WIN32 adds -mwindows (GUI subsystem); override to console in dev configs so
    # stdout/stderr are visible. GNU ld / lld (GNU compat) require GNU PE flags.
    if (WIN32 AND arg_EXECUTABLE)
        target_link_options(${arg_NAME} PRIVATE
                "$<$<OR:$<CONFIG:Debug>,$<CONFIG:RelWithDebInfo>>:-Wl,--subsystem,console>"
                "$<$<OR:$<CONFIG:Debug>,$<CONFIG:RelWithDebInfo>>:-Wl,--entry,WinMainCRTStartup>"
        )
    endif ()

    # Link Core
    if (CORE IN_LIST arg_USES)
        target_link_libraries(${arg_NAME}       PRIVATE ${APP_VENDOR}::Core)
        add_dependencies(${arg_NAME}                    ${APP_VENDOR}::Core)
    endif ()

    # Link Gfx
    if (GFX IN_LIST arg_USES)
        target_link_libraries(${arg_NAME}       PRIVATE ${APP_VENDOR}::Gfx)
        add_dependencies(${arg_NAME}                    ${APP_VENDOR}::Gfx)
    endif ()

    # ── Precompile Headers ──────────────────────────────────────────────────────
    #
    # ALL platforms (WIN32, LINUX, APPLE):
    #   A single shared wx_pch.gch binary is built once (in the Gfx builder role)
    #   and injected into every compilation — including .ixx module units — via an
    #   explicit -include-pch flag (target_compile_options, bypasses
    #   SKIP_PRECOMPILE_HEADERS / DISABLE_PRECOMPILE_HEADERS).  Because all Gfx BMIs
    #   and all downstream consumer TUs share the same PCH binary, Clang loads the
    #   SLoc entries for wx / SDK / STL headers ONCE rather than once per BMI.
    #   Without this, loading 60+ Gfx BMIs exhausts Clang's 2 GB SLoc limit.
    #
    #   On macOS (libc++) the PCH is built with -D_LIBCPP_NO_ABI_TAG to match the
    #   Gfx BMI compile flags (Gfx sets that define as a PRIVATE target definition;
    #   it is not captured in the directory-level _hs_pch_dir_D sweep, so it must be
    #   appended explicitly).  This keeps the abi_tag state consistent across all TUs
    #   and avoids "definition with same mangled name" ODR conflicts in libc++ 21+.
    #
    #   PCH binary location — ONE path for everyone:
    #     ${CMAKE_INSTALL_PREFIX}/lib/cmake/pch/${APP_VENDOR}/wx_pch.gch
    #   Gfx (builder) writes the PCH DIRECTLY there; MyCare (consumer) reads it from
    #   there.  Using the same path in both roles is mandatory: Clang embeds the PCH
    #   path in every compiled BMI, and if a consumer provides the PCH at a different
    #   path (even a bit-for-bit copy), Clang loads both PCH files simultaneously and
    #   sees duplicate declarations for all STL/wx types → ODR errors.
    # ────────────────────────────────────────────────────────────────────────────

    if ( (WIN32 OR LINUX OR APPLE) AND GUI IN_LIST arg_USES AND GUI IN_LIST APP_FEATURES)
        # CRITICAL: all targets — builders (Gfx) AND consumers (MyCare) — must use the
        # PCH at the SAME FILE PATH.  Clang embeds the PCH path in every BMI (.pcm).
        # If consumers provide a PCH at a different path (even a binary-identical copy),
        # Clang loads BOTH PCH files and sees duplicate declarations for all STL/wx types
        # (e.g. std::basic_string_view) → "definition provided earlier" ODR errors.
        # Fix: Gfx writes the PCH directly to the staged location; everyone references
        # the same path.
        set(_hs_pch_dir "${CMAKE_INSTALL_PREFIX}/lib/cmake/pch/${APP_VENDOR}")
        set(_hs_pch_bin "${_hs_pch_dir}/wx_pch.gch")

        if (NOT GFX IN_LIST arg_USES)
            # This is the wx-provider (Gfx main library). Build the shared PCH
            # binary here; plugins and consumers depend on it transitively.
            if (NOT TARGET _hs_wx_pch)
                set(_hs_wx_I "")
                foreach(_inc IN LISTS HS_wxIncludePaths)
                    if(_inc)
                        list(APPEND _hs_wx_I "-I${_inc}")
                    endif()
                endforeach()
                set(_hs_wx_D "")
                foreach(_def IN LISTS HS_wxDefines)
                    if(NOT "${_def}" MATCHES "^-D")
                        list(APPEND _hs_wx_D "-D${_def}")
                    else()
                        list(APPEND _hs_wx_D "${_def}")
                    endif()
                endforeach()
                # Target triple for cross-compile (empty on native builds)
                set(_hs_pch_target_flag "")
                if(CMAKE_CXX_COMPILER_TARGET)
                    set(_hs_pch_target_flag "--target=${CMAKE_CXX_COMPILER_TARGET}")
                endif()
                # Toolchain-provided sysroot/system-include flags (e.g. -nostdinc + -isystem)
                separate_arguments(_hs_pch_cxx_flags UNIX_COMMAND "${CMAKE_CXX_FLAGS}")
                # The PCH must be built with the same optimization level as its
                # consumers.  Do not hard-code a Release level here: this project
                # uses -O3 in CMAKE_CXX_FLAGS_RELEASE, and Clang records the level
                # in the .gch metadata and rejects a consumer using another level.
                # Debug has no explicit optimization flag by default, which is
                # equivalent to -O0.
                set(_hs_pch_release_opt "-O0")
                if ("${CMAKE_CXX_FLAGS_RELEASE}" MATCHES "(^| )(-O[0-3s]|-Ofast|-Oz)( |$)")
                    set(_hs_pch_release_opt "${CMAKE_MATCH_2}")
                endif ()
                set(_hs_pch_debug_opt "-O0")
                if ("${CMAKE_CXX_FLAGS_DEBUG}" MATCHES "(^| )(-O[0-3s]|-Ofast|-Oz)( |$)")
                    set(_hs_pch_debug_opt "${CMAKE_MATCH_2}")
                endif ()
                # Directory-level compile definitions (e.g. _UCRT, _WIN32_WINNT from toolchain
                # add_compile_definitions — not in CMAKE_CXX_FLAGS)
                get_directory_property(_hs_pch_dir_defs COMPILE_DEFINITIONS)
                set(_hs_pch_dir_D "")
                foreach(_def IN LISTS _hs_pch_dir_defs)
                    if(_def)
                        if(NOT "${_def}" MATCHES "^-D")
                            list(APPEND _hs_pch_dir_D "-D${_def}")
                        else()
                            list(APPEND _hs_pch_dir_D "${_def}")
                        endif()
                    endif()
                endforeach()
                unset(_hs_pch_dir_defs)
                # Platform-specific CRT/codegen flags: MSVC runtime selection on
                # MSVC-ABI Windows; PIC + the DEBUG define GUI targets carry on Linux.
                # MinGW-ABI Windows (WinX cross-compile, or native UCRT64/clang-gnu-driver
                # builds like winllvm) has no msvcrtd/ucrtd import lib, so embedding a
                # --dependent-lib= default-lib directive for it breaks the final link.
                if (WIN32 AND NOT MINGW)
                    set(_hs_pch_crt_flags
                        "-D_DLL" "-D_MT"
                        "-Xclang"
                        "$<IF:$<CONFIG:Debug>,--dependent-lib=msvcrtd,--dependent-lib=msvcrt>")
                else()
                    set(_hs_pch_crt_flags
                        "$<IF:$<CONFIG:Debug>,-DDEBUG,-DNDEBUG>"
                        "-fPIC")
                    if (APPLE)
                        # PCH must match the BMI compile flags: Gfx compiles with _LIBCPP_NO_ABI_TAG
                        # (PRIVATE target define, not captured in _hs_pch_dir_D), so add it explicitly.
                        list(APPEND _hs_pch_crt_flags "-D_LIBCPP_NO_ABI_TAG")
                    endif()
                endif()
                file(MAKE_DIRECTORY "${_hs_pch_dir}")
                add_custom_command(
                    OUTPUT  "${_hs_pch_bin}"
                    COMMAND ${CMAKE_COMMAND} -E make_directory "${_hs_pch_dir}"
                    COMMAND ${CMAKE_CXX_COMPILER}
                            ${_hs_pch_target_flag}
                            ${_hs_pch_cxx_flags}
                            "-std=c++23"
                            "$<IF:$<CONFIG:Debug>,${_hs_pch_debug_opt},${_hs_pch_release_opt}>"
                            "-D$<IF:$<CONFIG:Debug>,_DEBUG,NDEBUG>"
                            ${_hs_pch_crt_flags}
                            ${_hs_pch_dir_D}
                            ${_hs_wx_D}
                            ${_hs_wx_I}
                            ${HS_wxCompilerOptions}
                            "-fno-implicit-modules"
                            "-fno-implicit-module-maps"
                            "-Wno-deprecated-declarations"
                            "-Wno-ignored-attributes"
                            "-x" "c++-header"
                            "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/pch/wx_pch.h"
                            "-o" "${_hs_pch_bin}"
#                    DEPENDS "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/pch/wx_pch.h"
                    COMMENT "Building shared wx PCH -> ${_hs_pch_bin}"
                    VERBATIM
                )
                unset(_hs_pch_target_flag)
                unset(_hs_pch_cxx_flags)
                unset(_hs_pch_debug_opt)
                unset(_hs_pch_release_opt)
                unset(_hs_pch_dir_D)
                unset(_hs_pch_crt_flags)
                add_custom_target(_hs_wx_pch DEPENDS "${_hs_pch_bin}")
                message("_hs_pch_bin is ${_hs_pch_bin}")

                # PCH is written directly to the staged location; no separate install step.
            endif()
        endif()

        # Apply shared PCH to this target's .cpp SOURCES always. Do NOT apply it to
        # .ixx MODULES via target-wide target_compile_options -- Clang requires
        # PCH-identical state between an importer and any BMI it imports, and a
        # target-wide PRIVATE -include-pch makes CMake's cross-target C++20 module
        # support treat every module this target imports from an IN-TREE CMake
        # target (e.g. Gfx importing Core, both built by the SAME configure) as
        # "incompatible", silently recompiling the exporting side's module under
        # this target's PCH. For a Core module Gfx imports, that shadow recompile
        # inherits Gfx's PCH requirement but not Gfx's wx include path (Core rightly
        # has none), so it fails to resolve wx/wx.h -- and even when it doesn't fail
        # outright, it's a wx-tainted recompile of code that's supposed to be
        # unconditionally GUI-free.
        #
        # That risk is specific to in-tree module imports within THIS configure
        # (i.e. building Libs itself, where Gfx imports Core's .ixx as CMake
        # targets in the same build graph). It does NOT apply to a downstream
        # consumer project (MyCare, or any other app) importing Core's/Gfx's
        # modules -- those are already-built, staged BMIs found via
        # -fprebuilt-module-path, not in-tree CMake targets CMake's scanner could
        # ever shadow-recompile. For such a consumer, excluding .ixx from the PCH
        # left it exposed to exactly the failure the PCH exists to prevent: empirically,
        # Clang 22 segfaults deserializing a cross-package BMI (e.g. Core's Database.pcm)
        # from a MyCare .ixx with no PCH applied ("Clang's 2 GB SLoc limit" per the
        # comment above), and the crash disappears once -include-pch is added to that
        # same .ixx compile -- SOMETIMES: see the KNOWN REMAINING ISSUE note above the
        # -fmodule-file=std= flag earlier in this function. This PCH fix and that flag
        # both help but neither is a complete fix on its own; the BMI-identity mismatch
        # is the real root cause and is being addressed on wip/shared-std-module.
        # So scope the .ixx exclusion to Libs' own build only.
        set(_hs_pch_to_ixx OFF)
        if (NOT CMAKE_PROJECT_NAME STREQUAL "Libs")
            set(_hs_pch_to_ixx ON)
        endif ()
        if (arg_SOURCES)
            set_source_files_properties(${arg_SOURCES} PROPERTIES
                    COMPILE_OPTIONS "-include-pch;${_hs_pch_bin}"
            )
        endif()
        if (arg_MODULES AND _hs_pch_to_ixx)
            set_source_files_properties(${arg_MODULES} PROPERTIES
                    COMPILE_OPTIONS "-include-pch;${_hs_pch_bin}"
                    SKIP_PRECOMPILE_HEADERS OFF
            )
        endif()
        unset(_hs_pch_to_ixx)
        if (LINUX)
            # The shared PCH is built -fPIC (Gfx is a shared library). Executable
            # TUs default to -fPIE and Clang's PCH validation rejects the PIC/PIE
            # LangOpts mismatch ("is pie differs").  Appending -fPIC here (after
            # CMake's -fPIE, so it wins) normalizes every PCH consumer to PIC;
            # the executable is still linked -pie, and PIC objects link fine
            # into a PIE binary.
            target_compile_options(${arg_NAME} PRIVATE "-fPIC")
        endif()
        if (TARGET _hs_wx_pch)
            add_dependencies(${arg_NAME} _hs_wx_pch)
        endif()

        unset(_hs_wx_I)
        unset(_hs_wx_D)
    elseif (0)
        # Non-WIN32 or WIN32 non-GUI: STL-only PCH.
        target_precompile_headers(${arg_NAME} PRIVATE
            "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/pch/core_pch.h"
        )
    endif ()

    # Link wxWidgets directly (no Widgets wrapper library)
    if (GUI IN_LIST arg_USES AND GUI IN_LIST APP_FEATURES)
        target_compile_definitions(${arg_NAME}  PRIVATE
            ${HS_wxDefines}
            USING_WIDGETS
            USING_wxWidgets
            _FILE_OFFSET_BITS=64
        )
        if (NOT WIN32 AND NOT LINUX AND NOT APPLE)
            # wx PCH fallback for any future non-WIN32/LINUX/APPLE GUI platform.
            # WIN32, LINUX, and APPLE all use the shared wx_pch.gch built above.
            # Do NOT define WX_PRECOMP — that activates wx's own PCH mechanism and conflicts.
            target_precompile_headers(${arg_NAME} PRIVATE
                "${CMAKE_CURRENT_FUNCTION_LIST_DIR}/pch/wx_pch.h"
            )
        endif ()
        if (${BUILD_TYPE} STREQUAL "Debug")
            target_compile_definitions(${arg_NAME}  PRIVATE DEBUG _DEBUG)
        else ()
            target_compile_definitions(${arg_NAME}  PRIVATE NDEBUG)
        endif ()

        target_compile_options(${arg_NAME}      PRIVATE ${HS_wxCompilerOptions})
        target_include_directories(${arg_NAME}  SYSTEM PRIVATE ${HS_wxIncludePaths})
        target_link_directories(${arg_NAME}     PRIVATE ${HS_wxLibraryPaths})
        if(NOT (WIN32 AND GFX IN_LIST arg_USES))
            # On WIN32, GFX consumers get wx symbols from libhoffsoft_gfx.dll.a
            # (Gfx.dll is built with --export-all-symbols). Linking static wx alongside
            # the import lib produces duplicate symbol errors.
            target_link_libraries(${arg_NAME} PRIVATE ${HS_wxLibraries} ${HS_wxFrameworks})
        endif()
        target_link_options(${arg_NAME}     PRIVATE ${HS_wxLinkOptions})
    endif ()
    # @formatter:on

    if (APPLE AND BUILD_DEBUG)
        add_custom_command(TARGET ${arg_NAME} POST_BUILD
                COMMAND dsymutil "$<TARGET_FILE:${arg_NAME}>"
                COMMENT "Generating ${arg_NAME}.dSYM"
                VERBATIM
        )
    endif ()

    unset(arg_NAME_UC)
    unset(arg_NAME_LC)

endfunction()