Merge remote-tracking branch 'upstream/master' into aj-rust-custom-target

12 files changed, 707 insertions, 688 deletions

diff --git a/doc/languages-frameworks/beam.section.md b/doc/languages-frameworks/beam.section.md
new file mode 100644
index 000000000000..ad3b94880b5c
--- /dev/null
+++ b/doc/languages-frameworks/beam.section.md
@@ -0,0 +1,84 @@
+# BEAM Languages (Erlang, Elixir & LFE) {#sec-beam}
+
+## Introduction {#beam-introduction}
+
+In this document and related Nix expressions, we use the term, *BEAM*, to describe the environment. BEAM is the name of the Erlang Virtual Machine and, as far as we're concerned, from a packaging perspective, all languages that run on the BEAM are interchangeable. That which varies, like the build system, is transparent to users of any given BEAM package, so we make no distinction.
+
+## Structure {#beam-structure}
+
+All BEAM-related expressions are available via the top-level `beam` attribute, which includes:
+
+  - `interpreters`: a set of compilers running on the BEAM, including multiple Erlang/OTP versions (`beam.interpreters.erlangR19`, etc), Elixir (`beam.interpreters.elixir`) and LFE (`beam.interpreters.lfe`).
+
+  - `packages`: a set of package builders (Mix and rebar3), each compiled with a specific Erlang/OTP version, e.g.  `beam.packages.erlangR19`.
+
+The default Erlang compiler, defined by `beam.interpreters.erlang`, is aliased as `erlang`. The default BEAM package set is defined by `beam.packages.erlang` and aliased at the top level as `beamPackages`.
+
+To create a package builder built with a custom Erlang version, use the lambda, `beam.packagesWith`, which accepts an Erlang/OTP derivation and produces a package builder similar to `beam.packages.erlang`.
+
+Many Erlang/OTP distributions available in `beam.interpreters` have versions with ODBC and/or Java enabled or without wx (no observer support). For example, there's `beam.interpreters.erlangR22_odbc_javac`, which corresponds to `beam.interpreters.erlangR22` and `beam.interpreters.erlangR22_nox`, which corresponds to `beam.interpreters.erlangR22`.
+
+## Build Tools {#build-tools}
+
+### Rebar3 {#build-tools-rebar3}
+
+We provide a version of Rebar3, under `rebar3`. We also provide a helper to fetch Rebar3 dependencies from a lockfile under `fetchRebar3Deps`.
+
+### Mix & Erlang.mk {#build-tools-other}
+
+Both Mix and Erlang.mk work exactly as expected. There is a bootstrap process that needs to be run for both, however, which is supported by the `buildMix` and `buildErlangMk` derivations, respectively.
+
+## How to Install BEAM Packages {#how-to-install-beam-packages}
+
+BEAM builders are not registered at the top level, simply because they are not relevant to the vast majority of Nix users. To install any of those builders into your profile, refer to them by their attribute path `beamPackages.rebar3`:
+
+```ShellSession
+$ nix-env -f "<nixpkgs>" -iA beamPackages.rebar3
+```
+
+## Packaging BEAM Applications {#packaging-beam-applications}
+
+### Erlang Applications {#packaging-erlang-applications}
+
+#### Rebar3 Packages {#rebar3-packages}
+
+The Nix function, `buildRebar3`, defined in `beam.packages.erlang.buildRebar3` and aliased at the top level, can be used to build a derivation that understands how to build a Rebar3 project.
+
+If a package needs to compile native code via Rebar3's port compilation mechanism, add `compilePort = true;` to the derivation.
+
+#### Erlang.mk Packages {#erlang-mk-packages}
+
+Erlang.mk functions similarly to Rebar3, except we use `buildErlangMk` instead of `buildRebar3`.
+
+#### Mix Packages {#mix-packages}
+
+Mix functions similarly to Rebar3, except we use `buildMix` instead of `buildRebar3`.
+
+Alternatively, we can use `buildHex` as a shortcut:
+
+## How to Develop {#how-to-develop}
+
+### Creating a Shell {#creating-a-shell}
+
+Usually, we need to create a `shell.nix` file and do our development inside of the environment specified therein. Just install your version of erlang and other interpreter, and then user your normal build tools.  As an example with elixir:
+
+```nix
+{ pkgs ? import "<nixpkgs"> {} }:
+
+with pkgs;
+
+let
+
+  elixir = beam.packages.erlangR22.elixir_1_9;
+
+in
+mkShell {
+  buildInputs = [ elixir ];
+
+  ERL_INCLUDE_PATH="${erlang}/lib/erlang/usr/include";
+}
+```
+
+#### Building in a Shell (for Mix Projects) {#building-in-a-shell}
+
+Using a `shell.nix` as described (see <xref linkend="creating-a-shell"/>) should just work.
diff --git a/doc/languages-frameworks/beam.xml b/doc/languages-frameworks/beam.xml
deleted file mode 100644
index addab24f7f6d..000000000000
--- a/doc/languages-frameworks/beam.xml
+++ /dev/null
@@ -1,159 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="sec-beam">
- <title>BEAM Languages (Erlang, Elixir &amp; LFE)</title>
-
- <section xml:id="beam-introduction">
-  <title>Introduction</title>
-
-  <para>
-   In this document and related Nix expressions, we use the term, <emphasis>BEAM</emphasis>, to describe the environment. BEAM is the name of the Erlang Virtual Machine and, as far as we're concerned, from a packaging perspective, all languages that run on the BEAM are interchangeable. That which varies, like the build system, is transparent to users of any given BEAM package, so we make no distinction.
-  </para>
- </section>
-
- <section xml:id="beam-structure">
-  <title>Structure</title>
-
-  <para>
-   All BEAM-related expressions are available via the top-level <literal>beam</literal> attribute, which includes:
-  </para>
-
-  <itemizedlist>
-   <listitem>
-    <para>
-     <literal>interpreters</literal>: a set of compilers running on the BEAM, including multiple Erlang/OTP versions (<literal>beam.interpreters.erlangR19</literal>, etc), Elixir (<literal>beam.interpreters.elixir</literal>) and LFE (<literal>beam.interpreters.lfe</literal>).
-    </para>
-   </listitem>
-   <listitem>
-    <para>
-     <literal>packages</literal>: a set of package builders (Mix and rebar3), each compiled with a specific Erlang/OTP version, e.g. <literal>beam.packages.erlangR19</literal>.
-    </para>
-   </listitem>
-  </itemizedlist>
-
-  <para>
-   The default Erlang compiler, defined by <literal>beam.interpreters.erlang</literal>, is aliased as <literal>erlang</literal>. The default BEAM package set is defined by <literal>beam.packages.erlang</literal> and aliased at the top level as <literal>beamPackages</literal>.
-  </para>
-
-  <para>
-   To create a package builder built with a custom Erlang version, use the lambda, <literal>beam.packagesWith</literal>, which accepts an Erlang/OTP derivation and produces a package builder similar to <literal>beam.packages.erlang</literal>.
-  </para>
-
-  <para>
-   Many Erlang/OTP distributions available in <literal>beam.interpreters</literal> have versions with ODBC and/or Java enabled or without wx (no observer support). For example, there's <literal>beam.interpreters.erlangR22_odbc_javac</literal>, which corresponds to <literal>beam.interpreters.erlangR22</literal> and <literal>beam.interpreters.erlangR22_nox</literal>, which corresponds to <literal>beam.interpreters.erlangR22</literal>.
-  </para>
- </section>
-
- <section xml:id="build-tools">
-  <title>Build Tools</title>
-
-  <section xml:id="build-tools-rebar3">
-   <title>Rebar3</title>
-
-   <para>
-    We provide a version of Rebar3, under <literal>rebar3</literal>. We also provide a helper to fetch Rebar3 dependencies from a lockfile under <literal>fetchRebar3Deps</literal>.
-   </para>
-  </section>
-
-  <section xml:id="build-tools-other">
-   <title>Mix &amp; Erlang.mk</title>
-
-   <para>
-    Both Mix and Erlang.mk work exactly as expected. There is a bootstrap process that needs to be run for both, however, which is supported by the <literal>buildMix</literal> and <literal>buildErlangMk</literal> derivations, respectively.
-   </para>
-  </section>
- </section>
-
- <section xml:id="how-to-install-beam-packages">
-  <title>How to Install BEAM Packages</title>
-
-  <para>
-   BEAM builders are not registered at the top level, simply because they are not relevant to the vast majority of Nix users.
-   To install any of those builders into your profile, refer to them by their attribute path <literal>beamPackages.rebar3</literal>:
-  </para>
-
-<screen>
-<prompt>$ </prompt>nix-env -f &quot;&lt;nixpkgs&gt;&quot; -iA beamPackages.rebar3
-</screen>
-</section>
-
- <section xml:id="packaging-beam-applications">
-  <title>Packaging BEAM Applications</title>
-
-  <section  xml:id="packaging-erlang-applications">
-   <title>Erlang Applications</title>
-
-   <section xml:id="rebar3-packages">
-    <title>Rebar3 Packages</title>
-
-    <para>
-     The Nix function, <literal>buildRebar3</literal>, defined in <literal>beam.packages.erlang.buildRebar3</literal> and aliased at the top level, can be used to build a derivation that understands how to build a Rebar3 project.
-    </para>
-
-    <para>
-     If a package needs to compile native code via Rebar3's port compilation mechanism, add <literal>compilePort = true;</literal> to the derivation.
-    </para>
-   </section>
-
-   <section xml:id="erlang-mk-packages">
-    <title>Erlang.mk Packages</title>
-
-    <para>
-     Erlang.mk functions similarly to Rebar3, except we use <literal>buildErlangMk</literal> instead of <literal>buildRebar3</literal>.
-    </para>
-
-   </section>
-
-   <section xml:id="mix-packages">
-    <title>Mix Packages</title>
-
-    <para>
-     Mix functions similarly to Rebar3, except we use <literal>buildMix</literal> instead of <literal>buildRebar3</literal>.
-    </para>
-
-    <para>
-     Alternatively, we can use <literal>buildHex</literal> as a shortcut:
-    </para>
-   </section>
-  </section>
- </section>
-
- <section xml:id="how-to-develop">
-  <title>How to Develop</title>
-
-  <section xml:id="creating-a-shell">
-   <title>Creating a Shell</title>
-
-  <para>
-    Usually, we need to create a <literal>shell.nix</literal> file and do our development inside of the environment specified therein. Just install your version of erlang and other interpreter, and then user your normal build tools.
-    As an example with elixir:
-  </para>
-
-<programlisting>
-{ pkgs ? import &quot;&lt;nixpkgs&quot;&gt; {} }:
-
-with pkgs;
-
-let
-
-  elixir = beam.packages.erlangR22.elixir_1_9;
-
-in
-mkShell {
-  buildInputs = [ elixir ];
-
-  ERL_INCLUDE_PATH="${erlang}/lib/erlang/usr/include";
-}
-</programlisting>
-
-   <section xml:id="building-in-a-shell">
-    <title>Building in a Shell (for Mix Projects)</title>
-
-    <para>
-     Using a <literal>shell.nix</literal> as described (see <xref
-      linkend="creating-a-shell"/>) should just work.
-    </para>
-   </section>
-  </section>
- </section>
-</section>
diff --git a/doc/languages-frameworks/dotnet.section.md b/doc/languages-frameworks/dotnet.section.md
index c56f4728bed8..88fd74db8256 100644
--- a/doc/languages-frameworks/dotnet.section.md
+++ b/doc/languages-frameworks/dotnet.section.md
@@ -64,9 +64,9 @@ $ dotnet --info
 
 The `dotnetCorePackages.sdk_X_Y` is preferred over the old dotnet-sdk as both major and minor version are very important for a dotnet environment. If a given minor version isn't present (or was changed), then this will likely break your ability to build a project.
 
-## dotnetCorePackages.sdk vs dotnetCorePackages.netcore vs dotnetCorePackages.aspnetcore
+## dotnetCorePackages.sdk vs vs dotnetCorePackages.net vs dotnetCorePackages.netcore vs dotnetCorePackages.aspnetcore
 
-The `dotnetCorePackages.sdk` contains both a runtime and the full sdk of a given version. The `netcore` and `aspnetcore` packages are meant to serve as minimal runtimes to deploy alongside already built applications.
+The `dotnetCorePackages.sdk` contains both a runtime and the full sdk of a given version. The `net`, `netcore` and `aspnetcore` packages are meant to serve as minimal runtimes to deploy alongside already built applications. For runtime versions >= .NET 5 `net` is used while `netcore` is used for older .NET Core runtime version.
 
 ## Packaging a Dotnet Application
 
diff --git a/doc/languages-frameworks/go.section.md b/doc/languages-frameworks/go.section.md
new file mode 100644
index 000000000000..b4228d9d313d
--- /dev/null
+++ b/doc/languages-frameworks/go.section.md
@@ -0,0 +1,140 @@
+# Go {#sec-language-go}
+
+## Go modules {#ssec-language-go}
+
+The function `buildGoModule` builds Go programs managed with Go modules. It builds a [Go Modules](https://github.com/golang/go/wiki/Modules) through a two phase build:
+
+- An intermediate fetcher derivation. This derivation will be used to fetch all of the dependencies of the Go module.
+- A final derivation will use the output of the intermediate derivation to build the binaries and produce the final output.
+
+### Example for `buildGoModule` {#ex-buildGoModule}
+
+In the following is an example expression using `buildGoModule`, the following arguments are of special significance to the function:
+
+- `vendorSha256`: is the hash of the output of the intermediate fetcher derivation. `vendorSha256` can also take `null` as an input. When `null` is used as a value, rather than fetching the dependencies and vendoring them, we use the vendoring included within the source repo. If you'd like to not have to update this field on dependency changes, run `go mod vendor` in your source repo and set `vendorSha256 = null;`
+- `runVend`: runs the vend command to generate the vendor directory. This is useful if your code depends on c code and go mod tidy does not include the needed sources to build.
+
+```nix
+pet = buildGoModule rec {
+  pname = "pet";
+  version = "0.3.4";
+
+  src = fetchFromGitHub {
+    owner = "knqyf263";
+    repo = "pet";
+    rev = "v${version}";
+    sha256 = "0m2fzpqxk7hrbxsgqplkg7h2p7gv6s1miymv3gvw0cz039skag0s";
+  };
+
+  vendorSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j";
+
+  runVend = true;
+
+  meta = with lib; {
+    description = "Simple command-line snippet manager, written in Go";
+    homepage = "https://github.com/knqyf263/pet";
+    license = licenses.mit;
+    maintainers = with maintainers; [ kalbasit ];
+    platforms = platforms.linux ++ platforms.darwin;
+  };
+}
+```
+
+## `buildGoPackage` (legacy) {#ssec-go-legacy}
+
+The function `buildGoPackage` builds legacy Go programs, not supporting Go modules.
+
+### Example for `buildGoPackage`
+
+In the following is an example expression using buildGoPackage, the following arguments are of special significance to the function:
+
+- `goPackagePath` specifies the package's canonical Go import path.
+- `goDeps` is where the Go dependencies of a Go program are listed as a list of package source identified by Go import path. It could be imported as a separate `deps.nix` file for readability. The dependency data structure is described below.
+
+```nix
+deis = buildGoPackage rec {
+  pname = "deis";
+  version = "1.13.0";
+
+  goPackagePath = "github.com/deis/deis";
+
+  src = fetchFromGitHub {
+    owner = "deis";
+    repo = "deis";
+    rev = "v${version}";
+    sha256 = "1qv9lxqx7m18029lj8cw3k7jngvxs4iciwrypdy0gd2nnghc68sw";
+  };
+
+  goDeps = ./deps.nix;
+}
+```
+
+The `goDeps` attribute can be imported from a separate `nix` file that defines which Go libraries are needed and should be included in `GOPATH` for `buildPhase`:
+
+```nix
+# deps.nix
+[ # goDeps is a list of Go dependencies.
+  {
+    # goPackagePath specifies Go package import path.
+    goPackagePath = "gopkg.in/yaml.v2";
+    fetch = {
+      # `fetch type` that needs to be used to get package source.
+      # If `git` is used there should be `url`, `rev` and `sha256` defined next to it.
+      type = "git";
+      url = "https://gopkg.in/yaml.v2";
+      rev = "a83829b6f1293c91addabc89d0571c246397bbf4";
+      sha256 = "1m4dsmk90sbi17571h6pld44zxz7jc4lrnl4f27dpd1l8g5xvjhh";
+    };
+  }
+  {
+    goPackagePath = "github.com/docopt/docopt-go";
+    fetch = {
+      type = "git";
+      url = "https://github.com/docopt/docopt-go";
+      rev = "784ddc588536785e7299f7272f39101f7faccc3f";
+      sha256 = "0wwz48jl9fvl1iknvn9dqr4gfy1qs03gxaikrxxp9gry6773v3sj";
+    };
+  }
+]
+```
+
+To extract dependency information from a Go package in automated way use [go2nix](https://github.com/kamilchm/go2nix). It can produce complete derivation and `goDeps` file for Go programs.
+
+You may use Go packages installed into the active Nix profiles by adding the following to your ~/.bashrc:
+
+```bash
+for p in $NIX_PROFILES; do
+    GOPATH="$p/share/go:$GOPATH"
+done
+```
+
+## Attributes used by the builders {#ssec-go-common-attributes}
+
+Both `buildGoModule` and `buildGoPackage` can be tweaked to behave slightly differently, if the following attributes are used:
+
+### `buildFlagsArray` and `buildFlags`: {#ex-goBuildFlags-noarray}
+
+These attributes set build flags supported by `go build`. We recommend using `buildFlagsArray`. The most common use case of these attributes is to make the resulting executable aware of its own version. For example:
+
+```nix
+  buildFlagsArray = [
+    # Note: single quotes are not needed.
+    "-ldflags=-X main.Version=${version} -X main.Commit=${version}"
+  ];
+```
+
+```nix
+  buildFlagsArray = ''
+    -ldflags=
+    -X main.Version=${version}
+    -X main.Commit=${version}
+  '';
+```
+
+### `deleteVendor` {#var-go-deleteVendor}
+
+Removes the pre-existing vendor directory. This should only be used if the dependencies included in the vendor folder are broken or incomplete.
+
+### `subPackages` {#var-go-subPackages}
+
+Limits the builder from building child packages that have not been listed. If <varname>subPackages</varname> is not specified, all child packages will be built.
diff --git a/doc/languages-frameworks/go.xml b/doc/languages-frameworks/go.xml
deleted file mode 100644
index ebdcf616054c..000000000000
--- a/doc/languages-frameworks/go.xml
+++ /dev/null
@@ -1,248 +0,0 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="sec-language-go">
- <title>Go</title>
-
- <section xml:id="ssec-go-modules">
-  <title>Go modules</title>
-
-  <para>
-   The function <varname> buildGoModule </varname> builds Go programs managed with Go modules. It builds a <link xlink:href="https://github.com/golang/go/wiki/Modules">Go modules</link> through a two phase build:
-   <itemizedlist>
-    <listitem>
-     <para>
-      An intermediate fetcher derivation. This derivation will be used to fetch all of the dependencies of the Go module.
-     </para>
-    </listitem>
-    <listitem>
-     <para>
-      A final derivation will use the output of the intermediate derivation to build the binaries and produce the final output.
-     </para>
-    </listitem>
-   </itemizedlist>
-  </para>
-
-  <example xml:id='ex-buildGoModule'>
-   <title>buildGoModule</title>
-<programlisting>
-pet = buildGoModule rec {
-  pname = "pet";
-  version = "0.3.4";
-
-  src = fetchFromGitHub {
-    owner = "knqyf263";
-    repo = "pet";
-    rev = "v${version}";
-    sha256 = "0m2fzpqxk7hrbxsgqplkg7h2p7gv6s1miymv3gvw0cz039skag0s";
-  };
-
-  vendorSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j"; <co xml:id='ex-buildGoModule-1' />
-
-  runVend = true; <co xml:id='ex-buildGoModule-2' />
-
-  meta = with lib; {
-    description = "Simple command-line snippet manager, written in Go";
-    homepage = "https://github.com/knqyf263/pet";
-    license = licenses.mit;
-    maintainers = with maintainers; [ kalbasit ];
-    platforms = platforms.linux ++ platforms.darwin;
-  };
-}
-</programlisting>
-  </example>
-
-  <para>
-   <xref linkend='ex-buildGoModule'/> is an example expression using buildGoModule, the following arguments are of special significance to the function:
-   <calloutlist>
-    <callout arearefs='ex-buildGoModule-1'>
-     <para>
-      <varname>vendorSha256</varname> is the hash of the output of the intermediate fetcher derivation.
-     </para>
-    </callout>
-    <callout arearefs='ex-buildGoModule-2'>
-     <para>
-      <varname>runVend</varname> runs the vend command to generate the vendor directory. This is useful if your code depends on c code and go mod tidy does not include the needed sources to build.
-     </para>
-    </callout>
-   </calloutlist>
-  </para>
-
-  <para>
-   <varname>vendorSha256</varname> can also take <varname>null</varname> as an input. When `null` is used as a value, rather than fetching the dependencies and vendoring them, we use the vendoring included within the source repo. If you'd like to not have to update this field on dependency changes, run `go mod vendor` in your source repo and set 'vendorSha256 = null;'
-  </para>
- </section>
-
- <section xml:id="ssec-go-legacy">
-  <title>Go legacy</title>
-
-  <para>
-   The function <varname> buildGoPackage </varname> builds legacy Go programs, not supporting Go modules.
-  </para>
-
-  <example xml:id='ex-buildGoPackage'>
-   <title>buildGoPackage</title>
-<programlisting>
-deis = buildGoPackage rec {
-  pname = "deis";
-  version = "1.13.0";
-
-  goPackagePath = "github.com/deis/deis"; <co xml:id='ex-buildGoPackage-1' />
-
-  src = fetchFromGitHub {
-    owner = "deis";
-    repo = "deis";
-    rev = "v${version}";
-    sha256 = "1qv9lxqx7m18029lj8cw3k7jngvxs4iciwrypdy0gd2nnghc68sw";
-  };
-
-  goDeps = ./deps.nix; <co xml:id='ex-buildGoPackage-2' />
-}
-</programlisting>
-  </example>
-
-  <para>
-   <xref linkend='ex-buildGoPackage'/> is an example expression using buildGoPackage, the following arguments are of special significance to the function:
-   <calloutlist>
-    <callout arearefs='ex-buildGoPackage-1'>
-     <para>
-      <varname>goPackagePath</varname> specifies the package's canonical Go import path.
-     </para>
-    </callout>
-    <callout arearefs='ex-buildGoPackage-2'>
-     <para>
-      <varname>goDeps</varname> is where the Go dependencies of a Go program are listed as a list of package source identified by Go import path. It could be imported as a separate <varname>deps.nix</varname> file for readability. The dependency data structure is described below.
-     </para>
-    </callout>
-   </calloutlist>
-  </para>
-
-  <para>
-   The <varname>goDeps</varname> attribute can be imported from a separate <varname>nix</varname> file that defines which Go libraries are needed and should be included in <varname>GOPATH</varname> for <varname>buildPhase</varname>.
-  </para>
-
-  <example xml:id='ex-goDeps'>
-   <title>deps.nix</title>
-<programlisting>
-[ <co xml:id='ex-goDeps-1' />
-  {
-    goPackagePath = "gopkg.in/yaml.v2"; <co xml:id='ex-goDeps-2' />
-    fetch = {
-      type = "git"; <co xml:id='ex-goDeps-3' />
-      url = "https://gopkg.in/yaml.v2";
-      rev = "a83829b6f1293c91addabc89d0571c246397bbf4";
-      sha256 = "1m4dsmk90sbi17571h6pld44zxz7jc4lrnl4f27dpd1l8g5xvjhh";
-    };
-  }
-  {
-    goPackagePath = "github.com/docopt/docopt-go";
-    fetch = {
-      type = "git";
-      url = "https://github.com/docopt/docopt-go";
-      rev = "784ddc588536785e7299f7272f39101f7faccc3f";
-      sha256 = "0wwz48jl9fvl1iknvn9dqr4gfy1qs03gxaikrxxp9gry6773v3sj";
-    };
-  }
-]
-</programlisting>
-  </example>
-
-  <para>
-   <calloutlist>
-    <callout arearefs='ex-goDeps-1'>
-     <para>
-      <varname>goDeps</varname> is a list of Go dependencies.
-     </para>
-    </callout>
-    <callout arearefs='ex-goDeps-2'>
-     <para>
-      <varname>goPackagePath</varname> specifies Go package import path.
-     </para>
-    </callout>
-    <callout arearefs='ex-goDeps-3'>
-     <para>
-      <varname>fetch type</varname> that needs to be used to get package source. If <varname>git</varname> is used there should be <varname>url</varname>, <varname>rev</varname> and <varname>sha256</varname> defined next to it.
-     </para>
-    </callout>
-   </calloutlist>
-  </para>
-
-  <para>
-   To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/kamilchm/go2nix">go2nix</link>. It can produce complete derivation and <varname>goDeps</varname> file for Go programs.
-  </para>
-
-  <para>
-   You may use Go packages installed into the active Nix profiles by adding the following to your ~/.bashrc:
-<screen>
-for p in $NIX_PROFILES; do
-    GOPATH="$p/share/go:$GOPATH"
-done
-</screen>
-  </para>
- </section>
-
- <section xml:id="ssec-go-common-attributes">
-  <title>Attributes used by the builders</title>
-
-  <para>
-   Both <link xlink:href="#ssec-go-modules"><varname>buildGoModule</varname></link> and <link xlink:href="#ssec-go-modules"><varname>buildGoPackage</varname></link> can be tweaked to behave slightly differently, if the following attributes are used:
-  </para>
-
-  <variablelist>
-   <varlistentry xml:id="var-go-buildFlagsArray">
-    <term>
-     <varname>buildFlagsArray</varname> and <varname>buildFlags</varname>
-    </term>
-    <listitem>
-     <para>
-      These attributes set build flags supported by <varname>go build</varname>. We recommend using <varname>buildFlagsArray</varname>. The most common use case of these attributes is to make the resulting executable aware of its own version. For example:
-     </para>
-     <example xml:id='ex-goBuildFlags-nospaces'>
-      <title>buildFlagsArray</title>
-<programlisting>
-  buildFlagsArray = [
-    "-ldflags=-X main.Version=${version} -X main.Commit=${version}" <co xml:id='ex-goBuildFlags-1' />
-  ];
-</programlisting>
-     </example>
-     <calloutlist>
-      <callout arearefs='ex-goBuildFlags-1'>
-       <para>
-        Note: single quotes are not needed.
-       </para>
-      </callout>
-     </calloutlist>
-     <example xml:id='ex-goBuildFlags-noarray'>
-      <title>buildFlagsArray</title>
-<programlisting>
-  buildFlagsArray = ''
-    -ldflags=
-    -X main.Version=${version}
-    -X main.Commit=${version}
-  '';
-</programlisting>
-     </example>
-    </listitem>
-   </varlistentry>
-   <varlistentry xml:id="var-go-deleteVendor">
-    <term>
-     <varname>deleteVendor</varname>
-    </term>
-    <listitem>
-     <para>
-      Removes the pre-existing vendor directory. This should only be used if the dependencies included in the vendor folder are broken or incomplete.
-     </para>
-    </listitem>
-   </varlistentry>
-   <varlistentry xml:id="var-go-subPackages">
-    <term>
-     <varname>subPackages</varname>
-    </term>
-    <listitem>
-     <para>
-      Limits the builder from building child packages that have not been listed. If <varname>subPackages</varname> is not specified, all child packages will be built.
-     </para>
-    </listitem>
-   </varlistentry>
-  </variablelist>
- </section>
-</section>
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index 728a38c264a3..7a4c54fca8d0 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -7,18 +7,19 @@
  </para>
  <xi:include href="agda.section.xml" />
  <xi:include href="android.section.xml" />
- <xi:include href="beam.xml" />
+ <xi:include href="beam.section.xml" />
  <xi:include href="bower.xml" />
  <xi:include href="coq.xml" />
  <xi:include href="crystal.section.xml" />
  <xi:include href="emscripten.section.xml" />
  <xi:include href="gnome.xml" />
- <xi:include href="go.xml" />
+ <xi:include href="go.section.xml" />
  <xi:include href="haskell.section.xml" />
  <xi:include href="idris.section.xml" />
  <xi:include href="ios.section.xml" />
  <xi:include href="java.xml" />
  <xi:include href="lua.section.xml" />
+ <xi:include href="maven.section.xml" />
  <xi:include href="node.section.xml" />
  <xi:include href="ocaml.xml" />
  <xi:include href="perl.xml" />
@@ -26,7 +27,7 @@
  <xi:include href="python.section.xml" />
  <xi:include href="qt.xml" />
  <xi:include href="r.section.xml" />
- <xi:include href="ruby.xml" />
+ <xi:include href="ruby.section.xml" />
  <xi:include href="rust.section.xml" />
  <xi:include href="texlive.xml" />
  <xi:include href="titanium.section.xml" />
diff --git a/doc/languages-frameworks/java.xml b/doc/languages-frameworks/java.xml
index bf0fc4883922..881d492b5bff 100644
--- a/doc/languages-frameworks/java.xml
+++ b/doc/languages-frameworks/java.xml
@@ -32,7 +32,7 @@ nativeBuildInputs = [ jdk ];
  </para>
 
  <para>
-  If your Java package provides a program, you need to generate a wrapper script to run it using the OpenJRE. You can use <literal>makeWrapper</literal> for this:
+  If your Java package provides a program, you need to generate a wrapper script to run it using a JRE. You can use <literal>makeWrapper</literal> for this:
 <programlisting>
 nativeBuildInputs = [ makeWrapper ];
 
@@ -43,7 +43,21 @@ installPhase =
       --add-flags "-cp $out/share/java/foo.jar org.foo.Main"
   '';
 </programlisting>
-  Note the use of <literal>jre</literal>, which is the part of the OpenJDK package that contains the Java Runtime Environment. By using <literal>${jre}/bin/java</literal> instead of <literal>${jdk}/bin/java</literal>, you prevent your package from depending on the JDK at runtime.
+Since the introduction of the Java Platform Module System in Java 9, Java distributions typically no longer ship with a general-purpose JRE: instead, they allow generating a JRE with only the modules required for your application(s). Because we can't predict what modules will be needed on a general-purpose system, the default <package>jre</package> package is the full JDK. When building a minimal system/image, you can override the <literal>modules</literal> parameter on <literal>jre_minimal</literal> to build a JRE with only the modules relevant for you:
+<programlisting>
+let
+  my_jre = pkgs.jre_minimal.override {
+    modules = [
+      # The modules used by 'something' and 'other' combined:
+      "java.base"
+      "java.logging"
+    ];
+  };
+  something = (pkgs.something.override { jre = my_jre; });
+  other = (pkgs.other.override { jre = my_jre; });
+in
+  ...
+</programlisting>
  </para>
 
  <para>
diff --git a/doc/languages-frameworks/maven.section.md b/doc/languages-frameworks/maven.section.md
new file mode 100644
index 000000000000..fe183e7ba3cc
--- /dev/null
+++ b/doc/languages-frameworks/maven.section.md
@@ -0,0 +1,354 @@
+---
+title: Maven
+author: Farid Zakaria
+date: 2020-10-15
+---
+
+# Maven
+
+Maven is a well-known build tool for the Java ecosystem however it has some challenges when integrating into the Nix build system.
+
+The following provides a list of common patterns with how to package a Maven project (or any JVM language that can export to Maven) as a Nix package.
+
+For the purposes of this example let's consider a very basic Maven project with the following `pom.xml` with a single dependency on [emoji-java](https://github.com/vdurmont/emoji-java).
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0