From 14d49ddc40f6631a2b588c4d35e0ce265a4d68e1 Mon Sep 17 00:00:00 2001
From: Kamil Chmielewski <kamil.chm@gmail.com>
Date: Fri, 10 Jun 2016 20:26:13 +0200
Subject: [PATCH] buildGoPackage: updated docs for goPackages after rework in
 https://github.com/NixOS/nixpkgs/pull/16017

---
 doc/languages-frameworks/go.xml | 143 ++++++++++++++++++++------------
 1 file changed, 88 insertions(+), 55 deletions(-)

diff --git a/doc/languages-frameworks/go.xml b/doc/languages-frameworks/go.xml
index d715765f6a14..520c338b9a87 100644
--- a/doc/languages-frameworks/go.xml
+++ b/doc/languages-frameworks/go.xml
@@ -5,27 +5,29 @@
 <title>Go</title>
 
 <para>The function <varname>buildGoPackage</varname> builds
-standard Go packages.
+standard Go programs.
 </para>
 
 <example xml:id='ex-buildGoPackage'><title>buildGoPackage</title>
 <programlisting>
-net = buildGoPackage rec {
-  name = "go.net-${rev}";
-  goPackagePath = "golang.org/x/net"; <co xml:id='ex-buildGoPackage-1' />
-  subPackages = [ "ipv4" "ipv6" ]; <co xml:id='ex-buildGoPackage-2' />
-  rev = "e0403b4e005";
+deis = buildGoPackage rec {
+  name = "deis-${version}";
+  version = "1.13.0";
+  
+  goPackagePath = "github.com/deis/deis"; <co xml:id='ex-buildGoPackage-1' />
+  subPackages = [ "client" ]; <co xml:id='ex-buildGoPackage-2' />
+
   src = fetchFromGitHub {
-    inherit rev;
-    owner = "golang";
-    repo = "net";
-    sha256 = "1g7cjzw4g4301a3yqpbk8n1d4s97sfby2aysl275x04g0zh8jxqp";
+    owner = "deis";
+    repo = "deis";
+    rev = "v${version}";
+    sha256 = "1qv9lxqx7m18029lj8cw3k7jngvxs4iciwrypdy0gd2nnghc68sw";
   };
-  goPackageAliases = [ "code.google.com/p/go.net" ]; <co xml:id='ex-buildGoPackage-3' />
-  propagatedBuildInputs = [ goPackages.text ]; <co xml:id='ex-buildGoPackage-4' />
-  buildFlags = "--tags release"; <co xml:id='ex-buildGoPackage-5' />
-  disabled = isGo13;<co xml:id='ex-buildGoPackage-6' />
-};
+
+  goDeps = ./deps.json; <co xml:id='ex-buildGoPackage-3' />
+
+  buildFlags = "--tags release"; <co xml:id='ex-buildGoPackage-4' />
+}
 </programlisting>
 </example>
 
@@ -47,64 +49,94 @@ the following arguments are of special significance to the function:
       packages will be built.
     </para>
     <para>
-      In this example only <literal>code.google.com/p/go.net/ipv4</literal> and
-      <literal>code.google.com/p/go.net/ipv6</literal> will be built.
+      In this example only <literal>github.com/deis/deis/client</literal> will be built.
     </para>
   </callout>
 
   <callout arearefs='ex-buildGoPackage-3'>
     <para>
-      <varname>goPackageAliases</varname> is a list of alternative import paths
-      that are valid for this library.
-      Packages that depend on this library will automatically rename
-      import paths that match any of the aliases to <literal>goPackagePath</literal>.
-    </para>
-    <para>
-      In this example imports will be renamed from
-      <literal>code.google.com/p/go.net</literal> to
-      <literal>golang.org/x/net</literal> in every package that depend on the
-      <literal>go.net</literal> library.
+      <varname>goDeps</varname> is where the Go dependencies of a Go program are listed
+      in a JSON format described below.
     </para>
   </callout>
 
   <callout arearefs='ex-buildGoPackage-4'>
-    <para>
-      <varname>propagatedBuildInputs</varname> is where the dependencies of a Go library are
-      listed. Only libraries should list <varname>propagatedBuildInputs</varname>. If a standalone
-      program is being built instead, use <varname>buildInputs</varname>. If a library's tests require
-      additional dependencies that are not propagated, they should be listed in <varname>buildInputs</varname>.
-    </para>
-  </callout>
-
-  <callout arearefs='ex-buildGoPackage-5'>
     <para>
       <varname>buildFlags</varname> is a list of flags passed to the go build command.
     </para>
   </callout>
 
-  <callout arearefs='ex-buildGoPackage-6'>
-    <para>
-      If <varname>disabled</varname> is <literal>true</literal>,
-      nix will refuse to build this package.
-    </para>
-    <para>
-      In this example the package will not be built for go 1.3. The <literal>isGo13</literal>
-      is an utility function that returns <literal>true</literal> if go used to build the
-      package has version 1.3.x.
-    </para>
-  </callout>
-
 </calloutlist>
 
 </para>
 
-<para>
-Reusable Go libraries may be found in the <varname>goPackages</varname> set. You can test
-build a Go package as follows:
+<para>The <varname>goDeps</varname> attribute should point to a JSON file that defines which Go libraries
+  are needed and should be included in <varname>GOPATH</varname> for <varname>buildPhase</varname>.
 
-<screen>
-$ nix-build -A goPackages.net
-</screen>
+</para>
+
+<example xml:id='ex-goDeps'><title>deps.json</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"
+        }
+    },
+    {
+    "include": "../../libs.json", <co xml:id='ex-goDeps-4' />
+    "packages": [ <co xml:id='ex-goDeps-5' />
+            "github.com/docopt/docopt-go",
+            "golang.org/x/crypto",
+        ]
+    }
+]
+</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>
+
+  <callout arearefs='ex-goDeps-4'>
+    <para>
+      <varname>include</varname> could be used to reuse <varname>goDeps</varname> between Go programs.
+      There is a common libs set in <varname>&lt;nixpkgs/pkgs/development/go-modules/libs.json&gt;</varname>
+      with pinned versions of many packages that you can reuse.
+    </para>
+  </callout>
+
+  <callout arearefs='ex-goDeps-5'>
+    <para>
+      <varname>packages</varname> enumerates all Go packages that will be imported from included file.
+    </para>
+  </callout>
+
+</calloutlist>
 
 </para>
 
@@ -119,6 +151,7 @@ done
 </screen>
 </para>
 
-  <para>To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/kamilchm/go2nix">go2nix</link>.</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>
 </section>