Merge commit 'da1a2b1eeafa66b4419b4f275396d8a731eccb61'

2 files changed, 210 insertions, 131 deletions

diff --git a/nixpkgs/doc/languages-frameworks/go.xml b/nixpkgs/doc/languages-frameworks/go.xml
index ab4c9f0f7c88..6f6e7925a1b5 100644
--- a/nixpkgs/doc/languages-frameworks/go.xml
+++ b/nixpkgs/doc/languages-frameworks/go.xml
@@ -3,12 +3,91 @@
          xml:id="sec-language-go">
  <title>Go</title>
 
- <para>
-  The function <varname>buildGoPackage</varname> builds standard Go programs.
- </para>
+ <section xml:id="ssec-go-modules">
+  <title>Go modules</title>
 
- <example xml:id='ex-buildGoPackage'>
-  <title>buildGoPackage</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 {
+  name = "pet-${version}";
+  version = "0.3.4";
+
+  src = fetchFromGitHub {
+    owner = "knqyf263";
+    repo = "pet";
+    rev = "v${version}";
+    sha256 = "0m2fzpqxk7hrbxsgqplkg7h2p7gv6s1miymv3gvw0cz039skag0s";
+  };
+
+  modSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j"; <co xml:id='ex-buildGoModule-1' />
+
+  subPackages = [ "." ]; <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>modSha256</varname> is the hash of the output of the
+      intermediate fetcher derivation.
+     </para>
+    </callout>
+    <callout arearefs='ex-buildGoModule-2'>
+     <para>
+      <varname>subPackages</varname> 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>
+    </callout>
+   </calloutlist>
+  </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 {
   name = "deis-${version}";
@@ -29,56 +108,56 @@ deis = buildGoPackage rec {
   buildFlags = "--tags release"; <co xml:id='ex-buildGoPackage-4' />
 }
 </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>subPackages</varname> 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>
-    <para>
-     In this example only <literal>github.com/deis/deis/client</literal> will
-     be built.
-    </para>
-   </callout>
-   <callout arearefs='ex-buildGoPackage-3'>
-    <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>
-   <callout arearefs='ex-buildGoPackage-4'>
-    <para>
-     <varname>buildFlags</varname> is a list of flags passed to the go build
-     command.
-    </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>
+  </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>subPackages</varname> 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>
+     <para>
+      In this example only <literal>github.com/deis/deis/client</literal> will
+      be built.
+     </para>
+    </callout>
+    <callout arearefs='ex-buildGoPackage-3'>
+     <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>
+    <callout arearefs='ex-buildGoPackage-4'>
+     <para>
+      <varname>buildFlags</varname> is a list of flags passed to the go build
+      command.
+     </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' />
   {
@@ -101,60 +180,62 @@ deis = buildGoPackage rec {
   }
 ]
 </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>
-  <varname>buildGoPackage</varname> produces
-  <xref linkend='chap-multiple-output' xrefstyle="select: title" /> where
-  <varname>bin</varname> includes program binaries. You can test build a Go
-  binary as follows:
+  </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>
+   <varname>buildGoPackage</varname> produces
+   <xref linkend='chap-multiple-output' xrefstyle="select: title" /> where
+   <varname>bin</varname> includes program binaries. You can test build a Go
+   binary as follows:
 <screen>
     $ nix-build -A deis.bin
   </screen>
-  or build all outputs with:
+   or build all outputs with:
 <screen>
     $ nix-build -A deis.all
   </screen>
-  <varname>bin</varname> output will be installed by default with
-  <varname>nix-env -i</varname> or <varname>systemPackages</varname>.
- </para>
+   <varname>bin</varname> output will be installed by default with
+   <varname>nix-env -i</varname> or <varname>systemPackages</varname>.
+  </para>
 
- <para>
-  You may use Go packages installed into the active Nix profiles by adding the
-  following to your ~/.bashrc:
+  <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>
+  </para>
+ </section>
 </section>
diff --git a/nixpkgs/doc/languages-frameworks/ocaml.xml b/nixpkgs/doc/languages-frameworks/ocaml.xml
index ea0770616802..0deadf2edd03 100644
--- a/nixpkgs/doc/languages-frameworks/ocaml.xml
+++ b/nixpkgs/doc/languages-frameworks/ocaml.xml
@@ -4,39 +4,38 @@
  <title>OCaml</title>
 
  <para>
-   OCaml libraries should be installed in
-   <literal>$(out)/lib/ocaml/${ocaml.version}/site-lib/</literal>. Such
-   directories are automatically added to the <literal>$OCAMLPATH</literal>
-   environment variable when building another package that depends on them
-   or when opening a <literal>nix-shell</literal>.
+  OCaml libraries should be installed in
+  <literal>$(out)/lib/ocaml/${ocaml.version}/site-lib/</literal>. Such
+  directories are automatically added to the <literal>$OCAMLPATH</literal>
+  environment variable when building another package that depends on them or
+  when opening a <literal>nix-shell</literal>.
  </para>
 
  <para>
-   Given that most of the OCaml ecosystem is now built with dune,
-   nixpkgs includes a convenience build support function called
-   <literal>buildDunePackage</literal> that will build an OCaml package
-   using dune, OCaml and findlib and any additional dependencies provided
-   as <literal>buildInputs</literal> or <literal>propagatedBuildInputs</literal>.
+  Given that most of the OCaml ecosystem is now built with dune, nixpkgs
+  includes a convenience build support function called
+  <literal>buildDunePackage</literal> that will build an OCaml package using
+  dune, OCaml and findlib and any additional dependencies provided as
+  <literal>buildInputs</literal> or <literal>propagatedBuildInputs</literal>.
  </para>
 
  <para>
-   Here is a simple package example. It defines an (optional) attribute
-   <literal>minimumOCamlVersion</literal> that will be used to throw a
-   descriptive evaluation error if building with an older OCaml is attempted.
-   It uses the <literal>fetchFromGitHub</literal> fetcher to get its source.
-   It sets the <literal>doCheck</literal> (optional) attribute to
-   <literal>true</literal> which means that tests will be run with
-   <literal>dune runtest -p angstrom</literal> after the build
-   (<literal>dune build -p angstrom</literal>) is complete.
-   It uses <literal>alcotest</literal> as a build input (because it is needed
-   to run the tests) and <literal>bigstringaf</literal> and
-   <literal>result</literal> as propagated build inputs (thus they will also
-   be available to libraries depending on this library).
-   The library will be installed using the <literal>angstrom.install</literal>
-   file that dune generates.
+  Here is a simple package example. It defines an (optional) attribute
+  <literal>minimumOCamlVersion</literal> that will be used to throw a
+  descriptive evaluation error if building with an older OCaml is attempted. It
+  uses the <literal>fetchFromGitHub</literal> fetcher to get its source. It
+  sets the <literal>doCheck</literal> (optional) attribute to
+  <literal>true</literal> which means that tests will be run with <literal>dune
+  runtest -p angstrom</literal> after the build (<literal>dune build -p
+  angstrom</literal>) is complete. It uses <literal>alcotest</literal> as a
+  build input (because it is needed to run the tests) and
+  <literal>bigstringaf</literal> and <literal>result</literal> as propagated
+  build inputs (thus they will also be available to libraries depending on this
+  library). The library will be installed using the
+  <literal>angstrom.install</literal> file that dune generates.
  </para>
 
- <programlisting>
+<programlisting>
 { stdenv, fetchFromGitHub, buildDunePackage, alcotest, result, bigstringaf }:
 
 buildDunePackage rec {
@@ -66,14 +65,14 @@ buildDunePackage rec {
  </programlisting>
 
  <para>
-   Here is a second example, this time using a source archive generated with
-   <literal>dune-release</literal>. It is a good idea to use this archive when
-   it is available as it will usually contain substituted variables such as a
-   <literal>%%VERSION%%</literal> field. This library does not depend
-   on any other OCaml library and no tests are run after building it.
+  Here is a second example, this time using a source archive generated with
+  <literal>dune-release</literal>. It is a good idea to use this archive when
+  it is available as it will usually contain substituted variables such as a
+  <literal>%%VERSION%%</literal> field. This library does not depend on any
+  other OCaml library and no tests are run after building it.
  </para>
 
- <programlisting>
+<programlisting>
 { stdenv, fetchurl, buildDunePackage }:
 
 buildDunePackage rec {
@@ -95,5 +94,4 @@ buildDunePackage rec {
   };
 }
  </programlisting>
-
 </section>