# Copyright (C) 2026 The Qt Company Ltd.
# SPDX-License-Identifier: BSD-3-Clause

# Manual block to opt out of the include guard.
if(NOT QT_NO_CMAKE_INCLUDE_GUARD)
    include_guard(GLOBAL)
endif()

# An improved re-implementation of `include_guard()`
#
# Aside from the options that `include_guard` supports, which roughly map to `#pragma once` in C++
# (because it operates based on CMAKE_CURRENT_LIST_FILE), the function also supports a string-based
# GUARD_KEY option to implement an include guard similar to a C++ `#ifndef` include guard. This
# prevents including copies stored at different paths.
#
# The include guard can be opted out of, by setting QT_NO_CMAKE_INCLUDE_GUARD to ON. Then the macro
# is a no-op.
#
# Synopsis
#
#   __qt_internal_cmake_include_guard(
#     [GUARD_KEY <key>]
#     [LOCAL|DIRECTORY|GLOBAL]
#   )
#
# Arguments
#
# `GUARD_KEY`
#   A string key to identify the include guard. If specified, the include guard is implemented by
#   setting a global property with a name based on the key, and checking for its existence at the
#   call site. Currently only works when used in conjunction with `GLOBAL`.
#   Recommended, because it's more robust than path based checks.
#
# `LOCAL`
#   Equivalent to `include_guard()`.
#
# `DIRECTORY`
#   Equivalent to `include_guard(DIRECTORY)`.
#
# `GLOBAL`
#   Equivalent to `include_guard(GLOBAL)`.
#
# Notes
# The file providing the macro needs to be included early enough, to be available for use in
# files that use it.
macro(__qt_internal_cmake_include_guard)
    # Only parse and handle the arguments if the opt is not set.
    if(NOT QT_NO_CMAKE_INCLUDE_GUARD)
        set(_qt_cig_opt_args
            LOCAL
            DIRECTORY
            GLOBAL
        )
        set(_qt_cig_single_args
            GUARD_KEY
        )
        cmake_parse_arguments(_qt_cig_arg "${_qt_cig_opt_args}" "${_qt_cig_single_args}" "" ${ARGN})
        if(DEFINED _qt_cig_arg_UNPARSED_ARGUMENTS)
            message(FATAL_ERROR "__qt_internal_cmake_include_guard "
                "unknown arguments: '${_qt_cig_arg_UNPARSED_ARGUMENTS}'")
        endif()

        if(_qt_cig_arg_GUARD_KEY)
            if(_qt_cig_arg_GLOBAL)
                # Use a global property to track when to exit early.
                set(_qt_cig_prop_name "_qt_cmake_include_guard_${_qt_cig_arg_GUARD_KEY}")
                get_property(_qt_cig_already_included GLOBAL PROPERTY "${_qt_cig_prop_name}")
                if(_qt_cig_already_included)
                    unset(_qt_cig_prop_name)
                    unset(_qt_cig_already_included)

                    # Returns out of the file where the macro was called.
                    return()
                endif()
                set_property(GLOBAL PROPERTY "${_qt_cig_prop_name}" "ON")
                unset(_qt_cig_prop_name)
                unset(_qt_cig_already_included)
            else()
                message(FATAL_ERROR "GUARD_KEY is currently only supported with the GLOBAL option.")
            endif()
        else()
            # For non GUARD_KEY guards, use the default cmake implementation which is based on the
            # file path / CMAKE_CURRENT_LIST_FILE.
            if(_qt_cig_arg_GLOBAL)
                include_guard(GLOBAL)
            elseif(_qt_cig_arg_DIRECTORY)
                include_guard(DIRECTORY)
            elseif(_qt_cig_arg_LOCAL)
                include_guard()
            else()
                message(FATAL_ERROR "One of LOCAL, DIRECTORY or GLOBAL option must be specified.")
            endif()
        endif()
    endif()
endmacro()