diff --git a/Help/variable/CMAKE_LANG_BYTE_ORDER.rst b/Help/variable/CMAKE_LANG_BYTE_ORDER.rst index 78f0ae6943..da60af6584 100644 --- a/Help/variable/CMAKE_LANG_BYTE_ORDER.rst +++ b/Help/variable/CMAKE_LANG_BYTE_ORDER.rst @@ -18,3 +18,78 @@ and ``CUDA``. If :variable:`CMAKE_OSX_ARCHITECTURES` specifies multiple architectures, the value of ``CMAKE__BYTE_ORDER`` is non-empty only if all architectures share the same byte order. + +Examples +^^^^^^^^ + +Example: Checking Endianness +"""""""""""""""""""""""""""" + +Checking endianness (byte order) of the target architecture in a CMake +project, where ``C`` language is one of the enabled languages, and storing +the result in a variable ``WORDS_BIGENDIAN``: + +.. code-block:: cmake + + if(CMAKE_C_BYTE_ORDER STREQUAL "BIG_ENDIAN") + set(WORDS_BIGENDIAN TRUE) + elseif(CMAKE_C_BYTE_ORDER STREQUAL "LITTLE_ENDIAN") + set(WORDS_BIGENDIAN FALSE) + else() + set(WORDS_BIGENDIAN FALSE) + message(WARNING "Endianness could not be determined.") + endif() + +Or, if the project doesn't have ``C`` language enabled, it can be replaced +with some other enabled language. For example, if ``CXX`` is enabled: + +.. code-block:: cmake + + if(CMAKE_CXX_BYTE_ORDER STREQUAL "BIG_ENDIAN") + set(WORDS_BIGENDIAN TRUE) + elseif(CMAKE_CXX_BYTE_ORDER STREQUAL "LITTLE_ENDIAN") + set(WORDS_BIGENDIAN FALSE) + else() + set(WORDS_BIGENDIAN FALSE) + message(WARNING "Endianness could not be determined.") + endif() + +Note, that in most cases this can be simplified by only checking for a +big-endian target: + +.. code-block:: cmake + + if(CMAKE_C_BYTE_ORDER STREQUAL "BIG_ENDIAN") + set(WORDS_BIGENDIAN TRUE) + else() + set(WORDS_BIGENDIAN FALSE) + endif() + +Example: Per-language Endianness Check +"""""""""""""""""""""""""""""""""""""" + +Most of the time, architectures used today are consistent in endianness +across compilers. But here's when per-language endianness check can matter: + +* Cross-compilation to different architectures (e.g., big-endian embedded + system). + +* Heterogeneous toolchains where one target architecture is for C language + and another target is for different language. + +* Static libraries or binaries reused across platforms (e.g., distributing + precompiled CUDA kernels). + +.. code-block:: cmake + + if(CMAKE_C_BYTE_ORDER) + message(STATUS "C byte order: ${CMAKE_C_BYTE_ORDER}") + endif() + + if(CMAKE_CXX_BYTE_ORDER) + message(STATUS "C++ byte order: ${CMAKE_CXX_BYTE_ORDER}") + endif() + + if(CMAKE_CUDA_BYTE_ORDER) + message(STATUS "CUDA byte order: ${CMAKE_CUDA_BYTE_ORDER}") + endif() diff --git a/Modules/TestBigEndian.cmake b/Modules/TestBigEndian.cmake index a64303d09c..4b31780768 100644 --- a/Modules/TestBigEndian.cmake +++ b/Modules/TestBigEndian.cmake @@ -7,19 +7,74 @@ TestBigEndian .. deprecated:: 3.20 - Supserseded by the :variable:`CMAKE__BYTE_ORDER` variable. + Superseded by the :variable:`CMAKE__BYTE_ORDER` variable. -Check if the target architecture is big endian or little endian. +This module provides a command to check the endianness (byte order) of the +target architecture. + +Load this module in a CMake project with: + +.. code-block:: cmake + + include(TestBigEndian) + +Commands +^^^^^^^^ + +This module provides the following command: .. command:: test_big_endian + Checks if the target architecture is big-endian or little-endian: + .. code-block:: cmake test_big_endian() - Stores in variable ```` either 1 or 0 indicating whether the - target architecture is big or little endian. + This command stores in variable ```` either 1 or 0 indicating whether + the target architecture is big or little endian. + At least one of the supported languages must be enabled in + CMake project when using this command. + + Supported languages are ``C``, ``CXX``. + + .. versionchanged:: 3.20 + This command is now mainly a wrapper around the + :variable:`CMAKE__BYTE_ORDER` where also ``OBJC``, ``OBJCXX``, + and ``CUDA`` languages are supported. + +Examples +^^^^^^^^ + +Example: Checking Endianness +"""""""""""""""""""""""""""" + +Checking endianness of the target architecture with this module and storing +the result in a CMake variable ``WORDS_BIGENDIAN``: + +.. code-block:: cmake + + include(TestBigEndian) + test_big_endian(WORDS_BIGENDIAN) + +Example: Checking Endianness in New Code +"""""""""""""""""""""""""""""""""""""""" + +As of CMake 3.20, this module should be replaced with the +:variable:`CMAKE__BYTE_ORDER` variable. For example, in a project, +where ``C`` language is one of the enabled languages: + +.. code-block:: cmake + + if(CMAKE_C_BYTE_ORDER STREQUAL "BIG_ENDIAN") + set(WORDS_BIGENDIAN TRUE) + elseif(CMAKE_C_BYTE_ORDER STREQUAL "LITTLE_ENDIAN") + set(WORDS_BIGENDIAN FALSE) + else() + set(WORDS_BIGENDIAN FALSE) + message(WARNING "Endianness could not be determined.") + endif() #]=======================================================================] include_guard()