path: root/src/corelib/global/qcompilerdetection.qdoc

// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \headerfile <QtCompilerDetection>
    \inmodule QtCore
    \title Compiler-specific Macro Definitions
    \ingroup funclists

    \brief The <QtCompilerDetection> header file includes various
    compiler-specific macros.

    The <QtCompilerDetection> header file provides a range of macros (Q_CC_*)
    that are defined if the application is compiled using the specified
    compiler. For example, the Q_CC_SUN macro is defined if the application is
    compiled using Forte Developer, or Sun Studio C++.

    The purpose of these macros is to enable programmers to add
    compiler-specific code to their application.
*/

/*!
    \macro Q_CC_SYM
    \relates <QtCompilerDetection>

    Defined if the application is compiled using Digital Mars C/C++
    (used to be Symantec C++).
*/

/*!
    \macro Q_CC_MSVC
    \relates <QtCompilerDetection>

    Defined if the application is compiled using Microsoft Visual
    C/C++, Intel C++ for Windows.
*/

/*!
    \macro Q_CC_CLANG
    \relates <QtCompilerDetection>

    Defined if the application is compiled using Clang.
*/

/*!
    \macro Q_CC_BOR
    \relates <QtCompilerDetection>

    Defined if the application is compiled using Borland/Turbo C++.
*/

/*!
    \macro Q_CC_WAT
    \relates <QtCompilerDetection>

    Defined if the application is compiled using Watcom C++.
*/

/*!
    \macro Q_CC_GNU
    \relates <QtCompilerDetection>

    Defined if the application is compiled using GNU Compiler Collection (GCC).
*/

/*!
    \macro Q_CC_COMEAU
    \relates <QtCompilerDetection>

    Defined if the application is compiled using Comeau C++.
*/

/*!
    \macro Q_CC_EDG
    \relates <QtCompilerDetection>

    Defined if the application is compiled using Edison Design Group
    C++.
*/

/*!
    \macro Q_CC_OC
    \relates <QtCompilerDetection>

    Defined if the application is compiled using CenterLine C++.
*/

/*!
    \macro Q_CC_SUN
    \relates <QtCompilerDetection>

    Defined if the application is compiled using Forte Developer, or
    Sun Studio C++.
*/

/*!
    \macro Q_CC_MIPS
    \relates <QtCompilerDetection>

    Defined if the application is compiled using MIPSpro C++.
*/

/*!
    \macro Q_CC_DEC
    \relates <QtCompilerDetection>

    Defined if the application is compiled using DEC C++.
*/

/*!
    \macro Q_CC_HPACC
    \relates <QtCompilerDetection>

    Defined if the application is compiled using HP aC++.
*/

/*!
    \macro Q_CC_USLC
    \relates <QtCompilerDetection>

    Defined if the application is compiled using SCO OUDK and UDK.
*/

/*!
    \macro Q_CC_CDS
    \relates <QtCompilerDetection>

    Defined if the application is compiled using Reliant C++.
*/

/*!
    \macro Q_CC_KAI
    \relates <QtCompilerDetection>

    Defined if the application is compiled using KAI C++.
*/

/*!
    \macro Q_CC_INTEL
    \relates <QtCompilerDetection>
    \obsolete

    This macro used to be defined if the application was compiled with the old
    Intel C++ compiler for Linux, macOS or Windows. The new oneAPI C++ compiler
    is just a build of Clang and therefore does not define this macro.

    \sa Q_CC_CLANG
*/

/*!
    \macro Q_CC_HIGHC
    \relates <QtCompilerDetection>

    Defined if the application is compiled using MetaWare High C/C++.
*/

/*!
    \macro Q_CC_PGI
    \relates <QtCompilerDetection>

    Defined if the application is compiled using Portland Group C++.
*/

/*!
    \macro Q_CC_GHS
    \relates <QtCompilerDetection>

    Defined if the application is compiled using Green Hills
    Optimizing C++ Compilers.
*/

/*!
    \macro void Q_FALLTHROUGH()
    \relates <QtCompilerDetection>
    \since 5.8

    Can be used in switch statements at the end of case block to tell the compiler
    and other developers that the lack of a break statement is intentional.

    This is useful since a missing break statement is often a bug, and some
    compilers can be configured to emit warnings when one is not found.

    \sa Q_UNREACHABLE(), Q_UNREACHABLE_RETURN()
*/

/*!
    \macro Q_LIKELY(expr)
    \relates <QtCompilerDetection>
    \since 4.8

    \brief Hints to the compiler that the enclosed condition, \a expr, is
    likely to evaluate to \c true.

    Use of this macro can help the compiler to optimize the code.

    Example:

    \snippet code/src_corelib_global_qglobal.cpp qlikely

    \sa Q_UNLIKELY()
*/

/*!
    \macro Q_UNLIKELY(expr)
    \relates <QtCompilerDetection>
    \since 4.8

    \brief Hints to the compiler that the enclosed condition, \a expr, is
    likely to evaluate to \c false.

    Use of this macro can help the compiler to optimize the code.

    Example:

    \snippet code/src_corelib_global_qglobal.cpp qunlikely

    \sa Q_LIKELY()
*/

/*!
    \macro Q_CONSTINIT
    \relates <QtCompilerDetection>
    \since 6.4

    \brief Enforces constant initialization when supported by the compiler.

    If the compiler supports the C++20 \c{constinit} keyword, Clang's
    \c{[[clang::require_constant_initialization]]} or GCC's \c{__constinit},
    then this macro expands to the first one of these that is available,
    otherwise it expands to nothing.

    Variables marked as \c{constinit} cause a compile-error if their
    initialization would have to be performed at runtime.

    \note Constant-initialized variables may still have load-time impact if
    they have non-trivial destruction.

    For constants, you can use \c{constexpr} since C++11, but \c{constexpr}
    makes variables \c{const}, too, whereas \c{constinit} ensures constant
    initialization, but doesn't make the variable \c{const}:

    \table
    \header \li Keyword       \li Added \li immutable \li constant-initialized
    \row    \li \c{const}     \li C++98 \li yes       \li not required
    \row    \li \c{constexpr} \li C++11 \li yes       \li required
    \row    \li \c{constinit} \li C++20 \li no        \li required
    \endtable
*/

/*!
    \macro Q_DECL_EXPORT
    \relates <QtCompilerDetection>

    This macro marks a symbol for shared library export (see
     \l{sharedlibrary.html}{Creating Shared Libraries}).

    \sa Q_DECL_IMPORT
*/

/*!
    \macro Q_DECL_IMPORT
    \relates <QtCompilerDetection>

    This macro declares a symbol to be an import from a shared library (see
    \l{sharedlibrary.html}{Creating Shared Libraries}).

    \sa Q_DECL_EXPORT
*/

/*!
    \macro Q_DECL_CONSTEXPR
    \relates <QtCompilerDetection>
    \deprecated [6.4] Use the \c constexpr keyword instead.

    This macro can be used to declare variable that should be constructed at compile-time,
    or an inline function that can be computed at compile-time.

    \sa Q_DECL_RELAXED_CONSTEXPR
*/

/*!
    \macro Q_DECL_RELAXED_CONSTEXPR
    \relates <QtCompilerDetection>
    \deprecated [6.4] Use the \c constexpr keyword instead.

    This macro can be used to declare an inline function that can be computed
    at compile-time according to the relaxed rules from C++14.

    \sa Q_DECL_CONSTEXPR
*/

/*!
    \macro Q_DECL_NOTHROW
    \relates <QtCompilerDetection>
    \since 5.0
    \deprecated [6.4] Use the \c noexcept keyword instead.

    This macro marks a function as never throwing, under no
    circumstances. If the function does nevertheless throw, the
    behavior is undefined.

    \sa Q_DECL_NOEXCEPT, Q_DECL_NOEXCEPT_EXPR()
*/

/*!
    \macro Q_DECL_NOEXCEPT
    \relates <QtCompilerDetection>
    \since 5.0
    \deprecated [6.4] Use the \c noexcept keyword instead.

    This macro marks a function as never throwing. If the function
    does nevertheless throw, the behavior is defined:
    std::terminate() is called.


    \sa Q_DECL_NOTHROW, Q_DECL_NOEXCEPT_EXPR()
*/

/*!
    \macro Q_DECL_NOEXCEPT_EXPR(x)
    \relates <QtCompilerDetection>
    \since 5.0
    \deprecated [6.4] Use the \c noexcept keyword instead.

    This macro marks a function as non-throwing if \a x is \c true. If
    the function does nevertheless throw, the behavior is defined:
    std::terminate() is called.


    \sa Q_DECL_NOTHROW, Q_DECL_NOEXCEPT
*/

/*!
    \macro Q_DECL_OVERRIDE
    \since 5.0
    \deprecated
    \relates <QtCompilerDetection>

    This macro can be used to declare an overriding virtual
    function. Use of this markup will allow the compiler to generate
    an error if the overriding virtual function does not in fact
    override anything.

    It expands to "override".

    The macro goes at the end of the function, usually after the
    \c{const}, if any:
    \snippet code/src_corelib_global_qglobal.cpp qdecloverride

    \sa Q_DECL_FINAL
*/

/*!
    \macro Q_DECL_FINAL
    \since 5.0
    \deprecated
    \relates <QtCompilerDetection>

    This macro can be used to declare an overriding virtual or a class
    as "final", with Java semantics. Further-derived classes can then
    no longer override this virtual function, or inherit from this
    class, respectively.

    It expands to "final".

    The macro goes at the end of the function, usually after the
    \c{const}, if any:
    \snippet code/src_corelib_global_qglobal.cpp qdeclfinal-1

    For classes, it goes in front of the \c{:} in the class
    definition, if any:
    \snippet code/src_corelib_global_qglobal.cpp qdeclfinal-2

    \sa Q_DECL_OVERRIDE
*/

/*!
    \macro const char* Q_FUNC_INFO()
    \relates <QtCompilerDetection>

    Expands to a string that describe the function the macro resides in. How this string looks
    more specifically is compiler dependent. With GNU GCC it is typically the function signature,
    while with other compilers it might be the line and column number.

    Q_FUNC_INFO can be conveniently used with qDebug(). For example, this function:

    \snippet code/src_corelib_global_qglobal.cpp 22

    when instantiated with the integer type, will with the GCC compiler produce:

    \tt{const TInputType& myMin(const TInputType&, const TInputType&) [with TInputType = int] was called with value1: 3 value2: 4}

    If this macro is used outside a function, the behavior is undefined.
*/

/*!
    \macro Q_NODISCARD_CTOR
    \relates <QtCompilerDetection>
    \since 6.6

    \brief Expands to \c{[[nodiscard]]} on compilers that accept it on constructors.

    Otherwise it expands to nothing.

    Constructors marked as Q_NODISCARD_CTOR cause a compiler warning if a call
    site doesn't use the resulting object.

    This macro is exists solely to prevent warnings on compilers that don't
    implement the feature. If your supported platforms all allow \c{[[nodiscard]]}
    on constructors, we strongly recommend you use the C++ attribute directly instead
    of this macro.

    \sa Q_NODISCARD_CTOR_X
*/

/*!
    \macro Q_NODISCARD_X(message)
    \macro Q_NODISCARD_CTOR_X(message)
    \relates <QtCompilerDetection>
    \since 6.7

    \brief Expand to \c{[[nodiscard(message)]]} on compilers that support the feature.

    Otherwise they expand to \c {[[nodiscard]]} and Q_NODISCARD_CTOR, respectively.

    \sa Q_NODISCARD_CTOR
*/