build(cmake): add assertion helper
Adds a very small assertion helper function to simplify validation in
some of the larger functions introduced in later commits.
This function takes a condition and a message, and will abort the build
with the message if the condition fails.
Change-Id: Ib33c3580c0e464ec945a56501d68fbccaae7ed72
Signed-off-by: Chris Kay <chris.kay@arm.com>
diff --git a/cmake/Modules/ArmAssert.cmake b/cmake/Modules/ArmAssert.cmake
new file mode 100644
index 0000000..1ec554f
--- /dev/null
+++ b/cmake/Modules/ArmAssert.cmake
@@ -0,0 +1,76 @@
+#[=======================================================================[.rst:
+ArmAssert
+---------
+
+.. default-domain:: cmake
+
+.. command:: arm_assert
+
+Assert an invariant, and fail the build if the invariant is broken.
+
+.. code-block:: cmake
+
+ arm_assert(CONDITION <condition> [MESSAGE <message>])
+
+This function takes a condition ``<condition>`` in :ref:`Condition Syntax`,
+evaluates it, and fails the build with the message ``<message>`` if evaluation
+does not yield a truthy result. If no message is provided, the ``<condition>``
+is instead printed.
+
+.. code-block:: cmake
+ :caption: Example usage (with message)
+ :linenos:
+
+ arm_assert(
+ CONDITION STACK GREATER_EQUAL 256
+ MESSAGE "The stack must be at least 256 bytes.")
+
+ # CMake Error at cmake/Modules/ArmAssert.cmake:42 (message):
+ # The stack must be at least 256 bytes.
+ # Call Stack (most recent call first):
+ # CMakeLists.txt:42 (arm_assert)
+
+ # ... and is functionally identical to...
+
+ if(NOT STACK GREATER_EQUAL 256)
+ message(FATAL_ERROR "The stack must be at least 256 bytes.")
+ endif()
+
+.. code-block:: cmake
+ :caption: Example usage (without message)
+ :linenos:
+
+ arm_assert(CONDITION STACK GREATER_EQUAL 256)
+
+ # CMake Error at cmake/Modules/ArmAssert.cmake:42 (message):
+ # An assertion was triggered: STACK GREATER_EQUAL 256
+ # Call Stack (most recent call first):
+ # CMakeLists.txt:42 (arm_assert)
+
+ # ... and is functionally identical to...
+
+ if(NOT STACK GREATER_EQUAL 256)
+ message(FATAL_ERROR "An assertion was triggered: STACK GREATER_EQUAL 256")
+ endif()
+#]=======================================================================]
+
+include_guard()
+
+function(arm_assert)
+ set(options "")
+ set(single-args "")
+ set(multi-args "CONDITION;MESSAGE")
+
+ cmake_parse_arguments(PARSE_ARGV 0 ARG
+ "${options}" "${single-args}" "${multi-args}")
+
+ if(NOT DEFINED ARG_MESSAGE)
+ set(ARG_MESSAGE "An assertion was triggered: " ${ARG_CONDITION})
+ endif()
+
+ string(REPLACE ";" "" ARG_MESSAGE "${ARG_MESSAGE}")
+
+ if(NOT (${ARG_CONDITION}))
+ message(FATAL_ERROR "${ARG_MESSAGE}")
+ endif()
+endfunction()
diff --git a/docs/cmake/manual/module/external/ArmAssert.rst b/docs/cmake/manual/module/external/ArmAssert.rst
new file mode 100644
index 0000000..f3b78b7
--- /dev/null
+++ b/docs/cmake/manual/module/external/ArmAssert.rst
@@ -0,0 +1,5 @@
+.. cmake-module:: ../../../../../cmake/Modules/ArmAssert.cmake
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/cmake/manual/modules.rst b/docs/cmake/manual/modules.rst
index c9b6059..b23ab14 100644
--- a/docs/cmake/manual/modules.rst
+++ b/docs/cmake/manual/modules.rst
@@ -33,6 +33,8 @@
:glob:
:maxdepth: 1
+ module/external/*
+
Find Modules
------------