Added documentation.

docs/markdown/Installing.md

@@ -4,7 +4,8 @@ short-description: Installing targets
 
 # 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 @@ shared_library('mylib', 'libfile.c', install : true)
 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_data(['file1.txt', 'file2.txt'],
              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 @@ install_data(sources : 'foo.dat', install_dir : '/etc') # -> /etc/foo.dat
 
 ## 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 @@ mkdir "${DESTDIR}/${MESON_INSTALL_PREFIX}/mydir"
 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 @@ Telling Meson to run this script at install time is a one-liner.
 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
+```

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