diff --git a/cmake/Assertion.cmake b/cmake/Assertion.cmake index 827ec51..7e37f74 100644 --- a/cmake/Assertion.cmake +++ b/cmake/Assertion.cmake @@ -1,18 +1,59 @@ -# This code is licensed under the terms of the MIT License. +# MIT License +# # Copyright (c) 2024 Alfi Maulana +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in all +# copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +# SOFTWARE. + +# This module contains a collection of assertion functions and other utilities +# for testing CMake code. +# +# The main feature of this module is the `assert` function for asserting the +# given condition in the style of CMake's `if` function. If the assertion fails, +# it will throw a fatal error message with information about the context of the +# asserted condition. +# +# This module also supports CMake test creation using the `assertion_add_test` +# function. This function will create a new test that processes the given file +# in script mode with variables, functions, and macros from this module +# available in the given file. +# +# If this module is processed in script mode, it may optionally include other +# modules by passing the paths of the other modules as additional arguments +# after `--`. cmake_minimum_required(VERSION 3.17) # This variable contains the path to the included `Assertion.cmake` module. set(ASSERTION_LIST_FILE "${CMAKE_CURRENT_LIST_FILE}") -# Add a new test that runs a CMake file in script mode. +# Adds a new test that processes the given CMake file in script mode. # # assertion_add_test( [NAME ]) # -# This function adds a new test that will run the specified `` CMake file -# in script mode. If `` is specified, it will use that as the test name; +# This function adds a new test that will process the given `` in script +# mode. If `NAME` is specified, it will use `` as the test name; # otherwise, it will use `` instead. +# +# Internally, the test will process this module in script mode and include the +# given `` at the end of the module, allowing variables, functions, and +# macros in this module to be available in the `` without the need to +# include this module from the ``. function(assertion_add_test FILE) cmake_parse_arguments(PARSE_ARGV 1 ARG "" NAME "") @@ -30,11 +71,12 @@ endfunction() # # fail(...) # -# This macro throws a fatal error message formatted from the given lines. +# This macro throws a fatal error message formatted from the given ``. # -# It formats the given `` by appending all of them into a single string. -# For each given line, if it is a variable, it will be expanded and indented by -# 2 spaces. +# It formats the message by concatenating all the lines into a single message +# with no separator between the lines. If one of the lines is a variable, it +# will be expanded and indented by two spaces before being concatenated with the +# other lines. macro(fail FIRST_LINE) if(DEFINED "${FIRST_LINE}") set(MESSAGE "${${FIRST_LINE}}") @@ -56,13 +98,14 @@ endmacro() # Asserts the given condition. # -# assert() +# assert(...) # -# This function performs an assertion on the given condition. It will output a -# fatal error message if the assertion fails. +# This function performs an assertion on the given ``. If the +# assertion fails, it will output a formatted fatal error message with +# information about the context of the asserted condition. # -# Refer to the documentation of the `if` function for supported conditions to -# perform the assertion. +# Refer to the documentation of CMake's `if` function for more information about +# supported conditions for the assertion. function(assert) cmake_parse_arguments(PARSE_ARGV 0 ARG "" "" "") if(${ARG_UNPARSED_ARGUMENTS}) @@ -166,11 +209,14 @@ endfunction() # Asserts whether a command call throws a fatal error message. # -# assert_fatal_error(CALL [...] MESSAGE ...) +# assert_fatal_error(CALL [...] MESSAGE ...) # -# This function asserts whether a function or macro named `` called -# with the specified arguments throws a fatal error message that matches the -# expected ``. +# This function asserts whether a function or macro named ``, called +# with the specified ``, throws a fatal error message that matches +# the expected ``. +# +# If more than one `` string is given, they are concatenated into a +# single message with no separator between the strings. function(assert_fatal_error) cmake_parse_arguments(PARSE_ARGV 0 ARG "" "" "CALL;MESSAGE") string(JOIN "" EXPECTED_MESSAGE ${ARG_MESSAGE}) @@ -241,17 +287,23 @@ endfunction() # Asserts whether the given command correctly executes a process. # # assert_execute_process( -# [COMMAND] [...] [OUTPUT ...] [ERROR ...]) +# [COMMAND] [...] +# [OUTPUT ...] +# [ERROR ...]) # -# This function asserts whether the given command and arguments successfully -# execute a process. +# This function asserts whether the given `` and `` +# successfully execute a process. If `ERROR` is specified, it instead asserts +# whether it fails to execute the process. # # If `OUTPUT` is specified, it also asserts whether the output of the executed -# process matches the expected ``. +# process matches the expected ``. If more than one `` string +# is given, they are concatenated into a single output with no separator between +# the strings. # -# If `ERROR` is specified, this function asserts whether the given command and -# arguments fail to execute a process. It also asserts whether the error of the -# executed process matches the expected ``. +# If `ERROR` is specified, it also asserts whether the error of the executed +# process matches the expected ``. If more than one `` string +# is given, they are concatenated into a single error with no separator between +# the strings. function(assert_execute_process) cmake_parse_arguments(PARSE_ARGV 0 ARG "" "" "COMMAND;OUTPUT;ERROR") @@ -303,8 +355,13 @@ endfunction() # # section(...) # -# This function begins a new test section named ``. Use the `endsection` -# function to end the test section. +# This function begins a new test section named ``. It prints the test +# section name and indents all subsequent messages by two spaces. +# +# If more than one `` string is given, they are concatenated into a single +# name with no separator between the strings. +# +# Use the `endsection` function to end the test section. function(section NAME) cmake_parse_arguments(PARSE_ARGV 1 ARG "" "" "") string(JOIN "" NAME "${NAME}" ${ARG_UNPARSED_ARGUMENTS})