diff --git a/Help/release/3.0.rst b/Help/release/3.0.rst index 375519d68b..fe9fe1beba 100644 --- a/Help/release/3.0.rst +++ b/Help/release/3.0.rst @@ -205,8 +205,8 @@ Properties Modules ------- -* The :module:`CheckTypeSize` module ``check_type_size`` macro and - the :module:`CheckStructHasMember` module ``check_struct_has_member`` +* The :module:`CheckTypeSize` module ``check_type_size()`` command and + the :module:`CheckStructHasMember` module ``check_struct_has_member()`` command learned a new ``LANGUAGE`` option to optionally check C++ types. * The :module:`ExternalData` module learned to work with no diff --git a/Modules/CheckTypeSize.cmake b/Modules/CheckTypeSize.cmake index 8a9ff2c701..9643d87c00 100644 --- a/Modules/CheckTypeSize.cmake +++ b/Modules/CheckTypeSize.cmake @@ -5,68 +5,92 @@ CheckTypeSize ------------- -Check sizeof a type +This module provides a command to check the size of a C/C++ type or expression. -.. command:: check_type_size - - .. code-block:: cmake - - check_type_size( [BUILTIN_TYPES_ONLY] - [LANGUAGE ]) - - Check if the type exists and determine its size. Results are reported - in the following variables: - - ``HAVE_`` - Holds a true or false value indicating whether the type exists. - - ```` - Holds one of the following values: - - ```` - Type has non-zero size ````. - - ``0`` - Type has architecture-dependent size. This may occur when - :variable:`CMAKE_OSX_ARCHITECTURES` has multiple architectures. - In this case ``_CODE`` contains C preprocessor tests - mapping from each architecture macro to the corresponding type size. - The list of architecture macros is stored in ``_KEYS``, - and the value for each key is stored in ``-``. - - "" (empty string) - Type does not exist. - - ``_CODE`` - Holds C preprocessor code to define the macro ```` to the size - of the type, or to leave the macro undefined if the type does not exist. - - The options are: - - ``BUILTIN_TYPES_ONLY`` - - Support only compiler-builtin types. If *not* given, the macro checks - for headers ````, ````, and ````, and - saves results in ``HAVE_SYS_TYPES_H``, ``HAVE_STDINT_H``, and - ``HAVE_STDDEF_H``. The type size check automatically includes the - available headers, thus supporting checks of types defined in the headers. - - ``LANGUAGE `` - Use the ```` compiler to perform the check. - Acceptable values are ``C`` and ``CXX``. - If not specified, it defaults to ``C``. - -Despite the name of the macro you may use it to check the size of more -complex expressions, too. To check e.g. for the size of a struct -member you can do something like this: +Load this module in a CMake project with: .. code-block:: cmake - check_type_size("((struct something*)0)->member" SIZEOF_MEMBER) + include(CheckTypeSize) +Commands +^^^^^^^^ -The following variables may be set before calling this macro to modify -the way the check is run: +This module provides the following command: + +.. command:: check_type_size + + Checks once whether the C/C++ type or expression exists and determines its + size: + + .. code-block:: cmake + + check_type_size( [BUILTIN_TYPES_ONLY] [LANGUAGE ]) + + The arguments are: + + ```` + The type or expression being checked. + + ```` + The name of the variable and a prefix used for storing the check results. + + ``BUILTIN_TYPES_ONLY`` + If given, only compiler-builtin types will be supported in the check. + If *not* given, the command checks for common headers ````, + ````, and ````, and saves results in + ``HAVE_SYS_TYPES_H``, ``HAVE_STDINT_H``, and ``HAVE_STDDEF_H`` internal + cache variables. The type size check automatically includes the available + headers, thus supporting checks of types defined in the headers. + + ``LANGUAGE `` + Uses the ```` compiler to perform the check. + Acceptable values are ``C`` and ``CXX``. + If not specified, it defaults to ``C``. + + .. rubric:: Result Variables + + Results are reported in the following variables: + + ``HAVE_`` + Internal cache variable that holds a boolean true or false value + indicating whether the type or expression ```` exists. + + ```` + Internal cache variable that holds one of the following values: + + ```` + If the type or expression exists, it will have a non-zero size + ```` in bytes. + + ``0`` + When type has architecture-dependent size; This may occur when + :variable:`CMAKE_OSX_ARCHITECTURES` has multiple architectures. + In this case ``_CODE`` contains preprocessor tests + mapping from each architecture macro to the corresponding type size. + The list of architecture macros is stored in ``_KEYS``, + and the value for each key is stored in ``-``. + + "" (empty string) + When type or expression does not exist. + + ``_CODE`` + CMake variable that holds preprocessor code to define the macro + ```` to the size of the type, or to leave the macro undefined + if the type does not exist. + + Despite the name of this command, it may also be used to determine the size + of more complex expressions. For example, to check the size of a struct + member: + + .. code-block:: cmake + + check_type_size("((struct something*)0)->member" SIZEOF_MEMBER) + + .. rubric:: Variables Affecting the Check + + The following variables may be set before calling this command to modify + the way the check is run: .. include:: /module/include/CMAKE_REQUIRED_FLAGS.rst @@ -83,7 +107,8 @@ the way the check is run: .. include:: /module/include/CMAKE_REQUIRED_QUIET.rst ``CMAKE_EXTRA_INCLUDE_FILES`` - list of extra headers to include. + A :ref:`semicolon-separated list ` of extra header + files to include when performing the check. Examples ^^^^^^^^