Kitware/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-10-14 02:08:27 +08:00
Code Issues Projects Releases Wiki Activity

TestBigEndian, CMAKE_<LANG>_BYTE_ORDER: Update documentation

Browse Source 
- Fixed typo in the module description.
- Added examples section highlighting the code migration towards the
  `CMAKE_<LANG>_BYTE_ORDER` variable.
- Documented command similar to other modules.
- Added examples for the `CMAKE_<LANG>_BYTE_ORDER` variable and
  explained when endianness for different languages can be used.
This commit is contained in:
Peter Kokot
2025-07-16 13:50:08 +02:00
parent 47df2a940a
commit 59da6d9e5c
2 changed files with 134 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
Help/variable/CMAKE_LANG_BYTE_ORDER.rst
View File

@@ -18,3 +18,78 @@ and ``CUDA``.
If :variable:`CMAKE_OSX_ARCHITECTURES` specifies multiple architectures, the
value of ``CMAKE_<LANG>_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()

63
Modules/TestBigEndian.cmake
View File

@@ -7,19 +7,74 @@ TestBigEndian
.. deprecated:: 3.20
Supserseded by the :variable:`CMAKE_<LANG>_BYTE_ORDER` variable.
Superseded by the :variable:`CMAKE_<LANG>_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(<var>)
Stores in variable ``<var>`` either 1 or 0 indicating whether the
target architecture is big or little endian.
This command stores in variable ``<var>`` 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_<LANG>_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_<LANG>_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()