lib.extendMkDerivation: add argument excludeFunctionArgNames and improve argument documentation

[ShamrockLee]

• Add an optional excludeFunctionArgNames argument to lib.customisation.extendMkDerivation to remove deprecated/does-not-mean-to-be-specified build helper arguments from __functionArgs.
  • For projects supporting multiple Nixpkgs channels, lib.functionArgs can be used as a way to check whether an argument is supported by a function. For example, nixpkgs-review uses lib.functionArgs to detect if pkgs.buildEnv supports argument ignoreSingleFileOutputs for Nixpkgs revision under review (see PR nix/review_shell.nix: use ignoreSingleFileOutputs whenever available Mic92/nixpkgs-review#427).
  • Deprecated arguments usually need to stay usable for some period of time for backward compatibility purposes, but we want tooling to know early that the support is already dropped. excludeFunctionArgNames provides such mechanism.
• Improve documentation about the default value of each argument of lib.extendMkDerivation.

Things done

• Built on platform:
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• Tested, as applicable:
  • NixOS tests in nixos/tests.
  • Package tests at passthru.tests.
  • Tests in lib/tests or pkgs/test for functions and "core" functionality.
• Ran nixpkgs-review on this PR. See nixpkgs-review usage.
• Tested basic functionality of all binary files, usually in ./result/bin/.
• Nixpkgs Release Notes
  • Package update: when the change is major or breaking.
• NixOS Release Notes
  • Module addition: when adding a new NixOS module.
  • Module update: when the change is significant.
• Fits CONTRIBUTING.md, pkgs/README.md, maintainers/README.md and other READMEs.

---

Add a 👍 reaction to pull requests you find important.

[ShamrockLee]

nixpkgs-review result

Generated using nixpkgs-review-gha

Command: nixpkgs-review pr 459124
Commit: bff91748acff531d407a4a69394180bacac54f5e (subsequent changes)
Merge: 5ddc37393b39a48d2a2d71fc9785ad9a4dfd472e

Logs: https://github.com/ShamrockLee/nixpkgs-review-gha/actions/runs/19135188631

---

x86_64-linux

⏩ 2 packages blacklisted:

• nixos-install-tools
• tests.nixos-functions.nixos-test

✅ 3 packages built:

• extra-container
• nixos-container
• nixpkgs-manual

---

aarch64-linux

⏩ 2 packages blacklisted:

• nixos-install-tools
• tests.nixos-functions.nixos-test

✅ 3 packages built:

• extra-container
• nixos-container
• nixpkgs-manual

---

x86_64-darwin (sandbox = relaxed)

✅ 1 package built:

• nixpkgs-manual

---

aarch64-darwin (sandbox = relaxed)

✅ 1 package built:

• nixpkgs-manual

[MattSturgeon]

I'm curious when this will be useful.

In most cases, we should be able to remove the deprecated arg from the destructured args and instead use { ... }@args: together with args ? deprecated or args.deprecated or "default".

[ShamrockLee]

In most cases, we should be able to remove the deprecated arg from the destructured args and instead use { ... }@args: together with args ? deprecated or args.deprecated or \"default\".

Trivial build helpers, fetchers, and special build helpers typically avoid ellipses. The deprecated argument still needs to be present in the set pattern before hard removal.

Without dedicated functionArgs filtering on the lib.extendMkDerivation side, one would need to decorate extendDrvArgs manually, which changes the indentation and creates unnecessarily large diff.

[MattSturgeon]

I have some feedback on the doc comment, but most of it predates this PR and can be addressed separately if preferred.

The typo should be addressed, but otherwise the actual changes LGTM.

[philiptaron]

I feel really queasy about backporting this change. Could you make a strong argument for changing/extending the function semantics two months before the branch goes quiescent?

[ShamrockLee]

I feel really queasy about backporting this change. Could you make a strong argument for changing/extending the function semantics two months before the branch goes quiescent?

I only thought about build helper backporting when I added the label. I found no "strong arguments" supporting its backport. Let's drop the backporting label.

[philiptaron]

LGTM % Matt's suggestions about the documentation.

[philiptaron]

The semantics here, as I understand them:

1. If inheritFunctionArgs is set to true (the default)
   a. Whatever the arguments are to constructDrv will be used
   b. Except for those listed in excludeDrvArgNames, which will be excluded.
2. The arguments for the derived build helper will override that.
   So if constructDrv had an argument without a default, but the derived build helper had a default, the result would have a default.
3. Finally, no matter where it came from, if an argument is mentioned in the excludeFunctionArgNames list, it will be removed from the function arguments list.

I like those semantics.

[MattSturgeon]

I feel really queasy about backporting this change. Could you make a strong argument for changing/extending the function semantics two months before the branch goes quiescent?

I thought about adding the label myself (before I noticed it was already added).

My argument being that core build helpers should (usually) have a consistent interface across supported releases, so that packages that use them can backport changes relying on said interfaces if needed. This is a semantically trivial change, so I'm comfortable with it being backported.

However, on the flip side, future deprecations that use the new excludeDrvArgNames argument are unlikely to themselves be backported to a nearly-end-of-life release, so I guess we shouldn't need to backport this interface.