Add example of how to depend one pkg_deb .changes file (#484)

* Add .changes file to pkg_deb DefaultInfo

- Add tests for that
- Improve the example about finding output file paths to show how to
  get the implicit outputs like the changes file.

Fixes #477

* revert push to DefaultInfo, leaving just the example
* revert now unneeded tests

examples/where_is_my_output/BUILD

@@ -39,3 +39,18 @@ pkg_deb(
     package = "mwp",
     version = "3.14",
 )
+
+# We can also depend just on the .changes file
+
+filegroup(
+    name = "the_changes_file",
+    srcs = [":deb"],
+    output_group = "changes",
+)
+
+genrule(
+    name = "use_changes_file",
+    srcs = [":the_changes_file"],
+    outs = ["copy_of_changes.txt"],
+    cmd = "cp $(location :the_changes_file) $@",
+)

examples/where_is_my_output/README.md

@@ -23,7 +23,7 @@ to inspect a target and print exactly what we need. Let's try it:
 
 ```shell
 bazel build :deb
-bazel cquery :deb --output=starlark --starlark:file=show_deb_outputs.bzl 2>/dev/null
+bazel cquery :deb --output=starlark --starlark:file=show_all_outputs.bzl 2>/dev/null
 ```
 
 That should produce something like
@@ -35,15 +35,15 @@ changes: bazel-out/k8-fastbuild/bin/mwp_3.changes
 
 ### How it works
 
-show_deb_outputs.bzl is a Starlark script that must contain a function with the
+show_all_outputs.bzl is a Starlark script that must contain a function with the
 name `format`, that takes a single argument. The argument is typically named
 target, and is a configured Bazel target, as you might have access to while
 writing a custom rule. We can inspect its providers and print them in a useful
 way.
 
 For pkg_deb, there are two files, the .deb file and the .changes, and both are
 passed along in the rule's OutputGroupInfo provider. This snippet below (from
-show_deb_outputs.bzl) prints them.
+show_all_outputs.bzl) prints them.
 
 ```python
 def format(target):
@@ -64,3 +64,34 @@ def format(target):
 A full explanation of why this works is beyond the scope of this example. It
 requires some knowledge of how to write custom Bazel rules. See the Bazel
 documentation for more information.
+
+## Using an implicit output as input to another rule.
+
+Sometimes a rule will create an implicit output that the user does not
+explicitly specify as an attribute of the target. The .changes file from
+pkg_deb is an example. If we want another rule to depend on an implicitly
+created file, we can do that with a filegroup that specifies the specific
+output group containing that file.
+
+In the example below, `:deb` is a rule producing an explicit .deb output
+and an implict .changes output. We refer to the .changes file using the
+`filegroup` and specifying the desired output group name. Then, any rule
+can use this `filegroup` as an input.
+
+```python
+
+pkg_deb(name = "deb", ...)
+
+filegroup(
+    name = "the_changes_file",
+    srcs = [":deb"],
+    output_group = "changes",
+)
+
+genrule(
+    name = "use_changes_file",
+    srcs = [":the_changes_file"],
+    outs = ["copy_of_changes.txt"],
+    cmd = "cp $(location :the_changes_file) $@",
+)
+```

examples/where_is_my_output/show_deb_outputs.bzl → examples/where_is_my_output/show_all_outputs.bzl

@@ -16,7 +16,7 @@
 # Extract the paths to the various outputs of pkg_deb
 #
 # Usage:
-#   bazel cquery //:debian --output=starlark --starlark:file=show_deb_outputs.bzl
+#   bazel cquery //:deb --output=starlark --starlark:file=show_all_outputs.bzl
 #
 
 def format(target):