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. You can test the removal of these rules with Bazel at version >= 0.28.0.

bazel build --//tools/build_defs/pkg:incompatible_no_build_defs_pkg  target...

For more information, follow issue 8857

rules_pkg

Overview

These build rules are used for building various packaging such as tarball and debian package.

Basic Example

This example is a simplification of the debian packaging of Bazel:

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

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 = "debian-data",
    extension = "tar.gz",
    deps = [
        ":bazel-bin",
        ":bazel-tools",
    ],
)

pkg_deb(
    name = "bazel-debian",
    architecture = "amd64",
    built_using = "unzip (6.0.1)",
    data = ":debian-data",
    depends = [
        "zlib1g-dev",
        "unzip",
    ],
    description_file = "debian/description",
    homepage = "http://bazel.build",
    maintainer = "The Bazel Authors <bazel-dev@googlegroups.com>",
    package = "bazel",
    version = "0.1.1",
)

Here, the Debian 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,
debian-data creates a gzip-compressed tarball that merge the three previous tarballs.

debian-data is then used for the data content of the debian archive created by pkg_deb.

Future work

Support more format, especially pkg_zip.
Maybe a bit more integration with the docker_build rule.

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", ... },`

pkg_deb

pkg_deb(name, data, package, architecture, maintainer, preinst, postinst, prerm, postrm, version, version_file, description, description_file, built_using, built_using_file, priority, section, homepage, depends, suggests, enhances, conflicts, predepends, recommends)

Create a debian package. See http://www.debian.org/doc/debian-policy/ch-controlfields.html for more details on this.

Attributes
`name`	`Name, required` A unique name for this rule.
`data`	`File, required` A tar file that contains the data for the debian package (basically the list of files that will be installed by this package).
`package`	`String, required` The name of the package.
`architecture`	`String, default to 'all'` The architecture that this package target. See http://www.debian.org/ports/.
`maintainer`	`String, required` The maintainer of the package.
`preinst`, `postinst`, `prerm` and `postrm`	`Files, optional` Respectively, the pre-install, post-install, pre-remove and post-remove scripts for the package. See http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html.
`config`	`File, optional` config file used for debconf integration. See https://www.debian.org/doc/debian-policy/ch-binary.html#prompting-in-maintainer-scripts.
`templates`	`File, optional` templates file used for debconf integration. See https://www.debian.org/doc/debian-policy/ch-binary.html#prompting-in-maintainer-scripts.
`conffiles`, `conffiles_file`	`String list or File, optional` The list of conffiles or a file containing one conffile per line. Each item is an absolute path on the target system where the deb is installed. See https://www.debian.org/doc/manuals/debian-faq/ch-pkg_basics.en.html#s-conffile.
`version`, `version_file`	`String or File, required` The package version provided either inline (with `version`) or from a file (with `version_file`).
`description`, `description_file`	`String or File, required` The package description provided either inline (with `description`) or from a file (with `description_file`).
`built_using`, `built_using_file`	`String or File` The tool that were used to build this package provided either inline (with `built_using`) or from a file (with `built_using_file`).
`priority`	`String, default to 'optional'` The priority of the package. See http://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities.
`section`	`String, default to 'contrib/devel'` The section of the package. See http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections.
`homepage`	`String, optional` The homepage of the project.
`depends`, `suggests`, `enhances`, `conflicts`, `predepends` and `recommends`.	`String list, optional` The list of dependencies in the project. See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps.