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 outputspkg_mkdirs
describes directory structurespkg_mklink
describes symbolic linkspkg_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:
- Files are
exclude
d renames
orstrip_prefix
is applied.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 rename
d 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
exclude
d 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_files
s 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 filegroup
s.
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_file
s 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
exclude
d.
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:
You need to create an empty directory in your package.
Your package needs to explicitly own a directory, even if it already owns files in those directories.
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
).
pkg_mklink_impl
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 = "",
)
name
A unique name for this target.
attributes
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_name
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.
target
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.
pkg_mklink
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,
)
name
target name
link_name
the path in the package that should point to the target.
target
target path that the link should point to.
attributes
file attributes.
src
kwargs
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(
)