Packaging for Bazel

Deprecated

These rules have been extracted from the Bazel sources and are now available at bazelbuild/rules_pkg (docs).

Issues and PRs against the built-in versions of these rules will no longer be addressed. This page will exist for reference until the code is removed from Bazel.

For more information, follow issue 8857

rules_pkg

Rules

Overview

pkg_tar() is available for building a .tar file without depending on anything besides Bazel. Since this feature is deprecated and will eventually be removed from Bazel, you should migrate to @rules_pkg.

Basic Example

This example is a simplification of building Bazel and creating a distribution tarball.

load("@bazel_tools//tools/build_defs/pkg:pkg.bzl", "pkg_tar")

pkg_tar(
    name = "bazel-bin",
    strip_prefix = "/src",
    package_dir = "/usr/bin",
    srcs = ["//src:bazel"],
    mode = "0755",
)

pkg_tar(
    name = "bazel-tools",
    strip_prefix = "/",
    package_dir = "/usr/share/lib/bazel/tools",
    srcs = ["//tools:package-srcs"],
    mode = "0644",
)

pkg_tar(
    name = "bazel-all",
    extension = "tar.gz",
    deps = [
        ":bazel-bin",
        ":bazel-tools",
    ],
)

Here, a package is built from three pkg_tar targets:

  • bazel-bin creates a tarball with the main binary (mode 0755) in /usr/bin,
  • bazel-tools create a tarball with the base workspace (mode 0644) to /usr/share/bazel/tools ; the modes attribute let us specifies executable files,
  • bazel-all creates a gzip-compressed tarball that merge the two previous tarballs.

pkg_tar

pkg_tar(name, extension, strip_prefix, package_dir, srcs,
mode, modes, deps, symlinks)

Creates a tar file from a list of inputs.

Attributes
name Name, required

A unique name for this rule.
extension String, default to 'tar'

The extension for the resulting tarball. The output file will be 'name.extension'. This extension also decide on the compression: if set to tar.gz or tgz then gzip compression will be used and if set to tar.bz2 or tar.bzip2 then bzip2 compression will be used.

strip_prefix String, optional

Root path of the files.

The directory structure from the files is preserved inside the tarball but a prefix path determined by strip_prefix is removed from the directory structure. This path can be absolute from the workspace root if starting with a / or relative to the rule's directory. A relative path may start with "./" (or be ".") but cannot use ".." to go up level(s). By default, the strip_prefix attribute is unused and all files are supposed to have no prefix. A strip_prefix of "" (the empty string) means the same as the default.

package_dir String, optional

Target directory.

The directory in which to expand the specified files, defaulting to '/'. Only makes sense accompanying files.

srcs List of files, optional

File to add to the layer.

A list of files that should be included in the archive.

mode String, default to 0555

Set the mode of files added by the files attribute.

mtime int, seconds since Jan 1, 1970, default to -1 (ignored)

Set the mod time of files added by the files attribute.

portable_mtime bool, default True

Set the mod time of files added by the files attribute to a 2000-01-01.

modes Dictionary, default to '{}'

A string dictionary to change default mode of specific files from files. Each key should be a path to a file before appending the prefix package_dir and the corresponding value the octal permission of to apply to the file.

modes = { "tools/py/2to3.sh": "0755", ... },

owner String, default to '0.0'

UID.GID to set the default numeric owner for all files provided in files.

owners Dictionary, default to '{}'

A string dictionary to change default owner of specific files from files. Each key should be a path to a file before appending the prefix package_dir and the corresponding value the UID.GID numeric string for the owner of the file. When determining owner ids, this attribute is looked first then owner.

owners = { "tools/py/2to3.sh": "42.24", ... },

ownername String, optional

username.groupname to set the default owner for all files provided in files (by default there is no owner names).

ownernames Dictionary, default to '{}'

A string dictionary to change default owner of specific files from files. Each key should be a path to a file before appending the prefix package_dir and the corresponding value the username.groupname string for the owner of the file. When determining ownernames, this attribute is looked first then ownername.

owners = { "tools/py/2to3.sh": "leeroy.jenkins", ... },

deps List of labels, optional

Tar files to extract and include in this tar package.

A list of tarball labels to merge into the output tarball.

symlinks Dictionary, optional

Symlinks to create in the output tarball.

symlinks = { "/path/to/link": "/path/to/target", ... },

remap_paths Dictionary, optional

Source path prefixes to remap in the tarfile.

remap_paths = { "original/path/prefix": "replaced/path", ... },