From d9b26b1f952a9f7991fcff4353a1d6f464cb7400 Mon Sep 17 00:00:00 2001 From: bunnie Date: Sun, 7 Jan 2024 16:59:33 +0800 Subject: [PATCH 01/16] RFC: proposed rustfmt settings for the project --- .vscode/settings.json | 3 +++ rustfmt.toml | 41 +++++++++++++++++++++++++++++++++++++++-- 2 files changed, 42 insertions(+), 2 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 87327e126..4a39a6a4b 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -23,5 +23,8 @@ "**/.DS_Store": true, "**/Thumbs.db": true }, + "rust-analyzer.rustfmt.extraArgs": [ + "+nightly" + ], "cSpell.language": "en,fr" } diff --git a/rustfmt.toml b/rustfmt.toml index 58e3e66e0..976c1dd93 100644 --- a/rustfmt.toml +++ b/rustfmt.toml @@ -15,6 +15,43 @@ ignore = [ "services/shellchat", "services/spinor", "services/susres", + "services/pddb", ] -# Note: run this on Linux to fix Windows changing .rs files to +x: -# find . -name "*.rs" -exec chmod -x {} \; \ No newline at end of file +# Notes: +# - @generated in the first five lines of a file suppresses formatting for generated files! +# - run this on Linux to fix Windows changing .rs files to +x: +# `find . -name "*.rs" -exec chmod -x {} \;` + +# I can't rely on contributors using .editorconfig +newline_style = "Unix" +# require the shorthand instead of it being optional +use_field_init_shorthand = true +# outdated default — `?` was unstable at the time +# additionally the `try!` macro is deprecated now +use_try_shorthand = true +# Computers in the 90's had 132 column displays[1], and the displays were 1/6th the area. +# 110 columns doesn't seem like a big stretch... +# [1] https://en.wikipedia.org/wiki/VGA_text_mode +max_width = 110 +# Max to use the max width for everything or Default. See https://rust-lang.github.io/rustfmt/?version=v1.4.38&search=#use_small_heuristics +use_small_heuristics = "Max" + +# Unstable features below +unstable_features = true +version = "Two" +# code can be 110 characters, why not comments? +comment_width = 110 +# quicker manual lookup +group_imports = "StdExternalCrate" +# why use an attribute if a normal doc comment would suffice? +normalize_doc_attributes = true +# why not? +format_code_in_doc_comments = true +format_macro_bodies = true +format_macro_matchers = true +format_strings = false +wrap_comments = true +fn_single_line = true +reorder_impl_items = true +reorder_imports = false +reorder_modules = false From 45edea44b352bd99ce6410add10108c73910f845 Mon Sep 17 00:00:00 2001 From: bunnie Date: Sun, 7 Jan 2024 17:37:30 +0800 Subject: [PATCH 02/16] Remove the exclusions If we harmonize on `rustfmt` for the repo, all exclusions would be removed. --- rustfmt.toml | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/rustfmt.toml b/rustfmt.toml index 976c1dd93..908856bbc 100644 --- a/rustfmt.toml +++ b/rustfmt.toml @@ -1,22 +1,3 @@ -# if you want to format 'em, then you can maintain 'em! -ignore = [ - "services/codec", - "services/com", - "services/engine-25519", - "services/gam", - "services/graphics-server", - "services/ime-frontend", - "services/ime-plugin-shell", - "services/jtag", - "services/keyboard", - "services/llio", - "services/root-keys", - "services/rtc", - "services/shellchat", - "services/spinor", - "services/susres", - "services/pddb", -] # Notes: # - @generated in the first five lines of a file suppresses formatting for generated files! # - run this on Linux to fix Windows changing .rs files to +x: From fafee5bc72594909aed844f2f2bdf4e652670128 Mon Sep 17 00:00:00 2001 From: bunnie Date: Sun, 7 Jan 2024 17:38:51 +0800 Subject: [PATCH 03/16] If PR is accepted, we'd make formatOnSave true by default --- .vscode/settings.json | 1 + 1 file changed, 1 insertion(+) diff --git a/.vscode/settings.json b/.vscode/settings.json index 4a39a6a4b..858d1e488 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -26,5 +26,6 @@ "rust-analyzer.rustfmt.extraArgs": [ "+nightly" ], + "editor.formatOnSave": true, "cSpell.language": "en,fr" } From 59d65d6334fbb0dd1586b2639cf81628a8d83e04 Mon Sep 17 00:00:00 2001 From: bunnie Date: Tue, 9 Jan 2024 14:29:00 +0800 Subject: [PATCH 04/16] Update rustfmt.toml absorb feedback on alphabetical ordering --- rustfmt.toml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/rustfmt.toml b/rustfmt.toml index 908856bbc..0cdd79b5f 100644 --- a/rustfmt.toml +++ b/rustfmt.toml @@ -34,5 +34,6 @@ format_strings = false wrap_comments = true fn_single_line = true reorder_impl_items = true -reorder_imports = false -reorder_modules = false +# this helps with merges, even though it destroys logical cohesion +reorder_imports = true +reorder_modules = true From d510a806deca47b77927e87323a4d5855f296a5a Mon Sep 17 00:00:00 2001 From: bunnie Date: Thu, 11 Jan 2024 21:19:41 +0800 Subject: [PATCH 05/16] cleanup build.yml action I think we don't need to run the full rust toolchain script, just `rustup update`? Also update actions version for checkout and comments. --- .github/workflows/build.yml | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 1a1f4193d..b6c6e0c22 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -18,15 +18,11 @@ jobs: sudo apt update sudo apt install -y libxkbcommon-dev - - name: Install stable toolchain - uses: actions-rs/toolchain@v1 - with: - profile: minimal - toolchain: "1.75.0" - default: true + - name: Update to latest toolchain + run: rustup update - name: Checkout sources - uses: actions/checkout@v2 + uses: actions/checkout@v4 - name: Fetch tags run: git fetch --prune --unshallow --tags @@ -38,5 +34,5 @@ jobs: - name: Clean out old target directory (in case of libstd change) run: rm -rf target/* - - name: Build hosted-ci + - name: Build CI targets run: cargo xtask ${{ matrix.task }} --no-verify From 99a238107bf41d40cb64031ff135c6fb96f95f81 Mon Sep 17 00:00:00 2001 From: bunnie Date: Thu, 11 Jan 2024 21:20:26 +0800 Subject: [PATCH 06/16] add a proposed rustfmt check --- .github/workflows/rustfmt_check.yml | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 .github/workflows/rustfmt_check.yml diff --git a/.github/workflows/rustfmt_check.yml b/.github/workflows/rustfmt_check.yml new file mode 100644 index 000000000..1d0d4e52c --- /dev/null +++ b/.github/workflows/rustfmt_check.yml @@ -0,0 +1,19 @@ +# From https://github.com/samblenny/autofmt-demo/blob/main/.github/workflows/rustfmt_check.yml +name: rustfmt_check +on: push +jobs: + rustfmt_check: + runs-on: ubuntu-latest + steps: + - name: Check out branch source + uses: actions/checkout@v4 + + - name: Install rustfmt from nightly toolchain + run: | + rustup toolchain install nightly + rustup component add rustfmt --toolchain nightly + + - name: Run cargo +nightly fmt --check + run: cargo +nightly fmt --check + + - run: echo "status = ${{ job.status }}" \ No newline at end of file From da60e825844c7e23ebd2c3fe3a6c1bcf15166de9 Mon Sep 17 00:00:00 2001 From: bunnie Date: Thu, 11 Jan 2024 21:20:41 +0800 Subject: [PATCH 07/16] add a proposed trailing whitespace check --- .github/workflows/trailing_whitespace_check.yml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) create mode 100644 .github/workflows/trailing_whitespace_check.yml diff --git a/.github/workflows/trailing_whitespace_check.yml b/.github/workflows/trailing_whitespace_check.yml new file mode 100644 index 000000000..6635dd60f --- /dev/null +++ b/.github/workflows/trailing_whitespace_check.yml @@ -0,0 +1,16 @@ +# From https://github.com/samblenny/autofmt-demo/blob/main/.github/workflows/trailing_whitespace_check.yml +name: trailing_whitespace_check +on: push +jobs: + trailing_whitespace_check: + runs-on: ubuntu-latest + steps: + - name: Check out branch source + uses: actions/checkout@v4 + + - name: Check .rs files for trailing whitespace + run: > + find . -name '*.rs' -print0 + | xargs -0 grep -c --with-filename '[ \t]$' + | grep -v ':0$' + | perl -e 'while(<>){print;$n+=1};if($n>0){exit 1;};print "PASS\n";' \ No newline at end of file From ca5845c2f65dbf1198e6472fd9734c96af1dae5e Mon Sep 17 00:00:00 2001 From: bunnie Date: Thu, 11 Jan 2024 21:24:14 +0800 Subject: [PATCH 08/16] checkout the `main` rustfmt.toml prior to running CI this is necessary so that patches can't sneak through by modifying rustfmt.toml to bypass a CI checke. --- .github/workflows/rustfmt_check.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/workflows/rustfmt_check.yml b/.github/workflows/rustfmt_check.yml index 1d0d4e52c..38626bca0 100644 --- a/.github/workflows/rustfmt_check.yml +++ b/.github/workflows/rustfmt_check.yml @@ -13,6 +13,9 @@ jobs: rustup toolchain install nightly rustup component add rustfmt --toolchain nightly + - name: Ensure the `main` branch rustfmt is applied for the run + run: git checkout main rustfmt.toml + - name: Run cargo +nightly fmt --check run: cargo +nightly fmt --check From 5f0e2a48b0f0251869fe6489a87a174252d1664a Mon Sep 17 00:00:00 2001 From: bunnie Date: Thu, 11 Jan 2024 21:44:11 +0800 Subject: [PATCH 09/16] cleanup missing -P specifier on grep regex looks like the regex is perl syntax --- .github/workflows/trailing_whitespace_check.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/trailing_whitespace_check.yml b/.github/workflows/trailing_whitespace_check.yml index 6635dd60f..6ed97eb89 100644 --- a/.github/workflows/trailing_whitespace_check.yml +++ b/.github/workflows/trailing_whitespace_check.yml @@ -11,6 +11,6 @@ jobs: - name: Check .rs files for trailing whitespace run: > find . -name '*.rs' -print0 - | xargs -0 grep -c --with-filename '[ \t]$' + | xargs -0 grep -c --with-filename -P '[ \t]$' | grep -v ':0$' | perl -e 'while(<>){print;$n+=1};if($n>0){exit 1;};print "PASS\n";' \ No newline at end of file From 6405f91fd71486534ad93bbbb807d046a9140699 Mon Sep 17 00:00:00 2001 From: bunnie Date: Thu, 11 Jan 2024 21:49:46 +0800 Subject: [PATCH 10/16] have to fetch main before we can checkout the rustfmt.toml --- .github/workflows/rustfmt_check.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/rustfmt_check.yml b/.github/workflows/rustfmt_check.yml index 38626bca0..5077b0adc 100644 --- a/.github/workflows/rustfmt_check.yml +++ b/.github/workflows/rustfmt_check.yml @@ -14,7 +14,9 @@ jobs: rustup component add rustfmt --toolchain nightly - name: Ensure the `main` branch rustfmt is applied for the run - run: git checkout main rustfmt.toml + run: | + git fetch --no-tags --prune --no-recurse-submodules --depth=1 origin/main + git checkout main rustfmt.toml - name: Run cargo +nightly fmt --check run: cargo +nightly fmt --check From 86afec01609b35ab663c8989ba07f07c9e532f02 Mon Sep 17 00:00:00 2001 From: bunnie Date: Thu, 11 Jan 2024 21:51:11 +0800 Subject: [PATCH 11/16] fix origin statement sorry this is all pushing to GH directly, the only way i know how to test this is to push to the branch :P so y'all get to see me flail. --- .github/workflows/rustfmt_check.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/rustfmt_check.yml b/.github/workflows/rustfmt_check.yml index 5077b0adc..4b08e7da7 100644 --- a/.github/workflows/rustfmt_check.yml +++ b/.github/workflows/rustfmt_check.yml @@ -15,7 +15,7 @@ jobs: - name: Ensure the `main` branch rustfmt is applied for the run run: | - git fetch --no-tags --prune --no-recurse-submodules --depth=1 origin/main + git fetch --no-tags --prune --no-recurse-submodules --depth=1 origin main git checkout main rustfmt.toml - name: Run cargo +nightly fmt --check From 62a351f813c8c4c007328d00710fc0c7bc72585b Mon Sep 17 00:00:00 2001 From: bunnie Date: Thu, 11 Jan 2024 21:52:36 +0800 Subject: [PATCH 12/16] maybe this is the trick? ugh. --- .github/workflows/rustfmt_check.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/rustfmt_check.yml b/.github/workflows/rustfmt_check.yml index 4b08e7da7..ab860b605 100644 --- a/.github/workflows/rustfmt_check.yml +++ b/.github/workflows/rustfmt_check.yml @@ -15,7 +15,7 @@ jobs: - name: Ensure the `main` branch rustfmt is applied for the run run: | - git fetch --no-tags --prune --no-recurse-submodules --depth=1 origin main + git fetch --no-tags --prune --no-recurse-submodules --depth=1 origin origin/main git checkout main rustfmt.toml - name: Run cargo +nightly fmt --check From d14e1b26085a761bf210d576391486ce771cfac0 Mon Sep 17 00:00:00 2001 From: bunnie Date: Thu, 11 Jan 2024 21:56:52 +0800 Subject: [PATCH 13/16] another try... maybe i'm reading the gh automation error message wrong? --- .github/workflows/rustfmt_check.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/rustfmt_check.yml b/.github/workflows/rustfmt_check.yml index ab860b605..876d2965b 100644 --- a/.github/workflows/rustfmt_check.yml +++ b/.github/workflows/rustfmt_check.yml @@ -15,8 +15,8 @@ jobs: - name: Ensure the `main` branch rustfmt is applied for the run run: | - git fetch --no-tags --prune --no-recurse-submodules --depth=1 origin origin/main - git checkout main rustfmt.toml + git fetch --no-tags --prune --no-recurse-submodules --depth=1 origin main + git checkout origin/main rustfmt.toml - name: Run cargo +nightly fmt --check run: cargo +nightly fmt --check From 40b4c8941432bb9b926e742a992e1ef2ee22cfae Mon Sep 17 00:00:00 2001 From: bunnie Date: Thu, 11 Jan 2024 22:21:50 +0800 Subject: [PATCH 14/16] add a formatting document this hopefully helps new users get started with formatting. didn't want to edit the CONTRIBUTING.md file because it already has a lot of other stuff in there not specific to formatting. --- FORMATTING.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 FORMATTING.md diff --git a/FORMATTING.md b/FORMATTING.md new file mode 100644 index 000000000..9e2efdf90 --- /dev/null +++ b/FORMATTING.md @@ -0,0 +1,50 @@ +# Formatting Guidelines + +All contributions to Xous must comply with two formatting guidelines: + +1. Run `rustfmt` using our `rustfmt.toml` with a nightly toolchain +2. Remove trailing whitespaces + +## Resources + +Our `rustfmt` requires a Rust nightly toolchain. + +Install a nightly toolchain with + +`rustup toolchain install nightly` + +From here, you may run `rustfmt` on the command line with + +`cargo +nightly fmt -p ` + +Unfortunately, one cannot simply run `rustfmt` on a single file with nightly from the command line without changing the default toolchain. However, there are various plugins one can use to help with this. + +### vscode + +If you are using `vscode`, add these lines to your `settings.json` file: + +```json +"rust-analyzer.rustfmt.extraArgs": [ + "+nightly" + ], +"files.trimTrailingWhitespace": true, +"editor.formatOnSave": true, +``` + +The default `settings.json` that comes with the repo already has these built in. + +### `pre-commit` + +[pre-commit](https://pre-commit.com/) is a tool that can be configured to run github actions locally. + +The development workflow looks like this: + + 1. the developer installs pre-commit on their machine and runs pre-commit install from within the xous-core directory: it'll set up the necessary dependencies, and sets up a local git pre-commit hook to run them + 2. development flows as expected + 3. at commit time, one of two things can happen + a. code is formatted correctly already, commit gets written + b. code is not formatted correctly, commit is aborted, code gets formatted automatically + +### Other tools + +If you have your own workflow, please contribute a hint to this document so that others can benefit from it! From 676bab899fc7ce81bb56fdcd0b7a5f33a42addb4 Mon Sep 17 00:00:00 2001 From: bunnie Date: Thu, 11 Jan 2024 22:22:39 +0800 Subject: [PATCH 15/16] add trailing whitespace removal to settings also format the file, because, hey guess what...format on save is on. :P --- .vscode/settings.json | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 858d1e488..dd25aa0c6 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,20 +1,31 @@ { - "rust-analyzer.cargo.target":"riscv32imac-unknown-xous-elf", - "rust-analyzer.check.overrideCommand":[ + "rust-analyzer.cargo.target": "riscv32imac-unknown-xous-elf", + "rust-analyzer.check.overrideCommand": [ "cargo", "check", - "--target", "riscv32imac-unknown-xous-elf", - "--target-dir", "target/analyzer", - "--features", "precursor", - "--features", "utralib/precursor", - "--features", "utralib/precursor-pvt", - "--message-format", "json" + "--target", + "riscv32imac-unknown-xous-elf", + "--target-dir", + "target/analyzer", + "--features", + "precursor", + "--features", + "utralib/precursor", + "--features", + "utralib/precursor-pvt", + "--message-format", + "json" ], "rust-analyzer.server.extraEnv": { "XOUS_SVD_FILE": "../precursors/soc.svd" }, - "rust-analyzer.cargo.features": ["precursor", "mass-storage"], - "rust-analyzer.files.excludeDirs": ["./loader/**"], + "rust-analyzer.cargo.features": [ + "precursor", + "mass-storage" + ], + "rust-analyzer.files.excludeDirs": [ + "./loader/**" + ], "files.exclude": { "**/.git": true, "**/.svn": true, @@ -26,6 +37,7 @@ "rust-analyzer.rustfmt.extraArgs": [ "+nightly" ], + "files.trimTrailingWhitespace": true, "editor.formatOnSave": true, "cSpell.language": "en,fr" -} +} \ No newline at end of file From eb77e76c9fa4c4ad412291eb8dcddd486de21ec9 Mon Sep 17 00:00:00 2001 From: bunnie Date: Thu, 11 Jan 2024 22:23:03 +0800 Subject: [PATCH 16/16] note new standards in the change log --- RELEASE-v0.9.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/RELEASE-v0.9.md b/RELEASE-v0.9.md index 8ae7fb6a5..f6bfa5ea6 100644 --- a/RELEASE-v0.9.md +++ b/RELEASE-v0.9.md @@ -462,6 +462,8 @@ perform the Xous firmware upgrade. This requires running manual update commands, - `sigchat` can now link up to an existing account - thanks to huge PR by @nhoj - `xtask` can accept out-of-tree apps using a syntax like `cargo xtask app-image sigchat:path-to-elf-file` thanks to PR by @kotval. This allows apps like `sigchat` to have AGPL licensing without contaminating `xous-core` - `sigchat` moved to its own repo with AGPL licensing: https://github.com/betrusted-io/sigchat +- Formatting and contribution standards have been modified. Formatting with `rustfmt` and trailing white space removal is now mandatory for all Xous contributions, see [#477](https://github.com/betrusted-io/xous-core/pull/477) for a discussion of how we got there and why. +- The repo has gone through a "flag day" where all the crates have been formatted, which means commits before the flag day may be more difficult to undo. The changes are committed on a crate-by-crate basis, so if something is really broken we can undo the formatting for the crate and add an exception to the rustfmt rules. ## Roadmap