tar

General-purpose rule to create tar archives.

Unlike pkg_tar from rules_pkg 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:

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

Rules

mtree_spec

Create an mtree specification to map a directory hierarchy. See https://man.freebsd.org/cgi/man.cgi?mtree(8)

Example usage (generated):

load("@aspect_bazel_lib//lib:tar.bzl", "mtree_spec")

mtree_spec(
    # A unique name for this target.
    name = "",
)

name

Required name.

A unique name for this target.

out

Optional label.

Resulting specification file to write

srcs

Optional list of labels. Default: []

Files that are placed into the tar

tar_rule

Rule that executes BSD tar. Most users should use the tar macro, rather than load this directly.

Example usage (generated):

load("@aspect_bazel_lib//lib:tar.bzl", "tar_rule")

tar_rule(
    # A unique name for this target.
    name = "",
    # An mtree specification file
    mtree = "",
)

name

Required name.

A unique name for this target.

args

Optional list of strings. Default: []

Additional flags permitted by BSD tar; see the man page.

compress

Optional string. Default: ""

Compress the archive file with a supported algorithm.

mode

Optional string. Default: "create"

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.

mtree

Required label.

An mtree specification file

out

Optional label.

Resulting tar file to write. If absent, [name].tar is written.

srcs

Optional list of labels. Default: []

    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.

Macros and Functions

tar

Wrapper macro around 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.

Example usage (generated):

load("@aspect_bazel_lib//lib:tar.bzl", "tar")

tar(
    # name of resulting `tar_rule`
    name = "",
)

name

Required.

name of resulting tar_rule

mtree

Optional. Default: "auto"

"auto", or an array of specification lines, or a label of a file that contains the lines. Subject to $(location) and "Make variable" substitution.

stamp

Optional. Default: 0

should mtree attribute be stamped

kwargs

Optional.

additional named parameters to pass to tar_rule

tar_lib.implementation

Example usage (generated):

load("@aspect_bazel_lib//lib:tar.bzl", "tar_lib")

tar_lib.implementation(
    ctx = None,
)

ctx

Required.

tar_lib.mtree_implementation

Example usage (generated):

load("@aspect_bazel_lib//lib:tar.bzl", "tar_lib")

tar_lib.mtree_implementation(
    ctx = None,
)

ctx

Required.

tar_lib.common.add_compression_args

Example usage (generated):

load("@aspect_bazel_lib//lib:tar.bzl", "tar_lib")

tar_lib.common.add_compression_args(
    compress = None,
    args = [],
)

compress

Required.

args

Required.