README.md
Bazel helpers library
Base Starlark libraries and basic Bazel rules which are useful for constructing rulesets and BUILD files.
This module depends on bazel-skylib. In theory all these utilities could be upstreamed to bazel-skylib, but the declared scope of that project is narrow and it's very difficult to get anyone's attention to review PRs there.
Installation
Installation instructions are included on each release: https://github.com/bazel-contrib/bazel-lib/releases
To use a commit rather than a release, you can point at any SHA of the repo.
For example to use commit abc123
:
- Replace
url = "https://github.com/bazel-contrib/bazel-lib/releases/download/v0.1.0/bazel-lib-v0.1.0.tar.gz"
with a GitHub-provided source archive likeurl = "https://github.com/bazel-contrib/bazel-lib/archive/abc123.tar.gz"
- Replace
strip_prefix = "bazel-lib-0.1.0"
withstrip_prefix = "bazel-lib-abc123"
- Update the
sha256
. The easiest way to do this is to comment out the line, then Bazel will print a message with the correct value.
Note that GitHub source archives don't have a strong guarantee on the sha256 stability, see https://github.blog/2023-02-21-update-on-the-future-stability-of-source-code-archives-and-hashes
Public API
Packaging
- tar Run BSD
tar
to produce archives.
Copying files
- copy_directory Copies directories to another package.
- copy_file Copies files to another package.
- copy_to_bin Copies a source file to output tree at the same workspace-relative path.
- copy_to_directory Copies and arranges files and directories into a new directory.
- write_source_files Write to one or more files or folders in the source tree. Stamp out tests that ensure the sources exist and are up to date.
Transforming files
- jq A toolchain and custom rule for running jq, a tool that is "like sed for json".
- yq A toolchain and custom rule for running yq, a "YAML, JSON and XML processor".
Manipulating paths
- directory_path Provide a label to reference some path within a directory, via DirectoryPathInfo.
- output_files Forwards a subset of the files (via the DefaultInfo provider) from a given target's DefaultInfo or OutputGroupInfo.
Writing rules
- expand_make_vars Perform make variable and location substitutions in strings..
- expand_template Substitute templates with make variables, location resolves, stamp variables, and arbitrary strings.
- paths Useful path resolution methods.
- transitions Transition sources to a provided platform.
- lists Functional-style helpers for working with list data structures.
- utils Various utils for labels and globs.
- params_file Generate encoded params file from a list of arguments.
- repo_utils Useful methods for repository rule implementations.
- run_binary Like skylib's run_binary but adds directory output support.
- stamping Support version stamping in custom rules.
- base64 Starlark Base64 encoder & decoder.
Testing
- bats_test: A test runner for the Bash Automated Testing System.
Generating documentation
- docs Rules for generating docs and stamping tests to ensure they are up to date.