Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Document how to ship pre-built tools #117

Merged
merged 2 commits into from
May 7, 2024
Merged

docs: Document how to ship pre-built tools #117

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
63c958c
docs: Document how to ship pre-built tools
alexeagle May 2, 2024
89bb1d5
Update README.md
alexeagle May 6, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Copy this template to create a Bazel ruleset.

Features:

- follows the official style guide at https://docs.bazel.build/versions/main/skylark/deploying.html
- follows the official style guide at https://bazel.build/rules/deploying
- allows for both WORKSPACE.bazel and bzlmod (MODULE.bazel) usage
- includes Bazel formatting as a pre-commit hook (using [buildifier])
- includes stardoc API documentation generator
Expand All @@ -13,10 +13,6 @@ Features:
- release using GitHub Actions just by pushing a tag
- the release artifact doesn't need to be built by Bazel, but can still exclude files and stamp the version

See https://docs.bazel.build/versions/main/skylark/deploying.html#readme

[buildifier]: https://github.com/bazelbuild/buildtools/tree/master/buildifier#readme

Ready to get started? Copy this repo, then

1. search for "com_myorg_rules_mylang" and replace with the name you'll use for your workspace
Expand All @@ -28,6 +24,12 @@ Ready to get started? Copy this repo, then
1. (optional) install the [Renovate app](https://github.com/apps/renovate) to get auto-PRs to keep the dependencies up-to-date.
1. delete this section of the README (everything up to the SNIP).

Optional: if you write tools for your rules to call, you should avoid toolchain dependencies for those tools leaking to all users.
For example, https://github.com/aspect-build/rules_py actions rely on a couple of binaries written in Rust, but we don't want users to be forced to
fetch a working Rust toolchain. Instead we want to ship pre-built binaries on our GH releases, and the ruleset fetches these as toolchains.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add that there should always be an option for users to override pre-built binaries.
Pre-built binaries will not necessarily work on all platforms that a user cares about. E.g. on Linux pre-built binaries often end up being dynamically linked, meaning they likely won't work on NixOS due to mismatching loader paths, and linking against libc with some specific version constraints that might not work on the user's distribution.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, it's implied by the toolchain registration mechanism that end users could always register a matching toolchain first that points to a target that's built from source. I wonder if that requires a longer example in some documentation

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a sentence about it - could you approve if this looks good now pls?

See https://blog.aspect.build/releasing-bazel-rulesets-rust for information on how to do this.
Note that users who *do* want to build tools from source should still be able to do so, they just need to register a different toolchain earlier.

---- SNIP ----

# Bazel rules for mylang
Expand Down