Commit 6e4a1b18 authored by John Ericson's avatar John Ericson
Browse files

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: default avatarRobert Hensing <roberth@users.noreply.github.com>
parent 3dcde1c3

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

+45 −3
Original line number Diff line number Diff line
@@ -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

+1 −0
Original line number Diff line number Diff line
@@ -123,4 +123,5 @@ 


  hasPkgConfigModule = callPackage ./hasPkgConfigModule/tester.nix { };



  testMetaPkgConfig = callPackage ./testMetaPkgConfig/tester.nix { };

}

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

0 → 100644
+14 −0
Original line number Diff line number Diff line 
{ 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

+4 −0
Original line number Diff line number Diff line
@@ -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

+1 −0
Original line number Diff line number Diff line
@@ -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;