Added documentation.
diff --git a/docs/markdown/Installing.md b/docs/markdown/Installing.md
index b8e6a81..8348d4a 100644
--- a/docs/markdown/Installing.md
+++ b/docs/markdown/Installing.md
@@ -4,7 +4,8 @@
# Installing
-By default Meson will not install anything. Build targets can be installed by tagging them as installable in the definition.
+By default Meson will not install anything. Build targets can be
+installed by tagging them as installable in the definition.
```meson
project('install', 'c')
@@ -14,8 +15,8 @@
There is usually no need to specify install paths or the like. Meson
will automatically install it to the standards-conforming location. In
this particular case the executable is installed to the `bin`
-subdirectory of the install prefix. However if you wish to override the
-install dir, you can do that with the `install_dir` argument.
+subdirectory of the install prefix. However if you wish to override
+the install dir, you can do that with the `install_dir` argument.
```meson
executable('prog', 'prog.c', install : true, install_dir : 'my/special/dir')
@@ -42,7 +43,9 @@
install_dir : 'share/myapp')
```
-Sometimes you want to copy an entire subtree directly. For this use case there is the `install_subdir` command, which can be used like this.
+Sometimes you want to copy an entire subtree directly. For this use
+case there is the `install_subdir` command, which can be used like
+this.
```meson
install_subdir('mydir', install_dir : 'include') # mydir subtree -> include/mydir
@@ -59,7 +62,10 @@
## Custom install behavior
-Sometimes you need to do more than just install basic targets. Meson makes this easy by allowing you to specify a custom script to execute at install time. As an example, here is a script that generates an empty file in a custom directory.
+Sometimes you need to do more than just install basic targets. Meson
+makes this easy by allowing you to specify a custom script to execute
+at install time. As an example, here is a script that generates an
+empty file in a custom directory.
```bash
#!/bin/sh
@@ -68,7 +74,10 @@
touch "${DESTDIR}/${MESON_INSTALL_PREFIX}/mydir/file.dat"
```
-As you can see, Meson sets up some environment variables to help you write your script (`DESTDIR` is not set by Meson, it is inherited from the outside environment). In addition to the install prefix, Meson also sets the variables `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT`.
+As you can see, Meson sets up some environment variables to help you
+write your script (`DESTDIR` is not set by Meson, it is inherited from
+the outside environment). In addition to the install prefix, Meson
+also sets the variables `MESON_SOURCE_ROOT` and `MESON_BUILD_ROOT`.
Telling Meson to run this script at install time is a one-liner.
@@ -76,12 +85,32 @@
meson.add_install_script('myscript.sh')
```
-The argument is the name of the script file relative to the current subdirectory.
+The argument is the name of the script file relative to the current
+subdirectory.
## DESTDIR support
-Sometimes you need to install to a different directory than the install prefix. This is most common when building rpm or deb packages. This is done with the `DESTDIR` environment variable and it is used just like with other build systems:
+Sometimes you need to install to a different directory than the
+install prefix. This is most common when building rpm or deb
+packages. This is done with the `DESTDIR` environment variable and it
+is used just like with other build systems:
```console
$ DESTDIR=/path/to/staging/area ninja install
```
+
+## Custom install behaviour
+
+The default install target (executed via, e.g., `ninja install`) does
+installing with reasonable default options. More control over the
+install behaviour can be achieved with the `meson install` command,
+that has been available since 0.47.0.
+
+For example, if you wish to install the current setup without
+rebuilding the code (which the default install target always does) and
+only installing those files that have changed, you would run this
+command in the build tree:
+
+```console
+$ meson install --no-rebuild --only-changed
+```
diff --git a/docs/markdown/snippets/install_command.md b/docs/markdown/snippets/install_command.md
new file mode 100644
index 0000000..68866c9
--- /dev/null
+++ b/docs/markdown/snippets/install_command.md
@@ -0,0 +1,12 @@
+## Made install a top level Meson command
+
+You can now run `meson install` in your build directory and it will do
+the install. It has several command line options you can toggle the
+behaviour that is not in the default `ninja install` invocation. This
+is similar to how `meson test` already works.
+
+For example, to install only the files that have changed, you can do:
+
+```console
+meson install --only-changed
+```
