From 884b76f273ee396ffbbb2760db27f1c99c88b502 Mon Sep 17 00:00:00 2001 From: flode Date: Thu, 31 Aug 2023 16:48:29 +0200 Subject: [PATCH 1/2] Document that package_dir also uses package_variables The pkg_zip and pkg_tar rule already support variable substitution in their package_dir parameter, it was only documented for package_variables so far. --- doc_build/common.md | 2 +- docs/latest.md | 12 +++++++----- pkg/private/tar/tar.bzl | 3 ++- pkg/private/zip/zip.bzl | 3 ++- 4 files changed, 12 insertions(+), 8 deletions(-) diff --git a/doc_build/common.md b/doc_build/common.md index d2be5edb..73edf5b3 100644 --- a/doc_build/common.md +++ b/doc_build/common.md @@ -10,7 +10,7 @@ These attributes are used in several rules within this module. | :------------- | :------------- | :-------------: | :-------------: | :------------- | | 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`. | Label | optional | None | +| 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 diff --git a/docs/latest.md b/docs/latest.md index fd92c0a2..2fc7828f 100755 --- a/docs/latest.md +++ b/docs/latest.md @@ -39,7 +39,7 @@ These attributes are used in several rules within this module. | :------------- | :------------- | :-------------: | :-------------: | :------------- | | 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`. | Label | optional | None | +| 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 @@ -290,7 +290,7 @@ pkg_tar(name, build_tar | ownername | - | String | optional | "." | | ownernames | - | Dictionary: String -> String | optional | {} | | owners | - | Dictionary: String -> String | optional | {} | -| package_dir | Prefix to be prepend to all paths written. | String | optional | "" | +| package_dir | Prefix to be prepend to all paths written. 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_dir_file | - | Label | optional | None | | package_file_name | See Common Attributes | String | optional | "" | | package_variables | See Common Attributes | Label | optional | None | @@ -313,8 +313,8 @@ Zip archive creation rule and associated logic. ## pkg_zip 
-pkg_zip(name, mode, out, package_dir, package_file_name, package_variables,
-             private_stamp_detect, srcs, stamp, strip_prefix, timestamp)
+pkg_zip(name, compression_level, compression_type, mode, out, package_dir, package_file_name,
+             package_variables, private_stamp_detect, srcs, stamp, strip_prefix, timestamp)
@@ -325,9 +325,11 @@ pkg_zip(name, mode, name | A unique name for this target. | Name | required | | +| 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" | | mode | The default mode for all files in the archive. | String | optional | "0555" | | out | output file name. Default: name + ".zip". | Label | required | | -| package_dir | The prefix to add to all all paths in the archive. | String | optional | "/" | +| package_dir | Prefix to be prepend to all paths written. 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_file_name | See Common Attributes | String | optional | "" | | package_variables | See Common Attributes | Label | optional | None | | private_stamp_detect | - | Boolean | optional | False | diff --git a/pkg/private/tar/tar.bzl b/pkg/private/tar/tar.bzl index 912163b1..58e32282 100644 --- a/pkg/private/tar/tar.bzl +++ b/pkg/private/tar/tar.bzl @@ -253,7 +253,8 @@ pkg_tar_impl = rule( doc = """(note: Use strip_prefix = "." to strip path to the package but preserve relative paths of sub directories beneath the package.)""" ), "package_dir": attr.string( - doc = """Prefix to be prepend to all paths written.""" + doc = """Prefix to be prepend to all paths written. +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).""", ), "package_dir_file": attr.label(allow_single_file = True), "deps": attr.label_list(allow_files = tar_filetype), diff --git a/pkg/private/zip/zip.bzl b/pkg/private/zip/zip.bzl index 9230de63..bea6109d 100644 --- a/pkg/private/zip/zip.bzl +++ b/pkg/private/zip/zip.bzl @@ -103,7 +103,8 @@ pkg_zip_impl = rule( default = "0555", ), "package_dir": attr.string( - doc = """The prefix to add to all all paths in the archive.""", + doc = """Prefix to be prepend to all paths written. +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).""", default = "/", ), "strip_prefix": attr.string(), From 1589a47542ca09d02d3366895adb22d7ce87e570 Mon Sep 17 00:00:00 2001 From: flode Date: Mon, 4 Sep 2023 13:08:24 +0200 Subject: [PATCH 2/2] Make Common Attributes linkable --- doc_build/common.md | 6 +++--- docs/latest.md | 24 ++++++++++++------------ pkg/private/deb/deb.bzl | 6 +++--- pkg/private/tar/tar.bzl | 6 +++--- pkg/private/zip/zip.bzl | 6 +++--- 5 files changed, 24 insertions(+), 24 deletions(-) diff --git a/doc_build/common.md b/doc_build/common.md index 73edf5b3..7933de10 100644 --- a/doc_build/common.md +++ b/doc_build/common.md @@ -8,9 +8,9 @@ These attributes are used in several rules within this module. | 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 | +| 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 diff --git a/docs/latest.md b/docs/latest.md index 2fc7828f..6d6e4a55 100755 --- a/docs/latest.md +++ b/docs/latest.md @@ -37,9 +37,9 @@ These attributes are used in several rules within this module. | 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 | +| 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 @@ -126,10 +126,10 @@ pkg_deb(name, archit | 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 | Label | required | | +| out | See [Common Attributes](#out) | Label | required | | | package | The name of the package | String | required | | -| package_file_name | See Common Attributes. Default: "{package}-{version}-{architecture}.deb | String | optional | "" | -| package_variables | See Common Attributes | Label | optional | None | +| 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 | [] | @@ -290,10 +290,10 @@ pkg_tar(name, build_tar | ownername | - | String | optional | "." | | ownernames | - | Dictionary: String -> String | optional | {} | | owners | - | Dictionary: String -> String | optional | {} | -| package_dir | Prefix to be prepend to all paths written. 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_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_dir_file | - | Label | optional | None | -| package_file_name | See Common Attributes | String | optional | "" | -| package_variables | See Common Attributes | 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 | {} | @@ -329,9 +329,9 @@ pkg_zip(name, c | 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" | | 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 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_file_name | See Common Attributes | String | optional | "" | -| package_variables | See Common Attributes | Label | optional | None | +| 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 | diff --git a/pkg/private/deb/deb.bzl b/pkg/private/deb/deb.bzl index d9b6935b..9083d08b 100644 --- a/pkg/private/deb/deb.bzl +++ b/pkg/private/deb/deb.bzl @@ -341,15 +341,15 @@ See https://www.debian.org/doc/debian-policy/ch-files.html#s-config-files.""", # Common attributes "out": attr.output( - doc = """See Common Attributes""", + doc = """See [Common Attributes](#out)""", mandatory = True ), "package_file_name": attr.string( - doc = """See Common Attributes. + doc = """See [Common Attributes](#package_file_name). Default: "{package}-{version}-{architecture}.deb""", ), "package_variables": attr.label( - doc = """See Common Attributes""", + doc = """See [Common Attributes](#package_variables)""", providers = [PackageVariablesInfo], ), diff --git a/pkg/private/tar/tar.bzl b/pkg/private/tar/tar.bzl index 58e32282..379a7010 100644 --- a/pkg/private/tar/tar.bzl +++ b/pkg/private/tar/tar.bzl @@ -254,7 +254,7 @@ pkg_tar_impl = rule( ), "package_dir": attr.string( doc = """Prefix to be prepend to all paths written. -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).""", +The name may contain variables, same as [package_file_name](#package_file_name)""", ), "package_dir_file": attr.label(allow_single_file = True), "deps": attr.label_list(allow_files = tar_filetype), @@ -279,9 +279,9 @@ The name may contain variables in the forms {var} and $(var). The values for sub # Common attributes "out": attr.output(mandatory = True), - "package_file_name": attr.string(doc = "See Common Attributes"), + "package_file_name": attr.string(doc = "See [Common Attributes](#package_file_name)"), "package_variables": attr.label( - doc = "See Common Attributes", + doc = "See [Common Attributes](#package_variables)", providers = [PackageVariablesInfo], ), "stamp": attr.int( diff --git a/pkg/private/zip/zip.bzl b/pkg/private/zip/zip.bzl index bea6109d..eb2d19cb 100644 --- a/pkg/private/zip/zip.bzl +++ b/pkg/private/zip/zip.bzl @@ -104,7 +104,7 @@ pkg_zip_impl = rule( ), "package_dir": attr.string( doc = """Prefix to be prepend to all paths written. -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).""", +The name may contain variables, same as [package_file_name](#package_file_name)""", default = "/", ), "strip_prefix": attr.string(), @@ -134,9 +134,9 @@ The list of compressions is the same as Python's ZipFile: https://docs.python.or doc = """output file name. Default: name + ".zip".""", mandatory = True, ), - "package_file_name": attr.string(doc = "See Common Attributes"), + "package_file_name": attr.string(doc = "See [Common Attributes](#package_file_name)"), "package_variables": attr.label( - doc = "See Common Attributes", + doc = "See [Common Attributes](#package_variables)", providers = [PackageVariablesInfo], ), "stamp": attr.int(