Improve documentation of build_file and add tests

Adds some user documentation on how to generate bazel targets for the
repositories generated by `nixpkgs_package`.

Also adds two tests to check whether this actually works as
documented.

README.md

@@ -168,9 +168,8 @@ nixpkgs clone in `nix_file` or `nix_file_content`.
       <td>
         <p><code>Label-keyed String dict; optional</code></p>
         <p>A dictionary mapping repositoriy labels to `NIX_PATH` entries.</p>
-        <p>Setting it to <pre>
-repositories = { "myrepo" : "//:myrepo" }
-</pre>
+        <p>Setting it to
+           <pre><code>repositories = { "myrepo" : "//:myrepo" }</code></pre>
            for example would replace all instances
            of <code>&lt;myrepo&gt;</code> in the called nix code by the
            path to the target <code>"//:myrepo"</code>. See the
@@ -182,17 +181,46 @@ repositories = { "myrepo" : "//:myrepo" }
     <tr>
       <td><code>build_file</code></td>
       <td>
-        <p><code>String; optional</code></p>
-        <p>The file to use as the BUILD file for this repository. This
-           attribute is a label relative to the main workspace. The
-           file does not need to be named BUILD, but can be.</p>
+        <p><code>Label; optional</code></p>
+        <p>The file to use as the BUILD file for this repository.
+           Its contents are copied copied into the file
+           <code>BUILD</code> in root of the nix output folder.
+           The Label does not need to be named BUILD, but can be.
+        </p>
+        <p>For common use cases we provide filegroups that expose
+           certain files as targets:
+          <dl>
+            <dt><code>:bin</code></dt>
+            <dd>Everything in the <code>bin/</code> directory.</dd>
+            <dt><code>:lib</code></dt>
+            <dd>All <code>.so</code> and <code>.a</code> files
+              that can be found in subdirectories of
+              <code>lib/</code>.</dd>
+            <dt><code>:include</code></dt>
+            <dd>All <code>.h</code> files
+              that can be found in subdirectories of
+              <code>bin/</code>.</dd>
+          </dl>
+        </p>
+        <p>If you need different files from the nix package,
+          you can reference them like this: <pre><code>package(default_visibility = [ "//visibility:public" ])
+filegroup(
+  name = "our-docs",
+  srcs = glob(["share/doc/ourpackage/**/*"]),
+)</code></pre>
+          See the bazel documentation of
+          <a href="https://docs.bazel.build/versions/master/be/general.html#filegroup">filegroup</a>
+          and
+          <a href="https://docs.bazel.build/versions/master/be/functions.html#glob">glob</a>.
+        </p>
       </td>
     </tr>
     <tr>
       <td><code>build_file_content</code></td>
       <td>
         <p><code>String; optional</code></p>
-        <p>The content for the BUILD file for this repository.</p>
+        <p>Like <code>build_file</code>, but a string of the contents
+          instead of a file name.</p>
       </td>
     </tr>
   </tbody>

WORKSPACE

@@ -55,3 +55,22 @@ nixpkgs_package(
   nix_file_deps = ["//tests:pkgname.nix"],
   repositories = { "nixpkgs": "//:nixpkgs.nix" },
 )
+
+nixpkgs_package(
+  name = "output-filegroup-test",
+  nix_file = "//tests:output.nix",
+  repositories = { "nixpkgs": "//:nixpkgs.nix" },
+)
+
+nixpkgs_package(
+  name = "output-filegroup-manual-test",
+  nix_file = "//tests:output.nix",
+  repositories = { "nixpkgs": "//:nixpkgs.nix" },
+  build_file_content = """
+package(default_visibility = [ "//visibility:public" ])
+filegroup(
+  name = "manual-filegroup",
+  srcs = glob(["hi-i-exist", "hi-i-exist-too", "bin/*"]),
+)
+""",
+)

tests/BUILD

@@ -1,17 +1,49 @@
 package(default_testonly = 1)
 
-[sh_test(
-  name= "run-{0}".format(test),
-  srcs = ["test_bin.sh"],
-  args=["$(location @{0}//:bin)".format(test)],
-  data = ["@{0}//:bin".format(test)],
-  timeout = "short",
-) for test in [
-    "hello",
-    "expr-test",
-    "attribute-test",
-    "expr-attribute-test",
-    "nix-file-test",
-    "nix-file-deps-test",
-    "nixpkgs-git-repository-test",
-]]
+[
+    # All of these tests use the "hello" binary to see
+    # whether different invocations of `nixpkgs_package`
+    # produce a valid bazel repository.
+    sh_test(
+        name= "run-{0}".format(test),
+        srcs = ["test_bin.sh"],
+        args=["$(location @{0}//:bin)".format(test)],
+        data = ["@{0}//:bin".format(test)],
+        timeout = "short",
+    ) for test in [
+        "hello",
+        "expr-test",
+        "attribute-test",
+        "expr-attribute-test",
+        "nix-file-test",
+        "nix-file-deps-test",
+        "nixpkgs-git-repository-test",
+    ]
+] \
++ \
+[
+    # These tests use the nix package generated by ./output.nix
+
+    # Checks whether the `:include` filegroup of `nixpkgs_package`
+    # repositories works as intended
+    # (that the expected number of files are inside the target)
+    sh_test(
+        name = "run-test-include",
+        srcs = ["test_output.sh"],
+        data = ["@output-filegroup-test//:include"],
+        args = ["2", "$(locations @output-filegroup-test//:include)"],
+        timeout = "short",
+    ),
+
+    # Checks whether specifying a manual filegroup in the
+    # `nixpkgs_package` BUILD file works as well.
+    sh_test(
+        name = "run-test-manual-filegroup",
+        srcs = ["test_output.sh"],
+        data = ["@output-filegroup-manual-test//:manual-filegroup"],
+        args = [
+            "3",
+            "$(locations @output-filegroup-manual-test//:manual-filegroup)"],
+        timeout = "short",
+    )
+]

tests/output.nix

@@ -0,0 +1,13 @@
+with import <nixpkgs> {};
+
+runCommand "some-output" {
+  preferLocalBuild = true;
+  allowSubstitutes = false;
+} ''
+  mkdir -p $out/{bin,include/mylib}
+  touch $out/hi-i-exist
+  touch $out/hi-i-exist-too
+  touch $out/bin/im-a-binary
+  touch $out/include/mylib/im-a-header.h
+  touch $out/include/mylib/im-also-a-header.h
+''

tests/test_output.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+# first param is the expected number of files given by `locations`
+expected_length="$1"
+
+# rest of the arguments are files
+shift
+no_of_files=$#
+
+if [ "$no_of_files" -ne "$expected_length" ]; then
+    echo "Should have received $expected_length files, but got $no_of_files:"
+    for f in "$@"; do
+        echo "$f"
+    done
+    exit 1
+fi