meson: Allow directory options outside of prefix

This bring us in line with Autotools and CMake and it is useful
for platforms like Nix, which install projects
into multiple independent prefixes.

As a consequence, `get_option` might return absolute paths for some
directory options, if a directory outside of prefix is passed.

This is technically a backwards incompatible change but its effect
should be minimal, thanks to widespread use of `join_paths`/`/` operator
and pkg-config generator module. It should only cause an issue when
a path were constructed by concatenating the value of directory path option.

Also remove a comment about commonpath since we do not use that since
<https://github.com/mesonbuild/meson/commit/00f5dadd5b7d71c30bd7393d165a87f554eb92e5>.

Fixes: https://github.com/mesonbuild/meson/issues/2561

4 files changed, 27 insertions, 15 deletions

diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md
index 613b8b8..db3c3e8 100644
--- a/docs/markdown/Builtin-options.md
+++ b/docs/markdown/Builtin-options.md
@@ -23,13 +23,15 @@ For legacy reasons `--warnlevel` is the cli argument for the
 They can also be edited after setup using `meson configure
 -Doption=value`.
 
-Installation options are all relative to the prefix, except:
+Installation options are usually relative to the prefix but it should
+not be relied on, since they can be absolute paths in the following cases:
 
 * When the prefix is `/usr`: `sysconfdir` defaults to `/etc`,
  `localstatedir` defaults to `/var`, and `sharedstatedir` defaults to
  `/var/lib`
 * When the prefix is `/usr/local`: `localstatedir` defaults
  to `/var/local`, and `sharedstatedir` defaults to `/var/local/lib`
+* When an absolute path outside of prefix is provided by the user/distributor.
 
 ### Directories
 
diff --git a/docs/markdown/snippets/dir_options_outside_prefix.md b/docs/markdown/snippets/dir_options_outside_prefix.md
new file mode 100644
index 0000000..ceb5e50
--- /dev/null
+++ b/docs/markdown/snippets/dir_options_outside_prefix.md
@@ -0,0 +1,12 @@
+## All directory options now support paths outside of prefix
+
+Previously, Meson only allowed most directory options to be relative to prefix.
+This restriction has been now lifted, bringing us in line with Autotools and
+CMake. It is also useful for platforms like Nix, which install projects into
+multiple independent prefixes.
+
+As a consequence, `get_option` might return absolute paths for any
+directory option, if a directory outside of prefix is passed. This
+is technically a backwards incompatible change but its effect
+should be minimal, thanks to widespread use of `join_paths`/
+`/` operator and pkg-config generator module.
diff --git a/docs/yaml/functions/_build_target_base.yaml b/docs/yaml/functions/_build_target_base.yaml
index 62424b6..68df5d8 100644
--- a/docs/yaml/functions/_build_target_base.yaml
+++ b/docs/yaml/functions/_build_target_base.yaml
@@ -161,10 +161,10 @@ kwargs:
   install_dir:
     type: str
     description: |
-      override install directory for this file. The value is
-      relative to the `prefix` specified. F.ex, if you want to install
-      plugins into a subdir, you'd use something like this: `install_dir :
-      get_option('libdir') / 'projectname-1.0'`.
+      override install directory for this file. If the value is a relative path,
+      it will be considered relative the `prefix` option.
+      For example, if you want to install plugins into a subdir, you'd use
+      something like this: `install_dir : get_option('libdir') / 'projectname-1.0'`.
 
   install_mode:
     type: list[str | int]
diff --git a/docs/yaml/functions/get_option.yaml b/docs/yaml/functions/get_option.yaml
index 0bf0042..7f7982e 100644
--- a/docs/yaml/functions/get_option.yaml
+++ b/docs/yaml/functions/get_option.yaml
@@ -5,16 +5,14 @@ description: |
   specified in the positional argument.
 
   Note that the value returned for built-in options that end in `dir`
-  such as `bindir` and `libdir` is always a path relative to (and
-  inside) the `prefix`.
-
-  The only exceptions are: `sysconfdir`, `localstatedir`, and
-  `sharedstatedir` which will return the value passed during
-  configuration as-is, which may be absolute, or relative to `prefix`.
-  [`install_dir` arguments](Installing.md) handles that as expected, but
-  if you need the absolute path to one of these e.g. to use in a define
-  etc., you should use `get_option('prefix') /
-  get_option('localstatedir')`
+  such as `bindir` and `libdir` is usually a path relative to (and
+  inside) the `prefix` but you should not rely on that, as it can also
+  be an absolute path [in some cases](Builtin-options.md#Universal options).
+  [`install_dir` arguments](Installing.md) handle that as expected
+  but if you need an absolute path, e.g. to use in a define etc.,
+  you should use the path concatenation operator like this:
+  `get_option('prefix') / get_option('localstatedir')`.
+  Never manually join paths as if they were strings.
 
   For options of type `feature` a
   [[@feature]] option object