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

2 files changed, 51 insertions, 0 deletions

diff --git a/docs/markdown/snippets/install_headers_preserve_path_arg.md b/docs/markdown/snippets/install_headers_preserve_path_arg.md
new file mode 100644
index 000000000..c41fceb34
--- /dev/null
+++ b/docs/markdown/snippets/install_headers_preserve_path_arg.md
@@ -0,0 +1,35 @@
+## Added preserve_path arg to 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
+
+```meson
+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
+```
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.