diff --git a/CHANGELOG.md b/CHANGELOG.md index 4dbef8f7..8a5e7c24 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,71 @@ +# Release 0.10.0 + +**New Features** +- Allow $(var) substitution in filenames (#620) +- Rough prototype of @since processing. (#617) +- First cut at runfiles support in pkg_* rules (#605) +- Allow substitution of user-defined variables in RPM preamble (#787) +- Add %posttrans scriptlet to RPM package (#799) +- Allow additional RPM macro defines (#794) +- Bring tar runfiles up to feature parity with pkg_files.runfiles. (#754) +- Add support for `Obsoletes` tag in RPM definition (#778) +- pkg_deb: allow data.tar.zst (#761) +- Add support for failing on file conflicts. (#683) +- Make pkg_zip compression configurable (#737) +- Append changelog to RPM spec file (#726) +- Add basic include_runfiles to pkg_files. (#724) +- Add changelog attribute to pkg_deb (#725) +- Add support for setting uid/gid from pkg_attributes (#671) + +**Bug Fixes** +- Explicitly set the FILE bit in zip external attributes. (#802) +- Explicitly set `%{_builddir}` macro (#792) +- Only inject pre and post scriptlets when provided (#788) +- Don't load cc toolchain from rules_cc (#779) +- doc: Fixup external manual references (#777) +- Get bzlmod working in CI (#766) +- use runfiles from rules_python (#768) +- When pkg_tar.prefix_dir == base of symlink path, don't double-dip. (#749) +- add imports to fix bazel --noexperimental_python_import_all_repositories flag (#630) +- Align pkg_rpm returned files with other rules (#692) +- fix(pkg_tar): properly normalize paths for empty files (#760) +- Document that package_dir also uses package_variables (#747) +- Fix handling paths with whitepsaces (#733) +- Fix python 3.6, doesn't support compresslevel +- Use Gzip compress level 6 (#720) +- write debian Date field in UTC rather than local time (#712) +- [pkg_deb] Fix multiline fields in changes file (#691) + +**Breaking Changes +- Remove PackageArtifactsInfo. (#752) + +Thanks to: Adam Azarchs, Alex Eagle, August Karlstedt, Austin Schuh, Adrian Vogelsgesang, +flode, Florian Scheibner, Ignas Kaziukėnas, Jean-Hadrien Chabran, Matt, +Mike Kelly, Paul Draper, Sam Schwebach, Tomasz Wojno, and Vertexwahn +for contributions to this release. + +# Release 0.9.x + +**New Features** +- Add OutputGroupInfo for pkg_rpm rule (#684) +- Add verify_archive rule to do e2e tests on built archives. (#669) +- Expose tar manifest as an output (#643) +- Support license attribute in pkg_deb (#651) +- Add support for the txz extension in pkg_tar (#653) (#654) + +**Bug Fixes** +- pkg_tar should not prefix tree artifacts with ./ (#681) +- Fix a potential TypeException caused by None type (#668) +- pkg_zip: Some unicode file handling fixes and basic tests (#641) +- pkg_tar, pkg_zip: improve support for long paths on Windows (#672) +- Explicitly store implicit parent directories in zip files (#640) +- Remove unnecessary `to_list()` calls (#639) + +Thanks to: Clint Harrison Qingyu Sui, Fabian Meumertzheim, Ryan Beasley, Andrew Psaltis +Alex Eagle, Nils Semmelrock, and Doug Rabson +for contributions to this release. + + # Release 0.8.0 **New Features** diff --git a/docs/0.10.0/reference.md b/docs/0.10.0/reference.md new file mode 100755 index 00000000..59393635 --- /dev/null +++ b/docs/0.10.0/reference.md @@ -0,0 +1,726 @@ +# rules_pkg - 0.10.0 + +
+

Common Attributes

+ + +

Packaging Rules

+ + +

File Tree Creation Rules

+ +
+ + + +### Common Attributes + +These attributes are used in several rules within this module. + +**ATTRIBUTES** + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :-------------: | :-------------: | :------------- | +| out | Name of the output file. This file will always be created and used to access the package content. If `package_file_name` is also specified, `out` will be a symlink. | String | required | | +| package_file_name | The name of the file which will contain the package. The name may contain variables in the forms `{var}` and $(var)`. The values for substitution are specified through `package_variables` or taken from [ctx.var](https://bazel.build/rules/lib/ctx#var). | String | optional | package type specific | +| package_variables | A target that provides `PackageVariablesInfo` to substitute into `package_file_name`. `pkg_zip` and `pkg_tar` also support this in `package_dir` | Label | optional | None | +| attributes | Attributes to set on entities created within packages. Not to be confused with bazel rule attributes. See 'Mapping "Attributes"' below | Undefined. | optional | Varies. Consult individual rule documentation for details. | + +See +[examples/naming_package_files](https://github.com/bazelbuild/rules_pkg/tree/main/examples/naming_package_files) +for examples of how `out`, `package_file_name`, and `package_variables` +interact. + +
Since 0.8.0
: File name substitution now supports the $(var) syntax. +
Since 0.8.0
: File name substitution now supports direct use of [ctx.var](https://bazel.build/rules/lib/ctx#var). + + + +### Mapping "Attributes" + +The "attributes" attribute specifies properties of package contents as used in +rules such as `pkg_files`, and `pkg_mkdirs`. These allow fine-grained control +of the contents of your package. For example: + +```python +attributes = pkg_attributes( + mode = "0644", + user = "root", + group = "wheel", + my_custom_attribute = "some custom value", +) +``` + +`mode`, `user`, and `group` correspond to common UNIX-style filesystem +permissions. Attributes should always be specified using the `pkg_attributes` +helper macro. + +Each mapping rule has some default mapping attributes. At this time, the only +default is "mode", which will be set if it is not otherwise overridden by the user. + +If `user` and `group` are not specified, then defaults for them will be chosen +by the underlying package builder. Any specific behavior from package builders +should not be relied upon. + +Any other attributes should be specified as additional arguments to +`pkg_attributes`. + + + +Rule for creating Debian packages. + + + +## pkg_deb + +
+pkg_deb(name, architecture, architecture_file, breaks, built_using, built_using_file,
+             changelog, conffiles, conffiles_file, config, conflicts, data, depends, depends_file,
+             description, description_file, distribution, enhances, homepage, license, maintainer,
+             out, package, package_file_name, package_variables, postinst, postrm, predepends,
+             preinst, prerm, priority, provides, recommends, replaces, section, suggests, templates,
+             triggers, urgency, version, version_file)
+
+ + + Create a Debian package. + + This rule produces 2 artifacts: a .deb and a .changes file. The DefaultInfo will + include both. If you need downstream rule to specifically depend on only the .deb or + .changes file then you can use `filegroup` to select distinct output groups. + + **OutputGroupInfo** + - `out` the Debian package or a symlink to the actual package. + - `deb` the package with any precise file name created with `package_file_name`. + - `changes` the .changes file. + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| architecture | Package architecture. Must not be used with architecture_file. | String | optional | "all" | +| architecture_file | File that contains the package architecture. Must not be used with architecture. | Label | optional | None | +| breaks | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| built_using | The tool that were used to build this package provided either inline (with built_using) or from a file (with built_using_file). | String | optional | "" | +| built_using_file | The tool that were used to build this package provided either inline (with built_using) or from a file (with built_using_file). | Label | optional | None | +| changelog | The package changelog. See https://www.debian.org/doc/debian-policy/ch-source.html#s-dpkgchangelog. | Label | optional | None | +| conffiles | 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/debian-policy/ch-files.html#s-config-files. | List of strings | optional | [] | +| conffiles_file | 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/debian-policy/ch-files.html#s-config-files. | Label | optional | None | +| config | config file used for debconf integration. See https://www.debian.org/doc/debian-policy/ch-binary.html#prompting-in-maintainer-scripts. | Label | optional | None | +| conflicts | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| data | A tar file that contains the data for the debian package. | Label | required | | +| depends | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| depends_file | File that contains a list of package dependencies. Must not be used with depends. See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | Label | optional | None | +| description | The package description. Must not be used with description_file. | String | optional | "" | +| description_file | The package description. Must not be used with description. | Label | optional | None | +| distribution | "distribution: See http://www.debian.org/doc/debian-policy. | String | optional | "unstable" | +| enhances | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| homepage | The homepage of the project. | String | optional | "" | +| license | The license of the project. | String | optional | "" | +| maintainer | The maintainer of the package. | String | required | | +| out | See [Common Attributes](#out) | Label | required | | +| package | The name of the package | String | required | | +| package_file_name | See [Common Attributes](#package_file_name). Default: "{package}-{version}-{architecture}.deb | String | optional | "" | +| package_variables | See [Common Attributes](#package_variables) | Label | optional | None | +| postinst | The post-install script for the package. See http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html. | Label | optional | None | +| postrm | The post-remove script for the package. See http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html. | Label | optional | None | +| predepends | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| preinst | "The pre-install script for the package. See http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html. | Label | optional | None | +| prerm | The pre-remove script for the package. See http://www.debian.org/doc/debian-policy/ch-maintainerscripts.html. | Label | optional | None | +| priority | The priority of the package. See http://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities. | String | optional | "" | +| provides | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| recommends | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| replaces | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| section | The section of the package. See http://www.debian.org/doc/debian-policy/ch-archive.html#s-subsections. | String | optional | "" | +| suggests | See http://www.debian.org/doc/debian-policy/ch-relationships.html#s-binarydeps. | List of strings | optional | [] | +| templates | templates file used for debconf integration. See https://www.debian.org/doc/debian-policy/ch-binary.html#prompting-in-maintainer-scripts. | Label | optional | None | +| triggers | triggers file for configuring installation events exchanged by packages. See https://wiki.debian.org/DpkgTriggers. | Label | optional | None | +| urgency | "urgency: See http://www.debian.org/doc/debian-policy. | String | optional | "medium" | +| version | Package version. Must not be used with version_file. | String | optional | "" | +| version_file | File that contains the package version. Must not be used with version. | Label | optional | None | + + + + + +Provides rules for creating RPM packages via pkg_filegroup and friends. + +pkg_rpm() depends on the existence of an rpmbuild toolchain. Many users will +find to convenient to use the one provided with their system. To enable that +toolchain add the following stanza to WORKSPACE: + +``` +# Find rpmbuild if it exists. +load("@rules_pkg//toolchains/rpm:rpmbuild_configure.bzl", "find_system_rpmbuild") +find_system_rpmbuild(name="rules_pkg_rpmbuild") +``` + + + + +## pkg_rpm + +
+pkg_rpm(name, architecture, binary_payload_compression, changelog, conflicts, debug, defines,
+        description, description_file, group, license, obsoletes, package_file_name, package_name,
+        package_variables, post_scriptlet, post_scriptlet_file, posttrans_scriptlet,
+        posttrans_scriptlet_file, postun_scriptlet, postun_scriptlet_file, pre_scriptlet,
+        pre_scriptlet_file, preun_scriptlet, preun_scriptlet_file, provides, release, release_file,
+        requires, requires_contextual, rpmbuild_path, source_date_epoch, source_date_epoch_file,
+        spec_template, srcs, summary, url, version, version_file)
+
+ +Creates an RPM format package via `pkg_filegroup` and friends. + + The uses the outputs of the rules in `mappings.bzl` to construct arbitrary + RPM packages. Attributes of this rule provide preamble information and + scriptlets, which are then used to compose a valid RPM spec file. + + This rule will fail at analysis time if: + + - Any `srcs` input creates the same destination, regardless of other + attributes. + + This rule only functions on UNIXy platforms. The following tools must be + available on your system for this to function properly: + + - `rpmbuild` (as specified in `rpmbuild_path`, or available in `$PATH`) + + - GNU coreutils. BSD coreutils may work, but are not tested. + + To set RPM file attributes (like `%config` and friends), set the + `rpm_filetag` in corresponding packaging rule (`pkg_files`, etc). The value + is prepended with "%" and added to the `%files` list, for example: + + ``` + attrs = {"rpm_filetag": ("config(missingok, noreplace)",)}, + ``` + + Is the equivalent to `%config(missingok, noreplace)` in the `%files` list. + + This rule produces 2 artifacts: an .rpm and a .changes file. The DefaultInfo will + include both. If you need downstream rule to specifically depend on only the .rpm or + .changes file then you can use `filegroup` to select distinct output groups. + + **OutputGroupInfo** + - `out` the RPM or a symlink to the actual package. + - `rpm` the package with any precise file name created with `package_file_name`. + - `changes` the .changes file. + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| architecture | Package architecture.

This currently sets the BuildArch tag, which influences the output architecture of the package.

Typically, BuildArch only needs to be set when the package is known to be cross-platform (e.g. written in an interpreted language), or, less common, when it is known that the application is only valid for specific architectures.

When no attribute is provided, this will default to your host's architecture. This is usually what you want. | String | optional | "" | +| binary_payload_compression | Compression mode used for this RPM

Must be a form that rpmbuild(8) knows how to process, which will depend on the version of rpmbuild in use. The value corresponds to the %_binary_payload macro and is set on the rpmbuild(8) command line if provided.

Some examples of valid values (which may not be supported on your system) can be found [here](https://git.io/JU9Wg). On CentOS systems (also likely Red Hat and Fedora), you can find some supported values by looking for %_binary_payload in /usr/lib/rpm/macros. Other systems have similar files and configurations.

If not provided, the compression mode will be computed by rpmbuild itself. Defaults may vary per distribution or build of rpm; consult the relevant documentation for more details.

WARNING: Bazel is currently not aware of action threading requirements for non-test actions. Using threaded compression may result in overcommitting your system. | String | optional | "" | +| changelog | - | Label | optional | None | +| conflicts | List of capabilities that conflict with this package when it is installed.

Corresponds to the "Conflicts" preamble tag.

See also: https://rpm-software-management.github.io/rpm/manual/dependencies.html | List of strings | optional | [] | +| debug | Debug the RPM helper script and RPM generation | Boolean | optional | False | +| defines | Additional definitions to pass to rpmbuild | Dictionary: String -> String | optional | {} | +| description | Multi-line description of this package, corresponds to RPM %description.

Exactly one of description or description_file must be provided. | String | optional | "" | +| description_file | File containing a multi-line description of this package, corresponds to RPM %description. | Label | optional | None | +| group | Optional; RPM "Group" tag.

NOTE: some distributions (as of writing, Fedora > 17 and CentOS/RHEL > 5) have deprecated this tag. Other distributions may require it, but it is harmless in any case. | String | optional | "" | +| license | RPM "License" tag.

The software license for the code distributed in this package.

The underlying RPM builder requires you to put something here; if your package is not going to be distributed, feel free to set this to something like "Internal". | String | required | | +| obsoletes | List of rpm capability expressions that this package obsoletes.

Corresponds to the "Obsoletes" preamble tag.

See also: https://rpm-software-management.github.io/rpm/manual/dependencies.html | List of strings | optional | [] | +| package_file_name | See 'Common Attributes' in the rules_pkg reference.

If this is not provided, the package file given a NVRA-style (name-version-release.arch) output, which is preferred by most RPM repositories. | String | optional | "" | +| package_name | Optional; RPM name override.

If not provided, the name attribute of this rule will be used instead.

This influences values like the spec file name. | String | optional | "" | +| package_variables | See 'Common Attributes' in the rules_pkg reference | Label | optional | None | +| post_scriptlet | RPM %post scriptlet. Currently only allowed to be a shell script.

post_scriptlet and post_scriptlet_file are mutually exclusive. | String | optional | "" | +| post_scriptlet_file | File containing the RPM %post scriptlet | Label | optional | None | +| posttrans_scriptlet | RPM %posttrans scriptlet. Currently only allowed to be a shell script.

posttrans_scriptlet and posttrans_scriptlet_file are mutually exclusive. | String | optional | "" | +| posttrans_scriptlet_file | File containing the RPM %posttrans scriptlet | Label | optional | None | +| postun_scriptlet | RPM %postun scriptlet. Currently only allowed to be a shell script.

postun_scriptlet and postun_scriptlet_file are mutually exclusive. | String | optional | "" | +| postun_scriptlet_file | File containing the RPM %postun scriptlet | Label | optional | None | +| pre_scriptlet | RPM %pre scriptlet. Currently only allowed to be a shell script.

pre_scriptlet and pre_scriptlet_file are mutually exclusive. | String | optional | "" | +| pre_scriptlet_file | File containing the RPM %pre scriptlet | Label | optional | None | +| preun_scriptlet | RPM %preun scriptlet. Currently only allowed to be a shell script.

preun_scriptlet and preun_scriptlet_file are mutually exclusive. | String | optional | "" | +| preun_scriptlet_file | File containing the RPM %preun scriptlet | Label | optional | None | +| provides | List of rpm capabilities that this package provides.

Corresponds to the "Provides" preamble tag.

See also: https://rpm-software-management.github.io/rpm/manual/dependencies.html | List of strings | optional | [] | +| release | RPM "Release" tag

Exactly one of release or release_file must be provided. | String | optional | "" | +| release_file | File containing RPM "Release" tag. | Label | optional | None | +| requires | List of rpm capability expressions that this package requires.

Corresponds to the "Requires" preamble tag.

See also: https://rpm-software-management.github.io/rpm/manual/dependencies.html | List of strings | optional | [] | +| requires_contextual | Contextualized requirement specifications

This is a map of various properties (often scriptlet types) to capability name specifications, e.g.:

python             {"pre": ["GConf2"],"post": ["GConf2"], "postun": ["GConf2"]}


Which causes the below to be added to the spec file's preamble:

             Requires(pre): GConf2             Requires(post): GConf2             Requires(postun): GConf2


This is most useful for ensuring that required tools exist when scriptlets are run, although there may be other valid use cases. Valid keys for this attribute may include, but are not limited to:

- pre - post - preun - postun - pretrans - posttrans

For capabilities that are always required by packages at runtime, use the requires attribute instead.

See also: https://rpm-software-management.github.io/rpm/manual/more_dependencies.html

NOTE: pkg_rpm does not check if the keys of this dictionary are acceptable to rpm(8). | Dictionary: String -> List of strings | optional | {} | +| rpmbuild_path | Path to a rpmbuild binary. Deprecated in favor of the rpmbuild toolchain | String | optional | "" | +| source_date_epoch | Value to export as SOURCE_DATE_EPOCH to facilitate reproducible builds

Implicitly sets the %clamp_mtime_to_source_date_epoch in the subordinate call to rpmbuild to facilitate more consistent in-RPM file timestamps.

Negative values (like the default) disable this feature. | Integer | optional | -1 | +| source_date_epoch_file | File containing the SOURCE_DATE_EPOCH value.

Implicitly sets the %clamp_mtime_to_source_date_epoch in the subordinate call to rpmbuild to facilitate more consistent in-RPM file timestamps. | Label | optional | None | +| spec_template | Spec file template.

Use this if you need to add additional logic to your spec files that is not available by default.

In most cases, you should not need to override this attribute. | Label | optional | //pkg/rpm:template.spec.tpl | +| srcs | Mapping groups to include in this RPM.

These are typically brought into life as pkg_filegroups. | List of labels | required | | +| summary | RPM "Summary" tag.

One-line summary of this package. Must not contain newlines. | String | required | | +| url | RPM "URL" tag; this project/vendor's home on the Internet. | String | optional | "" | +| version | RPM "Version" tag.

Exactly one of version or version_file must be provided. | String | optional | "" | +| version_file | File containing RPM "Version" tag. | Label | optional | None | + + + + + +Rules for making .tar files. + + + +## pkg_tar + +
+pkg_tar(name, allow_duplicates_with_different_content, compressor, compressor_args, deps,
+             empty_dirs, empty_files, extension, files, include_runfiles, mode, modes, mtime, out,
+             owner, ownername, ownernames, owners, package_dir, package_dir_file, package_file_name,
+             package_variables, portable_mtime, private_stamp_detect, remap_paths, srcs, stamp,
+             strip_prefix, symlinks)
+
+ + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| allow_duplicates_with_different_content | If true, will allow you to reference multiple pkg_* which conflict (writing different content or metadata to the same destination). Such behaviour is always incorrect, but we provide a flag to support it in case old builds were accidentally doing it. Never explicitly set this to true for new code. | Boolean | optional | True | +| compressor | External tool which can compress the archive. | Label | optional | None | +| compressor_args | Arg list for compressor. | String | optional | "" | +| deps | tar files which will be unpacked and repacked into the archive. | List of labels | optional | [] | +| empty_dirs | - | List of strings | optional | [] | +| empty_files | - | List of strings | optional | [] | +| extension | - | String | optional | "tar" | +| files | Obsolete. Do not use. | Dictionary: Label -> String | optional | {} | +| include_runfiles | Include runfiles for executables. These appear as they would in bazel-bin.For example: 'path/to/myprog.runfiles/path/to/my_data.txt'. | Boolean | optional | False | +| mode | - | String | optional | "0555" | +| modes | - | Dictionary: String -> String | optional | {} | +| mtime | - | Integer | optional | -1 | +| out | - | Label | required | | +| owner | Default numeric owner.group to apply to files when not set via pkg_attributes. | String | optional | "0.0" | +| ownername | - | String | optional | "." | +| ownernames | - | Dictionary: String -> String | optional | {} | +| owners | - | Dictionary: String -> String | optional | {} | +| package_dir | Prefix to be prepend to all paths written.

This is applied as a final step, while writing to the archive. Any other attributes (e.g. symlinks) which specify a path, must do so relative to package_dir. The value may contain variables. See [package_file_name](#package_file_name) for examples. | String | optional | "" | +| package_dir_file | - | Label | optional | None | +| package_file_name | See [Common Attributes](#package_file_name) | String | optional | "" | +| package_variables | See [Common Attributes](#package_variables) | Label | optional | None | +| portable_mtime | - | Boolean | optional | True | +| private_stamp_detect | - | Boolean | optional | False | +| remap_paths | - | Dictionary: String -> String | optional | {} | +| srcs | Inputs which will become part of the tar archive. | List of labels | optional | [] | +| stamp | Enable file time stamping. Possible values:
  • stamp = 1: Use the time of the build as the modification time of each file in the archive.
  • stamp = 0: Use an "epoch" time for the modification time of each file. This gives good build result caching.
  • stamp = -1: Control the chosen modification time using the --[no]stamp flag.
    Since 0.5.0
    | Integer | optional | 0 | +| strip_prefix | (note: Use strip_prefix = "." to strip path to the package but preserve relative paths of sub directories beneath the package.) | String | optional | "" | +| symlinks | - | Dictionary: String -> String | optional | {} | + + + + + +Zip archive creation rule and associated logic. + + + +## pkg_zip + +
    +pkg_zip(name, allow_duplicates_with_different_content, compression_level, compression_type,
+             include_runfiles, mode, out, package_dir, package_file_name, package_variables,
+             private_stamp_detect, srcs, stamp, strip_prefix, timestamp)
+
    + + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| allow_duplicates_with_different_content | If true, will allow you to reference multiple pkg_* which conflict (writing different content or metadata to the same destination). Such behaviour is always incorrect, but we provide a flag to support it in case old builds were accidentally doing it. Never explicitly set this to true for new code. | Boolean | optional | True | +| compression_level | The compression level to use, 1 is the fastest, 9 gives the smallest results. 0 skips compression, depending on the method used | Integer | optional | 6 | +| compression_type | The compression to use. Note that lzma and bzip2 might not be supported by all readers. The list of compressions is the same as Python's ZipFile: https://docs.python.org/3/library/zipfile.html#zipfile.ZIP_STORED | String | optional | "deflated" | +| include_runfiles | See standard attributes. | Boolean | optional | False | +| mode | The default mode for all files in the archive. | String | optional | "0555" | +| out | output file name. Default: name + ".zip". | Label | required | | +| package_dir | Prefix to be prepend to all paths written. The name may contain variables, same as [package_file_name](#package_file_name) | String | optional | "/" | +| package_file_name | See [Common Attributes](#package_file_name) | String | optional | "" | +| package_variables | See [Common Attributes](#package_variables) | Label | optional | None | +| private_stamp_detect | - | Boolean | optional | False | +| srcs | List of files that should be included in the archive. | List of labels | optional | [] | +| stamp | Enable file time stamping. Possible values:
  • stamp = 1: Use the time of the build as the modification time of each file in the archive.
  • stamp = 0: Use an "epoch" time for the modification time of each file. This gives good build result caching.
  • stamp = -1: Control the chosen modification time using the --[no]stamp flag. | Integer | optional | 0 | +| strip_prefix | - | String | optional | "" | +| timestamp | Time stamp to place on all files in the archive, expressed as seconds since the Unix Epoch, as per RFC 3339. The default is January 01, 1980, 00:00 UTC.

    Due to limitations in the format of zip files, values before Jan 1, 1980 will be rounded up and the precision in the zip file is limited to a granularity of 2 seconds. | Integer | optional | 315532800 | + + + + + +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. + + + + +## filter_directory + +
    +filter_directory(name, excludes, outdir_name, prefix, renames, src, strip_prefix)
+
    + +Transform directories (TreeArtifacts) using pkg_filegroup-like semantics. + + Effective order of operations: + + 1) Files are `exclude`d + 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 `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. + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| excludes | Files to exclude from the output directory.

    Each element must refer to an individual file in src.

    All exclusions must be used. | List of strings | optional | [] | +| outdir_name | Name of output directory (otherwise defaults to the rule's name) | String | optional | "" | +| prefix | Prefix to add to all paths in the output directory.

    This does not include the output directory name, which will be added regardless. | String | optional | "" | +| 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. | Dictionary: String -> String | optional | {} | +| src | Directory (TreeArtifact) to process. | Label | required | | +| strip_prefix | Prefix to remove from all paths in the output directory.

    Must apply to all paths in the directory, even those rename'd. | String | optional | "" | + + + + +## pkg_filegroup + +
    +pkg_filegroup(name, prefix, srcs)
+
    + +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. + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| 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. | String | optional | "" | +| srcs | A list of packaging specifications to be grouped together. | List of labels | required | | + + + + +## pkg_files + +
    +pkg_files(name, attributes, excludes, include_runfiles, prefix, renames, srcs, strip_prefix)
+
    + +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`. `pkg_files` targets may be consumed by other `pkg_files` or + `pkg_filegroup` to build up complex layouts, or directly by top level + packaging rules such as `pkg_files`. + + 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. + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| 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. | String | optional | "{}" | +| 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. | List of labels | optional | [] | +| include_runfiles | Add runfiles for all srcs.

    The runfiles are in the paths that Bazel uses. For example, for the target //my_prog:foo, we would see files under paths like foo.runfiles/<repo name>/my_prog/<file> | Boolean | optional | False | +| 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. | String | optional | "" | +| 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 ".." | Dictionary: Label -> String | optional | {} | +| srcs | Files/Labels to include in the outputs of these rules | List of labels | required | | +| 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. | String | optional | "." | + + + + +## pkg_mkdirs + +
    +pkg_mkdirs(name, attributes, dirs)
+
    + +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. + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| 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. | String | optional | "{}" | +| 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). | List of strings | required | | + + + + +## pkg_mklink_impl + +
    +pkg_mklink_impl(name, attributes, link_name, target)
+
    + +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. + + + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| 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. | String | optional | "{}" | +| 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. | String | required | | +| 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. | String | required | | + + + + +## pkg_attributes + +
    +pkg_attributes(mode, user, group, uid, gid, kwargs)
+
    + +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", "group", "uid", or "gid" 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`). + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| mode | string: UNIXy octal permissions, as a string. | None | +| user | string: Filesystem owning user name. | None | +| group | string: Filesystem owning group name. | None | +| uid | int: Filesystem owning user id. | None | +| gid | int: Filesystem owning group id. | None | +| kwargs | any other desired attributes. | none | + +**RETURNS** + +A value usable in the "attributes" attribute in package mapping rules. + + + + +## pkg_mklink + +
    +pkg_mklink(name, link_name, target, attributes, src, kwargs)
+
    + +Create a symlink. + +Wraps [pkg_mklink_impl](#pkg_mklink_impl) + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| name | target name | none | +| link_name | the path in the package that should point to the target. | none | +| target | target path that the link should point to. | none | +| attributes | file attributes. | None | +| src | - | None | +| kwargs | - | none | + + + + +## strip_prefix.files_only + +
    +strip_prefix.files_only()
+
    + + + + + + + +## strip_prefix.from_pkg + +
    +strip_prefix.from_pkg(path)
+
    + + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| path | - | "" | + + + + +## strip_prefix.from_root + +
    +strip_prefix.from_root(path)
+
    + + + +**PARAMETERS** + + +| Name | Description | Default Value | +| :------------- | :------------- | :------------- | +| path | - | "" | + + + + + +Rules to create RPM archives. + +NOTE: this module is deprecated in favor of pkg/rpm_pfg.bzl. For more +information on the `pkg_filegroup` framework it uses, see pkg/mappings.bzl. + +pkg_rpm() depends on the existence of an rpmbuild toolchain. Many users will +find to convenient to use the one provided with their system. To enable that +toolchain add the following stanza to WORKSPACE: + + # Find rpmbuild if it exists. + load("@rules_pkg//toolchains/rpm:rpmbuild_configure.bzl", "find_system_rpmbuild") + find_system_rpmbuild(name="rules_pkg_rpmbuild") + + + + +## pkg_rpm + +
    +pkg_rpm(name, architecture, changelog, data, debug, release, release_file, rpmbuild_path,
+        source_date_epoch, source_date_epoch_file, spec_file, version, version_file)
+
    + +Legacy version + +**ATTRIBUTES** + + +| Name | Description | Type | Mandatory | Default | +| :------------- | :------------- | :------------- | :------------- | :------------- | +| name | A unique name for this target. | Name | required | | +| architecture | - | String | optional | "all" | +| changelog | - | Label | optional | None | +| data | - | List of labels | required | | +| debug | - | Boolean | optional | False | +| release | - | String | optional | "" | +| release_file | - | Label | optional | None | +| rpmbuild_path | - | String | optional | "" | +| source_date_epoch | - | Integer | optional | 0 | +| source_date_epoch_file | - | Label | optional | None | +| spec_file | - | Label | required | | +| version | - | String | optional | "" | +| version_file | - | Label | optional | None | + + + diff --git a/docs/index.md b/docs/index.md index dc50996b..b7b02591 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,6 +16,7 @@ attributes only defined in the "Legacy" documentation. You may have to consult more than one place to get a complete picture. * [Latest Snapshot at head](latest.md) +* [Version 0.10.0](0.10.0/reference.md) * [Version 0.9.1](0.9.1/reference.md) * [Version 0.8.0](0.8.0/reference.md) * [Version 0.7.0](0.7.0/reference.md)