fetchContents.cmake

include(FetchContent)

include(${cmake_root}/fetchContentsFns.cmake)
include(${cmake_root}/standardPackageData.cmake)
include(${cmake_root}/sqlish.cmake)

macro(_initializeVars)

    # @formatter:off
    set(FETCHCONTENT_QUIET OFF)

    # __alreadyLocated is CACHE INTERNAL so it persists across reconfigures.
    # Clear it here so each configure session starts fresh — stale entries would
    # cause scanLibraryTargets to skip libs already seen in a prior configure,
    # leaving yaml-cpp / magic_enum / eventpp / wxWidgets out of
    # combinedLibraryComponents and triggering unnecessary FetchContent rebuilds.
    set(__alreadyLocated "" CACHE INTERNAL "" FORCE)

    set(_CompileOptionsList ${${AUE_PREFIX}_CompileOptionsList})
    set(_DefinesList        ${${AUE_PREFIX}_DefinesList})
    set(_DependenciesList   ${${AUE_PREFIX}_DependenciesList})

    set(_IncludePathsList   ${${AUE_PREFIX}_SystemIncludePathsList})
    set(_LibrariesList      ${${AUE_PREFIX}_LibrariesList})
    set(_LibraryPathsList   ${${AUE_PREFIX}_LibraryPathsList})
    set(_LinkOptionsList    ${${AUE_PREFIX}_LinkOptionsList})
    set(_PrefixPathsList    ${${AUE_PREFIX}_PrefixPathsList})

    set(_wxCompilerOptions  ${${AUE_PREFIX}_wxCompilerOptions})
    set(_wxDefines          ${${AUE_PREFIX}_wxDefines})
    set(_wxFrameworks       ${${AUE_PREFIX}_wxFrameworks})
    set(_wxIncludePaths     ${${AUE_PREFIX}_wxIncludePaths})
    set(_wxLibraryPaths     ${${AUE_PREFIX}_wxLibraryPaths})
    set(_wxLibraries        ${${AUE_PREFIX}_wxLibraries})
    # @formatter:on

    list(APPEND pseudoFeatures APPEARANCE PRINT LOGGER)
    list(APPEND noLibPackages googletest)

endmacro()

########################################################################################################################
function(fetchContents)

    _initializeVars()

    set(options HELP)
    set(oneValueArgs PREFIX)
    set(multiValueArgs FEATURES)

    cmake_parse_arguments(AUE "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGV})

    if (AUE_HELP)
        fetchContentsHelp()
        return()
    endif ()
    if (AUE_UNPARSED_ARGUMENTS)
        msg(ALWAYS FATAL_ERROR "Unrecognised arguments passed to fetchContents() : ${AUE_UNPARSED_ARGUMENTS}")
    endif ()

    globalObjSet(GLOBAL_FEATURES "${AUE_FEATURES}")

    CREATE(TABLE allFeatures COLUMNS (${PkgColNames}))
    CREATE(TABLE initialFeatures COLUMNS (${PkgColNames}))
    CREATE(TABLE unifiedFeatures COLUMNS (${PkgColNames}))
    CREATE(TABLE resolvedNames COLUMNS (FslashP FeatureName PackageName HasPrereqs))

    msg()

    foreach (DRY_RUN IN ITEMS ON OFF)
        initialiseFeatureHandlers(${DRY_RUN})
        createStandardPackageData(${DRY_RUN})
        runPackageCallbacks(${DRY_RUN})
        msg()
    endforeach ()

    globalObjGet(GLOBAL_FEATURES _FEATURES)
    preProcessFeatures("${_FEATURES}" allFeatures userPackages)
    SELECT(COUNT AS numPackages FROM userPackages)
    set(aix 0)
    set(_APP_FEATURES)

    while (aix LESS numPackages)
        inc(aix)
        set(pkgIndex ${aix})

        # Get user's selected package
        SELECT(ROW AS _uPackage FROM userPackages WHERE ROWID = ${pkgIndex})

        list(GET _uPackage ${FIXName} _uFeatureName)
        list(GET _uPackage ${FIXPkgName} _uPackageName)
        list(GET _uPackage ${FIXNamespace} _uNS)

        # Get corresponding system package
        SELECT(ROW AS _sPackage FROM allFeatures WHERE "FeatureName" = "${_uFeatureName}" AND "PackageName" = "${_uPackageName}")

        list(GET _sPackage ${FIXName} _sFeatureName)
        list(GET _sPackage ${FIXPkgName} _sPackageName)
        list(GET _sPackage ${FIXKind} _sKind)

        # Integrity check
        if (NOT _uFeatureName STREQUAL "${_sFeatureName}")
            msg(ALWAYS FATAL_ERROR "Internal error: FC01 - Feature name mismatch \"${_uFeatureName}\" vs \"${_sFeatureName}\"")
        endif ()
        if (NOT _uPackageName STREQUAL "${_sPackageName}")
            msg(ALWAYS FATAL_ERROR "Internal error: FC02 - Package name mismatch \"${_uPackageName}\" vs \"${_sPackageName}\"")
        endif ()

        # Where we manipulate the feature to be a union of the _uPackage requirements (if any)
        # and system requirements (if any)

        # If we are here, we have the users    feature and options in ${_uPackage}
        # and we have the corresponding system feature and options in ${_sPackage}
        # The merged feature will be in ${wip}

        set(wip "${_sPackage}")
        _hs_sql_fields_to_storage(wip wip)

        unset(_uPkg)
        unset(_sPkg)
        unset(_uArgs)
        unset(_sArgs)
        unset(_args)
        unset(_uComps)
        unset(_sComps)
        unset(_comps)

        # Step 1. Merge Args
        list(GET _uPackage ${FIXArgs} _uArgs)
        list(GET _sPackage ${FIXArgs} _sArgs)


        if (NOT "${_uArgs}" STREQUAL "${_sArgs}")
            string(REPLACE "${_TOK_LIST_SEP}" ";" _uArgs "${_uArgs}")
            string(REPLACE "${_TOK_LIST_SEP}" ";" _sArgs "${_sArgs}")
            if (REQUIRED IN_LIST _sArgs AND OPTIONAL IN_LIST _uArgs)
                list(REMOVE_ITEM _uArgs OPTIONAL)
            elseif (REQUIRED IN_LIST _uArgs AND OPTIONAL IN_LIST _sArgs)
                list(REMOVE_ITEM _sArgs OPTIONAL)
            endif ()
            list(APPEND _sArgs ${_uArgs})
            list(REMOVE_DUPLICATES _sArgs)
            string(JOIN "${_TOK_LIST_SEP}" _args ${_sArgs})

            if (NOT _args)
                set(_args ${_TOK_EMPTY_FIELD})
            endif ()
            list(REMOVE_AT wip ${FIXArgs})
            list(INSERT wip ${FIXArgs} "${_args}")
        endif ()

        # Step 2. Merge Components (FIND_PACKAGE_ARGS COMPONENTS checked later)
        list(GET _uPackage ${FIXComponents} _uComps)
        list(GET _sPackage ${FIXComponents} _sComps)
        if (NOT "${_uComps}" STREQUAL "${_sComps}")
            string(REPLACE "${_TOK_LIST_SEP}" ";" _uComps "${_uComps}")
            string(REPLACE "${_TOK_LIST_SEP}" ";" _sComps "${_sComps}")
            list(APPEND _sComps ${_uComps})
            list(REMOVE_DUPLICATES _sComps)
            string(JOIN "${_TOK_LIST_SEP}" _comps ${_sComps})
            if (NOT _comps)
                set(_comps ${_TOK_EMPTY_FIELD})
            endif ()
            list(REMOVE_AT wip ${FIXComponents})
            list(INSERT wip ${FIXComponents} "${_comps}")
        endif ()

        # Step 3. Remove prerequisites from libraries (they are not used at link time)
        list(GET wip ${FIXKind} kkk)
        if (kkk STREQUAL "LIBRARY")
            list(REMOVE_AT wip ${FIXPrereqs})
            list(INSERT wip ${FIXPrereqs} ${_TOK_EMPTY_FIELD})
        endif ()

        INSERT(INTO initialFeatures VALUES (${wip}))

    endwhile ()
    unset(featureName)

    # ensure the caller is using the system libraries

    ####################################################################################################################
    function(_addPackages _rowID)
        set(haveIt OFF)

        SELECT(ROW AS hsf_SysPkg FROM systemPackagesOnly WHERE ROWID = ${_rowID})
        list(GET hsf_SysPkg ${FIXName} sys_Feature)
        list(GET hsf_SysPkg ${FIXPkgName} sys_Package)

        SELECT(COUNT AS numUserPackages FROM userPackages)

        set(featureIndex 0)
        while (featureIndex LESS numUserPackages)
            math(EXPR featureIndex "${featureIndex} + 1")
            set(thisIndex ${featureIndex})
            set(haveIt OFF)

            SELECT(ROW AS hsf_UsrPkg FROM userPackages WHERE ROWID = ${thisIndex})
            if (hsf_UsrPkg)
                list(GET hsf_UsrPkg ${FIXName} usr_Feature)
                list(GET hsf_UsrPkg ${FIXPkgName} usr_Package)

                # Is this exact package already in the user's list?

                if (usr_Feature STREQUAL ${sys_Feature} AND usr_Package STREQUAL ${sys_Package})
                    set(haveIt ON)
                endif ()
            endif ()

            if (NOT haveIt)
                _hs_sql_fields_to_storage(hsf_SysPkg _encodedPkg)
                INSERT(INTO initialFeatures VALUES (${_encodedPkg}))
            endif ()
        endwhile ()
    endfunction()
    ####################################################################################################################
    SELECT(* AS systemPackagesOnly FROM allFeatures WHERE "Kind" = "SYSTEM" AND "IsDefault" = 1)
    SQL_FOREACH(ROW IN systemPackagesOnly CALL _addPackages)

    # Re-order unifiedFeatureList based on prerequisites (Topological Sort)
    resolveDependencies(allFeatures initialFeatures unifiedFeatures resolvedNames)

    ####################################################################################################################
    ####################################################################################################################
    ################################ T H E   R E A L   W O R K   B E G I N S   H E R E #################################
    ####################################################################################################################
    ####################################################################################################################
    ##
    ## Nested function. How fancy
    ##

    function(processFeatures features feature_names)

        unset(removeFromDependencies)
        msg("CONSOLE IS ${_term_cols} characters wide")
        math(EXPR usableCols "${_term_cols} - 16")
        cmake_parse_arguments("apf" "IS_A_PREREQ;EARLY_MAKEAVAILABLE" "" "" ${ARGN})

        # Two-Pass Strategy:
        # Pass 0: Declare all FetchContents, handle PROCESS and FIND_PACKAGE (Metadata stage)
        # Pass 1: MakeAvailable and perform post-population fixes (Build stage)

        set(fix 0)
        set(lFName 0)
        set(lPName 0)
        set(prereqs)
        SELECT(COUNT AS numFeatures FROM ${feature_names})

        while (fix LESS numFeatures)
            inc(fix)
            set(row_id ${fix})

            SELECT(FeatureName AS f PackageName AS p FROM resolvedNames WHERE ROWID = ${row_id})
            longest(QUIET CURRENT ${lFName} TEXT "${f}" LONGEST lFName)
            longest(QUIET CURRENT ${lPName} TEXT "(${p})" LONGEST lPName)

            string(JOIN ", " l ${l} "${YELLOW}${f}${NC} (${GREEN}${p}${NC})")
        endwhile ()

        string(REPEAT "─" ${usableCols} divider)
        set(divider "${BOLD}${WHITE}${divider}${NC}")

        msg(CHECK_START "\n${BOLD}Processing ${numFeatures} features${NC} ${l}\n")
        list(APPEND CMAKE_MESSAGE_INDENT "\t")

        unset(combinedLibraryComponents)
        set(scannedLibraries)

        string(LENGTH "${APP_NAME}" appNameLen)
        string(LENGTH "Phase 1" phaseLen)
        math(EXPR phaseLineInternalPadding "${usableCols} - (${appNameLen} + ${phaseLen} + 2)")
        string(REPEAT " " ${phaseLineInternalPadding} phasePadding)

        set(itemN 0)
        set(ofM ${numFeatures})
        string(LENGTH "${ofM}" howLongIsOfM)

        foreach (pass_num RANGE 1)
            set(phase ${pass_num})
            inc(phase)

            msg("${divider}")
            msg("${BOLD}${YELLOW_BG}${BLACK} ${APP_NAME}${phasePadding}Phase ${phase} ${NC}")
            msg("${divider}\n")

            set(ixloupe 0)
            while (ixloupe LESS numFeatures)
                inc(ixloupe)
                set(ix ${ixloupe})

                macro(unsetLocalVars)
                    unset(COMPONENTS_KEYWORD)
                    unset(OVERRIDE_FIND_PACKAGE_KEYWORD)
                    unset(pkg_details)
                    unset(this_build)
                    unset(this_feature_name)
                    unset(this_find_package_args)
                    unset(this_find_package_components)
                    unset(this_flags)
                    unset(this_git_repo)
                    unset(this_hint)
                    unset(this_inc)
                    unset(this_kind)
                    unset(this_method)
                    unset(this_namespace)
                    unset(this_namespace_package_components)
                    unset(this_out)
                    unset(this_pkglc)
                    unset(this_pkgname)
                    unset(this_pkgnameLength)
                    unset(this_pkguc)
                    unset(this_src)
                    unset(this_tag)
                    unset(this_url)
                endmacro()

                unsetLocalVars()

                SELECT(FeatureName AS this_feature_name PackageName AS this_pkgname HasPrereqs AS prereqs FROM resolvedNames WHERE ROWID = ${ix})
                if (prereqs EQUAL 1)
                    set(apf_IS_A_PREREQ ON)
                endif ()

                parsePackage(features
                        # @formatter:off
                        FEATURE     ${this_feature_name}
                        PACKAGE     ${this_pkgname}
                        ARGS        this_find_package_args
                        BIN_DIR     this_bin
                        COMPONENTS  this_find_package_components
                        FETCH_FLAG  this_fetch
                        FLAGS       this_flags
                        GIT_REPO    this_git_repo
                        GIT_TAG     this_tag
                        INC_DIR     this_inc
                        KIND        this_kind
                        METHOD      this_method
                        NAMESPACE   this_namespace
                        OUTPUT      pkg_details
                        PREREQS     this_prereqs
                        SRC_DIR     this_src
                        URL         this_url
                        # @formatter:on
                )

                string(TOLOWER "${this_pkgname}" this_pkglc)
                string(TOUPPER "${this_pkgname}" this_pkguc)

                foreach (flag IN LISTS this_flags)
                    set(apf_${flag} ON)
                endforeach ()

                longest(RIGHT CURRENT ${lFName} TEXT "${this_feature_name}" LONGEST lFName PADDED dispFeatureName)
                longest(LEFT CURRENT ${lPName} TEXT "(${this_pkgname})" LONGEST longestPackageName PADDED dispPackageName)

                string(LENGTH "${ix}" howLongIsItemN)
                set(useThisAsItemN "${ix}")
                if (howLongIsItemN LESS howLongIsOfM)
                    set(useThisAsItemN " ${useThisAsItemN}")
                endif ()

                # ==========================================================================================================
                # PASS 0: DECLARATION & FIND_PACKAGE phase
                # ==========================================================================================================
                if (${pass_num} EQUAL 0)
                    msg(CHECK_START "${BOLD}${YELLOW}${dispFeatureName}${NC} ${GREEN}${dispPackageName}${NC} [${BOLD}${BLUE}${ITALICS}${UNDERLINE}${APP_NAME}${NC}${BLUE} Item${BOLD} ${useThisAsItemN}${NC}${BLUE} of ${BOLD}${ofM}${NC}] ${BOLD}${MAGENTA}Phase ${NC}${BOLD}1${NC}")
                    msg(" ")
                    list(APPEND CMAKE_MESSAGE_INDENT "\t")

                    if (this_pkgname IN_LIST combinedLibraryComponents)
                        # The feature is already PROVIDED by an upstream library target (e.g. HoffSoft::Core/Gfx).
                        # We must still "consume" it for this app, i.e. add the provided target to our link lists.

                        handleTarget(${this_pkgname})

                        list(POP_BACK CMAKE_MESSAGE_INDENT)
                        msg()
                        msg(CHECK_PASS "Feature already available without re-processing: linked to provided target")
                        msg("\n${divider}\n")
                        continue()
                    endif ()

                    if ("${this_method}" STREQUAL "PROCESS")
                        set(fn "${this_pkgname}_process")
                        if (COMMAND "${fn}")
                            cmake_language(CALL "${fn}" "${_IncludePathsList}" "${_LibrariesList}" "${_DefinesList}")
                        endif ()
                    endif ()

                    # Pre-download hooks (mostly for setting variables/policies)
                    set(fn "${this_pkgname}_preDownload")
                    if (COMMAND "${fn}")
                        cmake_language(CALL "${fn}" "${this_pkgname}" "${this_git_repo}" "${this_tag}" "${this_src}")
                    endif ()

                    if ("${this_method}" STREQUAL "FETCH_CONTENTS")
                        if (this_fetch)

                            # Check if a previously loaded LIBRARY already claimed this package
                            if (${this_pkgname}_ALREADY_FOUND OR TARGET ${this_pkgname}::${this_pkgname} OR TARGET ${this_pkgname})
                                msg(STATUS "${this_pkgname} already supplied by a library target. Skipping FetchContent.")
                                unset(magic_enum_ALREADY_FOUND CACHE)
                                unset(magic_enum_ALREADY_FOUND)
                                unset(magic_enum_ALREADY_FOUND CACHE)
                                #                                set(${this_pkgname}_ALREADY_FOUND ON CACHE  INTERNAL "" FORCE)
                                list(APPEND removeFromDependencies "${this_feature_name}" "${this_package}")
                                set(fn "${this_pkgname}_postDeclare")
                                if (COMMAND "${fn}")
                                    cmake_language(CALL "${fn}" "${this_pkgname}")
                                endif ()
                            else ()
                                # SYSTEM packages always build from source so they enter the
                                # HoffSoft:: install export set consistently on all platforms
                                # (e.g. yaml-cpp must not resolve to an IMPORTED sysroot target
                                # on WinX — it must be built and exported as HoffSoft::yaml-cpp).
                                # Inter-subproject reuse (Core built yaml-cpp, now Gfx sees it)
                                # is caught by the TARGET check in the enclosing if-block above,
                                # so no find_package probe is needed for SYSTEM packages.
                                if (NOT this_kind STREQUAL "SYSTEM")
                                    # Try to find the package first before declaring FetchContent
                                    # This allows Gfx to see what Core already fetched/built
                                    msg(STATUS "Checking if ${BOLD}${this_pkgname}${NC} is already available via find_package...")
                                    set(temporary_args ${this_find_package_args})
                                    list(REMOVE_ITEM temporary_args REQUIRED EXCLUDE_FROM_ALL FIND_PACKAGE_ARGS)
                                    find_package(${this_pkgname} QUIET ${temporary_args})
                                else ()
                                    # Clear any stale _FOUND cache from a prior configure so that
                                    # Pass 1's "already found" check does not skip MakeAvailable.
                                    unset(${this_pkgname}_FOUND)
                                    unset(${this_pkgname}_FOUND CACHE)
                                endif ()

                                if (${this_pkgname}_FOUND)
                                    msg(STATUS "${this_pkgname} ${GREEN}found.${NC} (${this_pkgname}_FOUND is ON) Skipping FetchContent.\n")
                                    # TODO:                                    set(${this_pkgname}_ALREADY_FOUND ON CACHE  INTERNAL "" FORCE)
                                elseif (TARGET ${this_pkgname}::${this_pkgname})
                                    msg(STATUS "${this_pkgname} ${GREEN}found.${NC} (TARGET ${this_pkgname}::${this_pkgname} exists) Skipping FetchContent.\n")
                                    # TODO:                                    set(${this_pkgname}_ALREADY_FOUND ON CACHE  INTERNAL "" FORCE)
                                elseif (TARGET ${this_pkgname})
                                    msg(STATUS "${this_pkgname} ${GREEN}found.${NC} (TARGET ${this_pkgname} exists) Skipping FetchContent.\n")
                                    # TODO:                                    set(${this_pkgname}_ALREADY_FOUND ON CACHE  INTERNAL "" FORCE)
                                else ()
                                    msg(STATUS "${MAGENTA}Nope!${NC} Doing it the hard way...")
                                    # Normalise source/URL keywords
                                    string(FIND "${this_url}" ".zip" azip)
                                    string(FIND "${this_url}" ".tar" atar)
                                    string(FIND "${this_url}" ".gz" agz)
                                    if (${azip} GREATER 0 OR ${atar} GREATER 0 OR ${agz} GREATER 0)
                                        set(SOURCE_KEYWORD "URL")
                                        unset(GIT_TAG_KEYWORD)
                                        unset(this_tag)
                                    else ()
                                        set(SOURCE_KEYWORD "GIT_REPOSITORY")
                                        set(GIT_TAG_KEYWORD "GIT_TAG")
                                    endif ()

                                    # Setup Override keywords
                                    list(LENGTH this_find_package_components num_components)
                                    list(LENGTH this_find_package_args num_args)
                                    if (num_args OR num_components)
                                        set(OVERRIDE_FIND_PACKAGE_KEYWORD "OVERRIDE_FIND_PACKAGE")
                                    endif ()
                                    if (num_components)
                                        set(COMPONENTS_KEYWORD "COMPONENTS")
                                    endif ()

                                    set(use_src "${EXTERNALS_DIR}/${this_pkgname}")
                                    if (this_src)
                                        set(use_src "${this_src}")
                                    endif ()

                                    set(use_bin)
                                    if (this_bin)
                                        set(use_bin "${this_bin}")
                                        set(use_subbin "${this_bin}-subbuild")
                                    endif ()

                                    set(outStr)
                                    # SYSTEM: treat this fetched package's own INTERFACE_INCLUDE_DIRECTORIES
                                    # as system headers wherever it's linked, so warnings/-Werror never fire
                                    # on vendored code (requires CMake >= 3.25; this project requires 3.28+).
                                    list(APPEND outStr "SYSTEM")
                                    list(APPEND outStr "${SOURCE_KEYWORD}" "${this_git_repo}")
                                    if (use_src)
                                        list(APPEND outStr "SOURCE_DIR" "${use_src}")
                                    endif ()
                                    if (use_bin)
                                        list(APPEND outStr "BINARY_DIR" "${use_bin}")
                                        list(APPEND outStr "SUBBUILD_DIR" "${use_subbin}")
                                    endif ()

                                    # Strip EXCLUDE_FROM_ALL: it is not a find_package keyword, and in CMake 4.x
                                    # CMP0170=NEW causes FetchContent_MakeAvailable to forward it to add_subdirectory,
                                    # which breaks relative-path source validation in the fetched content's CMakeLists.
                                    set(_fc_declare_args ${this_find_package_args})
                                    list(REMOVE_ITEM _fc_declare_args EXCLUDE_FROM_ALL)
                                    list(APPEND outStr "${OVERRIDE_FIND_PACKAGE_KEYWORD}" ${_fc_declare_args})
                                    unset(_fc_declare_args)
                                    list(APPEND outStr "${COMPONENTS_KEYWORD}" ${this_find_package_components})
                                    list(APPEND outStr "${GIT_TAG_KEYWORD}" "${this_tag}")

                                    string(REPLACE ";;" ";" outStr "${outStr}")
                                    string(REPLACE ";" " " output "${outStr}")

                                    msg(" FetchContent_Declare(${this_pkgname} ${output})")

                                    FetchContent_Declare(${this_pkgname} ${outStr})

                                    set(fn "${this_pkgname}_postDeclare")
                                    #                                    msg(STATUS "\nFetchContent_Declare(${this_pkgname} ${SOURCE_KEYWORD} ${this_git_repo} SOURCE_DIR ${EXTERNALS_DIR}/${this_pkgname} ${OVERRIDE_FIND_PACKAGE_KEYWORD} ${this_find_package_args} ${COMPONENTS_KEYWORD} ${this_find_package_components} ${GIT_TAG_KEYWORD} ${this_tag})")
                                    #
                                    #                                    FetchContent_Declare(${this_pkgname}
                                    #                                            ${SOURCE_KEYWORD} ${this_git_repo}
                                    #                                            SOURCE_DIR ${EXTERNALS_DIR}/${this_pkgname}
                                    #                                            ${OVERRIDE_FIND_PACKAGE_KEYWORD} ${this_find_package_args}
                                    #                                            ${COMPONENTS_KEYWORD} ${this_find_package_components}
                                    #                                            ${GIT_TAG_KEYWORD} ${this_tag})
                                    #
                                    #                                    set(fn "${this_pkgname}_postDeclare")
                                    if (COMMAND "${fn}")
                                        cmake_language(CALL "${fn}" "${this_pkgname}")
                                    endif ()
                                endif ()
                            endif ()
                        endif ()
                    elseif ("${this_method}" STREQUAL "FIND_PACKAGE")
                        if (NOT TARGET ${this_namespace}::${this_pkgname})

                            # 1. Is the library already available? (Probe it)
                            set(temporary_args ${this_find_package_args})
                            list(REMOVE_ITEM temporary_args REQUIRED FIND_PACKAGE_ARGS)

                            msg("Probing for ${this_pkgname}...")

                            if ("PATHS" IN_LIST this_find_package_args)
                                msg("BUMP the BUPP (prefix paths preserved)")
                                set(bump "${CMAKE_MODULE_PATH}")
                                set(bupp "${CMAKE_PREFIX_PATH}")
                                # unset(CMAKE_MODULE_PATH)
                                # unset(CMAKE_PREFIX_PATH)
                            else ()
                                msg("Ain't gonna BUMP the BUPP")
                            endif ()

                            msg("find_package(${this_pkgname} ${temporary_args})")

                            find_package(${this_pkgname} ${temporary_args})

                            if (bump)
                                set(CMAKE_MODULE_PATH "${bump}")
                            endif ()
                            if (bupp)
                                set(CMAKE_PREFIX_PATH "${bupp}")
                            endif ()

                            set(scanned${this_pkgname} OFF)
                            if (${this_pkgname}_FOUND)
                                msg("Found it!")
                                # Library exists! Scan it to see what 3rd-party targets it supplies
                                scanLibraryTargets("${features}" "${this_pkgname}" "${feature_names}")
                                handleTarget(${this_pkgname})
                                list(APPEND combinedLibraryComponents ${${this_pkgname}_COMPONENTS})
                                set(scanned${this_pkgname} ON)
                            else ()
                                msg("${this_pkgname} is not available (yet?)")
                                # Library not found yet. We must fulfill its metadata prerequisites
                                # so that we can eventually load it.
                                if (this_prereqs)
                                    msg(ALWAYS FATAL "Prerequisites not handled yet!!")
                                    #                                    CREATE(TABLE "${this_pkgname}Prerequisites" COLUMNS (${PkgColNames}))
                                    #                                    array(CREATE needed_prereqs "${this_pkgname}Prerequisites" RECORDS)
                                    #                                    record(CREATE needed_prereqFeatureNames "${this_pkgname}PrerequisiteNames")
                                    #                                    foreach (p IN LISTS this_prereqs)
                                    #                                        SplitAt("${p}" "=" preFeatName prePkgName)
                                    #                                        if (prePkg)
                                    #                                            getFeaturePackageByName("${DATA}" "${preFeatName}" "${prePkgName}" prePkg dc)
                                    #                                        else ()
                                    #                                            getFeaturePackageBy("${DATA}" "${preFeatName}" 0 prePkg)
                                    #                                        endif ()
                                    #                                        array(APPEND needed_prereqs RECORD "${prePkg}")
                                    #                                        record(APPEND needed_prereqFeatureNames "${p}")
                                    #                                    endforeach ()
                                    #
                                    #                                    msg(STATUS "Library ${this_pkgname} not found. Processing metadata prerequisites: ${needed_prereqs}")
                                    #                                    processFeatures("${needed_prereqs}" "${needed_prereqFeatureNames}")
                                endif ()
                            endif ()
                            #                            endif ()
                            # 2. Now attempt the real find_package
                            msg(STATUS "\nfind_package(${this_pkgname} ${this_find_package_args})")
                            find_package(${this_pkgname} ${this_find_package_args})

                            set(HANDLED OFF)
                            set(fn "${this_pkgname}_postMakeAvailable")
                            if (COMMAND "${fn}")
                                cmake_language(CALL "${fn}" "${this_src}" "${this_build}" "${OUTPUT_DIR}" "${BUILD_TYPE_LC}")
                            endif ()

                            if (NOT HANDLED AND ${this_pkgname}_FOUND)
                                if (${this_pkgname}_LIBRARIES)
                                    list(APPEND _LibrariesList ${${this_pkgname}_LIBRARIES})
                                endif ()
                                if (${this_pkgname}_INCLUDE_DIR)
                                    list(APPEND _IncludePathsList ${${this_pkgname}_INCLUDE_DIR})
                                endif ()

                                # Now that the library is found, scan it for transitives
                                set(scannedvar "scanned${this_pkgname}")
                                if (this_kind STREQUAL "LIBRARY" AND NOT scannedvar) # AND NOT combinedLibraryComponents)
                                    scanLibraryTargets("${DATA}" "${this_pkgname}" "${feature_names}")
                                    list(APPEND combinedLibraryComponents ${${this_pkgname}_COMPONENTS})
                                endif ()

                                handleTarget(${this_pkgname})
                            endif ()
                        else ()
                            msg("with the sound of mucus")
                            handleTarget(${this_pkgname})
                        endif ()
                    endif ()

                    list(POP_BACK CMAKE_MESSAGE_INDENT)
                    msg(" ")
                    msg(CHECK_PASS "${GREEN}Finished${NC}")

                endif ()

                # ==========================================================================================================
                # PASS 1: POPULATION & FIX phase
                # ==========================================================================================================

                if (${pass_num} EQUAL 1 OR apf_IS_A_PREREQ OR apf_EARLY_MAKEAVAILABLE)

                    msg(CHECK_START "${BOLD}${YELLOW}${dispFeatureName}${NC} ${GREEN}${dispPackageName}${NC} [${BOLD}${BLUE}${ITALICS}${UNDERLINE}${APP_NAME}${NC}${BLUE} Item${BOLD} ${useThisAsItemN}${NC}${BLUE} of ${BOLD}${ofM}${NC}] ${BOLD}${MAGENTA}Phase ${NC}${BOLD}1${NC}")
                    msg(" ")

                    list(APPEND CMAKE_MESSAGE_INDENT "\t")

                    if (${this_package}_PASS_TWO_COMPLETED)
                        list(POP_BACK CMAKE_MESSAGE_INDENT)
                        msg(" ")
                        msg(CHECK_PASS "(already been done)")
                    else ()
                        if (apf_IS_A_PREREQ)
                            set(${this_package}_PASS_TWO_COMPLETED ON)
                        endif ()

                        if (this_pkgname IN_LIST combinedLibraryComponents OR ${this_pkgname}_FOUND)
                            # Feature is already PROVIDED by an upstream library target.
                            # Still consume it for this app by adding the provided target to our link lists.
                            handleTarget(${this_pkgname})

                            # For FETCH_CONTENTS packages found via find_package (e.g. soci found in
                            # /usr/local from a prior install), handleTarget may not resolve namespace-
                            # qualified targets like SOCI::Core. Call postMakeAvailable so the package-
                            # specific handler can add those targets to _LibrariesList.
                            if ("${this_method}" STREQUAL "FETCH_CONTENTS")
                                set(fn "${this_pkgname}_postMakeAvailable")
                                set(HANDLED OFF)
                                if (COMMAND "${fn}")
                                    cmake_language(CALL "${fn}" "${this_src}" "${this_bin}" "${OUTPUT_DIR}" "${BUILD_TYPE_LC}")
                                endif ()
                            endif ()

                            list(POP_BACK CMAKE_MESSAGE_INDENT)
                            msg()
                            msg(CHECK_PASS "Feature already available without re-processing: linked to provided target")
                            msg("\n${divider}\n")
                            continue()
                        endif ()

                        if ("${this_method}" STREQUAL "FIND_PACKAGE")

                            if (NOT TARGET ${this_namespace}::${this_pkgname})
                                handleTarget(${this_pkgname})
                            endif ()

                        elseif ("${this_method}" STREQUAL "FETCH_CONTENTS" AND this_fetch)

                            set(use_src)
                            if (this_src)
                                set(use_src "${this_src}")
                            else ()
                                if (EXISTS "${EXTERNALS_DIR}/${this_pkgname}")
                                    set(use_src "${EXTERNALS_DIR}/${this_pkgname}")
                                endif ()
                            endif ()

                            set(use_bin)
                            if (this_bin)
                                set(use_bin "${this_bin}")
                            else ()
                                if (EXISTS "${BUILD_DIR}/${this_pkglc}-build")
                                    set(use_bin "${BUILD_DIR}/${this_pkglc}-build")
                                endif ()
                            endif ()

                            if (TARGET ${this_pkgname}::${this_pkgname} OR TARGET ${this_pkgname})
                                # Target was built by a prior subproject in this same CMake run
                                # (e.g. a dep built while processing Core, now consumed by Gfx).
                                # FetchContent_Declare was intentionally skipped in Pass 0, so
                                # calling FetchContent_MakeAvailable here would fail with
                                # "No content details recorded". Just link the existing target.
                                msg(STATUS "${this_pkgname} target already exists from a prior subproject. Skipping FetchContent_MakeAvailable.")
                                handleTarget(${this_pkgname})
                            elseif (NOT ${this_pkgname}_ALREADY_FOUND)
                                set(fn "${this_pkgname}_preMakeAvailable")
                                set(HANDLED OFF)
                                if (COMMAND "${fn}")
                                    cmake_language(CALL "${fn}" "${this_pkgname}")
                                endif ()

                                if (NOT HANDLED AND NOT ${this_feature_name} STREQUAL TESTING)
                                    msg(STATUS "\nFetchContent_MakeAvailable(${this_pkgname})")
                                    FetchContent_MakeAvailable(${this_pkgname})
                                    handleTarget(${this_pkgname})
                                endif ()
                            else ()
                                msg(" ")
                                msg(STATUS "${this_pkgname} already found, skipping population.")
                                #                                handleTarget(${this_pkgname})
                            endif ()

                            set(fn "${this_pkgname}_postMakeAvailable")
                            if (COMMAND "${fn}")
                                cmake_language(CALL "${fn}" "${use_src}" "${use_bin}" "${OUTPUT_DIR}" "${BUILD_TYPE_LC}")
                            endif ()

                            # Auto-include the standard 'include' folder if it exists and wasn't handled
                            if (EXISTS "${this_src}/include")
                                list(APPEND _IncludePathsList "${this_src}/include")
                            endif ()
                        else ()
                            msg("No Phase 2 step")
                        endif ()

                        # Final patching/fixing phase
                        set(fn "${this_pkgname}_fix")
                        if (COMMAND "${fn}")
                            cmake_language(CALL "${fn}" "${this_pkgname}" "${this_tag}" "${this_src}")
                        elseif (NOT ${this_pkgname}_PATCHED AND EXISTS "${cmake_root}/patches/${this_pkgname}")
                            unset(patches)
                            list(APPEND patches "${this_pkgname}|${EXTERNALS_DIR}/${this_pkgname}")
                            replaceFile("${this_pkgname}" ${patches})
                        endif ()

                        list(POP_BACK CMAKE_MESSAGE_INDENT)
                        msg(" ")
                        msg(CHECK_PASS "${GREEN}Finished${NC}")

                    endif ()
                endif ()

                inc(ix)

                msg("\n${divider}\n")

            endwhile () # this_feature_name

        endforeach () # pass_num
        list(POP_BACK CMAKE_MESSAGE_INDENT)
        msg(CHECK_PASS "${GREEN}OK${NC}\n")

        propegateUpwards("Interim" OFF)

    endfunction()

    processFeatures(unifiedFeatures resolvedNames)
    propegateUpwards("Finally" OFF)

endfunction()

macro(propegateUpwards whereWeAre REPORT)

    # @formatter:off
    list(APPEND ${AUE_PREFIX}_CompileOptionsList ${_CompileOptionsList} ${${AUE_PREFIX}_CompileOptionsList})
    list(APPEND ${AUE_PREFIX}_DefinesList        ${_DefinesList}        ${${AUE_PREFIX}_DefinesList})
    list(APPEND ${AUE_PREFIX}_DependenciesList   ${_DependenciesList}   ${${AUE_PREFIX}_DependenciesList})

    list(REMOVE_ITEM ${AUE_PREFIX}_DependenciesList ${removeFromDependencies})

    list(APPEND ${AUE_PREFIX}_SystemIncludePathsList   ${_IncludePathsList}   ${${AUE_PREFIX}_SystemIncludePathsList})
    list(APPEND ${AUE_PREFIX}_LibrariesList      ${_LibrariesList}      ${${AUE_PREFIX}_LibrariesList})
    list(APPEND ${AUE_PREFIX}_LibraryPathsList   ${_LibraryPathsList}   ${${AUE_PREFIX}_LibraryPathsList})
    list(APPEND ${AUE_PREFIX}_LinkOptionsList    ${_LinkOptionsList}    ${${AUE_PREFIX}_LinkOptionsList})
    list(APPEND ${AUE_PREFIX}_PrefixPathsList    ${_PrefixPathsList}    ${${AUE_PREFIX}_PrefixPathsList})

    list(APPEND ${AUE_PREFIX}_wxCompilerOptions  ${_wxCompilerOptions}  ${${AUE_PREFIX}_wxCompilerOptions})
    list(APPEND ${AUE_PREFIX}_wxDefines          ${_wxDefines}          ${${AUE_PREFIX}_wxDefines})
    list(APPEND ${AUE_PREFIX}_wxIncludePaths     ${_wxIncludePaths}     ${${AUE_PREFIX}_wxIncludePaths})
    list(APPEND ${AUE_PREFIX}_wxLibraryPaths     ${_wxLibraryPaths}     ${${AUE_PREFIX}_wxLibraryPaths})
    list(APPEND ${AUE_PREFIX}_wxLibraries        ${_wxLibraries}        ${${AUE_PREFIX}_wxLibraries})
    list(APPEND ${AUE_PREFIX}_wxFrameworks       ${_wxFrameworks}       ${${AUE_PREFIX}_wxFrameworks})

    list(REMOVE_DUPLICATES ${AUE_PREFIX}_CompileOptionsList)
    list(REMOVE_DUPLICATES ${AUE_PREFIX}_DefinesList)
    list(REMOVE_DUPLICATES ${AUE_PREFIX}_DependenciesList)
    list(REMOVE_DUPLICATES ${AUE_PREFIX}_SystemIncludePathsList)
    list(REMOVE_DUPLICATES ${AUE_PREFIX}_LibrariesList)
    list(REMOVE_DUPLICATES ${AUE_PREFIX}_LibraryPathsList)
    list(REMOVE_DUPLICATES ${AUE_PREFIX}_LinkOptionsList)
    list(REMOVE_DUPLICATES ${AUE_PREFIX}_PrefixPathsList)

    list(REMOVE_DUPLICATES ${AUE_PREFIX}_wxCompilerOptions)
    list(REMOVE_DUPLICATES ${AUE_PREFIX}_wxDefines)
    list(REMOVE_DUPLICATES ${AUE_PREFIX}_wxIncludePaths)
    list(REMOVE_DUPLICATES ${AUE_PREFIX}_wxLibraryPaths)
    list(REMOVE_DUPLICATES ${AUE_PREFIX}_wxLibraries)
    list(REMOVE_DUPLICATES ${AUE_PREFIX}_wxFrameworks)

    set(${AUE_PREFIX}_CompileOptionsList ${${AUE_PREFIX}_CompileOptionsList} PARENT_SCOPE)
    set(${AUE_PREFIX}_DefinesList        ${${AUE_PREFIX}_DefinesList}        PARENT_SCOPE)
    set(${AUE_PREFIX}_DependenciesList   ${${AUE_PREFIX}_DependenciesList}   PARENT_SCOPE)
    set(${AUE_PREFIX}_IncludePathsList   ${${AUE_PREFIX}_IncludePathsList}   PARENT_SCOPE)
    set(${AUE_PREFIX}_SystemIncludePathsList ${${AUE_PREFIX}_SystemIncludePathsList} PARENT_SCOPE)
    set(${AUE_PREFIX}_LibrariesList      ${${AUE_PREFIX}_LibrariesList}      PARENT_SCOPE)
    set(${AUE_PREFIX}_LibraryPathsList   ${${AUE_PREFIX}_LibraryPathsList}   PARENT_SCOPE)
    set(${AUE_PREFIX}_LinkOptionsList    ${${AUE_PREFIX}_LinkOptionsList}    PARENT_SCOPE)
    set(${AUE_PREFIX}_PrefixPathsList    ${${AUE_PREFIX}_PrefixPathsList}    PARENT_SCOPE)

    set(${AUE_PREFIX}_wxCompilerOptions  ${${AUE_PREFIX}_wxCompilerOptions}  PARENT_SCOPE)
    set(${AUE_PREFIX}_wxDefines          ${${AUE_PREFIX}_wxDefines}          PARENT_SCOPE)
    set(${AUE_PREFIX}_wxIncludePaths     ${${AUE_PREFIX}_wxIncludePaths}     PARENT_SCOPE)
    set(${AUE_PREFIX}_wxLibraryPaths     ${${AUE_PREFIX}_wxLibraryPaths}     PARENT_SCOPE)
    set(${AUE_PREFIX}_wxLibraries        ${${AUE_PREFIX}_wxLibraries}        PARENT_SCOPE)
    set(${AUE_PREFIX}_wxFrameworks       ${${AUE_PREFIX}_wxFrameworks}       PARENT_SCOPE)
    # @formatter:on

    if (${REPORT} STREQUAL "ON")
        log(TITLE "${whereWeAre}" LISTS

                ${AUE_PREFIX}_CompileOptionsList
                ${AUE_PREFIX}_DefinesList
                ${AUE_PREFIX}_DependenciesList
                ${AUE_PREFIX}_IncludePathsList
                ${AUE_PREFIX}_SystemIncludePathsList
                ${AUE_PREFIX}_LibrariesList
                ${AUE_PREFIX}_LibraryPathsList
                ${AUE_PREFIX}_LinkOptionsList
                ${AUE_PREFIX}_PrefixPathsList

                ${AUE_PREFIX}_wxCompilerOptions
                ${AUE_PREFIX}_wxDefines
                ${AUE_PREFIX}_wxIncludePaths
                ${AUE_PREFIX}_wxLibraryPaths
                ${AUE_PREFIX}_wxLibraries
                ${AUE_PREFIX}_wxFrameworks
        )
    endif ()
endmacro()