Package creation helper mapping rules.

This module declares Provider interfaces and rules for specifying the contents of packages in a package-type-agnostic way. The main rules supported here are the following:

  • pkg_files describes destinations for rule outputs
  • pkg_mkdirs describes directory structures
  • pkg_mklink describes symbolic links
  • pkg_filegroup creates groupings of above to add to packages

Rules that actually make use of the outputs of the above rules are not specified here.

Rules

filter_directory

Transform directories (TreeArtifacts) using pkg_filegroup-like semantics.

Effective order of operations:

  1. Files are excluded
  2. renames or strip_prefix is applied.
  3. prefix is applied

In particular, if a rename applies to an individual file, strip_prefix will not be applied to that particular file.

Each non-`rename``d path will look like this:

$OUTPUT_DIR/$PREFIX/$FILE_WITHOUT_STRIP_PREFIX

Each renamed path will look like this:

$OUTPUT_DIR/$PREFIX/$FILE_RENAMED

If an operation cannot be applied (strip_prefix) to any component in the directory, or if one is unused (exclude, rename), the underlying command will fail. See the individual attributes for details.

Example usage (generated)

load("@rules_pkg//pkg:mappings.bzl", "filter_directory")

filter_directory(
    # A unique name for this target.
    name = "",
    # Directory (TreeArtifact) to process.
    src = "",
)

name

A unique name for this target.

excludes

Files to exclude from the output directory.

Each element must refer to an individual file in src.

All exclusions must be used.

outdir_name

Name of output directory (otherwise defaults to the rule's name)

prefix

Prefix to add to all paths in the output directory.

This does not include the output directory name, which will be added regardless.

renames

Files to rename in the output directory.

Keys are destinations, values are sources prior to any path modifications (e.g. via prefix or strip_prefix). Files that are excluded must not be renamed.

This currently only operates on individual files. strip_prefix does not apply to them.

All renames must be used.

src

Directory (TreeArtifact) to process.

strip_prefix

Prefix to remove from all paths in the output directory.

Must apply to all paths in the directory, even those rename'd.


pkg_filegroup

Package contents grouping rule.

This rule represents a collection of packaging specifications (e.g. those created by pkg_files, pkg_mklink, etc.) that have something in common, such as a prefix or a human-readable category.

Example usage (generated)

load("@rules_pkg//pkg:mappings.bzl", "pkg_filegroup")

pkg_filegroup(
    # A unique name for this target.
    name = "",
    # A list of packaging specifications to be grouped together.
    srcs = [],
)

name

A unique name for this target.

prefix

A prefix to prepend to provided paths, applied like so:

  • For files and directories, this is simply prepended to the destination
  • For symbolic links, this is prepended to the "destination" part.

srcs

A list of packaging specifications to be grouped together.


pkg_files

General-purpose package target-to-destination mapping rule.

This rule provides a specification for the locations and attributes of targets when they are packaged. No outputs are created other than Providers that are intended to be consumed by other packaging rules, such as pkg_rpm.

Labels associated with these rules are not passed directly to packaging rules, instead, they should be passed to an associated pkg_filegroup rule, which in turn should be passed to packaging rules.

Consumers of pkg_filess will, where possible, create the necessary directory structure for your files so you do not have to unless you have special requirements. Consult pkg_mkdirs for more details.

Example usage (generated)

load("@rules_pkg//pkg:mappings.bzl", "pkg_files")

pkg_files(
    # A unique name for this target.
    name = "",
    # Files/Labels to include in the outputs of these rules
    srcs = [],
)

name

A unique name for this target.

attributes

Attributes to set on packaged files.

Always use pkg_attributes() to set this rule attribute.

If not otherwise overridden, the file's mode will be set to UNIX "0644", or the target platform's equivalent.

Consult the "Mapping Attributes" documentation in the rules_pkg reference for more details.

excludes

List of files or labels to exclude from the inputs to this rule.

Mostly useful for removing files from generated outputs or preexisting filegroups.

prefix

Installation prefix.

This may be an arbitrary string, but it should be understandable by the packaging system you are using to have the desired outcome. For example, RPM macros like %{_libdir} may work correctly in paths for RPM packages, not, say, Debian packages.

If any part of the directory structure of the computed destination of a file provided to pkg_filegroup or any similar rule does not already exist within a package, the package builder will create it for you with a reasonable set of default permissions (typically 0755 root.root).

It is possible to establish directory structures with arbitrary permissions using pkg_mkdirs.

renames

Destination override map.

This attribute allows the user to override destinations of files in pkg_files relative to the prefix attribute. Keys to the dict are source files/labels, values are destinations relative to the prefix, ignoring whatever value was provided for strip_prefix.

If the key refers to a TreeArtifact (directory output), you may specify the constant REMOVE_BASE_DIRECTORY as the value, which will result in all containing files and directories being installed relative to the otherwise specified install prefix (via the prefix and strip_prefix attributes), not the directory name.

The following keys are rejected:

  • Any label that expands to more than one file (mappings must be one-to-one).

  • Any label or file that was either not provided or explicitly excluded.

The following values result in undefined behavior:

  • "" (the empty string)

  • "."

  • Anything containing ".."

srcs

Files/Labels to include in the outputs of these rules

strip_prefix

What prefix of a file's path to discard prior to installation.

This specifies what prefix of an incoming file's path should not be included in the output package at after being appended to the install prefix (the prefix attribute). Note that this is only applied to full directory names, see strip_prefix for more details.

Use the strip_prefix struct to define this attribute. If this attribute is not specified, all directories will be stripped from all files prior to being included in packages (strip_prefix.files_only()).

If prefix stripping fails on any file provided in srcs, the build will fail.

Note that this only functions on paths that are known at analysis time. Specifically, this will not consider directories within TreeArtifacts (directory outputs), or the directories themselves. See also #269.


pkg_mkdirs

Defines creation and ownership of directories in packages

Use this if:

  1. You need to create an empty directory in your package.

  2. Your package needs to explicitly own a directory, even if it already owns files in those directories.

  3. You need nonstandard permissions (typically, not "0755") on a directory in your package.

For some package management systems (e.g. RPM), directory ownership (2) may imply additional semantics. Consult your package manager's and target distribution's documentation for more details.

Example usage (generated)

load("@rules_pkg//pkg:mappings.bzl", "pkg_mkdirs")

pkg_mkdirs(
    # A unique name for this target.
    name = "",
    # Directory names to make within the package
    dirs = [],
)

name

A unique name for this target.

attributes

Attributes to set on packaged directories.

Always use pkg_attributes() to set this rule attribute.

If not otherwise overridden, the directory's mode will be set to UNIX "0755", or the target platform's equivalent.

Consult the "Mapping Attributes" documentation in the rules_pkg reference for more details.

dirs

Directory names to make within the package

If any part of the requested directory structure does not already exist within a package, the package builder will create it for you with a reasonable set of default permissions (typically 0755 root.root).


Define a symlink within packages

This rule results in the creation of a single link within a package.

Symbolic links specified by this rule may point at files/directories outside of the package, or otherwise left dangling.

Example usage (generated)

load("@rules_pkg//pkg:mappings.bzl", "pkg_mklink_impl")

pkg_mklink_impl(
    # A unique name for this target.
    name = "",
    # Link "destination", a path within the package
    link_name = "",
    # Link "target", a path on the filesystem
    target = "",
)

A unique name for this target.

Attributes to set on packaged symbolic links.

Always use pkg_attributes() to set this rule attribute.

Symlink permissions may have different meanings depending on your host operating system; consult its documentation for more details.

If not otherwise overridden, the link's mode will be set to UNIX "0777", or the target platform's equivalent.

Consult the "Mapping Attributes" documentation in the rules_pkg reference for more details.

Link "destination", a path within the package.

This is the actual created symbolic link.

If the directory structure provided by this attribute is not otherwise created when exist within the package when it is built, it will be created implicitly, much like with pkg_files.

This path may be prefixed or rooted by grouping or packaging rules.

Link "target", a path on the filesystem.

This is what the link "points" to, and may point to an arbitrary filesystem path, even relative paths.


Macros and Functions

pkg_attributes

Format attributes for use in package mapping rules.

If "mode" is not provided, it will default to the mapping rule's default mode. These vary per mapping rule; consult the respective documentation for more details.

Not providing any of "user", or "group" will result in the package builder choosing one for you. The chosen value should not be relied upon.

Well-known attributes outside of the above are documented in the rules_pkg reference.

This is the only supported means of passing in attributes to package mapping rules (e.g. pkg_files).

Example usage (generated)

load("@rules_pkg//pkg:mappings.bzl", "pkg_attributes")

pkg_attributes(
)

mode

string: UNIXy octal permissions, as a string.

user

string: Filesystem owning user.

group

string: Filesystem owning group.

kwargs

any other desired attributes.


Create a symlink.

Example usage (generated)

load("@rules_pkg//pkg:mappings.bzl", "pkg_mklink")

pkg_mklink(
    # target name
    name = "",
    # the path in the package that should point to the target.
    link_name = None,
    # target path that the link should point to.
    target = None,
)

target name

the path in the package that should point to the target.

target path that the link should point to.

file attributes.


strip_prefix.files_only

Example usage (generated)

load("@rules_pkg//pkg:mappings.bzl", "strip_prefix")

strip_prefix.files_only(
)

strip_prefix.from_pkg

Example usage (generated)

load("@rules_pkg//pkg:mappings.bzl", "strip_prefix")

strip_prefix.from_pkg(
)

path


strip_prefix.from_root

Example usage (generated)

load("@rules_pkg//pkg:mappings.bzl", "strip_prefix")

strip_prefix.from_root(
)

path