Create rules for emitting PackageFilesInfo, PackageDirsInfo (#273)

Create rules for emitting PackageFilesInfo, PackageDirsInfo

This change creates rules for emitting `PackageFilesInfo` (`pkg_files`) and
`PackageDirsInfo` (`pkg_mkdirs`) providers.

The implementations and tests of these rules are largely similar to the rules
that currently exist in `experimental/pkg_filegroup.bzl`, with a few notable
differences:

- `pkg_filegroup` is replaced with `pkg_files`.  `pkg_filegroup` will be
  re-implemented as a grouping provider in a future change.

- `pkg_files` now checks for files that map to the same destination.  The check
  was previously deferred to the packaging rules themselves.  This behavior is
  now tested.

- `attributes` (formerly `attrs`) checks for `pkg_files` and friends are now no
  longer strict.  Only the "unix" attribute is verified.  The logic for how to
  check this isn't yet complete, but it's enough to make forward progress.

- `section` for `pkg_files` and `pkg_mkdirs` is removed.  It will be replaced
  with more specific attributes as needed.

- `make_strip_prefix` is removed in favor of the `strip_prefix` pseudo-module.

- Prefix stripping failures will now cause build failures.  The old
  `pkg_filegroup` rule would ignore them.

`pkg_mkdirs` is effectively unchanged, other than differences in the providers,
and `attributes`.  The tests are also effectively unchanged, excepting those
regarding `section` and the ones added above.

Additionally:

- The "common attributes" table pkg/docs/reference is now aligned, and
  describes the "attributes" attribute of `pkg_files` and `pkg_mkdirs`

pkg/WORKSPACE

@@ -46,7 +46,13 @@ load("@bazel_stardoc//:setup.bzl", "stardoc_repositories")
 
 stardoc_repositories()
 
+# TODO(nacl): remove this when the "new" framework is ready.
 local_repository(
     name = "experimental_test_external_repo",
     path = "experimental/tests/external_repo",
 )
+
+local_repository(
+    name = "mappings_test_external_repo",
+    path = "tests/mappings/external_repo",
+)

pkg/docs/reference.md

@@ -18,17 +18,54 @@ These attributes are used in several rules within this module.
 
 **ATTRIBUTES**
 
-| Name  | Description | Type | Mandatory | Default |
-| :------------- | :------------- | :-------------: | :-------------: | :------------- |
-| out | Name of the output file. This file will always be created and used to access the package content. If `package_file_name` is also specified, `out` will be a symlink. | String | required |  |
-| package_file_name |  The name of the file which will contain the package. The name may contain variables in the form `{var}`. The values for substitution are specified through `package_variables`.| String | optional | package type specific |
-| package_variables |  A target that provides `PackageVariablesInfo` to substitute into `package_file_name`.| <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None |
+| Name              | Description                                                                                                                                                                     | Type                                                               | Mandatory       | Default                                   |
+| :-------------    | :-------------                                                                                                                                                                  | :-------------:                                                    | :-------------: | :-------------                            |
+| out               | Name of the output file. This file will always be created and used to access the package content. If `package_file_name` is also specified, `out` will be a symlink.            | String                                                             | required        |                                           |
+| package_file_name | The name of the file which will contain the package. The name may contain variables in the form `{var}`. The values for substitution are specified through `package_variables`. | String                                                             | optional        | package type specific                     |
+| package_variables | A target that provides `PackageVariablesInfo` to substitute into `package_file_name`.                                                                                           | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional        | None                                      |
+| attributes        | Attributes to set on entities created within packages.  Not to be confused with bazel rule attributes.  See 'Mapping "Attributes"' below                                        | dict of String -> String List                                      | optional        | Varies.  See 'Mapping "Attributes"' below |
 
 See
 [examples/naming_package_files](https://github.com/bazelbuild/rules_pkg/tree/main/examples/naming_package_files)
 for examples of how `out`, `package_file_name`, and `package_variables`
 interact.
 
+<a name="mapping-attrs"></a>
+### Mapping "Attributes"
+
+The "attributes" attribute specifies properties of package contents as used in
+rules such as `pkg_files`, and `pkg_mkdirs`.  These allow fine-grained control
+of the contents of your package.  For example:
+
+```python
+attributes = {
+    "unix": ("0644", "myapp", "myapp"),
+    "my_custom_attribute": ("some custom value",),
+}
+```
+
+Known attributes include the following:
+
+#### `unix`
+
+Specifies basic UNIX-style filesystem permissions. For example:
+
+```python
+{"unix": ("0755", "root", "root")}
+```
+
+This is a three-element tuple, providing the filesystem mode (as an octal
+string, like above), user, and group.
+
+`"-"` may be provided in place of any of the values in the tuple.  Packaging
+rules will set these to a default, which will vary based on the underlying
+package builder and is otherwise unspecified.  Relying upon values set by it is
+not recommended.
+
+Package mapping rules typically set this to `("-", "-", "-")`.
+
+---
+
 <a name="pkg_tar"></a>
 ## pkg_tar