aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorEli Schwartz <eschwartz@archlinux.org>2021-10-03 14:35:30 -0400
committerEli Schwartz <eschwartz@archlinux.org>2021-10-08 14:35:00 -0400
commit108bd996ee72b16c14f0ee0ca86959b142582394 (patch)
tree2cc138363c7139ce3fa2ae918e75ac5b81d19c77 /docs
parent54e17ad5975252242712dc3b613bdbd0a2504e23 (diff)
downloadmeson-108bd996ee72b16c14f0ee0ca86959b142582394.zip
meson-108bd996ee72b16c14f0ee0ca86959b142582394.tar.gz
meson-108bd996ee72b16c14f0ee0ca86959b142582394.tar.bz2
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
Diffstat (limited to 'docs')
-rw-r--r--docs/markdown/snippets/install_emptydir.md18
-rw-r--r--docs/yaml/functions/install_emptydir.yaml27
-rw-r--r--docs/yaml/functions/install_subdir.yaml9
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`: