interpreter: Expose install_vala_* and deprecate install_dir > 1 for BuildTarget

For an end user it's opaque what these extra dirs do (even if in the
backend it's a fine data layout). Additionally, it isn't exactly obvious
that passing `install_dir : [true, true, true, true]` isn't valid if
`vala_gir` isn't set. This makes things much more obvious, and means
that an end user only needs to set values they want to overwrite.

Consider this:
```meson
library(
  'foo',
  'foo.vala',
  vala_gir : 'foo.gir',
  install : true,
  install_dir : [true, true, true, get_option('datadir') / 'mygir'],
)
```
The end use needs to know what all of these fields mean, and they need
to specify *every* field. Consider now:
```meson
library(
  'foo',
  'foo.vala',
  vala_gir : 'foo.gir',
  install : true,
  install_vala_gir_dir : get_option('datadir') / 'mygir',
)
```

This does not change the backend representation, since that works and is
mostly fine. There's probably some improvements that could be made to
group outputs and their install status together in such a way that we
cant have mismatched lists, but I haven't undertaken that here.

Author: dcbaker

docs/markdown/snippets/build_target_install_dir.md

@@ -0,0 +1,28 @@
+## BuildTarget(install_dir) length > 1 replaced with keywords
+
+Build Targets currently support (with limited documentation), passing an array
+of more than one element to `install_dir:` (except for in some wrappers), and
+will map these additional install_dir's to extra outputs. This is only used by vala, and has been replaced by explicit keyword arguments.
+
+Code like this:
+```meson
+library(
+  'foo',
+  'foo.vala',
+  install : true,
+  install_dir : [true, get_option('includedir') / 'foo', true],
+)
+```
+
+should now be written as the much clearer:
+
+```meson
+library(
+  'foo',
+  'foo.vala',
+  install : true,
+  install_vala_header_dir : get_option('includedir') / 'foo
+)
+```
+
+Note that now you only need to specify values you want to deviate from the default.

docs/yaml/functions/_build_target_base.yaml

@@ -180,6 +180,10 @@ kwargs:
       of build targets with multiple outputs. Currently, that means Vala. Setting
       them to `true` means "use the default", and `false` means, don't install.
 
+      *Since 1.10.0* Passing an array is deprecated, and install_vala_header,
+      install_vala_vapi, and install_vala_gir keyword arguments should be used
+      instead.
+
   install_mode:
     type: array[str | int]
     since: 0.47.0
@@ -376,3 +380,37 @@ kwargs:
       is not allowed to match a file or directory in the source
       directory, nor contain '..' to refer to the parent of the build
       directory.
+
+  install_vala_header:
+    type: str | bool
+    since: 1.10.0
+    description: |
+      If set to a string value, the vala generated header will be installed to
+      that path, if set to `true`, the default include path will be used, if
+      `false` the header will not be installed.
+
+      If it is unset then the value of `install_dir` will be used.
+
+  install_vala_vapi:
+    type: str | bool
+    since: 1.10.0
+    description: |
+      If set to a string value, the vala generated vapi library will be
+      installed to that path, if set to `true`, the default vapi path will be
+      used, if `false` the vapi library will not be installed.
+
+      If it is unset then the value of `install_dir` will be used.
+
+  install_vala_gir:
+    type: str | bool
+    since: 1.10.0
+    description: |
+      If set to a string value, the vala generated gir library will be
+      installed to that path, if set to `true`, the default gir path will be
+      used, if `false` the gir library will not be installed.
+
+      If it is unset then the value of `install_dir` will be used if `vala_gir`
+      is set to a value.
+
+      It is an error for this to be either `true` or a string and `vala_gir` to
+      be unset.

mesonbuild/build.py

@@ -160,7 +160,7 @@ class StaticLibraryKeywordArguments(BuildTargetKeywordArguments, total=False):
     'd_debug',
 }
 
-vala_kwargs = {'vala_header', 'vala_gir', 'vala_vapi'}
+vala_kwargs = {'vala_header', 'vala_gir', 'vala_vapi', 'install_vala_header', 'install_vala_gir', 'install_vala_vapi'}
 rust_kwargs = {'rust_crate_type', 'rust_dependency_map'}
 cs_kwargs = {'resources', 'cs_args'}
 swift_kwargs = {'swift_interoperability_mode', 'swift_module_name'}

mesonbuild/interpreter/interpreter.py

@@ -3544,12 +3544,18 @@ def build_target(self, node: mparser.BaseNode, args: T.Tuple[str, SourcesVarargs
 
         if targetclass is not build.Jar:
             kwargs = T.cast('kwtypes.Executable | kwtypes.StaticLibrary | kwtypes.SharedLibrary | kwtypes.SharedModule', kwargs)
+            # The order of these keys matters!
+            vala_keys = ('install_vala_header', 'install_vala_vapi', 'install_vala_gir')
+
             # Rewrite `install_dir : [main, vala_header, vala_vapi, vala_gir]`
             # Into split arguments
-            if kwargs['install_dir']:
+            if len(kwargs['install_dir']) > 1:
+                if any(kwargs[k] is not None for k in ('install_vala_gir', 'install_vala_header', 'install_vala_vapi')):
+                    raise InvalidArguments('Passing install_vala_* and more than one argument to install_dir are mutually exclusive')
+
                 install_dir = kwargs['install_dir'].pop(0)
 
-                for key in ['install_vala_header', 'install_vala_vapi', 'install_vala_gir']:
+                for key in vala_keys:
                     action = kwargs['install_dir'].pop(0) if kwargs['install_dir'] else install_dir
                     if isinstance(action, bool):
                         kwargs[key] = action
@@ -3561,9 +3567,24 @@ def build_target(self, node: mparser.BaseNode, args: T.Tuple[str, SourcesVarargs
                 # This was previously allowed, and tested, so we need to allow it to keep working.
                 if kwargs['vala_gir'] is None and kwargs['install_vala_gir']:
                     kwargs['install_vala_gir'] = False
+            elif kwargs['install_dir']:
+                for key in vala_keys:
+                    action = kwargs[key]
+                    if action is None:
+                        if key == 'install_vala_gir' and not kwargs['vala_gir']:
+                            continue
+                        action = kwargs['install_dir'][0]
+                    if isinstance(action, bool):
+                        kwargs[key] = action
+                    else:
+                        kwargs[key] = True
+                        kwargs[f'{key}_dir'] = action
             else:
                 kwargs['install_dir'] = [True]
 
+            if kwargs['vala_gir'] is None and kwargs['install_vala_gir']:
+                raise InvalidArguments('Cannot set `install_vala_gir` without `vala_gir`')
+
         target = targetclass(name, self.subdir, self.subproject, for_machine, srcs, struct, objs,
                              self.environment, self.compilers[for_machine], kwargs)
         if objs and target.uses_rust():

mesonbuild/interpreter/kwargs.py

@@ -366,6 +366,9 @@ class _BuildTarget(_BaseBuildTarget):
     d_module_versions: T.List[T.Union[str, int]]
     d_unittest: bool
     install_dir: T.List[T.Union[str, bool]]
+    install_vala_header: T.Union[str, bool, None]
+    install_vala_vapi: T.Union[str, bool, None]
+    install_vala_gir: T.Union[str, bool, None]
     rust_crate_type: T.Optional[Literal['bin', 'lib', 'rlib', 'dylib', 'cdylib', 'staticlib', 'proc-macro']]
     rust_dependency_map: T.Dict[str, str]
     swift_interoperability_mode: Literal['c', 'cpp']

mesonbuild/interpreter/type_checking.py

@@ -13,7 +13,7 @@
                      BothLibraries, SharedLibrary, StaticLibrary, Jar, Executable, StructuredSources)
 from ..options import OptionKey, UserFeatureOption
 from ..dependencies import Dependency, DependencyMethods, InternalDependency
-from ..interpreterbase.decorators import KwargInfo, ContainerTypeInfo, FeatureBroken
+from ..interpreterbase.decorators import KwargInfo, ContainerTypeInfo, FeatureBroken, FeatureDeprecated
 from ..mesonlib import (File, FileMode, MachineChoice, has_path_sep, listify, stringlistify,
                         EnvironmentVariables)
 from ..programs import ExternalProgram
@@ -595,6 +595,12 @@ def _extra_files_validator(args: T.List[T.Union[File, str]]) -> T.Optional[str]:
     return None
 
 
+def _bt_install_dir_deprecated(args: T.List[T.Union[str, bool]]) -> T.Iterator[FeatureCheckBase]:
+    if len(args) > 1:
+        yield FeatureDeprecated('passing more than one argument to install_dir', '1.10.0',
+                                'use the install_vala_* arguments instead')
+
+
 # Applies to all build_target like classes
 _ALL_TARGET_KWS: T.List[KwargInfo] = [
     OVERRIDE_OPTIONS_KW,
@@ -619,6 +625,7 @@ def _extra_files_validator(args: T.List[T.Union[File, str]]) -> T.Optional[str]:
         ContainerTypeInfo(list, (str, bool)),
         default=[],
         listify=True,
+        feature_validator=_bt_install_dir_deprecated,
     ),
     KwargInfo('implicit_include_directories', bool, default=True, since='0.42.0'),
     NATIVE_KW,
@@ -700,8 +707,11 @@ def _name_suffix_validator(arg: T.Optional[T.Union[str, T.List]]) -> T.Optional[
         since='0.51.0',
     ),
     KwargInfo('vala_gir', (str, NoneType)),
+    KwargInfo('install_vala_gir', (str, bool, NoneType), since='1.10.0'),
     KwargInfo('vala_header', (str, NoneType)),
+    KwargInfo('install_vala_header', (str, bool, NoneType), since='1.10.0'),
     KwargInfo('vala_vapi', (str, NoneType)),
+    KwargInfo('install_vala_vapi', (str, bool, NoneType), since='1.10.0'),
 ]
 
 def _validate_win_subsystem(value: T.Optional[str]) -> T.Optional[str]:

test cases/vala/7 shared library/lib/meson.build

@@ -27,7 +27,9 @@ shared_library('installed_vala_all_nolib', 'mylib.vala',
 shared_library('installed_vala_onlyh', 'mylib.vala',
   dependencies : valadeps,
   install : true,
-  install_dir : [false, get_option('includedir'), false])
+  install_vala_header : get_option('includedir'),
+  install_vala_vapi : false,
+  install_dir : [false])
 
 shared_library('installed_vala_onlyvapi', 'mylib.vala',
   dependencies : valadeps,

test cases/vala/7 shared library/meson.build

@@ -1,4 +1,4 @@
-project('shared library', 'vala', 'c')
+project('shared library', 'vala', 'c', meson_version : '>= 1.10.0')
 
 valadeps = [dependency('glib-2.0'), dependency('gobject-2.0')]