From 7bbc38a2619ba88a1438dedf3fbd0d48e5b0bb7b Mon Sep 17 00:00:00 2001 From: Matias Kinnunen Date: Wed, 21 Jul 2021 03:49:20 +0300 Subject: [PATCH] Improve readme (#904) --- README.adoc | 96 ++++++++++++++++++++++++++--------------------------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/README.adoc b/README.adoc index 06c5ee4..1304eea 100644 --- a/README.adoc +++ b/README.adoc @@ -25,10 +25,10 @@ cc *.c -o main Yay, all your tests passed! ``` -Just has a ton of useful features, and many improvements over Make: +`just` has a ton of useful features, and many improvements over `make`: -- Just is a command runner, not a build system, so it avoids much of - link:https://github.com/casey/just#what-are-the-idiosyncrasies-of-make-that-just-avoids[Make's +- `just` is a command runner, not a build system, so it avoids much of + link:https://github.com/casey/just#what-are-the-idiosyncrasies-of-make-that-just-avoids[`make`'s complexity and idiosyncrasies]. No need for `.PHONY` recipes! - Linux, MacOS, and Windows are supported with no additional dependencies. (Although if your system doesn't have an `sh`, you'll need to link:https://github.com/casey/just#shell[choose a different shell].) @@ -41,7 +41,7 @@ Just has a ton of useful features, and many improvements over Make: - Wherever possible, errors are resolved statically. Unknown recipes and circular dependencies are reported before anything runs. -- Just link:https://github.com/casey/just#dotenv-integration[loads `.env` +- `just` link:https://github.com/casey/just#dotenv-integration[loads `.env` files], making it easy to populate environment variables. - Recipes can be @@ -56,11 +56,11 @@ Just has a ton of useful features, and many improvements over Make: link:https://github.com/casey/just#writing-recipes-in-other-languages[arbitrary languages], like Python or NodeJS. -- `just` can be invoked from any subdirectory, not just the directory that contains the `Justfile`. +- `just` can be invoked from any subdirectory, not just the directory that contains the `justfile`. - And link:https://github.com/casey/just#manual[much more]! -If you need help with `just` please feel free to open an issue or ping me on link:https://discord.gg/ezYScXR[discord]. Feature requests and bug reports are always welcome! +If you need help with `just` please feel free to open an issue or ping me on link:https://discord.gg/ezYScXR[Discord]. Feature requests and bug reports are always welcome! [discrete] == Manual @@ -73,15 +73,15 @@ toc::[] `just` should run on any system with a reasonable `sh`, including Linux, MacOS, and the BSDs. -On Windows, `just` works with the `sh` provided by https://git-scm.com[Git for Windows], https://desktop.github.com[GitHub Desktop], and http://www.cygwin.com[Cygwin]. +On Windows, `just` works with the `sh` provided by https://git-scm.com[Git for Windows], https://desktop.github.com[GitHub Desktop], or http://www.cygwin.com[Cygwin]. If you'd rather not install `sh`, you can use the `shell` setting to use the shell of your choice. -Like Powershell: +Like PowerShell: ```make -# use Powershell instead of sh: +# use PowerShell instead of sh: set shell := ["powershell.exe", "-c"] hello: @@ -99,7 +99,7 @@ list: dir ``` -(Powershell is installed by default on Windows 7 SP1 and Windows Server 2008 R2 S1 and later, and `cmd.exe` is quite fiddly, so Powershell is recommended for most Windows users.) +(PowerShell is installed by default on Windows 7 SP1 and Windows Server 2008 R2 S1 and later, and `cmd.exe` is quite fiddly, so PowerShell is recommended for most Windows users.) === Packages @@ -120,7 +120,7 @@ list: |================================================================================================================================================================================================================================================================================================================================================================= -=== Pre-built Binaries +=== Pre-Built Binaries Pre-built binaries for Linux, MacOS, and Windows can be found on https://github.com/casey/just/releases[the releases page]. @@ -132,7 +132,7 @@ curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s - == Editor Support -`justfile` syntax is close enough to `make` that you may want to tell your editor to use make syntax highlighting for just. +`justfile` syntax is close enough to `make` that you may want to tell your editor to use `make` syntax highlighting for `just`. === Vim @@ -162,7 +162,7 @@ git clone https://github.com/NoahTheDuke/vim-just.git ==== Makefile Syntax Highlighting -Vim's built-in Makefile syntax highlighting isn't perfect for justfiles, but it's better than nothing. You can put the following in `~/.vim/filetype.vim`: +Vim's built-in makefile syntax highlighting isn't perfect for justfiles, but it's better than nothing. You can put the following in `~/.vim/filetype.vim`: ```vimscript if exists("did_load_filetypes") @@ -174,7 +174,7 @@ augroup filetypedetect augroup END ``` -Or add the following to a individual justfile to enable make mode on a per-file basis: +Or add the following to an individual justfile to enable `make` mode on a per-file basis: ``` # vim: set ft=make : @@ -184,7 +184,7 @@ Or add the following to a individual justfile to enable make mode on a per-file There is a MELPA package, https://melpa.org/#/just-mode[just-mode], for automatic Emacs syntax highlighting and automatic indentation in justfiles. -You can add the following to a individual justfile to enable make mode on a per-file basis: +You can add the following to an individual justfile to enable `make` mode on a per-file basis: ``` # Local Variables: @@ -444,7 +444,7 @@ If `dotenv-load` is `true`, a `.env` file will be loaded if present. Defaults to ==== Export -The `export` setting causes all Just variables to be exported as environment variables. Defaults to `false`. +The `export` setting causes all `just` variables to be exported as environment variables. Defaults to `false`. ```make set export @@ -500,7 +500,7 @@ foo: print("{{foos}}") ``` -Just passes the command to be executed as an argument. Many shells will need an additional flag, often `-c`, to make them evaluate the first argument. +`just` passes the command to be executed as an argument. Many shells will need an additional flag, often `-c`, to make them evaluate the first argument. ===== Python 3 @@ -659,7 +659,7 @@ Similar to unindented strings, indented double-quoted strings process escape seq === Ignoring Errors -Normally, if a command returns a nonzero exit status, execution will stop. To +Normally, if a command returns a non-zero exit status, execution will stop. To continue execution after a command, even if it fails, prefix the command with `-`: @@ -679,7 +679,7 @@ Done! === Functions -Just provides a few built-in functions that might be useful when writing recipes. +`just` provides a few built-in functions that might be useful when writing recipes. ==== System Information @@ -740,7 +740,7 @@ script: ==== Just Executable -- `just_executable()` - Absolute path to the just executable. +- `just_executable()` - Absolute path to the `just` executable. For example: @@ -1055,7 +1055,7 @@ And you type: $ just search "cat toupee" ``` -Just will run the command `lynx https://www.google.com/?q=cat toupee`, which will get parsed by `sh` as `lynx`, `https://www.google.com/?q=cat`, and `toupee`, and not the intended `lynx` and `https://www.google.com/?q=cat toupee`. +`just` will run the command `lynx https://www.google.com/?q=cat toupee`, which will get parsed by `sh` as `lynx`, `https://www.google.com/?q=cat`, and `toupee`, and not the intended `lynx` and `https://www.google.com/?q=cat toupee`. You can fix this by adding quotes: @@ -1071,11 +1071,11 @@ foo $bar: echo $bar ``` -=== Running recipes at the end of a recipe +=== Running Recipes at the End of a Recipe Dependencies of a recipes always run before a recipe starts. That is to say, the dependee always runs before the depender. -You can call Just recursively to run a recipe after a recipe ends. Given the following justfile: +You can call `just` recursively to run a recipe after a recipe ends. Given the following justfile: ```make a: @@ -1101,7 +1101,7 @@ echo 'C!' C! ``` -This has some limitations, since recipe `c` is run with an entirely new invocation of Just: Assignments will be recalculated, dependencies might run twice, and command line arguments will not be propagated to the child Just process. +This has some limitations, since recipe `c` is run with an entirely new invocation of `just`: Assignments will be recalculated, dependencies might run twice, and command line arguments will not be propagated to the child `just` process. === Writing Recipes in Other Languages @@ -1143,7 +1143,7 @@ Hello from ruby! === Safer Bash Shebang Recipes -If you're writing a Bash shebang recipe, consider adding `set -euxo pipefail`: +If you're writing a `bash` shebang recipe, consider adding `set -euxo pipefail`: ```make foo: @@ -1154,13 +1154,13 @@ foo: ``` It isn't strictly necessary, but `set -euxo pipefail` turns on a few useful -features that make Bash shebang recipes behave more like normal, linewise Just +features that make `bash` shebang recipes behave more like normal, linewise `just` recipe: -- `set -e` makes bash exit if a command fails. -- `set -u` makes bash exit if a variable is undefined. -- `set -x` makes bash print each script line before it's run. -- `set -o pipefail` makes bash exit if a command in a pipeline fails. +- `set -e` makes `bash` exit if a command fails. +- `set -u` makes `bash` exit if a variable is undefined. +- `set -x` makes `bash` print each script line before it's run. +- `set -o pipefail` makes `bash` exit if a command in a pipeline fails. Together, these avoid a lot of shell scripting gotchas. @@ -1181,12 +1181,12 @@ echo: The interpreter path `/bin/sh` will be translated to a Windows-style path using `cygpath` before being executed. -If the interpreter path does not contain a `/` it will be executed without being translated. This is useful if `cygpath` is not available, or you wish to pass a Windows style path to the interpreter. +If the interpreter path does not contain a `/` it will be executed without being translated. This is useful if `cygpath` is not available, or you wish to pass a Windows-style path to the interpreter. === Setting Variables in a Recipe -Recipe lines are interpreted by the shell, not Just, so it's not possible to set -Just variables in the middle of a recipe: +Recipe lines are interpreted by the shell, not `just`, so it's not possible to set +`just` variables in the middle of a recipe: ``` foo: @@ -1249,7 +1249,7 @@ foo: pwd ``` -=== Multi-line Constructs +=== Multi-Line Constructs Recipes without an initial shebang are evaluated and run line-by-line, which means that multi-line constructs probably won't do what you want. @@ -1441,11 +1441,11 @@ Bar! === Selecting Recipes to Run With an Interactive Chooser -The `--choose` subcommand makes just invoke a chooser to select which recipes +The `--choose` subcommand makes `just` invoke a chooser to select which recipes to run. Choosers should read lines containing recipe names from standard input and print one or more of those names separated by spaces to standard output. -Because there is currenly no way to run a recipe that requires arguments with +Because there is currently no way to run a recipe that requires arguments with `--choose`, such recipes will not be given to the chooser. Private recipes and aliases are also skipped. @@ -1473,7 +1473,7 @@ default: If the first argument passed to `just` contains a `/`, then the following occurs: 1. The argument is split at the last `/`. -2. The part before the last `/` is treated as a directory. Just will start its search for the justfile there, instead of in the current directory. +2. The part before the last `/` is treated as a directory. `just` will start its search for the justfile there, instead of in the current directory. 3. The part after the last slash is treated as a normal argument, or ignored if it is empty. This may seem a little strange, but it's useful if you wish to run a command in a justfile that is in a subdirectory. @@ -1556,7 +1556,7 @@ A non-normative grammar of justfiles can be found in link:GRAMMAR.md[]. === just.sh -Before `just` was a fancy rust program it was a tiny shell script that called `make`. You can find the old version in link:extras/just.sh[]. +Before `just` was a fancy Rust program it was a tiny shell script that called `make`. You can find the old version in link:extras/just.sh[]. === Non-Project Specific Justfile @@ -1578,7 +1578,7 @@ I'm pretty sure that nobody actually uses this feature, but it's there. == Contributing -`just` welcomes your contributions! `just` is released under the maximally permissive https://creativecommons.org/publicdomain/zero/1.0/legalcode.txt[CC0] public domain dedication and fallback license, so your changes must also released under this license. +`just` welcomes your contributions! `just` is released under the maximally permissive https://creativecommons.org/publicdomain/zero/1.0/legalcode.txt[CC0] public domain dedication and fallback license, so your changes must also be released under this license. === Janus @@ -1590,35 +1590,35 @@ Before merging a particularly large or gruesome change, Janus should be run to m === What are the idiosyncrasies of Make that Just avoids? -Make has some behaviors which are confusing, complicated, or make it unsuitable for use as a general command runner. +`make` has some behaviors which are confusing, complicated, or make it unsuitable for use as a general command runner. -One example is that under some circumstances, Make won't actually run the commands in a recipe. For example, if you have a file called `test` and the following makefile: +One example is that under some circumstances, `make` won't actually run the commands in a recipe. For example, if you have a file called `test` and the following makefile: ```make test: ./test ``` -Make will refuse to run your tests: +`make` will refuse to run your tests: ```sh $ make test make: `test' is up to date. ``` -Make assumes that the `test` recipe produces a file called `test`. Since this file exists and the recipe has no other dependencies, Make thinks that it doesn't have anything to do and exits. +`make` assumes that the `test` recipe produces a file called `test`. Since this file exists and the recipe has no other dependencies, `make` thinks that it doesn't have anything to do and exits. -To be fair, this behavior is desirable when using Make as a build system, but not when using it as a command runner. You can disable this behavior for specific targets using Make's built-in link:https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html[`.PHONY` target name], but the syntax is verbose and can be hard to remember. The explicit list of phony targets, written separately from the recipe definitions, also introduces the risk of accidentally defining a new non-phony target. In `just`, all recipes are treated as if they were phony. +To be fair, this behavior is desirable when using `make` as a build system, but not when using it as a command runner. You can disable this behavior for specific targets using `make`'s built-in link:https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html[`.PHONY` target name], but the syntax is verbose and can be hard to remember. The explicit list of phony targets, written separately from the recipe definitions, also introduces the risk of accidentally defining a new non-phony target. In `just`, all recipes are treated as if they were phony. -Other examples of Make’s idiosyncrasies include the difference between `=` and `:=` in assignments, the confusing error messages that are produced if you mess up your makefile, needing `$$` to use environment variables in recipes, and incompatibilities between different flavors of Make. +Other examples of `make`'s idiosyncrasies include the difference between `=` and `:=` in assignments, the confusing error messages that are produced if you mess up your makefile, needing `$$` to use environment variables in recipes, and incompatibilities between different flavors of `make`. -=== What's the relationship between just and cargo build scripts? +=== What's the relationship between Just and Cargo build scripts? -http://doc.crates.io/build-script.html[Cargo build scripts] have a pretty specific use, which is to control how cargo builds your rust project. This might include adding flags to `rustc` invocations, building an external dependency, or running some kind of codegen step. +http://doc.crates.io/build-script.html[`cargo` build scripts] have a pretty specific use, which is to control how `cargo` builds your Rust project. This might include adding flags to `rustc` invocations, building an external dependency, or running some kind of codegen step. `just`, on the other hand, is for all the other miscellaneous commands you might run as part of development. Things like running tests in different configurations, linting your code, pushing build artifacts to a server, removing temporary files, and the like. -Also, although `just` is written in rust, it can be used regardless of the language or build system your project uses. +Also, although `just` is written in Rust, it can be used regardless of the language or build system your project uses. == Further Ramblings