Add new debug() function

Adds a new debug() function that can be used in the meson.build to
log messages to the meson-log.txt that will not be printed to stdout
when configuring the project.

7 files changed, 46 insertions, 0 deletions

diff --git a/data/syntax-highlighting/vim/syntax/meson.vim b/data/syntax-highlighting/vim/syntax/meson.vim
index 0519bb2..2cb49e3 100644
--- a/data/syntax-highlighting/vim/syntax/meson.vim
+++ b/data/syntax-highlighting/vim/syntax/meson.vim
@@ -127,6 +127,7 @@ syn keyword mesonBuiltin
   \ vcs_tag
   \ warning
   \ range
+  \ debug
 
 if exists("meson_space_error_highlight")
   " trailing whitespace
diff --git a/docs/markdown/snippets/new-debug-function.md b/docs/markdown/snippets/new-debug-function.md
new file mode 100644
index 0000000..c900827
--- /dev/null
+++ b/docs/markdown/snippets/new-debug-function.md
@@ -0,0 +1,5 @@
+## Added `debug` function
+
+In addition to the `message()`, `warning()` and `error()` functions there is now the
+`debug()` function to log messages that only end up in the `meson-log.txt` logfile
+and are not printed to stdout at configure time.
diff --git a/docs/yaml/functions/debug.yaml b/docs/yaml/functions/debug.yaml
new file mode 100644
index 0000000..a64bd92
--- /dev/null
+++ b/docs/yaml/functions/debug.yaml
@@ -0,0 +1,14 @@
+name: debug
+returns: void
+since: 0.63.0
+description: Write the argument string to the meson build log.
+
+posargs:
+  message:
+    type: str | int | bool | list[str | int | bool] | dict[str | int | bool]
+    description: The message to print
+
+varargs:
+  name: msg
+  type: str | int | bool | list[str | int | bool] | dict[str | int | bool]
+  description: Additional parameters will be separated by spaces
diff --git a/mesonbuild/ast/interpreter.py b/mesonbuild/ast/interpreter.py
index e3d3e93..6128eef 100644
--- a/mesonbuild/ast/interpreter.py
+++ b/mesonbuild/ast/interpreter.py
@@ -157,6 +157,7 @@ class AstInterpreter(InterpreterBase):
                            'summary': self.func_do_nothing,
                            'range': self.func_do_nothing,
                            'structured_sources': self.func_do_nothing,
+                           'debug': self.func_do_nothing,
                            })
 
     def _unholder_args(self, args: _T, kwargs: _V) -> T.Tuple[_T, _V]:
diff --git a/mesonbuild/interpreter/interpreter.py b/mesonbuild/interpreter/interpreter.py
index 9b84231..b31b7a8 100644
--- a/mesonbuild/interpreter/interpreter.py
+++ b/mesonbuild/interpreter/interpreter.py
@@ -356,6 +356,7 @@ class Interpreter(InterpreterBase, HoldableObject):
                            'configuration_data': self.func_configuration_data,
                            'configure_file': self.func_configure_file,
                            'custom_target': self.func_custom_target,
+                           'debug': self.func_debug,
                            'declare_dependency': self.func_declare_dependency,
                            'dependency': self.func_dependency,
                            'disabler': self.func_disabler,
@@ -1324,6 +1325,13 @@ external dependencies (including libraries) must go to "dependencies".''')
         args_str = [stringifyUserArguments(i) for i in args]
         raise InterpreterException('Problem encountered: ' + ' '.join(args_str))
 
+    @noArgsFlattening
+    @FeatureNew('debug', '0.63.0')
+    @noKwargs
+    def func_debug(self, node, args, kwargs):
+        args_str = [stringifyUserArguments(i) for i in args]
+        mlog.debug('Debug:', *args_str)
+
     @noKwargs
     @noPosargs
     def func_exception(self, node, args, kwargs):
diff --git a/test cases/unit/104 debug function/meson.build b/test cases/unit/104 debug function/meson.build
new file mode 100644
index 0000000..c3f4c76
--- /dev/null
+++ b/test cases/unit/104 debug function/meson.build
@@ -0,0 +1,4 @@
+project('debug function', 'c')
+
+debug('This is an example debug output, should only end up in debug log')
+debug('Test logging other things', true, 1, ['Array'], {'Key' : 'Value'})
diff --git a/unittests/platformagnostictests.py b/unittests/platformagnostictests.py
index b5907a1..6e0951f 100644
--- a/unittests/platformagnostictests.py
+++ b/unittests/platformagnostictests.py
@@ -70,3 +70,16 @@ class PlatformAgnosticTests(BasePlatformTests):
     def test_python_dependency_without_pkgconfig(self):
         testdir = os.path.join(self.unit_test_dir, '102 python without pkgconfig')
         self.init(testdir, override_envvars={'PKG_CONFIG': 'notfound'})
+
+    def test_debug_function_outputs_to_meson_log(self):
+        testdir = os.path.join(self.unit_test_dir, '104 debug function')
+        log_msg = 'This is an example debug output, should only end up in debug log'
+        output = self.init(testdir)
+
+        # Check if message is not printed to stdout while configuring
+        assert(log_msg not in output)
+
+        # Check if message is written to the meson log
+        mesonlog = os.path.join(self.builddir, 'meson-logs/meson-log.txt')
+        with open(mesonlog, mode='r', encoding='utf-8') as file:
+            assert(log_msg in file.read())