document and raise an error for disallowed combination of install_headers args

It makes no sense to specify both:
- install_dir, which overrides the -Dincludedir= builtin option
- subdir, which suffixes the -Dincludedir= builtin option

We've always silently ignored the subdir in this case, which is really
surprising if someone actually passed it and expected it to do
something. We also confusingly didn't say anything in the documentation
about it.

Document that the options are incompatible, and explicitly check to see
if they are both passed -- if so, raise an error message pointing out
that only install_dir should be used.

Fixes #10046

2 files changed, 10 insertions, 4 deletions

diff --git a/docs/yaml/functions/install_headers.yaml b/docs/yaml/functions/install_headers.yaml
index 8dc8205..cf8fb9f 100644
--- a/docs/yaml/functions/install_headers.yaml
+++ b/docs/yaml/functions/install_headers.yaml
@@ -37,11 +37,14 @@ varargs:
 kwargs:
   install_dir:
     type: str
-    description: Where to install to
+    description: Where to install to.
 
   subdir:
     type: str
-    description: Use the `subdir` in the `install_dir`
+    description: |
+      Install to the `subdir` subdirectory of the default includedir.
+
+      Incompatible with the `install_dir` kwarg.
 
   install_mode:
     type: list[str | int]
diff --git a/mesonbuild/interpreter/interpreter.py b/mesonbuild/interpreter/interpreter.py
index 97ec7c8..b2d7224 100644
--- a/mesonbuild/interpreter/interpreter.py
+++ b/mesonbuild/interpreter/interpreter.py
@@ -2004,8 +2004,11 @@ external dependencies (including libraries) must go to "dependencies".''')
                              kwargs: 'kwargs.FuncInstallHeaders') -> build.Headers:
         source_files = self.source_strings_to_files(args[0])
         install_subdir = kwargs['subdir']
-        if install_subdir is not None and os.path.isabs(install_subdir):
-            mlog.deprecation('Subdir keyword must not be an absolute path. This will be a hard error in the next release.')
+        if install_subdir is not None:
+            if kwargs['install_dir'] is not None:
+                raise InterpreterException('install_headers: cannot specify both "install_dir" and "subdir". Use only "install_dir".')
+            if os.path.isabs(install_subdir):
+                mlog.deprecation('Subdir keyword must not be an absolute path. This will be a hard error in the next release.')
 
         h = build.Headers(source_files, install_subdir, kwargs['install_dir'],
                           kwargs['install_mode'], self.subproject)