meta.pkgConfigModules: Init convention

See docs.

Follow-up work:

- Existing packages should be converted

- `defaultPkgConfigPackages` should assert on `meta.pkgConfigModules`
  and let `tests.pkg-config` alone test the build results.

CC @sternenseemann

Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>

doc/languages-frameworks/pkg-config.section.md

@@ -4,6 +4,48 @@
 
 Nixpkgs provides a couple of facilities for working with this tool.
 
- - A [setup hook](#setup-hook-pkg-config) bundled with in the `pkg-config` package, to bring a derivation's declared build inputs into the environment.
- - The [`validatePkgConfig` setup hook](https://nixos.org/manual/nixpkgs/stable/#validatepkgconfig), for packages that provide pkg-config modules.
- - The `defaultPkgConfigPackages` package set: a set of aliases, named after the modules they provide. This is meant to be used by language-to-nix integrations. Hand-written packages should use the normal Nixpkgs attribute name instead.
+## Writing packages providing pkg-config modules
+
+Packages should set `meta.pkgConfigProvides` with the list of package config modules they provide.
+They should also use `testers.testMetaPkgConfig` to check that the final built package matches that list.
+Additionally, the [`validatePkgConfig` setup hook](https://nixos.org/manual/nixpkgs/stable/#validatepkgconfig), will do extra checks on to-be-installed pkg-config modules.
+
+A good example of all these things is zlib:
+
+```
+{ pkg-config, testers, ... }:
+
+stdenv.mkDerivation (finalAttrs: {
+  ...
+
+  nativeBuildInputs = [ pkg-config validatePkgConfig ];
+
+  passthru.tests.pkg-config = testers.testMetaPkgConfig finalAttrs.finalPackage;
+
+  meta = {
+    ...
+    pkgConfigModules = [ "zlib" ];
+  };
+})
+```
+
+## Accessing packages via pkg-config module name
+
+### Within Nixpkgs
+
+A [setup hook](#setup-hook-pkg-config) is bundled in the `pkg-config` package to bring a derivation's declared build inputs into the environment.
+This will populate environment variables like `PKG_CONFIG_PATH`, `PKG_CONFIG_PATH_FOR_BUILD`, and `PKG_CONFIG_PATH_HOST` based on:
+
+ - how `pkg-config` itself is depended upon
+
+ - how other dependencies are depended upon
+
+For more details see the section on [specifying dependencies in general](#ssec-stdenv-dependencies).
+
+Normal pkg-config commands to look up dependencies by name will then work with those environment variables defined by the hook.
+
+### Externally
+
+The `defaultPkgConfigPackages` package set is a set of aliases, named after the modules they provide.
+This is meant to be used by language-to-nix integrations.
+Hand-written packages should use the normal Nixpkgs attribute name instead.

pkgs/build-support/testers/default.nix

@@ -123,4 +123,5 @@
 
   hasPkgConfigModule = callPackage ./hasPkgConfigModule/tester.nix { };
 
+  testMetaPkgConfig = callPackage ./testMetaPkgConfig/tester.nix { };
 }

pkgs/build-support/testers/testMetaPkgConfig/tester.nix

@@ -0,0 +1,14 @@
+{ lib, runCommand, testers }:
+
+package:
+
+runCommand "check-meta-pkg-config-modules-for-${package.name}" {
+  meta = {
+    description = "Test whether ${package.name} exposes all pkg-config modules ${toString package.meta.pkgConfigModules}";
+  };
+  dependsOn = map
+    (moduleName: testers.hasPkgConfigModule { inherit package moduleName; })
+    package.meta.pkgConfigModules;
+} ''
+  echo "found all of ${toString package.meta.pkgConfigModules}" > "$out"
+''

pkgs/development/libraries/zlib/default.nix

@@ -8,6 +8,7 @@
 # the `.pc` file lists only the main output's lib dir.
 # If false, and if `{ static = true; }`, the .a stays in the main output.
 , splitStaticOutput ? shared && static
+, testers
 }:
 
 # Without either the build will actually still succeed because the build
@@ -127,10 +128,13 @@ stdenv.mkDerivation (finalAttrs: {
     "SHARED_MODE=1"
   ];
 
+  passthru.tests.pkg-config = testers.testMetaPkgConfig finalAttrs.finalPackage;
+
   meta = with lib; {
     homepage = "https://zlib.net";
     description = "Lossless data-compression library";
     license = licenses.zlib;
     platforms = platforms.all;
+    pkgConfigModules = [ "zlib" ];
   };
 })

pkgs/stdenv/generic/check-meta.nix

@@ -271,6 +271,7 @@ let
     sourceProvenance = listOf lib.types.attrs;
     maintainers = listOf (attrsOf anything); # TODO use the maintainer type from lib/tests/maintainer-module.nix
     priority = int;
+    pkgConfigModules = listOf str;
     platforms = listOf (either str (attrsOf anything));   # see lib.meta.platformMatch
     hydraPlatforms = listOf str;
     broken = bool;