chore: add docs
diff --git a/docs/tar.md b/docs/tar.md index 6697b44..b43193e 100644 --- a/docs/tar.md +++ b/docs/tar.md
@@ -1,16 +1,28 @@ <!-- Generated with Stardoc: http://skydoc.bazel.build --> -Wrapper to execute BSD tar +General-purpose rule to create tar archives. + +Unlike [pkg_tar from rules_pkg](https://github.com/bazelbuild/rules_pkg/blob/main/docs/latest.md#pkg_tar) +this: + +- Does not depend on any Python interpreter setup +- Does not have any custom program to produce the output, instead + we rely on a well-known C++ program called "tar". + Specifically, we use the BSD variant of tar since it provides a means + of controlling mtimes, uid, symlinks, etc. + +We also provide full control for tar'ring binaries including their runfiles. + <a id="tar_rule"></a> ## tar_rule <pre> -tar_rule(<a href="#tar_rule-name">name</a>, <a href="#tar_rule-mtree">mtree</a>, <a href="#tar_rule-out">out</a>, <a href="#tar_rule-srcs">srcs</a>) +tar_rule(<a href="#tar_rule-name">name</a>, <a href="#tar_rule-compress">compress</a>, <a href="#tar_rule-mtree">mtree</a>, <a href="#tar_rule-out">out</a>, <a href="#tar_rule-srcs">srcs</a>) </pre> - +Rule that executes BSD `tar`. Most users should use the [`tar`](#tar) macro, rather than load this directly. **ATTRIBUTES** @@ -18,6 +30,7 @@ | Name | Description | Type | Mandatory | Default | | :------------- | :------------- | :------------- | :------------- | :------------- | | <a id="tar_rule-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | | +| <a id="tar_rule-compress"></a>compress | Compress the archive file with a supported algorithm. | String | optional | "" | | <a id="tar_rule-mtree"></a>mtree | An mtree specification file | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | None | | <a id="tar_rule-out"></a>out | Resulting tar file to write | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | optional | | | <a id="tar_rule-srcs"></a>srcs | Files that are placed into the tar | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | required | | @@ -28,9 +41,22 @@ ## tar <pre> -tar(<a href="#tar-name">name</a>, <a href="#tar-out">out</a>, <a href="#tar-kwargs">kwargs</a>) +tar(<a href="#tar-name">name</a>, <a href="#tar-mtree">mtree</a>, <a href="#tar-kwargs">kwargs</a>) </pre> +Wrapper macro around [`tar_rule`](#tar_rule). + +Allows the mtree to be supplied as an array literal of lines, in addition to a separate file, e.g. + +``` +mtree =[ + "usr/bin uid=0 gid=0 mode=0755 type=dir", + "usr/bin/ls uid=0 gid=0 mode=0755 time=0 type=file content={}/a".format(package_name()), +], +``` + +For the format of a line, see "There are four types of lines in a specification" on the man page for BSD mtree, +https://man.freebsd.org/cgi/man.cgi?mtree(8) **PARAMETERS** @@ -38,8 +64,8 @@ | Name | Description | Default Value | | :------------- | :------------- | :------------- | -| <a id="tar-name"></a>name | <p align="center"> - </p> | none | -| <a id="tar-out"></a>out | <p align="center"> - </p> | <code>None</code> | -| <a id="tar-kwargs"></a>kwargs | <p align="center"> - </p> | none | +| <a id="tar-name"></a>name | name of resulting <code>tar_rule</code> | none | +| <a id="tar-mtree"></a>mtree | either an array of specification lines, or a label of a file that contains the lines. | <code>None</code> | +| <a id="tar-kwargs"></a>kwargs | additional named parameters to pass to <code>tar_rule</code> | none |
diff --git a/lib/BUILD.bazel b/lib/BUILD.bazel index 64e8541..a1e177d 100644 --- a/lib/BUILD.bazel +++ b/lib/BUILD.bazel
@@ -108,7 +108,11 @@ bzl_library( name = "tar", srcs = ["tar.bzl"], - deps = ["//lib/private/docs:tar"], + deps = [ + "//lib/private/docs:tar", + "@bazel_skylib//lib:types", + "@bazel_skylib//rules:write_file", + ], ) bzl_library(
diff --git a/lib/tar.bzl b/lib/tar.bzl index c807a40..ab3175a 100644 --- a/lib/tar.bzl +++ b/lib/tar.bzl
@@ -1,18 +1,48 @@ -"Wrapper to execute BSD tar" +"""General-purpose rule to create tar archives. + +Unlike [pkg_tar from rules_pkg](https://github.com/bazelbuild/rules_pkg/blob/main/docs/latest.md#pkg_tar) +this: + +- Does not depend on any Python interpreter setup +- Does not have any custom program to produce the output, instead + we rely on a well-known C++ program called "tar". + Specifically, we use the BSD variant of tar since it provides a means + of controlling mtimes, uid, symlinks, etc. + +We also provide full control for tar'ring binaries including their runfiles. +""" load("@bazel_skylib//lib:types.bzl", "types") load("@bazel_skylib//rules:write_file.bzl", "write_file") load("//lib/private:tar.bzl", _tar_lib = "tar_lib") tar_rule = rule( + doc = "Rule that executes BSD `tar`. Most users should use the [`tar`](#tar) macro, rather than load this directly.", implementation = _tar_lib.implementation, attrs = _tar_lib.attrs, toolchains = ["@aspect_bazel_lib//lib:tar_toolchain_type"], ) -# FIXME: needs docs -# buildifier: disable=function-docstring def tar(name, mtree = None, **kwargs): + """Wrapper macro around [`tar_rule`](#tar_rule). + + Allows the mtree to be supplied as an array literal of lines, in addition to a separate file, e.g. + + ``` + mtree =[ + "usr/bin uid=0 gid=0 mode=0755 type=dir", + "usr/bin/ls uid=0 gid=0 mode=0755 time=0 type=file content={}/a".format(package_name()), + ], + ``` + + For the format of a line, see "There are four types of lines in a specification" on the man page for BSD mtree, + https://man.freebsd.org/cgi/man.cgi?mtree(8) + + Args: + name: name of resulting `tar_rule` + mtree: either an array of specification lines, or a label of a file that contains the lines. + **kwargs: additional named parameters to pass to `tar_rule` + """ if types.is_list(mtree): write_target = "_{}.mtree".format(name) write_file(