xtask: fix interplay between fmt-on-save and xsync (#925)

Fixing the underlying issue from #914

This PR does a few things:

1. The `xtask-path` logic has been fixed to always drop the file under
`target/xtask-path`, regardless of whether a `--custom-root` is being
used or not.
2. A new `--run-on-save` parameter has been added to `xtask`, which can
be used to skip certain expensive checks when running `xtask` in
response to a file save event. It is not currently being used by the
open-source `xtask`, but plays an important role in the internal repo's
`xtask fmt` implementation.
3. Updates the Guide to make it more clear why one may or may not want
to opt into this functionality.

**These changes are not particularly interesting in isolation, but make
more sense when reviewed alongside the changes being made in the
internal repo.**

The fact we have this sort of coupling between the oss xtask and the
closed-source xtask is unfortunate, and something we should try and move
away from in the future...

Author: daprilik

Guide/src/dev_guide/getting_started/suggested_dev_env.md

@@ -153,21 +153,31 @@ adding the following line to `keybindings.json`:
 }
 ```
 
-### Running `cargo xtask fmt house-rules` on-save
+### GitHub Pull Request Integration
 
-The OpenVMM project includes a handful of custom "house rule" lints that are
-external to `rustfmt`. These are things like checking for the presence of
-copyright headers, enforcing single-trailing newlines, etc...
+As the repo is hosted on GitHub, you might find convenient to use the
+[GitHub Pull Request](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github)
+VSCode extension. That allows working through the PR feedback and
+issues without leaving the comfort of VSCode.
 
-These lints are enfoced using `cargo xtask fmt house-rules`, and can be
-automatically fixed by passing the `--fix` flag.
+### (Possibly Useful) Enabling 'house-rules' formatting on-save
 
-We recommend installing the
-[RunOnSave](https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave)
-extension, and configuring it to run these lints as part of your regular
-development flow.
+Aside from using `rustfmt`, the OpenVMM project also relies on a handful of
+extra formatting "house rules". e.g: enfocing the presence of copyright headers,
+enforcing single-trailing newlines, etc...
+
+CI will fail if files are not formatted with `cargo xtask fmt house-rules`.
 
-Set the following configuration in your `.vscode/settings.json`
+In general, there are 3 ways to fix "house rules" related lints:
+
+1. Manually fixing issues in response to automated feedback
+2. Invoking `cargo xtask fmt house-rules --fix` to fix the whole project
+3. Invoking `cargo xtask fmt house-rules --fix [FILE]` to fix a given file
+
+If you would prefer having "house-rules" enfoced whenever you save a file in
+VSCode, you can install the
+[RunOnSave](https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave)
+extension, and add the following configuration to `.vscode/settings.json`:
 
 ```json
 {
@@ -180,20 +190,13 @@ Set the following configuration in your `.vscode/settings.json`
             {
                 "match": ".*",
                 "isAsync": true,
-                "cmd": "$(cat ./target/xtask-path) fmt house-rules --fix ${file}"
+                "cmd": "$(cat ./target/xtask-path) --run-on-save fmt house-rules --fix ${file}"
             }
         ]
     },
 }
 ```
 
-### GitHub Pull Request Integration
-
-As the repo is hosted on GitHub, you might find convenient to use the
-[GitHub Pull Request](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-pull-request-github)
-VSCode extension. That allows working through the PR feedback and
-issues without leaving the comfort of VSCode.
-
 ## Setting up pre-commit and pre-push hooks
 
 It's never fun having CI reject your changes due to some minor formatting issue,

xtask/src/main.rs

@@ -34,6 +34,8 @@ pub struct XtaskCtx {
     pub root: PathBuf,
     /// xtask is running within a hook
     pub in_git_hook: bool,
+    /// xtask was invoked as part of a "run on save" operation
+    pub in_run_on_save: bool,
 }
 
 /// Common trait implemented by all Xtask subcommands.
@@ -59,6 +61,19 @@ struct Cli {
     /// repo, and any custom out-of-tree overlay repos.
     #[clap(long)]
     custom_root: Option<PathBuf>,
+
+    /// Signal that this `xtask` is being invoked as part of a "run on save"
+    /// operation.
+    ///
+    /// When set, certain tasks may choose to skip certain expensive checks in
+    /// order to execute as quickly as possible.
+    ///
+    /// e.g: instead of calling `cargo run` in order to execute a project-local
+    /// tool, `xtask` may instead attempt to find and use an existing pre-built
+    /// binary, if one is available. This will be faster, but may run the risk
+    /// of executing a slightly stale binary.
+    #[clap(long)]
+    run_on_save: bool,
 }
 
 #[expect(clippy::large_enum_variant)]
@@ -93,25 +108,26 @@ fn main() {
 fn try_main() -> anyhow::Result<()> {
     let cli = Cli::parse();
 
+    let orig_root = Path::new(&env!("CARGO_MANIFEST_DIR"))
+        .ancestors()
+        .nth(1)
+        .unwrap()
+        .to_path_buf();
+
     let root = cli
         .custom_root
         .map(std::path::absolute)
         .transpose()?
-        .unwrap_or_else(|| {
-            Path::new(&env!("CARGO_MANIFEST_DIR"))
-                .ancestors()
-                .nth(1)
-                .unwrap()
-                .to_path_buf()
-        });
+        .unwrap_or(orig_root.clone());
 
     // for consistency, always run xtasks as though they were run from the root
     std::env::set_current_dir(&root)?;
 
     // drop the path to the xtask binary in an easy-to-find place. this gets
-    // used by the pre-commit hook to avoid rebuilding the xtask.
+    // used by the pre-commit hook, as well as the fmt-on-save dev-flow to avoid
+    // rebuilding the xtask.
     if let Ok(path) = std::env::current_exe() {
-        if let Err(e) = fs_err::write(XTASK_PATH_FILE, path.display().to_string()) {
+        if let Err(e) = fs_err::write(orig_root.join(XTASK_PATH_FILE), path.display().to_string()) {
             log::debug!("Unable to create XTASK_PATH_FILE: {:#}", e)
         }
     }
@@ -123,6 +139,7 @@ fn try_main() -> anyhow::Result<()> {
     let ctx = XtaskCtx {
         root,
         in_git_hook: matches!(cli.command, Commands::Hook(..)),
+        in_run_on_save: cli.run_on_save,
     };
 
     match cli.command {

xtask/src/tasks/verify_size.rs

@@ -1,8 +1,6 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-// Copyright (C) Microsoft Corporation. All rights reserved.
-
 use crate::Xtask;
 use anyhow::Context;
 use object::read::Object;