How does buildEnv work? Why is it built in? How can I use it? What does the manifest argument do? Where is the documentation about buildEnv?
Are looking the actual buildenv.nix or the buildEnv function?
Because buildenv.nix is an internal mechanism of the Nix package manager not of much interest for non developer of Nix itself.
If you're interested in the buildEnv function is part of NixPkgs package collection, this function is implemented here:
https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/buildenv/default.nix
Even if the code give some hints, I didn't found any real documentation, but you can find some examples in the manual: https://nixos.org/nixpkgs/manual/#sec-building-environment
If I understand correctly, the manifest is also internal to Nix: It is a Nix file that contains a list of derivation that correspond to a given environment. You can have a look at one on a machine with nix in /nix/var/nix/profiles/per-user/root/channels/manifest.nix for example.
It is not very readable, it looks like this:
[ { meta = { }; name = "nixos-18.09pre143771.a8c71037e04"; out = { outPath = "/nix/store/yqxc408mhbcksnaqndkpdkg8ylcj2xhg-nixos-18.09pre143771.a8c71037e04"; }; outPath = "/nix/store/yqxc408mhbcksnaqndkpdkg8ylcj2xhg-nixos-18.09pre143771.a8c71037e04"; outputs = [ "out" ]; system = "x86_64-linux"; type = "derivation"; } { meta = { }; name = "nixos-1803-18.03.132768.94d80eb7247"; out = { outPath = "/nix/store/ih8bhvgmp47rs3acchkc9ch7f8760rpz-nixos-1803-18.03.132768.94d80eb7247"; }; outPath = "/nix/store/ih8bhvgmp47rs3acchkc9ch7f8760rpz-nixos-1803-18.03.132768.94d80eb7247"; outputs = [ "out" ]; system = "x86_64-linux"; type = "derivation"; } ]