Distribution.Nixpkgs.Meta

A representation of the meta section used in Nix expressions.

>>> :set -XOverloadedStrings>>> :{  let meta = nullMeta        & homepage .~ "http://example.org"        & description .~ "An example package"        & license .~ Unknown Nothing        & platforms .~ Just (Set.singleton (NixpkgsPlatformSingle (Platform X86_64 Linux)))        & badPlatforms .~ Nothing        & hydraPlatforms .~ Just Set.empty        & mainProgram .~ Just "example-binary"        & maintainers .~ Set.fromList ["joe", "jane"]        & broken .~ True  in print $ pPrint meta:}homepage = "http://example.org";description = "An example package";license = "unknown";platforms = [ "x86_64-linux" ];hydraPlatforms = lib.platforms.none;mainProgram = "example-binary";maintainers = [ lib.maintainers.jane lib.maintainers.joe ];broken = true;

Meta record with no field set, i.e. evaluating any will throw:

>>> nullMeta ^. homepage"*** Exception: undefined Meta.homepage...

Representation of platform(s) as supported by nixpkgs:

• NixpkgsPlatformGroup represents the name of a platform list as found in lib.platforms. For example, at the time of writing NixpkgsPlatformGroup "darwin" would represent the platform tuples x86_64-darwin, aarch64-darwin, i686-darwin and armv7a-darwin. Naturally, this is subject to change as nixpkgs updates lib.platforms.

• NixpkgsPlatformSingle indicates a single platform tuple represented using Cabal's Platform.

The former is useful to express related groups of platforms which have similar properties. The latter can be used to, for example, exclude a single, specific platform.

hackage2nix has used the latter approach historically and is being extended to support nixpkgs' platform groups as well for increased maintainer convenience.

The Pretty instance allows for converting a NixpkgsPlatform into a Nix expression compatible with meta.platforms:

>>> pPrint $ NixpkgsPlatformSingle $ Platform X86_64 NetBSD"x86_64-netbsd"

For NixpkgsPlatformGroup we assume that the lib attribute set is in scope:

>>> pPrint $ NixpkgsPlatformGroup $ ident # "riscv"lib.platforms.riscv

Obtain a NixpkgsPlatform from a string representation intended for config files.

• Every string starting with lib.platforms. or platforms. is parsed into NixpkgsPlatformGroup.

• All other strings are attempted to be interpreted as a nix(pkgs) style system tuple and parsed into NixpkgsPlatformSingle.

If none of these formats match the input String, Nothing is returned. A Just result thus only indicates that the format of the platform is sound — nixpkgsPlatformFromString does not check if the parsed platform actually exists.

NixpkgsPlatformSingle is parsed from system tuples as understood by Nix and nixpkgs. System tuples are derived from autoconf's target triplets, dropping the vendor part. They have the form cpu-os where os can either be a single component or of the form kernel-system (system is an autoconf term here, not a Nix system). Note that three component systems are very rare. The two main candidates x86_64-linux-musl and x86_64-linux-gnu are prohibited for historical reasons and represented as plain x86_64-linux instead.

Note that nixpkgsPlatformFromString expects to receive a valid system tuple, i.e. it will accept all system tuples that have a sound format (with the caveat that it will accept n-tuples for n >= 4 even though they are technically invalid). This is done because the ambiguity of system tuples requires knowledge over its legal contents in order to check their validity properly. Since lib.systems.elaborate from nixpkgs is the source of truth in this case, we want to avoid the need to continuously update distribution-nixpkgs to reflect its inner workings.

nixpkgsPlatformFromString does, however, some conversions to alleviate some discrepancies between Cabal and nixpkgs. Parsing and rendering system tuples using nixpkgsPlatformFromString and rendering them via the Pretty instance of NixpkgsPlatform should not change the system tuple for tuples accepted by nixpkgs. This has been tested for all known tuples (from lib.platforms and lib.systems.examples) as of 2024-12-01. Please open an issue if any newly added ones are not recognized properly.

Warning: nixpkgsPlatformFromString consequently tries to preserve all information of the passed system tuple. This means that it distinguishes between things that Cabal wouldn't, e.g. powerpc64 and powerpc64le. If you use this function to obtain a Platform that is later used to evaluate a .cabal file, it will behave unexpectedly in some situation. It is recommended to use Cabal's own facilities or Distribution.Nixpkgs.Haskell.Platform, provided by cabal2nix, instead.

nixpkgsPlatformFromString is also not the inverse operation for NixpkgsPlatform's Pretty instance. It is not intended for parsing Nix expressions.

>>> nixpkgsPlatformFromString "x86_64-netbsd"Just (NixpkgsPlatformSingle (Platform X86_64 NetBSD))>>> nixpkgsPlatformFromString "platforms.riscv"Just (NixpkgsPlatformGroup (Identifier "riscv"))>>> nixpkgsPlatformFromString "garbage"Nothing