watchexec/lib.rs
1//! Watchexec: a library for utilities and programs which respond to (file, signal, etc) events
2//! primarily by launching or managing other programs.
3//!
4//! Also see the CLI tool: <https://github.com/watchexec/watchexec>
5//!
6//! This library is powered by [Tokio](https://tokio.rs).
7//!
8//! The main way to use this crate involves constructing a [`Watchexec`] around a [`Config`], then
9//! running it. Handlers (defined in [`Config`]) are used to hook into Watchexec at various points.
10//! The config can be changed at any time with the `config` field on your [`Watchexec`] instance.
11//!
12//! It's recommended to use the [miette] erroring library in applications, but all errors implement
13//! [`std::error::Error`] so your favourite error handling library can of course be used.
14//!
15//! ```no_run
16//! use miette::{IntoDiagnostic, Result};
17//! use watchexec_signals::Signal;
18//! use watchexec::Watchexec;
19//!
20//! #[tokio::main]
21//! async fn main() -> Result<()> {
22//! let wx = Watchexec::new(|mut action| {
23//! // print any events
24//! for event in action.events.iter() {
25//! eprintln!("EVENT: {event:?}");
26//! }
27//!
28//! // if Ctrl-C is received, quit
29//! if action.signals().any(|sig| sig == Signal::Interrupt) {
30//! action.quit();
31//! }
32//!
33//! action
34//! })?;
35//!
36//! // watch the current directory
37//! wx.config.pathset(["."]);
38//!
39//! wx.main().await.into_diagnostic()?;
40//! Ok(())
41//! }
42//! ```
43//!
44//! Alternatively, you can use the modules exposed by the crate and the external crates such as
45//! [`notify`], [`clearscreen`](https://docs.rs/clearscreen), [`process_wrap`]... to build something
46//! more advanced, at the cost of reimplementing the glue code.
47//!
48//! Note that the library generates a _lot_ of debug messaging with [tracing]. **You should not
49//! enable printing even `error`-level log messages for this crate unless it's for debugging.**
50//! Instead, make use of the [`Config::on_error()`] method to define a handler for errors
51//! occurring at runtime that are _meant_ for you to handle (by printing out or otherwise).
52
53#![doc(html_favicon_url = "https://watchexec.github.io/logo:watchexec.svg")]
54#![doc(html_logo_url = "https://watchexec.github.io/logo:watchexec.svg")]
55#![warn(clippy::unwrap_used, missing_docs)]
56#![cfg_attr(not(test), warn(unused_crate_dependencies))]
57#![deny(rust_2018_idioms)]
58
59// the toolkit to make your own
60pub mod action;
61pub mod error;
62pub mod filter;
63pub mod paths;
64pub mod sources;
65
66// the core experience
67pub mod changeable;
68pub mod config;
69
70mod id;
71mod late_join_set;
72mod watched_path;
73mod watchexec;
74
75#[doc(inline)]
76pub use crate::{
77 id::Id,
78 watched_path::WatchedPath,
79 watchexec::{ErrorHook, Watchexec},
80};
81
82#[doc(no_inline)]
83pub use crate::config::Config;
84#[doc(no_inline)]
85pub use watchexec_supervisor::{command, job};
86
87#[cfg(debug_assertions)]
88#[doc(hidden)]
89pub mod readme_doc_check {
90 #[doc = include_str!("../README.md")]
91 pub struct Readme;
92}