Cached recipes

README.md

@@ -1503,6 +1503,7 @@ Recipes may be annotated with attributes that change their behavior.
 | Name | Description |
 |------|-------------|
 | `[confirm]`<sup>1.17.0</sup> | Require confirmation prior to executing recipe. |
+| `[cached]`<sup>Latest</sup> | See [Cached Recipes](#cached-recipes) |
 | `[confirm("prompt")]`<sup>1.23.0</sup> | Require confirmation prior to executing recipe with a custom prompt. |
 | `[linux]`<sup>1.8.0</sup> | Enable recipe on Linux. |
 | `[macos]`<sup>1.8.0</sup> | Enable recipe on MacOS. |
@@ -2487,6 +2488,26 @@ polyglot: python js perl sh ruby
 
 Run `just --help` to see all the options.
 
+### Cached Recipes
+
+Cached recipes only run when the recipe body changes, where the body is compared
+*after `{{interpolations}}` are evaluated*. This gives you fine control for when
+a recipe should rerun. It is recommended you add `.justcache/` to your
+`.gitignore`. **Note: This is currently an unstable feature and requires
+`--unstable`**.
+
+```just
+[cached]
+build:
+  @# This only runs when the hash of the file changes {{sha256_file("input.c")}}
+  gcc input.c -o output
+
+[cached]
+bad-example:
+  @# This will never rerun since the body never changes
+  gcc input.c -o output
+```
+
 ### Private Recipes
 
 Recipes and aliases whose name starts with a `_` are omitted from `just --list`:

src/attribute.rs

@@ -5,6 +5,7 @@ use super::*;
 #[serde(rename_all = "kebab-case")]
 pub(crate) enum Attribute<'src> {
   Confirm(Option<StringLiteral<'src>>),
+  Cached,
   Linux,
   Macos,
   NoCd,

src/compile_error.rs

@@ -46,6 +46,12 @@ impl Display for CompileError<'_> {
         recipe_line.ordinal(),
       ),
       BacktickShebang => write!(f, "Backticks may not start with `#!`"),
+      CachedDependsOnUncached { cached, uncached } => {
+        write!(
+          f,
+          "Cached recipes cannot depend on preceding uncached ones, yet `{cached}` depends on `{uncached}`",
+        )
+      }
       CircularRecipeDependency { recipe, ref circle } => {
         if circle.len() == 2 {
           write!(f, "Recipe `{recipe}` depends on itself")

src/compile_error_kind.rs

@@ -11,6 +11,10 @@ pub(crate) enum CompileErrorKind<'src> {
     recipe_line: usize,
   },
   BacktickShebang,
+  CachedDependsOnUncached {
+    cached: &'src str,
+    uncached: &'src str,
+  },
   CircularRecipeDependency {
     recipe: &'src str,
     circle: Vec<&'src str>,

src/error.rs

@@ -17,6 +17,14 @@ pub(crate) enum Error<'src> {
     token: Token<'src>,
     output_error: OutputError,
   },
+  CacheFileRead {
+    cache_filename: PathBuf,
+    io_error: io::Error,
+  },
+  CacheFileWrite {
+    cache_filename: PathBuf,
+    io_error: io::Error,
+  },
   ChooserInvoke {
     shell_binary: String,
     shell_arguments: String,
@@ -267,6 +275,8 @@ impl<'src> ColorDisplay for Error<'src> {
           }?,
         OutputError::Utf8(utf8_error) => write!(f, "Backtick succeeded but stdout was not utf8: {utf8_error}")?,
       }
+      CacheFileRead {cache_filename, io_error} => write!(f, "Failed to read cache file ({}): {}", cache_filename.display(), io_error)?,
+      CacheFileWrite{cache_filename, io_error} => write!(f, "Failed to write cache file ({}): {}", cache_filename.display(), io_error)?,
       ChooserInvoke { shell_binary, shell_arguments, chooser, io_error} => {
         let chooser = chooser.to_string_lossy();
         write!(f, "Chooser `{shell_binary} {shell_arguments} {chooser}` invocation failed: {io_error}")?;

src/justfile.rs

@@ -272,12 +272,15 @@ impl<'src> Justfile<'src> {
     }
 
     let mut ran = Ran::default();
+    let mut cache = JustfileCache::new(search)?;
+
     for invocation in invocations {
-      let context = RecipeContext {
+      let mut context = RecipeContext {
         settings: invocation.settings,
         config,
         scope: invocation.scope,
         search,
+        cache: &mut cache,
       };
 
       Self::run_recipe(
@@ -287,15 +290,15 @@ impl<'src> Justfile<'src> {
           .copied()
           .map(str::to_string)
           .collect::<Vec<String>>(),
-        &context,
+        &mut context,
         &dotenv,
         &mut ran,
         invocation.recipe,
         search,
       )?;
     }
 
-    Ok(())
+    return cache.save(search);
   }
 
   pub(crate) fn get_alias(&self, name: &str) -> Option<&Alias<'src>> {
@@ -403,12 +406,12 @@ impl<'src> Justfile<'src> {
 
   fn run_recipe(
     arguments: &[String],
-    context: &RecipeContext<'src, '_>,
+    context: &mut RecipeContext<'src, '_>,
     dotenv: &BTreeMap<String, String>,
     ran: &mut Ran<'src>,
     recipe: &Recipe<'src>,
     search: &Search,
-  ) -> RunResult<'src> {
+  ) -> RunResult<'src, ()> {
     if ran.has_run(&recipe.namepath, arguments) {
       return Ok(());
     }
@@ -445,9 +448,16 @@ impl<'src> Justfile<'src> {
       }
     }
 
-    recipe.run(context, dotenv, scope.child(), search, &positional)?;
+    let updated_hash = recipe.run(context, dotenv, scope.child(), search, &positional)?;
+    let recipe_hash_changed = updated_hash.is_some();
 
-    if !context.config.no_dependencies {
+    if let Some(body_hash) = updated_hash {
+      context
+        .cache
+        .insert_recipe(recipe.name.to_string(), body_hash);
+    }
+
+    if !context.config.no_dependencies && (!recipe.should_cache() || recipe_hash_changed) {
       let mut ran = Ran::default();
 
       for Dependency { recipe, arguments } in recipe.dependencies.iter().skip(recipe.priors) {

src/justfile_cache.rs

@@ -0,0 +1,87 @@
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::path::PathBuf;
+
+use super::*;
+
+#[derive(Debug, Serialize, Deserialize)]
+pub(crate) struct JustfileCache {
+  /// Only serialized for user debugging
+  pub(crate) justfile_path: PathBuf,
+  /// Only serialized for user debugging
+  pub(crate) working_directory: PathBuf,
+
+  pub(crate) recipes: HashMap<String, RecipeCache>,
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub(crate) struct RecipeCache {
+  /// The hash of the recipe body after evaluation
+  pub(crate) body_hash: String,
+  #[serde(skip)]
+  /// Has the hash changed this run. Needed for nested cached dependencies.
+  pub(crate) hash_changed: bool,
+}
+
+impl JustfileCache {
+  fn new_empty(search: &Search) -> Self {
+    Self {
+      justfile_path: search.justfile.clone(),
+      working_directory: search.working_directory.clone(),
+      recipes: HashMap::new(),
+    }
+  }
+
+  pub(crate) fn new<'run>(search: &Search) -> RunResult<'run, Self> {
+    let cache_file = &search.cache_file;
+    let this = if cache_file.exists() {
+      let file_contents =
+        fs::read_to_string(cache_file).map_err(|io_error| Error::CacheFileRead {
+          cache_filename: cache_file.clone(),
+          io_error,
+        })?;
+      // Ignore newer versions, incompatible old versions or corrupted cache files
+      serde_json::from_str(&file_contents)
+        .or(Err(()))
+        .unwrap_or_else(|()| Self::new_empty(search))
+    } else {
+      Self::new_empty(search)
+    };
+    Ok(this)
+  }
+
+  pub(crate) fn insert_recipe(&mut self, name: String, body_hash: String) {
+    self.recipes.insert(
+      name,
+      RecipeCache {
+        body_hash,
+        hash_changed: true,
+      },
+    );
+  }
+
+  pub(crate) fn save<'run>(&self, search: &Search) -> RunResult<'run, ()> {
+    let cache = serde_json::to_string(self).map_err(|_| Error::Internal {
+      message: format!("Failed to serialize cache: {self:?}"),
+    })?;
+
+    search
+      .cache_file
+      .parent()
+      .ok_or_else(|| {
+        io::Error::new(
+          io::ErrorKind::Unsupported,
+          format!(
+            "Cannot create parent directory of {}",
+            search.cache_file.display()
+          ),
+        )
+      })
+      .and_then(fs::create_dir_all)
+      .and_then(|()| fs::write(&search.cache_file, cache))
+      .map_err(|io_error| Error::CacheFileWrite {
+        cache_filename: search.cache_file.clone(),
+        io_error,
+      })
+  }
+}

src/lib.rs

@@ -24,18 +24,19 @@ pub(crate) use {
     enclosure::Enclosure, error::Error, evaluator::Evaluator, expression::Expression,
     fragment::Fragment, function::Function, function_context::FunctionContext,
     interrupt_guard::InterruptGuard, interrupt_handler::InterruptHandler, item::Item,
-    justfile::Justfile, keyed::Keyed, keyword::Keyword, lexer::Lexer, line::Line, list::List,
-    load_dotenv::load_dotenv, loader::Loader, name::Name, namepath::Namepath, ordinal::Ordinal,
-    output::output, output_error::OutputError, parameter::Parameter, parameter_kind::ParameterKind,
-    parser::Parser, platform::Platform, platform_interface::PlatformInterface, position::Position,
-    positional::Positional, ran::Ran, range_ext::RangeExt, recipe::Recipe,
-    recipe_context::RecipeContext, recipe_resolver::RecipeResolver, scope::Scope, search::Search,
-    search_config::SearchConfig, search_error::SearchError, set::Set, setting::Setting,
-    settings::Settings, shebang::Shebang, shell::Shell, show_whitespace::ShowWhitespace,
-    source::Source, string_kind::StringKind, string_literal::StringLiteral, subcommand::Subcommand,
-    suggestion::Suggestion, table::Table, thunk::Thunk, token::Token, token_kind::TokenKind,
-    unresolved_dependency::UnresolvedDependency, unresolved_recipe::UnresolvedRecipe,
-    use_color::UseColor, variables::Variables, verbosity::Verbosity, warning::Warning,
+    justfile::Justfile, justfile_cache::JustfileCache, keyed::Keyed, keyword::Keyword,
+    lexer::Lexer, line::Line, list::List, load_dotenv::load_dotenv, loader::Loader, name::Name,
+    namepath::Namepath, ordinal::Ordinal, output::output, output_error::OutputError,
+    parameter::Parameter, parameter_kind::ParameterKind, parser::Parser, platform::Platform,
+    platform_interface::PlatformInterface, position::Position, positional::Positional, ran::Ran,
+    range_ext::RangeExt, recipe::Recipe, recipe_context::RecipeContext,
+    recipe_resolver::RecipeResolver, scope::Scope, search::Search, search_config::SearchConfig,
+    search_error::SearchError, set::Set, setting::Setting, settings::Settings, shebang::Shebang,
+    shell::Shell, show_whitespace::ShowWhitespace, source::Source, string_kind::StringKind,
+    string_literal::StringLiteral, subcommand::Subcommand, suggestion::Suggestion, table::Table,
+    thunk::Thunk, token::Token, token_kind::TokenKind, unresolved_dependency::UnresolvedDependency,
+    unresolved_recipe::UnresolvedRecipe, use_color::UseColor, variables::Variables,
+    verbosity::Verbosity, warning::Warning,
   },
   std::{
     cmp,
@@ -142,6 +143,7 @@ mod interrupt_guard;
 mod interrupt_handler;
 mod item;
 mod justfile;
+mod justfile_cache;
 mod keyed;
 mod keyword;
 mod lexer;