Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.aspect.build/llms.txt

Use this file to discover all available pages before exploring further.

Documentation for @tar.bzl@v0.8.1 — View source
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()),
)
Compression is supported. Of course it takes additional time and resources. 
# Build this target to produce archive.tar.gz:
tar(
    name = "my_archive",
    compress = "gzip",
    ...
)
Normally if your tar file is small, you can keep using the built-in gzip, but if your tar file is large, over 1GB, parallel pigz will greatly improve the performance.
  1. Add pigz in MODULE.bazel; see https://registry.bazel.build/modules/pigz
  2. Use the new tar compressor attribute in your BUILD file, eg:
tar(
    name = "my_tar_file",
    compressor = "@pigz",
    compressor_args = "-n",
    ...
)

​
Rule: tar_rule

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

​
Attributes

​
name
name
required
A unique name for this target.
​
args
list of strings
default:"[]"
Additional flags permitted by BSD tar; see the man page.
​
srcs
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.
​
mode
string
default:"create"
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.
​
mtree
label
required
An mtree specification file
​
out
label
default:"None"
Resulting tar file to write. If absent, [name].tar is written.
​
compress
string
default:"\"\""
Compress the archive file with a supported algorithm.Default is "" which means no compression.
​
compressor
label
default:"None"
External tool which can compress the archive.
​
compressor_args
string
default:"\"\""
Arg list for compressor.
​
compute_unused_inputs
integer
default:"-1"
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.

​
Function: tar_lib.common.add_compression_args

​
Parameters

​
compress
name
required
​
args
name
required

​
Function: tar_lib.implementation

​
Parameters

​
ctx
name
required

​
Function: tar_lib.mtree_implementation

​
Parameters

​
ctx
name
required

​
Function: 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)
  1. mtree may be a label of a file containing the specification lines.

​
Parameters

​
name
name
required
name of resulting tar_rule
​
mtree
name
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.
​
mutate
name
default:"None"
a partially-applied mtree_mutate rule
​
include_runfiles
name
default:"None"
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.
​
stamp
name
default:"0"
should mtree attribute be stamped
​
kwargs
string_list
additional named parameters to pass to tar_rule