greg/just
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve readme (#904)

Browse Source
This commit is contained in:
Matias Kinnunen 2021-07-21 03:49:20 +03:00 committed by GitHub
parent 06d207a1ab
commit 7bbc38a261
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 48 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
README.adoc
View File

@ -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