Skip to main content
Version: 2.0.x

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.

TODO:

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 = "",
# Files that are placed into the tar
srcs = [],
)

name

Required name.

A unique name for this target.

out

Optional label.

Resulting specification file to write

srcs

Required list of labels.

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 = "",
# Files, directories, or other targets whose default outputs are placed into the tar
srcs = [],
)

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

Required 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.

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 rule.

  2. mtree may also 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)

  1. 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.

kwargs

Optional.

additional named parameters to pass to tar_rule