General-purpose rule to create tar archives. Unlike [pkg_tar from rules_pkg](https://github.com/bazelbuild/rules_pkg/blob/main/docs/latest.md#pkg_tar) this: - Does not depend on any Python interpreter setup - The "manifest" specification is a mature public API and uses a compact tabular format, fixing https://github.com/bazelbuild/rules_pkg/pull/238 - Does not have any custom program to produce the output, instead we rely on a well-known C++ program called "tar". Specifically, we use the BSD variant of tar since it provides a means of controlling mtimes, uid, symlinks, etc. We also provide full control for tar'ring binaries including their runfiles. ## Modifying metadata The `mtree_spec` rule can be used to create an mtree manifest for the tar file. Then you can mutate that spec, as it's just a simple text file, and feed the result as the `mtree` attribute of the `tar` rule. For example, to set the `uid` property, you could: ```starlark mtree_spec( name = "mtree", srcs = ["//some:files"], ) genrule( name = "change_owner", srcs = ["mtree"], outs = ["mtree.mutated"], cmd = "sed 's/uid=0/uid=1000/' <$< >$@", ) tar( name = "tar", srcs = ["//some:files"], mtree = "change_owner", ) ``` Note: We intend to contribute mutation features to https://github.com/vbatts/go-mtree to provide a richer API for things like `strip_prefix`. In the meantime, see the `lib/tests/tar/BUILD.bazel` file in this repo for examples. TODO: - Provide convenience for rules_pkg users to re-use or replace pkg_files trees ## mtree_spec 
mtree_spec(name, out, srcs)
Create an mtree specification to map a directory hierarchy. See https://man.freebsd.org/cgi/man.cgi?mtree(8) **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | out | Resulting specification file to write | Label | optional | | | srcs | Files that are placed into the tar | List of labels | required | | ## tar_rule 
tar_rule(name, args, compress, mode, mtree, out, srcs)
Rule that executes BSD `tar`. Most users should use the [`tar`](#tar) macro, rather than load this directly. **ATTRIBUTES** | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | name | A unique name for this target. | Name | required | | | args | Additional flags permitted by BSD tar; see the man page. | List of strings | optional | [] | | compress | Compress the archive file with a supported algorithm. | String | optional | "" | | mode | A mode indicator from the following list, copied from the tar manpage:

- create: Create a new archive containing the specified items. - append: Like create, but new entries are appended to the archive. Note that this only works on uncompressed archives stored in regular files. The -f option is required. - list: List archive contents to stdout. - update: Like append, but new entries are added only if they have a modification date newer than the corresponding entry in the archive. Note that this only works on uncompressed archives stored in regular files. The -f option is required. - extract: Extract to disk from the archive. If a file with the same name appears more than once in the archive, each copy will be extracted, with later copies overwriting (replacing) earlier copies. | String | optional | "create" | | mtree | An mtree specification file | Label | required | | | out | Resulting tar file to write. If absent, [name].tar is written. | Label | optional | | | srcs | Files, directories, or other targets whose default outputs are placed into the tar.

If any of the srcs are binaries with runfiles, those are copied into the resulting tar as well. | List of labels | required | | ## tar 
tar(name, mtree, stamp, kwargs)
Wrapper macro around [`tar_rule`](#tar_rule). ### Options for mtree mtree provides the "specification" or manifest of a tar file. See https://man.freebsd.org/cgi/man.cgi?mtree(8) Because BSD tar doesn't have a flag to set modification times to a constant, we must always supply an mtree input to get reproducible builds. See https://reproducible-builds.org/docs/archives/ for more explanation. 1. By default, mtree is "auto" which causes the macro to create an `mtree_spec` rule. 2. `mtree` may be supplied as an array literal of lines, e.g. ``` mtree =[ "usr/bin uid=0 gid=0 mode=0755 type=dir", "usr/bin/ls uid=0 gid=0 mode=0755 time=0 type=file content={}/a".format(package_name()), ], ``` For the format of a line, see "There are four types of lines in a specification" on the man page for BSD mtree, https://man.freebsd.org/cgi/man.cgi?mtree(8) 3. `mtree` may be a label of a file containing the specification lines. **PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | name | name of resulting tar_rule | none | | mtree | "auto", or an array of specification lines, or a label of a file that contains the lines. Subject to [$(location)](https://bazel.build/reference/be/make-variables#predefined_label_variables) and ["Make variable"](https://bazel.build/reference/be/make-variables) substitution. | "auto" | | stamp | should mtree attribute be stamped | 0 | | kwargs | additional named parameters to pass to tar_rule | none | ## tar_lib.implementation 
tar_lib.implementation(ctx)
**PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | ctx |

-

| none | ## tar_lib.mtree_implementation 
tar_lib.mtree_implementation(ctx)
**PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | ctx |

-

| none | ## tar_lib.common.add_compression_args 
tar_lib.common.add_compression_args(compress, args)
**PARAMETERS** | Name | Description | Default Value | | :------------- | :------------- | :------------- | | compress |

-

| none | | args |

-

| none |