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/UnitTest.cmake b/cmake/UnitTest.cmake
index 782dad9..d557eb0 100644
--- a/cmake/UnitTest.cmake
+++ b/cmake/UnitTest.cmake
@@ -4,14 +4,44 @@
# SPDX-License-Identifier: BSD-3-Clause
#
-include_guard(DIRECTORY)
+#[===[.rst:
+UnitTest CMake module
+---------------------
-# Trying to set CLANG_LIBRARY_PATH using the following methods
-# 1. Using cache or command line definition
-# Show warning if environment variable is also set but has different value
-# 2. Copying the value of CLANG_LIBRARY_PATH environment variable if set
-# 3. find_package (llvm-config, common paths or Windows registry)
-# If none of the above steps succeeded CMake emits a fatal error and stops
+Control flow
+^^^^^^^^^^^^
+
+1. Setting :cmake:variable:`CLANG_LIBRARY_PATH`
+
+ 1. Using :cmake:variable:`CLANG_LIBRARY_PATH` CMake variable
+
+ 2. Using ``CLANG_LIBRARY_PATH`` environment variable
+
+ 3. Trying to find by ``find_package`` function which calls :cmake:module:`FindLibClang`.
+
+2. Checking if ``c-picker`` command is available
+
+
+Variables
+^^^^^^^^^
+
+The module sets the following variables while it's checking its prerequisites.
+
+.. cmake:variable:: CLANG_LIBRARY_PATH
+
+libclang directory for c-picker
+
+.. cmake:variable:: CPICKER_COMMAND
+
+Path of c-picker executable which is part of the c-picker pip package.
+
+
+Functions
+^^^^^^^^^
+
+#]===]
+
+include_guard(DIRECTORY)
set(CLANG_LIBRARY_PATH_HELP "libclang directory for c-picker")
@@ -42,15 +72,71 @@
message(FATAL_ERROR "Please install c-picker using pip")
endif()
-# Global dependencies:
-# Variables
-# CPICKER_COMMAND: command of the c-picker
-# CPICKER_CACHE_PATH: root directory of the c-picker generate files
-# UNIT_TEST_COMMON_SOURCES: common source files for every test build
-# CLANG_LIBRARY_PATH: libclang directory for c-picker
-# Modules
-# CTest module should be included in the root CMakeLists.txt before calling this function
+#[===[.rst:
+.. cmake:command:: unit_test_add_suite
+ .. code-block:: cmake
+
+ unit_test_add_suite(
+ NAME test_name
+ SOURCES source_files
+ INCLUDE_DIRECTORIES include_directories
+ COMPILE_DEFINITIONS defines
+ DEPENDS dependencies
+ )
+
+ The ``unit_test_add_suite`` CMake function provides a convenient interface for
+ defining unit test suites. Basically its input is the test source files, include
+ paths and macro definitions and it internally does all the necessary steps to
+ have the test binary registered in CTest as a result.
+
+ Control flow:
+
+ 1. Adding new executable named ``NAME``
+
+ 2. Iterating throught ``SOURCES``
+
+ 1. If it's a normal source file add to the executable's source list
+ 2. If it's a YAML file add as a c-picker custom command and add the generated
+ file to the executable's source list
+
+ 3. Setting include directories
+
+ 4. Setting defines
+
+ 5. Adding extra dependencies of the test build
+
+ 6. Adding executable to the system as a test
+
+ Inputs:
+
+ ``NAME``
+ Unique name of the test suite
+
+ ``SOURCES`` (multi, optional)
+ Source files
+
+ ``INCLUDE_DIRECTORIES`` (multi, optional)
+ Include directories
+
+ ``COMPILE_DEFINITIONS`` (multi, optional)
+ Defines
+
+ ``DEPENDS`` (multi, optional)
+ Extra targets as dependencies of the test build
+
+ Global dependencies:
+
+ ``CPICKER_CACHE_PATH``
+ Root directory of the c-picker generated files
+
+ ``UNIT_TEST_COMMON_SOURCES``
+ Common source files for every test build
+
+ ``CTest``
+ Built-in testing module of CMake
+
+#]===]
function(unit_test_add_suite)
set(_OPTIONS_ARGS)
set(_ONE_VALUE_ARGS NAME)