bazel-lib/docs/tar.md

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

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 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, kwargs)

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.

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.	"auto"
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