Nixpkgs Development Guidelines: Meta Attributes, IFD, Overrides, and Source Management

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. * `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). ## Import From Derivation [Import From Derivation](https://nixos.org/manual/nix/unstable/language/import-from-derivation) (IFD) is disallowed in Nixpkgs for performance reasons: [Hydra](https://github.com/NixOS/hydra) evaluates the entire package set, and sequential builds during evaluation would increase evaluation times to become impractical. Import From Derivation can be worked around in some cases by committing generated intermediate files to version control and reading those instead. ## `overrideAttrs` and `overridePythonAttrs` Please do not introduce new uses of `overrideAttrs` or `overridePythonAttrs` in Nixpkgs. These functions are useful for out-of-tree code because they allow easy overriding a package without changing its source in Nixpkgs, but when contributing to Nixpkgs you *can* change the source of other packages. So instead of using the escape hatch that is overriding, you should try to provide proper support for the functionality you need, in ways that are visible and can be understood and accounted for by the maintainers of the patched package. Using `overrideAttrs` and `overridePythonAttrs` in Nixpkgs causes maintainability problems: * It's easy for multiple packages to end up duplicating basically the same override without noticing. * It's not clear when working on an overridden package that it's being overridden elsewhere in Nixpkgs, so `overrideAttrs` and `overridePythonAttrs` are fragile and can break accidentally when the overridden package is changed. * Package maintainers will not be requested for review of overrides, even though they are likely to have important knowledge about the package. * It is easy for overridden packages to be forgotten and remain around long after they are no longer necessary. * Dependency closures end up being bigger than necessary due to unnecessarily including multiple versions of the same package. Instead, keep all instances of the same package next to each other, and try to minimize how many different instances of a package are in Nixpkgs. If you need a patch applied to a dependency, discuss with the maintainer of that dependency whether it would be acceptable to apply to the main version of the package. If you need a different version of a dependency, first try modifying your package to work with the version in Nixpkgs — it's often not very hard! — and if that's not possible, try to factor out a function that can build multiple versions of the package, including the main version. If you need to enable or disable optional functionality of a dependency, add an explicit flag to the package and use `override` instead. ## Sources Always fetch source files using [Nixpkgs fetchers](https://nixos.org/manual/nixpkgs/unstable/#chap-pkgs-fetchers). Use reproducible sources with a high degree of availability. Prefer protocols that support proxies. A list of schemes for `mirror://` URLs can be found in [`pkgs/build-support/fetchurl/mirrors.nix`](build-support/fetchurl/mirrors.nix), and is supported by [`fetchurl`](https://nixos.org/manual/nixpkgs/unstable/#fetchurl). Other fetchers which end up relying on `fetchurl` may also support mirroring. The preferred source hash type is `sha256`.

This document continues discussing Nixpkgs `meta` attributes, specifically `meta.mainProgram` (how and when to set it for primary executables) and `meta.maintainers` (mandatory for new packages). It then prohibits 'Import From Derivation' (IFD) due to performance impacts on Hydra, suggesting committing generated files as a workaround. A significant section advises against introducing new uses of `overrideAttrs` and `overridePythonAttrs` within Nixpkgs itself, citing issues like duplication, fragility, lack of maintainer review, orphaned overrides, and increased dependency closures. Instead, it promotes direct source modification, adapting to existing dependencies, creating multi-version functions, or using explicit flags with `override`. Finally, it provides guidelines for source management, emphasizing the use of Nixpkgs fetchers, reproducible and highly available sources, proxy-supported protocols, `mirror://` URLs, and `sha256` as the preferred hash type.