Crate watchexec

source ·
Expand description

Watchexec: a library for utilities and programs which respond to (file, signal, etc) events primarily by launching or managing other programs.

Also see the CLI tool: https://watchexec.github.io/

This library is powered by Tokio.

The main way to use this crate involves constructing a Watchexec around a Config, then running it. [Handler][handler::Handler]s are used to hook into Watchexec at various points. The config can be changed at any time with the [Watchexec::reconfigure()] method.

It’s recommended to use the miette erroring library in applications, but all errors implement std::error::Error so your favourite error handling library can of course be used.

use miette::{IntoDiagnostic, Result};
use watchexec_signals::Signal;
use watchexec::Watchexec;

#[tokio::main]
async fn main() -> Result<()> {
    let wx = Watchexec::new(|mut action| {
        // print any events
        for event in action.events.iter() {
            eprintln!("EVENT: {event:?}");
        }

        // if Ctrl-C is received, quit
        if action.signals().any(|sig| sig == Signal::Interrupt) {
            action.quit();
        }

        action
    })?;

    // watch the current directory
    wx.config.pathset(["."]);

    wx.main().await.into_diagnostic()?;
    Ok(())
}

Alternatively, you can use the modules exposed by the crate and the external crates such as [ClearScreen][clearscreen] and Command Group to build something more advanced, at the cost of reimplementing the glue code.

Note that the library generates a lot of debug messaging with tracing. You should not enable printing even error-level log messages for this crate unless it’s for debugging. Instead, make use of the Config::on_error() method to define a handler for errors occurring at runtime that are meant for you to handle (by printing out or otherwise).

Re-exports

  • pub use crate::config::Config;
  • pub use watchexec_supervisor::command;
  • pub use watchexec_supervisor::job;

Modules

  • Processor responsible for receiving events, filtering them, and scheduling actions in response.
  • Changeable values.
  • Configuration and builders for crate::Watchexec.
  • Error types for critical, runtime, and specialised errors.
  • The Filterer trait for event filtering.
  • Utilities for paths and sets of paths.
  • Sources of events.

Structs

  • The environment given to the error handler.
  • Unique opaque identifier.
  • The main watchexec runtime.