Documentation Gaps

It's possible this is just me, but I find that there's several concepts implied by the Nix manuals that aren't explained well there. I'd like to contribute documentation for those myself, but there are cases where I don't understand it myself. (Or else I wouldn't want there to be documentation.)

There's no small danger that as I learn the answers to my questions, I'll forget the question in the first place, so I'd like to keep a little list of them here, by way of note taking.

I've noticed that several members of the community seem to know answers to these questions off the top of their heads - I hope they don't take the existence of this page personally: I'd love to bug them less on IRC.

What are setup hooks?

http://nixos.org/nixpkgs/manual/#ssec-setup-hooks enumerates projects that provide them. I think they're scripts that get run in dependent derivations during $stdenv/setup

Answer:
Mostly yes. Some of them are automatically enabled by default. Others you can enable on-demand, by adding them to your buildInputs — e.g. buildInputs = [ makeWrapper ]; (to find the "proper" name for this use, you must go top-level hunting). Then they will either auto-inject some steps into build phases (e.g. pkgconfig or autoconf), or allow you to use some useful scripts during build easily (e.g. makeWrapper — see wrapProgram and makeWrapper docs for details, then grep in nixpkgs for numerous usage examples).
See also <nixpkgs>/pkgs/build-support/setup-hooks for a list of some common setup hooks.

What's the relationship between `nix-env` and `buildEnv`

AFAICT, nix-env somehow assembles a buildEnv expression and the realization of that expression becomes a profile, somehow.

#1 loads the nix file in #2 and uses it to merge everything together, and #2 uses a copy of #3 that was compiled when nix got built.

Have a look also at nixpkgs/pkgs/build-support/buildenv/default.nix

How to add a new cross-compilation target/platform?

Creating a new crossSystem requires many parameters, which are severely undocumented. The official manual only glances over how to use cross compilation for pre-existing platforms, but not how to define new platforms.

Does nix support binary grafting like guix?

Grafting in guix is the concept ofr replacing a dependency in a package without needing to rebuild every package using it as build input. This functionality can be used to significantly lower the time of rebuilding packages with security updates.

In nixpkgs there is replace-dependency which provides this functionality but it is neither used nor explicitly documented as of right now (2017-06-22).

Answer: There is an open pull request and blog article to implement security updates

Tips for using nix-shell for development

mkShell is like stdenv.mkDerivationto dedicated for shell.nix. It adds one more feature where multiple package build inputs can all be merged together. This is useful when developing in a repo that has multiple packages (micro-services).

The structure and placement of nixpkgs

Basically something that documents what all the directories mean and where things are placed and how they are structured and why.

A list of all the trivial builders and build support

And an explanation of what they do and what they are used for.