Add install tags

Fixes: #7007.

4 files changed, 91 insertions, 27 deletions

diff --git a/docs/markdown/Installing.md b/docs/markdown/Installing.md
index 42c71f1..4a87ca3 100644
--- a/docs/markdown/Installing.md
+++ b/docs/markdown/Installing.md
@@ -74,7 +74,7 @@ giving an absolute install path.
 install_data(sources : 'foo.dat', install_dir : '/etc') # -> /etc/foo.dat
 ```
 
-## Custom install behavior
+## Custom install script
 
 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
@@ -133,23 +133,57 @@ command in the build tree:
 $ meson install --no-rebuild --only-changed
 ```
 
-## Finer control over install locations
-
-Sometimes it is necessary to only install a subsection of output files
-or install them in different directories. This can be done by
-specifying `install_dir` as an array rather than a single string. The
-array must have as many items as there are outputs and each entry
-specifies how the corresponding output file should be installed. For
-example:
-
-```meson
-custom_target(...
-    output: ['file1', 'file2', 'file3'],
-    install_dir: ['path1', false, 'path3'],
-    ...
-)
-```
-
-In this case `file1` would be installed to `/prefix/path1/file1`,
-`file2` would not be installed at all and `file3` would be installed
-to `/prefix/path3/file3'.
+## Installation tags
+
+*Since 0.60.0*
+
+It is possible to install only a subset of the installable files using
+`meson install --tags tag1,tag2` command line. When `--tags` is specified, only
+files that have been tagged with one of the tags are going to be installed.
+
+This is intended to be used by packagers (e.g. distributions) who typically
+want to split `libfoo`, `libfoo-dev` and `libfoo-doc` packages. Instead of
+duplicating the list of installed files per category in each packaging system,
+it can be maintained in a single place, directly in upstream `meson.build` files.
+
+Meson sets predefined tags on some files. More tags are likely to be added over
+time, please help extending the list of well known categories.
+- `devel`:
+  * `static_library()`,
+  * `install_headers()`,
+  * `pkgconfig.generate()`,
+  * `gnome.generate_gir()` - `.gir` file,
+  * Files installed into `libdir` and with `.a` or `.pc` extension,
+  * File installed into `includedir`.
+- `runtime`:
+  * `executable()`,
+  * `shared_library()`,
+  * `shared_module()`,
+  * `jar()`,
+  * Files installed into `bindir`.
+  * Files installed into `libdir` and with `.so` or `.dll` extension.
+- `python-runtime`:
+  * `python.install_sources()`.
+- `man`:
+  * `install_man()`.
+- `doc`:
+  * `gnome.gtkdoc()`,
+  * `hotdoc.generate_doc()`.
+- `i18n`:
+  * `i18n.gettext()`,
+  * `qt.compile_translations()`,
+  * Files installed into `localedir`.
+- `typelib`:
+  * `gnome.generate_gir()` - `.typelib` file.
+
+Custom installation tag can be set using the `install_tag` keyword argument
+on various functions such as `custom_target()`, `configure_file()`,
+`install_subdir()` and `install_data()`. See their respective documentation
+in the reference manual for details. It is recommended to use one of the
+predefined tags above when possible.
+
+Installable files that have not been tagged either automatically by Meson, or
+manually using `install_tag` keyword argument won't be installed when `--tags`
+is used. They are reported at the end of `<builddir>/meson-logs/meson-log.txt`,
+it is recommended to add missing `install_tag` to have a tag on each installable
+files.
diff --git a/docs/markdown/Python-module.md b/docs/markdown/Python-module.md
index 3b7b4f5..20eae1a 100644
--- a/docs/markdown/Python-module.md
+++ b/docs/markdown/Python-module.md
@@ -135,6 +135,9 @@ All positional and keyword arguments are the same as for
 - `subdir`: See documentation for the argument of the same name to
   [][`extension_module()`]
 
+- `install_tag` *(since 0.60.0)*: A string used by `meson install --tags` command
+  to install only a subset of the files. By default it has the tag `python-runtime`.
+
 #### `get_install_dir()`
 
 ``` meson
diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 6454830..fd78a1e 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -304,6 +304,9 @@ false otherwise.
   string, the file is not installed.
 - `install_mode` *(since 0.47.0)*: specify the file mode in symbolic format
   and optionally the owner/uid and group/gid for the installed files.
+- `install_tag` *(since 0.60.0)*: A string used by `meson install --tags` command
+  to install only a subset of the files. By default the file has no install
+  tag which means it is not being installed when `--tags` argument is specified.
 - `output`: the output file name. *(since 0.41.0)* may contain
   `@PLAINNAME@` or `@BASENAME@` substitutions. In configuration mode,
   the permissions of the input file (if it is specified) are copied to
@@ -378,7 +381,7 @@ following.
 - `install_dir`: If only one install_dir is provided, all outputs are installed there.
    *Since 0.40.0* Allows you to specify the installation directory for each
     corresponding output. For example:
-    ```
+    ```meson
     custom_target('different-install-dirs',
       output : ['first.file', 'second.file'],
       install : true,
@@ -388,15 +391,21 @@ following.
 
     To only install some outputs, pass `false` for the outputs that you
     don't want installed. For example:
-    ```
-        custom_target('only-install-second',
-          output : ['first.file', 'second.file'],
-          install : true,
-          install_dir : [false, 'otherdir])
+    ```meson
+    custom_target('only-install-second',
+      output : ['first.file', 'second.file'],
+      install : true,
+      install_dir : [false, 'otherdir])
     ```
     This would install `second.file` to `otherdir` and not install `first.file`.
 - `install_mode` *(since 0.47.0)*: the file mode and optionally the
   owner/uid and group/gid
+- `install_tag` *(since 0.60.0)*: A list of strings, one per output, used by
+  `meson install --tags` command to install only a subset of the files.
+  By default all outputs have no install tag which means they are not being
+  installed when `--tags` argument is specified. If only one tag is specified,
+  it is assumed that all outputs have the same tag. `false` can be used for
+  outputs that have no tag or are not installed.
 - `output`: list of output files
 - `env` *(since 0.57.0)*: environment variables to set, such as
   `{'NAME1': 'value1', 'NAME2': 'value2'}` or `['NAME1=value1', 'NAME2=value2']`,
@@ -729,6 +738,9 @@ be passed to [shared and static libraries](#library).
   and optionally the owner/uid and group/gid for the installed files.
 - `install_rpath`: a string to set the target's rpath to after install
   (but *not* before that). On Windows, this argument has no effect.
+- `install_tag` *(since 0.60.0)*: A string used by `meson install --tags` command
+  to install only a subset of the files. By default all build targets have the
+  tag `runtime` except for static libraries that have the `devel` tag.
 - `objects`: list of prebuilt object files (usually for third party
   products you don't have source to) that should be linked in this
   target, **never** use this for object files that you build yourself.
@@ -1103,6 +1115,9 @@ arguments. The following keyword arguments are supported:
   file from `rename` list. Nested paths are allowed and they are
   joined with `install_dir`. Length of `rename` list must be equal to
   the number of sources.
+- `install_tag` *(since 0.60.0)*: A string used by `meson install --tags` command
+  to install only a subset of the files. By default these files have no install
+  tag which means they are not being installed when `--tags` argument is specified.
 
 See [Installing](Installing.md) for more examples.
 
@@ -1201,6 +1216,9 @@ The following keyword arguments are supported:
   the owner/uid and group/gid for the installed files.
 - `strip_directory` *(since 0.45.0)*: install directory contents. `strip_directory=false` by default.
   If `strip_directory=true` only the last component of the source path is used.
+- `install_tag` *(since 0.60.0)*: A string used by `meson install --tags` command
+  to install only a subset of the files. By default these files have no install
+  tag which means they are not being installed when `--tags` argument is specified.
 
 For a given directory `foo`:
 ```text
@@ -1975,6 +1993,9 @@ the following methods.
   can be specified. If `true` the script will not be run if DESTDIR is set during
   installation. This is useful in the case the script updates system wide
   cache that is only needed when copying files into final destination.
+  *(since 0.60.0)* `install_tag` string keyword argument can be specified.
+  By default the script has no install tag which means it is not being run when
+  `meson install --tags` argument is specified.
 
   *(since 0.54.0)* If `meson install` is called with the `--quiet` option, the
   environment variable `MESON_INSTALL_QUIET` will be set.
diff --git a/docs/markdown/snippets/install_tag.md b/docs/markdown/snippets/install_tag.md
new file mode 100644
index 0000000..36df639
--- /dev/null
+++ b/docs/markdown/snippets/install_tag.md
@@ -0,0 +1,6 @@
+## Installation tags
+
+It is now possible to install only a subset of the installable files using
+`meson install --tags tag1,tag2` command line.
+
+See [documentation](Installing.md#installation-tags) for more details.