@chris-martin, thanks for your PR! By analyzing the history of the files in this pull request, we identified @edolstra, @Ericson2314 and @pSub to be potential reviewers.

I think this rather belongs into the general part describing phases, as one may want to disable others as well. There is hint that you can override whole phases, so I imagine we might add that it's often useful to disable individual phases by namePhase = "true"; and add a note that preName and postName are also skipped in that case (or if you override whole phase). What do you think?

However we fix it, the statement

One of these must be set.

must be qualified in some way, because right now it's flatly untrue? It's only true if you're using the default unpack phase.

I suppose we could also add a hint to the error message that you get when you don't specify src?

Anything related to a phase is void if you disable that phase or exchange its code – I'd think that doesn't need mentioning explicitly.

I think user-friendly documentation explicitly addresses particular problems that people are likely to run into, in the specific place where they're likely to look for the solution - rather than requiring everyone to read the entire manual and having a complete understanding of how everything comes together.

@copumpkin Can you elaborate? I'll be happy to update the PR to suggest it, but I don't really know what "just use runCommand" means, and the manual doesn't mention runCommand at all.

There is runCommand function that takes three arguments (name, attributes to pass to mkDerivation — most will become environment variables by default, and the command to run). It doesn't do anything by default, so it is used when you want just to concatenate two files into the output file or something like that.

It sounds like the consensus is that runCommand is the way to go here, so withdrawing this and putting in issue #25507 instead.

mkDerivation without unpack phase is still useful because of its fixup phase: https://github.com/nixos-users/wiki/wiki/General-recommendations#package-simple-custom-scripts

I don't know, I've lost all energy on this PR, it seems like an uphill battle.