bazel
/
bazel-lib
mirror of https://github.com/bazel-contrib/bazel-lib
2
0
Fork 0
Code Issues Releases Activity

chore: improve docs about mtree mutation (#692)

This commit is contained in:
Alex Eagle 2023-12-13 15:03:32 -08:00 committed by GitHub
parent d2638fe295
commit f65019be4e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 113 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
docs/tar.md generated
View File

@ -15,8 +15,39 @@ this:
We also provide full control for tar'ring binaries including their runfiles.
## Modifying metadata
The `mtree_spec` rule can be used to create an mtree manifest for the tar file.
Then you can mutate that spec, as it's just a simple text file, and feed the result
as the `mtree` attribute of the `tar` rule.
For example, to set the `uid` property, you could:
```starlark
mtree_spec(
name = "mtree",
srcs = ["//some:files"],
)
genrule(
name = "change_owner",
srcs = ["mtree"],
outs = ["mtree.mutated"],
cmd = "sed 's/uid=0/uid=1000/' <$< >$@",
)
tar(
name = "tar",
srcs = ["//some:files"],
mtree = "change_owner",
)
```
Note: We intend to contribute mutation features to https://github.com/vbatts/go-mtree
to provide a richer API for things like `strip_prefix`.
In the meantime, see the `lib/tests/tar/BUILD.bazel` file in this repo for examples.
TODO:
- Ensure we are reproducible, see https://reproducible-builds.org/docs/archives/
- Provide convenience for rules_pkg users to re-use or replace pkg_files trees
@ -83,9 +114,9 @@ Because BSD tar doesn't have a flag to set modification times to a constant,
we must always supply an mtree input to get reproducible builds.
See https://reproducible-builds.org/docs/archives/ for more explanation.
1. By default, mtree is "auto" which causes the macro to create an `mtree` rule.
1. By default, mtree is "auto" which causes the macro to create an `mtree_spec` rule.
2. `mtree` may also be supplied as an array literal of lines, e.g.
2. `mtree` may be supplied as an array literal of lines, e.g.
```
mtree =[

37
lib/tar.bzl
View File

@ -13,8 +13,39 @@ this:
We also provide full control for tar'ring binaries including their runfiles.
## Modifying metadata
The `mtree_spec` rule can be used to create an mtree manifest for the tar file.
Then you can mutate that spec, as it's just a simple text file, and feed the result
as the `mtree` attribute of the `tar` rule.
For example, to set the `uid` property, you could:
```starlark
mtree_spec(
name = "mtree",
srcs = ["//some:files"],
)
genrule(
name = "change_owner",
srcs = ["mtree"],
outs = ["mtree.mutated"],
cmd = "sed 's/uid=0/uid=1000/' <$< >$@",
)
tar(
name = "tar",
srcs = ["//some:files"],
mtree = "change_owner",
)
```
Note: We intend to contribute mutation features to https://github.com/vbatts/go-mtree
to provide a richer API for things like `strip_prefix`.
In the meantime, see the `lib/tests/tar/BUILD.bazel` file in this repo for examples.
TODO:
- Ensure we are reproducible, see https://reproducible-builds.org/docs/archives/
- Provide convenience for rules_pkg users to re-use or replace pkg_files trees
"""
@ -44,9 +75,9 @@ def tar(name, mtree = "auto", **kwargs):
we must always supply an mtree input to get reproducible builds.
See https://reproducible-builds.org/docs/archives/ for more explanation.
1. By default, mtree is "auto" which causes the macro to create an `mtree` rule.
1. By default, mtree is "auto" which causes the macro to create an `mtree_spec` rule.
2. `mtree` may also be supplied as an array literal of lines, e.g.
2. `mtree` may be supplied as an array literal of lines, e.g.
```
mtree =[

48
lib/tests/tar/BUILD.bazel
View File

@ -123,9 +123,8 @@ mtree_spec(
srcs = _SRCS5,
)
# This is a very simple way to mutate the mtree specification, just using regex.
# In theory, this can be used for arbitrary replacements like using mode=644 or something,
# but we'll probably have to add a richer API to the mtree_spec rule to make this more ergonomic.
# This is a low-tech way to mutate the mtree specification, just using regex.
# See docs on tar about future directions for mtree mutation
genrule(
name = "strip_prefix",
srcs = ["mtree5"],
@ -245,3 +244,46 @@ assert_tar_listing(
"-rwxr-xr-x 0 0 0 0 Jan 1 2023 lib/tests/tar/treeartifact/pkg",
],
)
# Case 8: setting owner of files
_SRCS8 = [
":fixture1",
"src_file",
]
mtree_spec(
name = "mtree8",
srcs = _SRCS8,
)
# This is a very simple way to mutate the mtree specification, just using regex.
# See docs on tar about future directions for mtree mutation
genrule(
name = "change_owner",
srcs = ["mtree8"],
outs = ["mtree8.mutated"],
# Modify uid and gid, e.g.
# lib/tests/tar/a uid=0 gid=0 time=1672560000 mode=0755 type=file content=bazel-out/darwin_arm64-opt/bin/lib/tests/tar/a
# ->
# lib/tests/tar/a uid=1000 gid=500 time=1672560000 mode=0755 type=file content=bazel-out/darwin_arm64-opt/bin/lib/tests/tar/a
cmd = "sed 's/uid=0/uid=1000/;s/gid=0/gid=500/' <$< >$@",
)
tar(
name = "tar_change_owner",
srcs = _SRCS8,
out = "8.tar",
mtree = "change_owner",
)
assert_tar_listing(
name = "test_change_owner",
actual = "tar_change_owner",
expected = [
"drwxr-xr-x 0 1000 500 0 Jan 1 2023 lib/",
"drwxr-xr-x 0 1000 500 0 Jan 1 2023 lib/tests/",
"drwxr-xr-x 0 1000 500 0 Jan 1 2023 lib/tests/tar/",
"-rwxr-xr-x 0 1000 500 7 Jan 1 2023 lib/tests/tar/a",
"-rwxr-xr-x 0 1000 500 21 Jan 1 2023 lib/tests/tar/src_file",
],
)