Implement `preserve_path` for install_headers

The `install_headers` function now has an optional argument
`preserve_path` that allows installing multi-directory
headerfile structures that live alongside sourcecode with a
single command.

For example, the headerfile structure

headers = [
  'one.h',
  'two.h',
  'alpha/one.h',
  'alpha/two.h',
  'alpha/three.h'
  'beta/one.h'
]

can now be passed to `install_headers(headers, subdir: 'mylib', preserve_path: true)`
and the resulting directory tree will look like

{prefix}
└── include
    └── mylib
        ├── alpha
        │   ├── one.h
        │   ├── two.h
        │   └── three.h
        ├── beta
        │   └── one.h
        ├── one.h
        └── two.h

Fixes #3371

1 files changed, 16 insertions, 0 deletions

diff --git a/docs/yaml/functions/install_headers.yaml b/docs/yaml/functions/install_headers.yaml
index cf8fb9f8d..50e1c5500 100644
--- a/docs/yaml/functions/install_headers.yaml
+++ b/docs/yaml/functions/install_headers.yaml
@@ -29,6 +29,13 @@ example: |
   install_headers('common.h', 'proj/kola.h', install_dir : 'cust', subdir : 'myproj')
   ```
 
+  This will install `common.h` into `/{prefix}/include` and `kola.h`
+  into `/{prefix}/include/proj/`:
+
+  ```meson
+  install_headers('common.h, 'proj/kola.h', preserve_path : true)
+  ```
+
 varargs:
   name: file
   type: file | str
@@ -54,3 +61,12 @@ kwargs:
       and optionally the owner/uid and group/gid for the installed files.
 
       See the `install_mode` kwarg of [[install_data]] for more information.
+
+  preserve_path:
+    type: bool
+    since: 0.63.0
+    default: false
+    description: |
+      Disable stripping child-direcories from header files when installing.
+
+      This is equivalent to GNU Automake's `nobase` option.