From 8a09cfe752d621b399ab28ac6b198a26d0df9712 Mon Sep 17 00:00:00 2001 From: Collin Donahue-Oponski Date: Thu, 6 Jul 2023 13:57:32 -0600 Subject: [PATCH] Update README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Is this right? As someone told by a different repo that "you need bazel", and then told by the bazel docs that "you need bazelisk" — without any context other than that bazelisk will install bezel for me — I had no idea what bazelisk is or how it's meant to be used. Adding this section to the Readme would have helped me, even if it sounds terribly obvious to you. --- README.md | 24 ++++++++++++++++++++---- 1 file changed, 20 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 35d46226..bd8f952e 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,26 @@ Frontend developers may want to install it with `npm install -g @bazel/bazelisk` > You will notice that it serves an analogous function for Bazel as the > [`nvm` utility](https://github.com/nvm-sh/nvm) which manages your version of Node.js. +Before Bazelisk was rewritten in Go, it was a Python script. +This still works and has the advantage that you can run it on any platform that has a Python interpreter, but is currently unmaintained and it doesn't support as many features. +The documentation below describes the newer Go version only. + +## Usage + +Run any `bazel` command using `bazelisk` in place of running `bazel`, e.g. + +``` +$ bazelisk help + [bazel release x.x.x] +Usage: bazel ... + +Available commands: + analyze-profile Analyzes build profile data. + aquery Analyzes the given targets and queries the action graph. + build Builds the specified targets. + ... +``` + Some ideas how to use it: - Install it as the `bazel` binary in your `PATH` (e.g. copy it to `/usr/local/bin/bazel`). Never worry about upgrading Bazel to the latest version again. @@ -35,10 +55,6 @@ Some ideas how to use it: If you install Bazelisk as `bazel` on your CI machines, too, you can even test Bazel upgrades via a normal presubmit / pull request. It will also ensure that users will not try to build your project with an incompatible version of Bazel, which is often a cause for frustration and failing builds. (But see the note below about ensuring your developers install Bazelisk.) -Before Bazelisk was rewritten in Go, it was a Python script. -This still works and has the advantage that you can run it on any platform that has a Python interpreter, but is currently unmaintained and it doesn't support as many features. -The documentation below describes the newer Go version only. - ## How does Bazelisk know which Bazel version to run? It uses a simple algorithm: