Change:
The documentation for says: "must be set when appropriate". What does it mean for to "be appropriate"? My guess is that is "appropriate" in one of the two cases: When the main binary exposed by the package is different than the attribute name in Nixpkgs. For instance, the Nixpkgs attribute exposes a main binary , so it should definitely have . For any package that exposes a "main" binary. In this case, even a package like (which is a top-level attribute in Nixpkgs called ), would also be required to set . (The inverse question would be, are packages required to set when the attribute name in Nixpkgs is the same as the main binary name? If so, this requirement should be clearly documented in the above README.) <!-- make sure this issue is not redundant or obsolete --- [X] checked [latest Nixpkgs manual] ([source][nixpkgs-source]) and [latest NixOS manual] ([source][nixos-source]) [x] checked [open documentation issues] for possible duplicates (I only sort of did this. It is hard to search for without getting a bunch of irrelevant issues) [x] checked [open documentation pull requests] for possible solutions [latest Nixpkgs manual]: [latest NixOS manual]: [nixpkgs-source]: [nixos-source]: [open documentation issues]: [open documentation pull requests]: Add a :+1: [reaction] to [issues you find important]. [reaction]: [issues you find important]:
Let me cc since I'm guessing he would likely know the answer to this (or at least be able to cc someone else who would).
meta.mainProgram should be set explicitly when it makes sense. Since 23.11 accesssing raises a warning if it wasn't set explicitly.
this is correct
I interpret that mainProgram is required for any derivation that has something executable in $out/bin
not correct. for example, pkgs.coreutils has something executable in $out/bin, but it should not have a mainProgram, because what would be the mainProgram of coreutils hence, .... "when appropriate"
I agree that coreutils shouldn't have mainProgram but just out curiosity coreutils actually contians bin/coreutils
I would like to throw in, that we should document that mainProgram should not be set to pname which was the previous behaviour.
Note that is also used in which has different constraints. The argument for this I've seen and to which I nowadays agree is that you could guess the mainProgram based on pname (and indeed does this) but, in pure Nix, there is no way to know whether that executable will actually exist in the built store path. may simply not have a binary under but would happily return that string. Using the result of that would lead to a confusing error at runtime. can get away with guessing because it has access to the built path and can then display a sane error message. (Though even there I could see the argument that it probably shouldn't even try to do so.) Additionally, implicit creation of implies that every package A. has executables and B. has an executable that would be considered its "main" program. I assert that this is not possible to determine automatically and must be done via manual human input. My conclusion is that should explicitly be declared when a main program exists for these reasons, even if it's the same as .
I agree with on this, I agree that this is what it should mean. A PR to the contributor docs would be great :)

Discussion:
* `meta.license` must be set and match the upstream license. * If there is no upstream license, `meta.license` should default to `lib.licenses.unfree`. * If in doubt, try to contact the upstream developers for clarification. <del> * `meta.mainProgram` must be set when appropriate. </del> <ins> * `meta.mainProgram` must be set to the name of the executable which facilitates the primary function or purpose of the package, if there is such an executable in `$bin/bin/` (or `$out/bin/`, if there is no `"bin"` output). * Packages that only have a single executable in the applicable directory above should set `meta.mainProgram`. For example, the package `ripgrep` only has a single executable `rg` under `$out/bin/`, so `ripgrep.meta.mainProgram` is set to `"rg"`. * Packages like `polkit_gnome` that have no executables in the applicable directory should not set `meta.mainProgram`. * Packages like `e2fsprogs` that have multiple executables, none of which can be considered the main program, should not set `meta.mainProgram`. * Packages which are not primarily used for a single executable do not need to set `meta.mainProgram`. * Always prefer using a hardcoded string (don't use `pname`, for example). * When in doubt, ask for reviewer input. </ins> * `meta.maintainers` must be set for new packages. See the Nixpkgs manual for more details on [standard meta-attributes](https://nixos.org/nixpkgs/manual/#sec-standard-meta-attributes).