Bazel Central Registry

@tar.bzl//tar:mtree.bzl

Helpers for mtree(8), see https://man.freebsd.org/cgi/man.cgi?mtree(8)

Mutating the tar contents

The mtree_spec rule can be used to create an mtree manifest for the tar file.
Then you can mutate that spec using mtree_mutate and feed the result
as the mtree attribute of the tar rule.

For example, to set the owner uid of files in the tar, you could:

_TAR_SRCS = ["//some:files"]

mtree_spec(
    name = "mtree",
    srcs = _TAR_SRCS,
)

mtree_mutate(
    name = "change_owner",
    mtree = ":mtree",
    owner = "1000",
)

tar(
    name = "tar",
    srcs = _TAR_SRCS,
    mtree = "change_owner",
)

Functions & Macros

mtree_mutate

Modify metadata in an mtree file.

Parameters

`*name`	name of the target, output will be `[name].mtree`.
`*mtree`	input mtree file, typically created by `mtree_spec`.
`srcs`	list of files to resolve symlinks for. Default: `None`
`preserve_symlinks`	`EXPERIMENTAL!` We may remove or change it at any point without further notice. Flag to determine whether to preserve symlinks in the tar. Default: `False`
`strip_prefix`	prefix to remove from all paths in the tar. Files and directories not under this prefix are dropped. Default: `None`
`package_dir`	directory prefix to add to all paths in the tar. Default: `None`
`mtime`	new modification time for all entries. Default: `None`
`owner`	new uid for all entries. Default: `None`
`ownername`	new uname for all entries. Default: `None`
`awk_script`	may be overridden to change the script containing the modification logic. Default: `Label("//tar/private:modify_mtree.awk")`
`kwargs`	additional named parameters to genrule

mutate

Factory function to make a partially-applied mtree_mutate rule.

Parameters

kwargs

Rules

mtree_spec

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

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`srcs`	`list of labels`	Files that are placed into the tar Default: `[]`
`out`	`label`	Resulting specification file to write Default: `None`
`include_runfiles`	`boolean`	Include the runfiles tree in the resulting mtree for targets that are executable. The runfiles are in the paths that Bazel uses. For example, for the target `//my_prog:foo`, we would see files under paths like `foo.runfiles/<repo name>/my_prog/<file>` Default: `True`

@tar.bzl//tar:tar.bzl

API for calling tar, see https://man.freebsd.org/cgi/man.cgi?tar(1)

Load from:

load("@tar.bzl", "tar")

Examples

Build this target to produce archive.tar:

tar(
    name = "archive",
    srcs = ["my-file.txt"],
)

Mutations allow modification of the archive's structure. For example to strip the package name:

load("@tar.bzl", "mutate", "tar")

tar(
    name = "new",
    srcs = ["my-file.txt"],
    # See arguments documented at
    # https://github.com/bazel-contrib/tar.bzl/blob/main/docs/mtree.md#mtree_mutate
    mutate = mutate(strip_prefix = package_name()),
)

Functions & Macros

tar_lib.common.add_compression_args

Parameters

`*compress`
`*args`

tar_lib.implementation

Parameters

*ctx

tar_lib.mtree_implementation

Parameters

*ctx

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.

By default, mtree is "auto" which causes the macro to create an mtree_spec rule.
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)

mtree may be a label of a file containing the specification lines.

Parameters

`*name`	name of resulting `tar_rule`
`mtree`	"auto", or an array of specification lines, or a label of a file that contains the lines. Subject to $(location) and "Make variable" substitution. Default: `"auto"`
`mutate`	a partially-applied `mtree_mutate` rule Default: `None`
`include_runfiles`	When using "auto" mtree, this controls whether to include runfiles. If mtree is supplied as an array literal of lines, you are already hardcoding list of included files. When mtree is a label, you need to set include_runfiles in mtree_specs. Default: `None`
`stamp`	should mtree attribute be stamped Default: `0`
`kwargs`	additional named parameters to pass to `tar_rule`

Rules

tar_rule

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

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`args`	`list of strings`	Additional flags permitted by BSD tar; see the man page. Default: `[]`
`srcs`	`list of labels`	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. Default: `[]`
`mode`	`string`	A mode indicator from the following list, copied from the tar manpage: create: Create a new archive containing the specified items. Other modes may be added in the future. Default: `"create"`
`*mtree`	`label`	An mtree specification file
`out`	`label`	Resulting tar file to write. If absent, `[name].tar` is written. Default: `None`
`compress`	`string`	Compress the archive file with a supported algorithm. Default: `""`
`compressor`	`label`	External tool which can compress the archive. Default: `None`
`compressor_args`	`string`	Arg list for `compressor`. Default: `""`
`compute_unused_inputs`	`integer`	Whether to discover and prune input files that will not contribute to the archive. Unused inputs are discovered by comparing the set of input files in `srcs` to the set of files referenced by `mtree`. Files not used for content by the mtree specification will not be read by the `tar` tool when creating the archive and can be pruned from the input set using the `unused_inputs_list` mechanism. Benefits: pruning unused input files can reduce the amount of work the build system must perform. Pruned files are not included in the (local)action cache key; changes to them do not invalidate the cache entry, which can lead to higher cache hit rates. Actions do not need to block on the availability of pruned inputs, which can increase the available parallelism of builds. Risks: pruning an actually-used input file can lead to unexpected, incorrect results. The comparison performed between `srcs` and `mtree` is currently inexact and may fail to handle handwritten or externally-derived mtree specifications. However, it is safe to use this feature when the lines found in `mtree` are derived from one or more `mtree_spec` rules, filtered and/or merged on whole-line basis only. Possible values: - `compute_unused_inputs = 1`: Always perform unused input discovery and pruning. - `compute_unused_inputs = 0`: Never discover or prune unused inputs. - `compute_unused_inputs = -1`: Discovery and pruning of unused inputs is controlled by the --[no]@tar.bzl//tar:tar_compute_unused_inputs flag. Default: `-1`