* perf: report unused inputs for the tar rule
The `mtree` spec passed to the `tar` rule very often selects a subset of the
inputs made available through the `srcs` attribute. In many cases, these
subsets do not break down cleanly along dependency-tree lines and there
is no simple way just pass less content to the `tar` rule.
One prominent example where this occurs is when constructing the tars
for OCI image layers. For instance when [building a Python-based
container image](https://github.com/bazel-contrib/rules_oci/blob/main/docs/python.md),
we might want to split the Python interpreter, third-party dependencies, and
application code into their own layers. This is done by [filtering the
`mtree_spec`](85cb2aaf8c/oci_python_image/py_layer.bzl (L39)).
However, in the operation to construct a `tar` from a subsetted mtree,
it is usually still an unsubsetted tree of `srcs` that gets passed. As
a result, the subset tarball is considered dependent upon a larger set
of sources than is strictly necessary.
This over-scoping runs counter to a very common objective associated with
breaking up an image into layers - isolating churn to a smaller slice of
the application. Because of the spurious relationships established in
Bazel's dependency graph, all tars get rebuilt anytime any content in
the application gets changed. Tar rebuilds can even be triggered by
changes to files that are completely filtered-out from all layers of the container.
Redundent creation of archive content is usually not too computationally
intensive, but the archives can be quite large in some cases, and
avoiding a rebuild might free up gigabytes of disk and/or network
bandwidth for
better use. In addition, eliminating the spurious dependency edges
removes erroneous constraints applied to the build action schedule;
these tend to push all Tar-building operations towards the end of a
build, even when some archive construction could be scheduled much earlier.
## Risk assessment and mitigation
The `unused_inputs_list` mechanism used to report spurious dependency
relationships is a bit difficult to use. Reporting an actually-used
input as unused can create difficult to diagnose problems down the line.
However, the behaviour of the `mtree`-based `tar` rule is sufficiently
simple and self-contained that I am fairly confident that this rule's
used/unused set can be determined accurately in a maintainable fashion.
Out of an abundance of caution I have gated this feature behind a
default-off flag. The `tar` rule will continue to operate as it had
before - typically over-reporting dependencies - unless the
`--@aspect_bazel_lib//lib:tar_compute_unused_inputs` flag is passed.
### Filter accuracy
The `vis` encoding used by the `mtree` format to resiliently handle path
names has a small amount of "play" to it - it is reversable but the
encoded representation of a string is not
unique. Two unequal encoded strings might decode to the same value; this
can happen when at least one of the encoded strings contains unnecessary
escapes that are nevertheless honoured by the decoder.
The unused-inputs set is determined using a filter that compares
`vis`-encoded strings. In the presence of non-canonically-encoded
paths, false-mismatches can lead to falsely reporting that an input is
unused.
The only `vis`-encoded path content that is under the control of callers
is the `mtree` content itself; all other `vis`-encoded strings are
constructed internally to this package, not exposed publicly, and are
all derived using the `lib/private/tar.bzl%_vis_encode` function; all of
these paths are expected to compare exactly. Additionally, it is expected that
many/most users will use this package's helpers (e.g. `mtree_spec`) when
crafting their mtree content; such content is also safe. It is only when
the user crafts their own mtree, or modifies an mtree spec's `content=`
fields' encoding in some way, that a risk of inaccurate reporting
arises. The chances for this are expected to be minor since this seems
like an inconvenient and not-particularly-useful thing for a user to go
out of their way to do.
* Also include other bsdtar toolchain files in keep set
* Add tri-state attribute to control unused-inputs behaviour
This control surface provides for granular control of the feature. The
interface is selected to mirror the common behaviour of `stamp` attributes.
* Add bzl_library level dep
* Update docs
* pre-commit
* Add reminder to change flag default on major-version bump
* Add note about how to make unused input computation exactly correct
* Add a test for unused_inputs listing
* Support alternate contents= form
This is accepted by bsdtar/libarchive. In fact `contents=` is the only of
the pair documented in `mtree(5)`; `content=` is an undocumented
alternate form supported by libarchive.
* Don't try to prune the unprunable
Bazel's interpretation of unused_inputs_list cannot accomodate certain
things in filenames. These are also likely to mess up our own
line-oriented protocol in the shellscript that produces this file.
Co-authored-by: Sahin Yort <thesayyn@gmail.com>
* Rerun docs update
---------
Co-authored-by: Sahin Yort <thesayyn@gmail.com>
* feat: support bzlmod repo name aliases in tarred runfiles
Under bzlmod, repos have aliases in addition to their canonical names;
in order for lookups using these canonical names to function properly,
a file name `_repo_mapping` is located in the root of the runfiles tree
and consulted to perform repo-name translation.
See: https://github.com/bazelbuild/proposals/blob/main/designs/2022-07-21-locating-runfiles-with-bzlmod.md
* pre-commit formatting
* Enable runfiles test under bzlmod
It works now.
* feat: add an option to not include copy_to_directory output in runfiles
* chore: docs update
* chore: don't repeat default
---------
Co-authored-by: Alex Eagle <alex@aspect.dev>
* Fix: Moving the preserve mtiem test logic to Go for portability
* add tags to disable remote caching, execution and force the test to always re-run
* include docs
* use the runfiles library for windows compatability
* mark the test as manual
* remove duplicate word in comment
* chore: reduce duplication of the long caveats text
---------
Co-authored-by: Alex Eagle <alex@aspect.dev>
* chore(deps): update coreutils to v0.0.27
This release has an `aarch64-apple-darwin` binary, eliminating the need
for a `version_override` hack to support that platform.
* chore: restore previous coreutils
Users should be able to pin and not have us break them
---------
Co-authored-by: Alex Eagle <alex@aspect.dev>
* chore: green up CI on main branch
We landed a test that broke the macos/windows builds, let's just disable it there
* chore: mark it flaky
* Update MODULE.bazel
* chore: turn off bzlmod misguided warning
These are misinformed, the module resolver should be permitted to find an MVS solution
* chore: update golden
* fix(docs): description of jq example didn't match behavior
I think this was wrong? Wish our examples were also executable...
---------
Co-authored-by: Derek Cormier <derek@aspect.dev>
Commit 3c121a9cd9 broke E2E tests with the
following error:
```
(23:31:56) ERROR: no such package '@@[unknown repo 'org_golang_x_sys' requested from @@aspect_bazel_lib~]//unix': The repository '@@[unknown repo 'org_golang_x_sys' requested from @@aspect_bazel_lib~]' could not be resolved: No repository visible as '@org_golang_x_sys' from repository '@@aspect_bazel_lib~'
```
The build worked when operating within the `aspect_bazel_lib` repo
itself, but not when importing it with Bzlmod. This is because the
`org_golang_x_sys` repo is imported indirectly by `rules_go`'s
`go_rules_dependencies` macro in the `WORKSPACE` file, which is still
active under bzlmod because there is no `WORKSPACE.bzlmod` file to
suppress it.
* perf: use darwin's clonefile syscall
This saves time and disk-space when copying files around on the same
device. File clones (aka reflinks) share backing disk blocks; they
differ from hardlinks in that inodes are not shared and the contents are
copy-on-write.
The Go standard library (as of v1.22) arranges to do a similar thing for file
copies on Linux (see: https://cs.opensource.google/go/go/+/refs/tags/go1.22.6:src/os/zero_copy_linux.go;l=53).
Unfortunately, Mac OS' more limited API is less amenable to that form of
transparent wrapping.
* Assign to named return params and use naked returns
* chore(deps): upgrade stardoc
This uses the Bazel 7 'starlark_doc_extract' rule which our docsite expects for slurping data.
* chore: stardoc setup in WORKSPACE too
* chore: skip stardoc on bazel 6 in cases where the legacy extractor produces different docstrings
renovate[bot]