Document how to run tools on the command line

readme.md

@@ -60,3 +60,30 @@ Tools may then be accessed using `@multitool//tools/tool-name`.
 ### Workspace Usage
 
 Instructions for using with WORKSPACE may be found in [release notes](https://github.com/theoremlp/rules_multitool/releases).
+
+### Creating convenience scripts
+
+When users need to execute tools directly, Bazel does not provide very good support for this,
+because it sets the working directory to the root of the runfiles tree, which breaks the ability of the tool to resolve configuration files and other relative paths.
+
+The typical workarounds are all bad:
+
+1. Change all paths the tool interacts with to be absolute, so that the working directory is inconsequential.
+2. Wrap the tool in a trivial `sh_binary` that can read `$BUILD_WORKING_DIRECTORY`.
+3. Use `--run_under="cd $PWD &&` however this [discards the analysis cache] slowing down this and the subsequent build.
+
+Instead, the authors recommend the following technique. Create a script like `tools/_multitool_run_under_cwd.sh` containing the following shell code:
+
+```sh
+#!/bin/bash
+# Workaround https://github.com/bazelbuild/bazel/issues/3325
+target="@multitool//tools/$(basename "$0")"
+bazel build "$target" && exec $(bazel 2>/dev/null cquery --output=files "$target") "$@"
+```
+
+Now just create symlinks such as `tools/mytool -> ./_multitool_run_under_cwd.sh`.
+This will build `@multitool//tools/mytool` and then execute the resulting binary in the current working directory.
+
+Developers can now just naively run `./tools/mytool --arg my/file` and don't need to worry about where the tool comes from.
+
+[discards the analysis cache]: https://github.com/bazelbuild/bazel/issues/10782