ref-manual: document cmake-qemu class

(From yocto-docs rev: b2e396bd970ea8f27ba575b49c1489e2181442b8)

Signed-off-by: Adrian Freihofer <adrian.freihofer@siemens.com>
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 29 insertions, 0 deletions

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 8d8bea4714..26d0e55cb4 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -377,6 +377,35 @@ If you need to install custom CMake toolchain files supplied by the application
 being built, you should install them (during :ref:`ref-tasks-install`) to the
 preferred CMake Module directory: ``${D}${datadir}/cmake/modules/``.
 
+.. _ref-classes-cmake-qemu:
+
+``cmake-qemu``
+==============
+
+The :ref:`ref-classes-cmake-qemu` class might be used instead of the
+:ref:`ref-classes-cmake` class. In addition to the features provided by the
+:ref:`ref-classes-cmake` class, the :ref:`ref-classes-cmake-qemu` class passes
+the ``CMAKE_CROSSCOMPILING_EMULATOR`` setting to ``cmake``. This allows to use
+QEMU user-mode emulation for the execution of cross-compiled binaries on the
+host machine.  For more information about ``CMAKE_CROSSCOMPILING_EMULATOR``
+please refer to the `related section of the CMake documentation
+<https://cmake.org/cmake/help/latest/variable/CMAKE_CROSSCOMPILING_EMULATOR.html>`__.
+
+Not all platforms are supported by QEMU. This class only works for machines with
+``qemu-usermode`` in the :ref:`ref-features-machine`. Using QEMU user-mode therefore
+involves a certain risk, which is also the reason why this feature is not part of
+the main :ref:`ref-classes-cmake` class by default.
+
+One use case is the execution of cross-compiled unit tests with CTest on the build
+machine. If ``CMAKE_CROSSCOMPILING_EMULATOR`` is configured::
+
+   cmake --build --target test
+
+works transparently with QEMU user-mode.
+
+If the CMake project is developed with this use case in mind this works very nicely.
+This also applies to an IDE configured to use ``cmake-native`` for cross-compiling.
+
 .. _ref-classes-cml1:
 
 ``cml1``