[Awesome Rust] Use cargo-watch to hot live reload for Cargo commands

Posted on 2021-06-26 Edited on 2023-09-02 In Programming Language , Rust , Awesome Rust Views: Word count in article: 6.7k Reading time ≈ 6 mins.

cargo-watch

Cargo Watch watches over your project’s source for changes, and runs Cargo commands when they occur.

Prerequites

Cargo is the Rust package manager. Cargo downloads your Rust package’s dependencies, compiles your packages, makes distributable packages, and uploads them to crates.io - https://crates.io/, the Rust community’s package registry.

Install Rust and Cargo

The easiest way to get Cargo is to install the current stable release of Rust by using rustup. Installing Rust using rustup will also install cargo.

On Linux and macOS systems, this is done as follows:

1	$ curl https://sh.rustup.rs -sSf \| sh

It will download a script, and start the installation. If everything goes well, you’ll see this appear:

1	Rust is installed now. Great!

Installation

Installed with the following command:

1	$ cargo install cargo-watch

Usages

By default, it runs check. You can easily override this, though:

$ cargo watch [-x command]...
A few examples:

# Run tests only
$ cargo watch -x test

# Run check then tests
$ cargo watch -x check -x test

# Run run with arguments
$ cargo watch -x 'run -- --some-arg'

# Run an arbitrary command
$ cargo watch -- echo Hello world

# Run with features passed to cargo
$ cargo watch --features "foo,bar"

There’s a lot more you can do! Here’s a copy of the help:

$ cargo watch -h     
cargo-watch 7.8.0
https://github.com/passcod/cargo-watch
Watches over your Cargo project’s source

USAGE:
    cargo watch [FLAGS] [OPTIONS]

FLAGS:
    -c, --clear              Clear the screen before each run
    -h, --help               Display this message
        --ignore-nothing     Ignore nothing, not even target/ and .git/
        --debug              Show debug output
        --why                Show paths that changed
    -q, --quiet              Suppress output from cargo-watch itself
        --no-gitignore       Don’t use .gitignore files
        --no-ignore          Don’t use .ignore files
        --no-restart         Don’t restart command while it’s still running
        --poll               Force use of polling for file changes
        --postpone           Postpone first run until a file changes
    -V, --version            Display version information
        --watch-when-idle    Ignore events emitted while the commands run. Will become default behaviour in
                             8.0.

OPTIONS:
    -x, --exec <cmd>...            Cargo command(s) to execute on changes [default: check]
    -s, --shell <cmd>...           Shell command(s) to execute on changes
    -d, --delay <delay>            File updates debounce delay in seconds [default: 0.5]
        --features <features>      List of features passed to cargo invocations
    -i, --ignore <pattern>...      Ignore a glob/gitignore-style pattern
        --use-shell <use-shell>    Use a different shell. E.g. --use-shell=bash
    -w, --watch <watch>...         Watch specific file(s) or folder(s) [default: .]
    -C, --workdir <workdir>        Change working directory before running command [default: crate root]

ARGS:
    <cmd:trail>...    Full command to run. -x and -s will be ignored!

Cargo commands (-x) are always executed before shell commands (-s). You can use the `-- command` style instead,
note you'll need to use full commands, it won't prefix `cargo` for you.

By default, your entire project is watched, except for the target/ and .git/ folders, and your .ignore and
.gitignore files are used to filter paths.

Ignore files

.gitignore files are used by default to ignore paths to watch and trigger runs. To stop honouring them, pass --no-gitignore.

.ignore files in the same syntax are also used by default. This file can be used to specify files that should be ignored by cargo watch but checked into git, without constantly adding --ignore abc options on the command-line. Do note that .ignore files may also be used by other programs, like ripgrep. To stop honouring these, pass --no-ignore.

Cargo watch also has an internal list of default ignores on top of those specified in files, like target/ and .git/`` and various other common types (logs, editor swap files, lockfiles, etc).

To skip absolutely all ignores, use the --ignore-nothing flag.

Ignore syntax

See the glob::Pattern docs for a more detailed specification of the glob matching syntax used for --ignore.

On Windows, patterns should be specified with Windows-style (\\) separators. Unix-style separators (/) would not match Windows paths, which could be confusing and give the appearance of commandline ignores not working.

From Cargo Watch 7.0.0, / in commandline ignores are automatically translated to \\ when running on Windows, but one should still try to write the correct patterns for the platform, as there may be more subtle differences.

From Cargo Watch 7.3.0, --ignore patterns were fixed to provide better experience with directory matching. Previously, ignoring a folder would need unyieldy -i folder/** patterns; now that is handled internally, and only -i folder is needed for the same effect.

Reloading servers seamlessly

Cargo Watch pairs very well with systemfd/Catflap, tools for Unixy platforms that lets one spawn a socket before the watcher runs that Rust servers can then bind to, avoiding request-dropping and the infamous ADDRINUSE error. For example:

1	$ systemfd --no-pid -s http::5000 -- cargo watch -x run

Of course, if you don’t need to guard against these issues or don’t want to modify your program to grab sockets instead of ports, you can use Cargo Watch as-is: it will happily just restart your server normally.

Restarting an application only if the build/check succeeds

Brought up by @LeDominikFeature Suggestion: conditional run · Issue #75 · watchexec/cargo-watch - https://github.com/watchexec/cargo-watch/issues/75, here’s a pattern that may be very useful: you’re working on a server or app, but want it to keep running while you’re writing a new feature or fixing a bug, potentially causing the code not to compile anymore in the meantime.

In this case, you can use this strategy: run a first cargo watch with check, build, test, or whatever you want, and append -s 'touch .trigger' (or equivalent for your platform). Then, run a second cargo watch simultaneously that only watches that .trigger file. For example:

1	$ cargo watch -x check -s 'touch .trigger'

and

1	$ cargo watch --no-gitignore -w .trigger -x run

The --no-gitignore flag ensures that you can safely add .trigger to your .gitignore file to avoid mistakenly committing it.

Troubleshooting

I want to embed Cargo Watch in my own (Rust) tool

It is not recommended to do that directly. You may of course call cargo-watch as any other program, and technically it exposes an (undocumented) library that could be directly / statically embedded. If you have no other option, that may be your best bet.

However, for most cases, consider building on top of Watchexec - https://watchexec.github.io/ instead. That is itself built on Notify | notify-rs/notify: 🔭 Cross-platform filesystem notification library for Rust. - https://github.com/notify-rs/notify, and both of these can be used as Rust libraries.

If you want to build a tool that runs, restarts, and otherwise manages commands in response to file changes, you’ll most probably want to use Watchexec.
If you want to build a tool that responds to file changes, but does not need to run commands, or does so in a way that is not well-supported by Watchexec, then Notify is your ticket.

See Troubleshooting - https://github.com/watchexec/cargo-watch#troubleshooting to leran more.