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;
}

[pushcx]

Thanks very much for the improvement, @vaibhavsagar, I can see how this looks more like a complete example. What command are you using to build? Do you have it in a hello directory? Are you running nix-build from within that directory, or a parent? Are you able to run nix-shell or nix-env?

(Asking because I've tried a bunch of variations like nix-build -A hello and nix-build -A . with no luck.)

[pushcx]

Thanks very much for the improvement, @vaibhavsagar, I can see how this looks more like a complete example. What command are you using to build? Do you have it in a hello directory? Are you running nix-build from within that directory, or a parent? Are you able to run nix-shell or nix-env?

(Asking because I've tried a bunch of variations like nix-build -A hello and nix-build -A . with no luck.)

[pushcx]

I sort of got it to start a build, but got a strange failure out of configure. I tried to run nix-shell because that seemed like the right tool but it also lacks newbie docs. There's a section over in the "nixpkgs" manual (though I'm not trying to contribute to a public package so I don't understand why it's there) but its description of "phases" don't at all match what's present in the shell and lead to a whole 'nother set of bugs and underdocumented topics. One again, I don't see any way forward with building a package.

I appreciate the folks who've tried to help, but I've reached my limit of time and frustration on this experiment. I'm unsubscribing from this issue; I don't know what your project standards are around closing or keeping issues open, so I'll leave it to a contributor to handle.

[pushcx]

I sort of got it to start a build, but got a strange failure out of configure. I tried to run nix-shell because that seemed like the right tool but it also lacks newbie docs. There's a section over in the "nixpkgs" manual (though I'm not trying to contribute to a public package so I don't understand why it's there) but its description of "phases" don't at all match what's present in the shell and lead to a whole 'nother set of bugs and underdocumented topics. One again, I don't see any way forward with building a package.

I appreciate the folks who've tried to help, but I've reached my limit of time and frustration on this experiment. I'm unsubscribing from this issue; I don't know what your project standards are around closing or keeping issues open, so I'll leave it to a contributor to handle.

[vaibhavsagar]

Oops, that's meant to go in a default.nix file that you then run by executing nix-build default.nix or just nix-build (which looks for a default.nix if no filename is provided).

[vaibhavsagar]

Oops, that's meant to go in a default.nix file that you then run by executing nix-build default.nix or just nix-build (which looks for a default.nix if no filename is provided).