7 files changed, 58 insertions, 11 deletions
diff --git a/doc/builders/fetchers.chapter.md b/doc/builders/fetchers.chapter.md
index b1b00106b6c..e36724f295f 100644
--- a/doc/builders/fetchers.chapter.md
+++ b/doc/builders/fetchers.chapter.md
@@ -6,7 +6,7 @@ When using Nix, you will frequently need to download source code and other files
 
 Because fixed output derivations are _identified_ by their hash, a common mistake is to update a fetcher's URL or a version parameter, without updating the hash. **This will cause the old contents to be used.** So remember to always invalidate the hash argument.
 
-For those who develop and maintain fetcheres, a similar problem arises with changes to the implementation of a fetcher. These may cause a fixed output derivation to fail, but won't normally be caught by tests because the supposed output is already in the store or cache. For the purpose of testing, you can use a trick that is embodied by the [`invalidateFetcherByDrvHash`](#sec-pkgs-invalidateFetcherByDrvHash) function. It uses the derivation `name` to create a unique output path per fetcher implementation, defeating the caching precisely where it would be harmful.
+For those who develop and maintain fetchers, a similar problem arises with changes to the implementation of a fetcher. These may cause a fixed output derivation to fail, but won't normally be caught by tests because the supposed output is already in the store or cache. For the purpose of testing, you can use a trick that is embodied by the [`invalidateFetcherByDrvHash`](#sec-pkgs-invalidateFetcherByDrvHash) function. It uses the derivation `name` to create a unique output path per fetcher implementation, defeating the caching precisely where it would be harmful.
 
 ## `fetchurl` and `fetchzip` {#fetchurl}
 
diff --git a/doc/builders/packages/etc-files.section.md b/doc/builders/packages/etc-files.section.md
new file mode 100644
index 00000000000..2405a54634d
--- /dev/null
+++ b/doc/builders/packages/etc-files.section.md
@@ -0,0 +1,18 @@
+# /etc files {#etc}
+
+Certain calls in glibc require access to runtime files found in /etc such as `/etc/protocols` or `/etc/services` -- [getprotobyname](https://linux.die.net/man/3/getprotobyname) is one such function.
+
+On non-NixOS distributions these files are typically provided by packages (i.e. [netbase](https://packages.debian.org/sid/netbase)) if not already pre-installed in your distribution. This can cause non-reproducibility for code if they rely on these files being present.
+
+If [iana-etc](https://hydra.nixos.org/job/nixos/trunk-combined/nixpkgs.iana-etc.x86_64-linux) is part of your _buildInputs_ then it will set the environment varaibles `NIX_ETC_PROTOCOLS` and `NIX_ETC_SERVICES` to the corresponding files in the package through a _setup-hook_.
+
+
+```bash
+> nix-shell -p iana-etc
+
+[nix-shell:~]$ env | grep NIX_ETC
+NIX_ETC_SERVICES=/nix/store/aj866hr8fad8flnggwdhrldm0g799ccz-iana-etc-20210225/etc/services
+NIX_ETC_PROTOCOLS=/nix/store/aj866hr8fad8flnggwdhrldm0g799ccz-iana-etc-20210225/etc/protocols
+```
+
+Nixpkg's version of [glibc](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/libraries/glibc/default.nix) has been patched to check for the existence of these environment variables. If the environment variable are *not set*, then it will attempt to find the files at the default location within _/etc_.
diff --git a/doc/builders/packages/index.xml b/doc/builders/packages/index.xml
index f5b05b0bbcc..206e1e49f1f 100644
--- a/doc/builders/packages/index.xml
+++ b/doc/builders/packages/index.xml
@@ -17,6 +17,7 @@
  <xi:include href="kakoune.section.xml" />
  <xi:include href="linux.section.xml" />
  <xi:include href="locales.section.xml" />
+ <xi:include href="etc-files.section.xml" />
  <xi:include href="nginx.section.xml" />
  <xi:include href="opengl.section.xml" />
  <xi:include href="shell-helpers.section.xml" />
diff --git a/doc/contributing/coding-conventions.chapter.md b/doc/contributing/coding-conventions.chapter.md
index 85c8626bd99..7a8e7741a33 100644
--- a/doc/contributing/coding-conventions.chapter.md
+++ b/doc/contributing/coding-conventions.chapter.md
@@ -181,6 +181,21 @@
   rev = "${version}";
   ```
 
+- Filling lists condionally _should_ be done with `lib.optional(s)` instead of using `if cond then [ ... ] else null` or `if cond then [ ... ] else [ ]`.
+
+  ```nix
+  buildInputs = lib.optional stdenv.isDarwin iconv;
+  ```
+
+  instead of
+
+  ```nix
+  buildInputs = if stdenv.isDarwin then [ iconv ] else null;
+  ```
+
+  As an exception, an explicit conditional expression with null can be used when fixing a important bug without triggering a mass rebuild.
+  If this is done a follow up pull request _should_ be created to change the code to `lib.optional(s)`.
+
 - Arguments should be listed in the order they are used, with the exception of `lib`, which always goes first.
 
 ## Package naming {#sec-package-naming}
diff --git a/doc/languages-frameworks/java.section.md b/doc/languages-frameworks/java.section.md
index 77919d43f74..371bdf6323f 100644
--- a/doc/languages-frameworks/java.section.md
+++ b/doc/languages-frameworks/java.section.md
@@ -72,6 +72,15 @@ in
   ...
 ```
 
+You can also specify what JDK your JRE should be based on, for example
+selecting a 'headless' build to avoid including a link to GTK+:
+
+```nix
+my_jre = pkgs.jre_minimal.override {
+  jdk = jdk11_headless;
+};
+```
+
 Note all JDKs passthru `home`, so if your application requires
 environment variables like `JAVA_HOME` being set, that can be done in a
 generic fashion with the `--set` argument of `makeWrapper`:
diff --git a/doc/languages-frameworks/r.section.md b/doc/languages-frameworks/r.section.md
index 56e3da64df2..ad0fb10987c 100644
--- a/doc/languages-frameworks/r.section.md
+++ b/doc/languages-frameworks/r.section.md
@@ -96,6 +96,11 @@ re-enter the shell.
 
 ## Updating the package set {#updating-the-package-set}
 
+There is a script and associated environment for regenerating the package
+sets and synchronising the rPackages tree to the current CRAN and matching
+BIOC release. These scripts are found in the `pkgs/development/r-modules`
+directory and executed as follows:
+
 ```bash
 nix-shell generate-shell.nix
 
@@ -112,12 +117,11 @@ Rscript generate-r-packages.R bioc-experiment > bioc-experiment-packages.nix.new
 mv bioc-experiment-packages.nix.new bioc-experiment-packages.nix
 ```
 
-`generate-r-packages.R <repo>` reads  `<repo>-packages.nix`, therefor the renaming.
-
-## Testing if the Nix-expression could be evaluated {#testing-if-the-nix-expression-could-be-evaluated}
-
-```bash
-nix-build test-evaluation.nix --dry-run
-```
+`generate-r-packages.R <repo>` reads  `<repo>-packages.nix`, therefore
+the renaming.
 
-If this exits fine, the expression is ok. If not, you have to edit `default.nix`
+Some packages require overrides to specify external dependencies or other
+patches and special requirements. These overrides are specified in the
+`pkgs/development/r-modules/default.nix` file. As the `*-packages.nix`
+contents are automatically generated it should not be edited and broken
+builds should be addressed using overrides.
diff --git a/doc/stdenv/stdenv.chapter.md b/doc/stdenv/stdenv.chapter.md
index 9befcaa51a9..02042407f6c 100644
--- a/doc/stdenv/stdenv.chapter.md
+++ b/doc/stdenv/stdenv.chapter.md
@@ -373,11 +373,11 @@ Additional file types can be supported by setting the `unpackCmd` variable (see
 
 ##### `srcs` / `src` {#var-stdenv-src}
 
-The list of source files or directories to be unpacked or copied. One of these must be set.
+The list of source files or directories to be unpacked or copied. One of these must be set. Note that if you use `srcs`, you should also set `sourceRoot` or `setSourceRoot`.
 
 ##### `sourceRoot` {#var-stdenv-sourceRoot}
 
-After running `unpackPhase`, the generic builder changes the current directory to the directory created by unpacking the sources. If there are multiple source directories, you should set `sourceRoot` to the name of the intended directory.
+After running `unpackPhase`, the generic builder changes the current directory to the directory created by unpacking the sources. If there are multiple source directories, you should set `sourceRoot` to the name of the intended directory. Set `sourceRoot = ".";` if you use `srcs` and control the unpack phase yourself.
 
 ##### `setSourceRoot` {#var-stdenv-setSourceRoot}