From 0b098711a32652e4e1222b5c5ce1c13816f2aabb Mon Sep 17 00:00:00 2001 From: Marc Herbert Date: Fri, 23 Jul 2021 09:06:22 +0000 Subject: [PATCH] Fix unit tests documentation Explain how to "steal" parameters from scripts/xtensa-build-all.sh Explain how to compile natively. Link the two sections with each other. `make platform_defconfig` was obsolete, replace with -DINIT_CONFIG Signed-off-by: Marc Herbert --- developer_guides/firmware/cmake.rst | 2 ++ developer_guides/unit_tests.rst | 52 ++++++++++++++++++++--------- 2 files changed, 38 insertions(+), 16 deletions(-) diff --git a/developer_guides/firmware/cmake.rst b/developer_guides/firmware/cmake.rst index c943cad1..3edbbad3 100644 --- a/developer_guides/firmware/cmake.rst +++ b/developer_guides/firmware/cmake.rst @@ -107,6 +107,8 @@ Unit Tests Optional arguments. Only for unit tests. +Read :ref:`unit_tests` first. + BUILD_UNIT_TESTS Default: OFF, if ON then builds unit tests. diff --git a/developer_guides/unit_tests.rst b/developer_guides/unit_tests.rst index ccb22201..86e6581c 100644 --- a/developer_guides/unit_tests.rst +++ b/developer_guides/unit_tests.rst @@ -14,35 +14,55 @@ For a successful compilation, it needs a toolchain thats supports C stdlib. Configuring for unit tests ************************** -In order to build and run unit tests, just pass additional flag to -CMake **-DBUILD_UNIT_TESTS=ON**. +Unit tests are built from the same, top-level CMakeLists.txt as the +firmware but with different CMake flags: **-DBUILD_UNIT_TESTS=ON** and a +couple others. + +Building unit tests can be more complex than building the firmware +because for the firmware the script ``./xtensa-build-all.sh`` hides most +the CMake configuration. For unit tests you must find a working +combination of environment variables and CMake flags. Fortunately +``./xtensa-build-all.sh`` logs some of its magic that you can "steal" +and re-use to build unit tests. Like this: + +- Export ``XTENSA_TOOLS_ROOT`` as you normally do when building the + firmware. +- Build the firmware using ``./xtensa-build-all.sh`` and take note of the + following variables in the build log: ``PATH``, ``XTENSA_SYSTEM`` and + the ``-DROOT_DIR`` parameter. +- ``export`` the ``PATH`` and ``XTENSA_SYSTEM`` values found above. +- Run cmake with ``-DBUILD_UNIT_TESTS=ON``, the ``-DROOT_DIR`` parameter above, + ``-DINIT_CONFIG`` and a new build directory +- Build and run the tests with ``make test`` or ``ninja test``. -Unit tests need a valid config for a used toolchain, so before building them you can use a default config such as: +Example: Running tests for APL +============================== .. code-block:: bash - make _defconfig + mkdir build_ut && cd build_ut + cmake -DBUILD_UNIT_TESTS=ON -DTOOLCHAIN=xt -DINIT_CONFIG=apollolake_defconfig \ + -DROOT_DIR=/xcc/install/builds/RG-2017.8-linux/X4H3I16w2D48w3a_2017_8/xtensa-elf .. + make -j4 && ctest -j8 -Then build and run all unit tests by entering: +.. note:: -.. code-block:: bash + Use -DTOOLCHAIN=xt option, -DTOOLCHAIN=xtensa--elf is not supported - make -j4 && ctest -j8 +Additional unit tests options can be found in :ref:`cmake`. +Compiling unit tests without a cross-compilation toolchain +========================================================== -Example: Running tests for APL -============================== +You can also compile the unit tests with your native compiler. You won't +be able to _run_ the tests but this can be convenient to test +compilation issues quickly: .. code-block:: bash - mkdir build_ut && cd build_ut - cmake -DTOOLCHAIN=xt -DROOT_DIR=$CONFIG_PATH/xtensa-elf -DBUILD_UNIT_TESTS=ON .. - make apollolake_defconfig - make -j4 && ctest -j8 + cmake -B build_ut -DBUILD_UNIT_TESTS_HOST=yes -DTOOLCHAIN=gcc \ + -DBUILD_UNIT_TESTS=ON -DINIT_CONFIG=something_defconfig -.. note:: - - Use -DTOOLCHAIN=xt option, -DTOOLCHAIN=xtensa--elf is not supported Wrapping objects for unit tests *******************************