diff --git a/Guide/src/dev_guide/getting_started/suggested_dev_env.md b/Guide/src/dev_guide/getting_started/suggested_dev_env.md index cddef1e812..290d064f60 100644 --- a/Guide/src/dev_guide/getting_started/suggested_dev_env.md +++ b/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, diff --git a/xtask/src/main.rs b/xtask/src/main.rs index f6176603e4..ae916c4e4a 100644 --- a/xtask/src/main.rs +++ b/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, + + /// 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 { diff --git a/xtask/src/tasks/verify_size.rs b/xtask/src/tasks/verify_size.rs index 4dabd7616c..d88d022bc0 100644 --- a/xtask/src/tasks/verify_size.rs +++ b/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;