From 442fd7dc73dcdd86212f833aa342e9d6d98fba32 Mon Sep 17 00:00:00 2001
From: Fredrik Salomonsson <plattfot@posteo.net>
Date: Wed, 13 Apr 2022 14:28:59 -0700
Subject: docs: Add documentation on pkgconfig.relocatable

- Documentation for the pkgconfig.relocatable module option in
Builtin-options. Gives an explanation on what it does, usefulness and
what error that can occur when using it.

- Add pkgconfig.relocatable release snippet. Similar to the
documentation in Builtin-options. Just a bit more brief.

- Add Pkgconfig to DataTests.test_builtin_options_documented in the
docs unit tests.
---
 docs/markdown/Builtin-options.md                | 21 +++++++++++++++++++++
 docs/markdown/snippets/pkgconfig-relocatable.md | 18 ++++++++++++++++++
 unittests/datatests.py                          |  2 +-
 3 files changed, 40 insertions(+), 1 deletion(-)
 create mode 100644 docs/markdown/snippets/pkgconfig-relocatable.md

diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md
index a7a6a89..7688914 100644
--- a/docs/markdown/Builtin-options.md
+++ b/docs/markdown/Builtin-options.md
@@ -275,6 +275,27 @@ Since 0.56.0 `warning_level` can also be defined per subproject.
 Some Meson modules have built-in options. They can be set by prefixing the option
 name with the module name: `-D<module>.<option>=<value>` (e.g. `-Dpython.platlibdir=/foo`).
 
+### Pkgconfig module
+
+| Option      | Default value | Possible values | Description                                                |
+|-------------|---------------|-----------------|------------------------------------------------------------|
+| relocatable | false         | true, false     | Generate the pkgconfig files as relocatable (Since 0.63.0) |
+
+*Since 0.63.0* The `pkgconfig.relocatable` option is used by the
+pkgconfig module, namely [`pkg.generate()`](Pkgconfig-module.md) and affect how the
+`prefix` in the generated pkgconfig file is set (not to be confused
+with the [install prefix](#directories)). When it is `true` the `prefix` will be
+relative to the `install_dir`. This allows the pkgconfig file to be
+moved around and still work, as long as the relative path is not
+broken. In general this allows for the whole installed package to be
+placed anywhere on the system and still work as a dependency. When it
+is set to `false` the `prefix` will be the same as the install prefix.
+
+An error will be raised if `pkgconfig.relocatable` is `true` and the
+`install_dir` for a generated pkgconfig file points outside the
+install prefix. For example if the install prefix is `/usr` and the
+`install_dir` for a pkgconfig file is `/var/lib/pkgconfig`.
+
 ### Python module
 
 | Option           | Default value | Possible values             | Description |
diff --git a/docs/markdown/snippets/pkgconfig-relocatable.md b/docs/markdown/snippets/pkgconfig-relocatable.md
new file mode 100644
index 0000000..901da6e
--- /dev/null
+++ b/docs/markdown/snippets/pkgconfig-relocatable.md
@@ -0,0 +1,18 @@
+## Installed pkgconfig files can now be relocatable
+
+The pkgconfig module now has a module option `pkgconfig.relocatable`.
+When set to `true`, the pkgconfig files generated will have their
+`prefix` variable set to be relative to their `install_dir`.
+
+For example to enable it from the command line run:
+
+```sh
+meson setup builddir -Dpkgconfig.relocatable=true …
+```
+
+It will only work if the `install_dir` for the generated pkgconfig
+files are located inside the install prefix of the package. Not doing
+so will cause an error.
+
+This should be useful on Windows or any other platform where
+relocatable packages are desired.
diff --git a/unittests/datatests.py b/unittests/datatests.py
index 4d4d3a1..9a46ec4 100644
--- a/unittests/datatests.py
+++ b/unittests/datatests.py
@@ -128,7 +128,7 @@ class DataTests(unittest.TestCase):
         mod_subcontents = []
         content = self._get_section_content("Module options", sections, md)
         subsections = tee(re.finditer(r"^### (.+)$", content, re.MULTILINE))
-        for idx, mod in enumerate(['Python']):
+        for idx, mod in enumerate(['Pkgconfig', 'Python']):
             mod_subcontents.append(self._get_section_content(f'{mod} module', subsections[idx], content))
         for subcontent in u_subcontents + mod_subcontents:
             # Find the option names
-- 
cgit v1.1