From f1a651d34193714cc47e91bbebce376e2a94510d Mon Sep 17 00:00:00 2001 From: Ivan Solovev Date: Thu, 29 Sep 2022 14:18:36 +0200 Subject: Provide documentation for qcompilerdetection.h header The description of the macros in this header should not belong to , so move it to a separate documentation page. Task-number: QTBUG-106154 Change-Id: Ic31604b96d9ebea6e8aac285b00a8d4c82b15c9a Reviewed-by: Thiago Macieira --- src/corelib/global/qcompilerdetection.h | 1 + src/corelib/global/qcompilerdetection.qdoc | 394 +++++++++++++++++++++++++++++ src/corelib/global/qglobal.cpp | 371 --------------------------- 3 files changed, 395 insertions(+), 371 deletions(-) create mode 100644 src/corelib/global/qcompilerdetection.qdoc (limited to 'src/corelib/global') diff --git a/src/corelib/global/qcompilerdetection.h b/src/corelib/global/qcompilerdetection.h index 27813f880d..c74f68324a 100644 --- a/src/corelib/global/qcompilerdetection.h +++ b/src/corelib/global/qcompilerdetection.h @@ -7,6 +7,7 @@ #endif #if 0 +#pragma qt_class(QtCompilerDetection) #pragma qt_sync_skip_header_check #pragma qt_sync_stop_processing #endif diff --git a/src/corelib/global/qcompilerdetection.qdoc b/src/corelib/global/qcompilerdetection.qdoc new file mode 100644 index 0000000000..05a4b89f1d --- /dev/null +++ b/src/corelib/global/qcompilerdetection.qdoc @@ -0,0 +1,394 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \headerfile + \inmodule QtCore + \title Compiler-specific Macro Definitions + \ingroup funclists + + \brief The header file includes various + compiler-specific macros. + + The 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 + + Defined if the application is compiled using Digital Mars C/C++ + (used to be Symantec C++). +*/ + +/*! + \macro Q_CC_MSVC + \relates + + Defined if the application is compiled using Microsoft Visual + C/C++, Intel C++ for Windows. +*/ + +/*! + \macro Q_CC_CLANG + \relates + + Defined if the application is compiled using Clang. +*/ + +/*! + \macro Q_CC_BOR + \relates + + Defined if the application is compiled using Borland/Turbo C++. +*/ + +/*! + \macro Q_CC_WAT + \relates + + Defined if the application is compiled using Watcom C++. +*/ + +/*! + \macro Q_CC_GNU + \relates + + Defined if the application is compiled using GNU Compiler Collection (GCC). +*/ + +/*! + \macro Q_CC_COMEAU + \relates + + Defined if the application is compiled using Comeau C++. +*/ + +/*! + \macro Q_CC_EDG + \relates + + Defined if the application is compiled using Edison Design Group + C++. +*/ + +/*! + \macro Q_CC_OC + \relates + + Defined if the application is compiled using CenterLine C++. +*/ + +/*! + \macro Q_CC_SUN + \relates + + Defined if the application is compiled using Forte Developer, or + Sun Studio C++. +*/ + +/*! + \macro Q_CC_MIPS + \relates + + Defined if the application is compiled using MIPSpro C++. +*/ + +/*! + \macro Q_CC_DEC + \relates + + Defined if the application is compiled using DEC C++. +*/ + +/*! + \macro Q_CC_HPACC + \relates + + Defined if the application is compiled using HP aC++. +*/ + +/*! + \macro Q_CC_USLC + \relates + + Defined if the application is compiled using SCO OUDK and UDK. +*/ + +/*! + \macro Q_CC_CDS + \relates + + Defined if the application is compiled using Reliant C++. +*/ + +/*! + \macro Q_CC_KAI + \relates + + Defined if the application is compiled using KAI C++. +*/ + +/*! + \macro Q_CC_INTEL + \relates + \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 + + Defined if the application is compiled using MetaWare High C/C++. +*/ + +/*! + \macro Q_CC_PGI + \relates + + Defined if the application is compiled using Portland Group C++. +*/ + +/*! + \macro Q_CC_GHS + \relates + + Defined if the application is compiled using Green Hills + Optimizing C++ Compilers. +*/ + +/*! + \macro void Q_FALLTHROUGH() + \relates + \since 5.8 + + Can be used in switch statements at the end of case block to tell the compiler + and other developers that 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() +*/ + +/*! + \macro Q_LIKELY(expr) + \relates + \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(), Q_ASSUME() +*/ + +/*! + \macro Q_UNLIKELY(expr) + \relates + \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 + \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 + + 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 + + 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 + \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 + \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 + \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 + \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 + \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 + + 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 + + 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 + + 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. +*/ diff --git a/src/corelib/global/qglobal.cpp b/src/corelib/global/qglobal.cpp index 47a14500ba..464a666edf 100644 --- a/src/corelib/global/qglobal.cpp +++ b/src/corelib/global/qglobal.cpp @@ -177,156 +177,6 @@ using namespace Qt::StringLiterals; System detection routines *****************************************************************************/ -/*! - \macro Q_CC_SYM - \relates - - Defined if the application is compiled using Digital Mars C/C++ - (used to be Symantec C++). -*/ - -/*! - \macro Q_CC_MSVC - \relates - - Defined if the application is compiled using Microsoft Visual - C/C++, Intel C++ for Windows. -*/ - -/*! - \macro Q_CC_CLANG - \relates - - Defined if the application is compiled using Clang. -*/ - -/*! - \macro Q_CC_BOR - \relates - - Defined if the application is compiled using Borland/Turbo C++. -*/ - -/*! - \macro Q_CC_WAT - \relates - - Defined if the application is compiled using Watcom C++. -*/ - -/*! - \macro Q_CC_GNU - \relates - - Defined if the application is compiled using GNU C++. -*/ - -/*! - \macro Q_CC_COMEAU - \relates - - Defined if the application is compiled using Comeau C++. -*/ - -/*! - \macro Q_CC_EDG - \relates - - Defined if the application is compiled using Edison Design Group - C++. -*/ - -/*! - \macro Q_CC_OC - \relates - - Defined if the application is compiled using CenterLine C++. -*/ - -/*! - \macro Q_CC_SUN - \relates - - Defined if the application is compiled using Forte Developer, or - Sun Studio C++. -*/ - -/*! - \macro Q_CC_MIPS - \relates - - Defined if the application is compiled using MIPSpro C++. -*/ - -/*! - \macro Q_CC_DEC - \relates - - Defined if the application is compiled using DEC C++. -*/ - -/*! - \macro Q_CC_HPACC - \relates - - Defined if the application is compiled using HP aC++. -*/ - -/*! - \macro Q_CC_USLC - \relates - - Defined if the application is compiled using SCO OUDK and UDK. -*/ - -/*! - \macro Q_CC_CDS - \relates - - Defined if the application is compiled using Reliant C++. -*/ - -/*! - \macro Q_CC_KAI - \relates - - Defined if the application is compiled using KAI C++. -*/ - -/*! - \macro Q_CC_INTEL - \relates - \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 - - Defined if the application is compiled using MetaWare High C/C++. -*/ - -/*! - \macro Q_CC_PGI - \relates - - Defined if the application is compiled using Portland Group C++. -*/ - -/*! - \macro Q_CC_GHS - \relates - - Defined if the application is compiled using Green Hills - Optimizing C++ Compilers. -*/ - /*! \macro Q_PROCESSOR_ALPHA \relates @@ -643,39 +493,6 @@ using namespace Qt::StringLiterals; \sa QSysInfo::buildCpuArchitecture() */ -/*! - \macro void Q_FALLTHROUGH() - \relates - \since 5.8 - - Can be used in switch statements at the end of case block to tell the compiler - and other developers that 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() -*/ - -/*! - \macro const char* Q_FUNC_INFO() - \relates - - 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. -*/ - /* Dijkstra's bisection algorithm to find the square root of an integer. Deliberately not exported as part of the Qt API, but used in both @@ -833,67 +650,6 @@ void qAbort() that qExchange() returns a non-const object, so Qt containers may detach. */ -/*! - \macro Q_LIKELY(expr) - \relates - \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(), Q_ASSUME() -*/ - -/*! - \macro Q_UNLIKELY(expr) - \relates - \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 - \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. - - 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 QT_POINTER_SIZE \relates @@ -1140,48 +896,6 @@ bool QInternal::activateCallbacks(Callback cb, void **parameters) \sa QT_NAMESPACE */ -/*! - \macro Q_DECL_EXPORT - \relates - - 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 - - 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 - \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 - \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 qMove(x) \relates @@ -1194,19 +908,6 @@ bool QInternal::activateCallbacks(Callback cb, void **parameters) qMove takes an rvalue reference to its parameter \a x, and converts it to an xvalue. */ -/*! - \macro Q_DECL_NOTHROW - \relates - \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 - behaviour is undefined. - - \sa Q_DECL_NOEXCEPT, Q_DECL_NOEXCEPT_EXPR() -*/ - /*! \macro QT_TERMINATE_ON_EXCEPTION(expr) \relates @@ -1237,78 +938,6 @@ bool QInternal::activateCallbacks(Callback cb, void **parameters) \sa Q_DECL_NOEXCEPT, Q_DECL_NOTHROW, qTerminate() */ -/*! - \macro Q_DECL_NOEXCEPT - \relates - \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 behaviour is defined: - std::terminate() is called. - - - \sa Q_DECL_NOTHROW, Q_DECL_NOEXCEPT_EXPR() -*/ - -/*! - \macro Q_DECL_NOEXCEPT_EXPR(x) - \relates - \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 behaviour is defined: - std::terminate() is called. - - - \sa Q_DECL_NOTHROW, Q_DECL_NOEXCEPT -*/ - -/*! - \macro Q_DECL_OVERRIDE - \since 5.0 - \deprecated - \relates - - 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 - - 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 -*/ - namespace QtPrivate { Q_LOGGING_CATEGORY(lcNativeInterface, "qt.nativeinterface") } -- cgit v1.2.3