Initial version of unit testing documentation
This commit includes the 'User guide' and 'Implementing tests' sections
for helping people building, running and writing unit tests. A more
detailed version of documentation is available under the 'Component
user manuals section'.
Change-Id: I67e93ac805d1f4e7727964f3d95a70436ae34733
Signed-off-by: Imre Kis <imre.kis@arm.com>
diff --git a/cmake/Coverage.cmake b/cmake/Coverage.cmake
index dd1e6ce..e5fae00 100644
--- a/cmake/Coverage.cmake
+++ b/cmake/Coverage.cmake
@@ -4,6 +4,52 @@
# SPDX-License-Identifier: BSD-3-Clause
#
+#[===[.rst:
+Coverage CMake module
+---------------------
+
+Control flow
+^^^^^^^^^^^^
+
+Using the code coverage feature of the system starts with including
+``Coverage`` module. This will implicitly check if all the requirements for
+generating coverage are fulfilled. This includes checking the following
+conditions.
+
+- Compiler is GCC
+- lcov executables exist
+- ``c-picker-coverage-mapper`` is available
+
+As the next step it sets the compiler flags to make GCC to generate binaries
+with coverage information.
+
+
+Variables
+^^^^^^^^^
+
+The module sets the following variables while it's checking its prerequisites.
+
+.. cmake:variable:: LCOV_COMMAND
+
+Path of lcov executable
+
+.. cmake:variable:: GENHTML_COMMAND
+
+Path of genhtml executable which is part of the lcov package.
+
+.. cmake:variable:: CPICKER_COVERAGE_MAPPER_COMMAND
+
+Path of ``c-picker-coverage-mapper`` executable which is provided by c-picker
+pip package.
+
+
+Functions
+^^^^^^^^^
+
+The module also contains functions for setting up the coverage feature.
+
+#]===]
+
include_guard(DIRECTORY)
# Checking GCC
@@ -56,8 +102,51 @@
add_dependencies(${TARGET} ${TARGET}_target_${CUSTOM_TARGET_SUFFIX})
endfunction()
-# Generates LCOV coverage info file by processing the .gcda and .gcno files.
-# The function also maps coverage of the c-picker generated files to the original source lines
+#[===[.rst:
+.. cmake:command:: coverage_generate
+
+ .. code-block:: cmake
+
+ coverage_generate(
+ NAME test_name
+ SOURCE_DIR source_directory
+ BINARY_DIR binary_directory
+ CPICKER_MAPPING_PATH c_picker_mapping_path
+ OUTPUT_FILE output_file
+ )
+
+ The function outputs an lcov info file for further processing. It also handles
+ the remapping of the coverage of the c-picker generated files.
+
+ Control flow:
+
+ 1. Running the ``lcov`` command for collecting the coverage data from the
+ available ``.gcda`` and ``.gcno`` files in the ``BINARY_DIR``.
+
+ 2. The output of previous step is processed by ``c-picker-coverage-mapper``.
+ This will remap the coverage of files in ``CPICKER_MAPPING_PATH`` to the
+ original source files.
+
+ 3. Adds the output file to the ``coverage`` target's dependency list.
+
+ Inputs:
+
+ ``NAME``
+ Test name included in lcov info file
+
+ ``SOURCE_DIR``
+ Directory of source files
+
+ ``BINARY_DIR``
+ Directory of the ``.gcda`` and ``.gcno`` files
+
+ ``CPICKER_MAPPING_PATH``
+ Path of c-picker generated files
+
+ ``OUTPUT_FILE``
+ Output lcov coverage info file
+
+#]===]
function(coverage_generate)
set(_OPTIONS_ARGS)
set(_ONE_VALUE_ARGS NAME SOURCE_DIR BINARY_DIR CPICKER_MAPPING_PATH OUTPUT_FILE)
@@ -93,7 +182,33 @@
)
endfunction()
-# Filters coverage info of files from the matching directory
+#[===[.rst:
+.. cmake:command:: coverage_filter
+
+ .. code-block:: cmake
+
+ coverage_filter(
+ INPUT_FILE input_file
+ OUTPUT_FILE output_file
+ INCLUDE_DIRECTORY include_directory
+ )
+
+ The function filters the coverage data by including only the coverage of the
+ files of ``INCLUDE_DIRECTORY`` or its subdirectories. It adds the filtered
+ output file to the ``coverage`` target's dependency list.
+
+ Inputs:
+
+ ``INPUT_FILE``
+ Input lcov coverage info file
+
+ ``OUTPUT_FILE``
+ Output lcov coverage info file
+
+ ``INCLUDE_DIRECTORY``
+ Root directory of included files
+
+#]===]
function(coverage_filter)
set(_OPTIONS_ARGS)
set(_ONE_VALUE_ARGS INPUT_FILE OUTPUT_FILE INCLUDE_DIRECTORY)
@@ -122,7 +237,30 @@
)
endfunction()
-# Generated an HTML report from the LCOV info file
+#[===[.rst:
+.. cmake:command:: coverage_generate_report
+
+ .. code-block:: cmake
+
+ coverage_generate_report(
+ INPUT_FILE input_file
+ OUTPUT_DIRECTORY output_directory
+ )
+
+ The function generates a HTML coverage report from the lcov info file into
+ the ``OUTPUT_DIRECTORY``. It adds the output directory to the
+ ``coverage_report`` target's dependency list.
+
+ Inputs:
+
+ ``INPUT_FILE``
+ Input lcov coverage info file
+
+ ``OUTPUT_DIRECTORY``
+ Output directory of the coverage report where the ``index.html`` is the
+ root file of the report.
+
+#]===]
function(coverage_generate_report)
set(_OPTIONS_ARGS)
set(_ONE_VALUE_ARGS INPUT_FILE OUTPUT_DIRECTORY)