@matthiasbeyer, thanks for your PR! By analyzing the history of the files in this pull request, we identified @Profpatsch, @lethalman and @abbradar to be potential reviewers.

To me, the complexity of this overshadows the point; this'd be clearer:

foo.overrideAttrs (attrs: {
  NIX_CFLAGS_COMPILE = (attrs.NIX_CFLAGS_COMPILE or "") + " -fgo-fast"
})

or some variation thereof. I also think it's redundant to say that it compiles foo with the listed flags: it is self-evident.

EDIT: syntax error

@joachifm Thanks for the suggestion. It is complicated because I couldn't find documentation on how to do this, so I had to hack this together myself. I will test your suggestions and update this PR shortly! 👍

Don't merge! I guess I missed a blank before the flag

Okay. I'm ready to fix things up!

What about moving that utility function to lib/ instead? While much more convenient than the expanded form, it makes the example less crisp, imo. Consider that readers must 1) process more information in total; 2) spend more effort to parse out the relevant parts of the example. I think it'd be better if the cflags example was more in line with the separateDebug example above it.

(As a side note, I think the cflags example is strictly redundant in the context of a function reference, as it fails to teach the reader anything new about overrideAttrs, but I suppose we can find a better home for it later).

@matthiasbeyer I think you could be a bit more explicit about what this env var does. It passes the flag directly to the compiler, and therefore it typically won't be shown during configuration as you found out. I think this is worth mentioning.

@joachifm you mean I should put this function into nixpkgs/lib?

@matthiasbeyer something like that. A function reference is not a good place for utility functions, imo.

I wonder whether https://github.com/NixOS/nixpkgs/blob/master/nixos/doc/manual/configuration/customizing-packages.xml would be a better place for this?

@joachifm this way? 😄

Will this get merged?