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`: