diff options
Diffstat (limited to 'src/corelib/global/qcompilerdetection.qdoc')
| -rw-r--r-- | src/corelib/global/qcompilerdetection.qdoc | 427 |
1 files changed, 427 insertions, 0 deletions
diff --git a/src/corelib/global/qcompilerdetection.qdoc b/src/corelib/global/qcompilerdetection.qdoc new file mode 100644 index 0000000000..191f26cc1f --- /dev/null +++ b/src/corelib/global/qcompilerdetection.qdoc @@ -0,0 +1,427 @@ +// 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 +*/ |