add install_emptydir function

This replaces the absolute hack of using

```
install_subdir('nonexisting', install_dir: 'share')
```

which requires you to make sure you don't accidentally or deliberately
have a completely different directory with the same name in your source
tree that is full of files you don't want installed. It also avoids
splitting the name in two and listing them in the wrong order.

You can also set the install mode of each directory component by listing
them one at a time in order, and in fact create nested structures at
all.

Fixes #1604
Properly fixes #2904

3 files changed, 51 insertions, 3 deletions

diff --git a/docs/markdown/snippets/install_emptydir.md b/docs/markdown/snippets/install_emptydir.md
new file mode 100644
index 0000000..baedf58
--- /dev/null
+++ b/docs/markdown/snippets/install_emptydir.md
@@ -0,0 +1,18 @@
+## install_emptydir function
+
+It is now possible to define a directory which will be created during
+installation, without creating it as a side effect of installing files into it.
+This replaces custom `meson.add_install_script()` routines. For example:
+
+```meson
+meson.add_install_script('sh', '-c', 'mkdir -p "$DESTDIR/@0@"'.format(path))
+```
+
+can be replaced by:
+
+```meson
+install_emptydir(path)
+```
+
+and as a bonus this works reliably on Windows, prints a sensible progress
+message, will be uninstalled by `ninja uninstall`, etc.
diff --git a/docs/yaml/functions/install_emptydir.yaml b/docs/yaml/functions/install_emptydir.yaml
new file mode 100644
index 0000000..9c874e2
--- /dev/null
+++ b/docs/yaml/functions/install_emptydir.yaml
@@ -0,0 +1,27 @@
+name: install_emptydir
+returns: void
+since: 0.60.0
+description: |
+  Installs a new directory entry to the location specified by the positional
+  argument. If the directory exists and is not empty, the contents are left in
+  place.
+
+varargs:
+  name: dirpath
+  type: str
+  description: Directory to create during installation.
+
+kwargs:
+  install_mode:
+    type: list[str | int]
+    description: |
+      Specify the file mode in symbolic format and optionally the owner/uid and
+      group/gid for the created directory.
+
+      See the `install_mode` kwarg of [[install_data]] for more information.
+    install_tag:
+      type: str
+      description: |
+        A string used by the `meson install --tags` command to install only a
+        subset of the files. By default this directory has no install tag which
+        means it is not installed when the `--tags` argument is specified.
diff --git a/docs/yaml/functions/install_subdir.yaml b/docs/yaml/functions/install_subdir.yaml
index 83df782..90baed2 100644
--- a/docs/yaml/functions/install_subdir.yaml
+++ b/docs/yaml/functions/install_subdir.yaml
@@ -5,9 +5,12 @@ description: |
   source tree to the location specified by the keyword argument
   `install_dir`.
 
-  If the subdirectory does not exist in the source tree, an empty directory is
-  created in the specified location. *(since 0.45.0)* A newly created
-  subdirectory may only be created in the keyword argument `install_dir`.
+  *(since 0.45.0, deprecated since 0.60.0)* If the subdirectory does not exist
+  in the source tree, an empty directory is created in the specified location.
+  A newly created subdirectory may only be created in the keyword argument
+  `install_dir`. There are a number of flaws with this method, and it was never
+  intentionally designed to work this way, please use [[install_emptydir]]
+  instead.
 
 example: |
   For a given directory `foo`: