From 23088e70e382764a54ed35cd62cb7f0bab99b74e Mon Sep 17 00:00:00 2001 From: Owen Jacobson Date: Tue, 7 Feb 2023 15:15:51 -0500 Subject: Expand on tools/ convention a bit based on experiences --- docs/code/tools-convention.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) (limited to 'docs/code') diff --git a/docs/code/tools-convention.md b/docs/code/tools-convention.md index ccb3d91..4d1175e 100644 --- a/docs/code/tools-convention.md +++ b/docs/code/tools-convention.md @@ -42,7 +42,7 @@ These scripts follow a few principles to ensure that they remain manageable: ## tools/example ## tools/example FILENAME ## - ## Runs the examples. If FILENAME is provided, then only the + ## Runs the examples. If FILENAME is provided, then only the ## example in FILENAME will actually be executed. * Minimize the use of arguments. Ideally, use only either no arguments, one argument, or an arbitrary number of arguments. Under no circumstances use options or flags. @@ -53,6 +53,8 @@ These scripts follow a few principles to ensure that they remain manageable: More generally, the intention is to encapsulate the commands needed to perform routine tasks, not to be complex software in their own right. +If you're using a project-specific shell environment (with [`direnv`](https://direnv.net) or similar), add `tools` to your `PATH` so that you can run tool scripts from anywhere in the project. Being able to type `build` and have the project build, regardless of where you're looking at that moment, is very helpful. For `direnv`'s `.envrc` this can be done using `PATH_add tools`. + ## Tradeoffs No approach is perfect, and this approach has its own consequences: @@ -61,6 +63,10 @@ No approach is perfect, and this approach has its own consequences: * There's always the temptation to Add Features to tools scripts, and it takes steady effort and careful judgment as to how to do so while hewing to the goals of the approach. For example, with Docker, I've had situations where I end up with two tools with nearly-identical Docker command lines (and thus code duplication to maintain) because I preferred to avoid adding an optional debug mode to an existing tools script. +* If you're not using `direnv`, the tools directory is only easily available to your shell if your `pwd` is the project root. This is awkward, and `sh` derivatives don't provide any convenient way to "search upwards" for commands. + +* Tool scripts need to take care to set their own `pwd` appropriately, which can take some thinking. What directory is appropriate depends on what the tool script needs to accomplish, so the right answer isn't always obvious. A convention of "always cd to the project root" covers most cases, but there are exceptions where the user's `pwd` or some other directory may be more appropriate. + ## Examples This site is built using two tools. `tools/build`: @@ -157,3 +163,11 @@ VERSION="$(detect-version)" py.test \ --image-version "${VERSION}" ``` + +## Alternatives + +* NAME's [`just`](https://github.com/casey/just) stores shell snippets in a project-wide `Justfile`. + + This allows for reliable generation of project-specific help and usage information from the `Justfile` and allows `just foo` to work from any directory in the project without project-specific shell configuration. + + On the other hand, it's another tool developers would need to install to get started on a project. `Justfile` entries can't be run without `just` (a problem `make` also has). -- cgit v1.2.3