Manual's build example doesn't build

[pushcx]

Chapter 13. A Simple Nix Expression (from doc/manual/expressions/simple-expression.xml) introduces building packages with a worked example of building GNU hello. I attempted to use this to learn to build nix packages and was unable to build the package. I don't know where I went wrong, so this bug report is something of a step-by-step. (For context, I'm a longtime professional linux sysadmin and developer who's totally new to nix. I was able to set up a NixOS box from its manual to play around with.)

The chapter is structured around three steps: writing a nix expression (13.1), writing a build script (13.2), and adding the package (13.3).

13.1 doesn't explain where to create default.nix, but from the note "It is customary to place each package in a separate directory" I figured I should create a test directory with this default.nix in it. In 13.2 I also put builder.sh in this directory.

Then instead of the section heading for 13.3 ("Arguments and Variables") matching the third bullet point in the intro, it's kind of a random name. It talks about editing all-packages.nix but the syntax is invalid. As a newbie, I don't have the experience to fill in ... so the example is unusable. Additionally it talks about editing pkgs/top-level/all-packages.nix like that directory already exists, and the only file by that name that find turned up is /nix/store/ilagh0i1vxhp68hd9r73lh0f2mjqbj5x-nixos-18.09pre143771.a8c71037e04/nixos/pkgs/top-level/all-packages.nix. The description of the nix store in 5.3 has a wishy-washy warning against editing files in /nix/store and I don't see any way to regenerate that hash (or maybe I don't need to? The introduction to the hash at the top of chapter 1 says it's only based on dependencies, not contents). Still, it isn't clear at all what I'm supposed to be doing to what file, or why this is required for building hello.

Then section 13.4 starts "You can now try to build Hello." and nix-build -A hello looks like it's assuming I put those files in a directory named hello, though after renaming my directory I got the error error: getting status of '/home/pushcx/default.nix': No such file or directory from outside the directory and from inside I got error: cannot auto-call a function that has an argument without a default value ('stdenv') (with no file name or line-number). The error message is useless because I'm trying to build a package, not auto-call a function, and "auto-call" does not appear in the manual. I don't see anything more to experiment with to try to fix this.

After chatting with infinisil in #nixos, I think the two causes of my confusion are:

1. The manual does not provide a complete, worked example of building a package.
2. The manual conflates building a package and contributing publicly to nixpkgs.

He suggested (via the bot, so is this a frequent problem?), "If a Nix file ./foo.nix starts with something like { bar, baz }:, you can build it with nix-build -E '(import <nixpkgs> {}).callPackage ./foo.nix {}'" This doesn't match the description of callPackage in the manual, which only explains callPackage as something you'd write in all-packages.nix rather than a command-line tool. And it doesn't account for writing a builder.sh.

Additionally, it would probably be worthwhile for someone on the team to watch a newbie try to work through the doc without answering any questions, because this wasn't the first issue I had to puzzle out, just the issue I couldn't puzzle out.

[vaibhavsagar]

It is frustrating that the example in the manual doesn't build, especially when only small changes are required to default.nix:

let
  pkgs = import <nixpkgs> {};
in
pkgs.stdenv.mkDerivation {
  name = "hello-2.1.1";
  builder = ./builder.sh;
  src = pkgs.fetchurl {
    url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
    sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
  };
  perl = pkgs.perl;
}

[vaibhavsagar]

It is frustrating that the example in the manual doesn't build, especially when only small changes are required to default.nix:

let
  pkgs = import <nixpkgs> {};
in
pkgs.stdenv.mkDerivation {
  name = "hello-2.1.1";
  builder = ./builder.sh;
  src = pkgs.fetchurl {
    url = ftp://ftp.nluug.nl/pub/gnu/hello/hello-2.1.1.tar.gz;
    sha256 = "1md7jsfd8pa45z73bz1kszpp01yw6x5ljkjk2hx7wl800any6465";
  };
  perl = pkgs.perl;
}