From f72759de573c97b291717cfe6043305b9797282e Mon Sep 17 00:00:00 2001 From: Adrian Freihofer Date: Sun, 31 Dec 2023 16:48:43 +0100 Subject: ref-manual: document cmake-qemu class (From yocto-docs rev: b2e396bd970ea8f27ba575b49c1489e2181442b8) Signed-off-by: Adrian Freihofer Reviewed-by: Michael Opdenacker Signed-off-by: Richard Purdie --- documentation/ref-manual/classes.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) (limited to 'documentation') 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 +`__. + +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`` -- cgit v1.2.3-54-g00ecf