Explain in more detail how .env and --attr work. Fixes #19

project0/README.md

@@ -123,10 +123,20 @@ You can open up a development environment for this project inside of a "Nix
 shell" by running:
 
 ```bash
-$ nix-shell -A env release0.nix
+$ nix-shell --attr env release0.nix
 ```
 
-... and then use `cabal` to build and run the `project0` executable:
+Normally `nix-shell` wouldn't require the `--attr` flag since `nix-shell` is
+designed to automatically compute the necessary development environment from
+the original derivation.  However, Haskell derivations are different and
+`nix-shell` doesn't work out of the box on them.  However, Haskell derivations
+are records that provide a `env` field which `nix-shell` can use to compute the
+development environment.  We pass the `--attr env` flag to specify that
+`nix-shell` should compute the development environment from the derivation's
+`env` "attribute".
+
+Once we open up the development environment we can use `cabal` to build and run
+the `project0` executable:
 
 ```bash
 $ cabal configure
@@ -171,7 +181,7 @@ The `nixpkgs` manual notes that if you only have Haskell dependencies you
 can also just run the following command once:
 
 ```
-$ nix-shell -A env release0.nix --run 'cabal configure'
+$ nix-shell --attr env release0.nix --run 'cabal configure'
 ```
 
 ... and then run all the other `cabal` commands without the Nix shell.  However,
@@ -397,17 +407,22 @@ all derivations in the set:
 $ nix-build release2.nix
 ```
 
-... or by specifying the attribute of the derivation you want to build:
+... or by specifying the attribute of the derivation you want to build using
+the same `--attr` flag we introduced before for `nix-shell`:
 
 ```bash
-$ nix-build -A project0 release2.nix
+$ nix-build --attr project0 release2.nix
 ```
 
+This `--attr` flag specifies that we only want to build the `project0` field
+of the record, and this flag comes in handy once the record has more than one
+field.
+
 You can also still open up a Nix shell, but you need to change the attribute you
 pass on the command line from `env` to `project0.env`:
 
 ```haskell
-$ nix-shell -A project0.env release2.nix
+$ nix-shell --attr project0.env release2.nix
 ```
 
 You can also avoid having to type this every time you initialize the project by

project1/README.md

@@ -86,7 +86,7 @@ We can also see which version our project selects if we build our project
 using `nix-build`:
 
 ```bash
-$ nix-build -A project1 release0.nix
+$ nix-build --attr project1 release0.nix
 these derivations will be built:
   /nix/store/8g54hjpim7l9s41c9wpcn1h2q8m254m5-project1-1.0.0.drv
 building path(s) ‘/nix/store/pi47yvw46xv346brajyrblwqhjmglhaj-project1-1.0.0’
@@ -192,7 +192,7 @@ At the time of this writing, if you try to build `release1.nix` then you will
 get the following build error:
 
 ```bash
-$ nix-build -A project1 release1.nix
+$ nix-build --attr project1 release1.nix
 these derivations will be built:
   /nix/store/r780xwf197a2gxn3008raq5k6xxid8mh-turtle-1.3.0.drv
   /nix/store/y6g5ya8lis6250fcj0mrw1kybjdara9i-project1-1.0.0.drv
@@ -252,7 +252,7 @@ However, that will still fail to build due to a test suite failure in
 `optparse-applicative-0.13.0.0`:
 
 ```bash
-$ nix-build -A project1 release2.nix
+$ nix-build --attr project1 release2.nix
 these derivations will be built:
   /nix/store/55b9hxwvknznfdqcksdfp8fqxifgw00p-optparse-applicative-0.13.0.0.drv
   /nix/store/9m816lg47c6wcgmjqpfxsyml4hgc739d-turtle-1.3.0.drv
@@ -322,7 +322,7 @@ in
 ... and now the build succeeds:
 
 ```bash
-$ nix-build -A project1 release3.nix 
+$ nix-build --attr project1 release3.nix 
 these derivations will be built:
   /nix/store/f17zxqqk582my4qfig78yvi6nv0vb588-turtle-1.3.0.tar.gz.drv
   /nix/store/vn2m1agg92fbmwj1h9168jywy5wmarah-turtle-1.3.0.drv
@@ -538,7 +538,7 @@ in
 By default, the above project is built using GHC 8.0.2:
 
 ```bash
-$ nix-build -A project1 release5.nix
+$ nix-build --attr project1 release5.nix
 ...
 Using ghc version 8.0.2 found on system at:
 /nix/store/7nl6dii88xd761nnz3xyh11qcnrqvqri-ghc-8.0.2/bin/ghc
@@ -551,7 +551,7 @@ Using ghc-pkg version 8.0.2 found on system at:
 ... but you can now override the compiler on the command line like this:
 
 ```bash
-$ nix-build --argstr compiler ghc7103 -A project1 release5.nix
+$ nix-build --argstr compiler ghc7103 --attr project1 release5.nix
 ...
 building path(s) ‘/nix/store/2c5w9j0dam8m2pn35jvbq2namf8y723f-optparse-applicative-0.13.0.0’
 setupCompilerEnvironmentPhase
@@ -626,7 +626,7 @@ in
 ... and now the build succeeds:
 
 ```bash
-$ nix-build --argstr compiler ghc7103 -A project1 release6.nix
+$ nix-build --argstr compiler ghc7103 --attr project1 release6.nix
 ...
 Using ghc version 7.10.3 found on system at:
 /nix/store/ik664w3cxq2jzr5kby0gwmcm0k96xgmg-ghc-7.10.3/bin/ghc

project2/README.md

@@ -136,13 +136,13 @@ instead of one:
 If we only care about building the project, then we would just run:
 
 ```bash
-$ nix-build -A project2 release.nix
+$ nix-build --attr project2 release.nix
 ```
 
 ... but if we want to build and test our project, we can run:
 
 ```bash
-$ nix-build -A test release.nix
+$ nix-build --attr test release.nix
 these derivations will be built:
   /nix/store/6z0jc3s2ya8j226rgma73w03pdphqwx8-project2-1.0.0.drv
   /nix/store/k82nnkiszzfcnjxq29gcbmgnh5cbfc51-check.drv

project3/README.md

@@ -8,7 +8,7 @@ to fix failing builds).
 Begin by running the following command to build the `morte` package:
 
 ```bash
-$ nix-build '<nixpkgs>' -A haskellPackages.morte
+$ nix-build '<nixpkgs>' --attr haskellPackages.morte
 ...
 /nix/store/z8rf74cylf9dqj63yb8p3j37sn8n49zf-morte-1.6.2
 ```
@@ -295,7 +295,7 @@ suite runs and passes, indicating that our code works with TAR files generated
 by `bsdtar`:
 
 ```bash
-$ nix-build -A project3 release1.nix these derivations will be built:
+$ nix-build --attr project3 release1.nix these derivations will be built:
   /nix/store/i7i38jx93qwxzwg9xakbd8lrfv9kbpi4-project3-1.0.0.drv
 building path(s) ‘/nix/store/2z661k6rnwyiimympn1anmghdybi7izc-project3-1.0.0’
 ...
@@ -394,7 +394,7 @@ and depends on several dynamic libraries that are packaged with `ghc`.  The
 final container is over 250 MB compressed and 1.5 GB uncompressed.
 
 ```bash
-$ nix-build -A docker-container-large release2.nix 
+$ nix-build --attr docker-container-large release2.nix 
 ...
 building path(s) ‘/nix/store/ml441hr1l5gw9piq8ysnjdaazjxapsci-project3-container.tar.gz’
 Adding layer
@@ -409,7 +409,7 @@ If you build the `docker-container-small` attribute you will get a much
 smaller container that is only 11 MB compressed and 27 MB uncompressed:
 
 ```bash
-$ nix-build -A docker-container-small release2.nix 
+$ nix-build --attr docker-container-small release2.nix 
 ...
 building path(s) ‘/nix/store/3mkrcqjnqv5vwid4qcaf3p1i70y87096-project3-container.tar.gz’
 Adding layer
@@ -435,7 +435,7 @@ command which lets you view all transitive dependencies for a given Nix package.
 Before the closure minimization, we get this dependency tree:
 
 ```bash
-$ nix-build -A project3 release2.nix these derivations will be built:
+$ nix-build --attr project3 release2.nix these derivations will be built:
 ...
 /nix/store/1nc7kaw3lp574hhi2bfxdb490q5kp2m8-project3-1.0.0
 
@@ -483,7 +483,7 @@ $ nix-store --query --requisites result
 After closure minimization we get this dependency tree:
 
 ```bash
-$ nix-build -A project3-minimal release2.nix 
+$ nix-build --attr project3-minimal release2.nix 
 ...
 /nix/store/i4fypk5m0rdwribpwacdd1nbzbfqcnpc-project3-minimal
 $ nix-store --query --requisites result