Allow, use, and enforce rustfmt in the codebase

.cargo/config.toml

@@ -5,3 +5,9 @@ rustflags = [
 rustdocflags = [
     "--cfg", "docs",
 ]
+
+[alias]
+# fmt = []  # Please use `cargo fmt-nightly` instead.
+fmt-nightly = ["r", "-q", "-p", "run-sh", "--", "./scripts/format.sh"]
+# In order for `cargo fmt` to Just Work™, you can run:
+# scripts/formatting/setup_cargo_fmt_override.sh

.git-blame-ignore-revs

@@ -0,0 +1,6 @@
+# Run this command to always ignore formatting commits in `git blame`
+# ```sh
+# git config blame.ignoreRevsFile '.git-blame-ignore-revs'
+# ```
+
+8a9b15953d5f56c54393e9c1f6e12c3749bc0164

.github/workflows/gh-pages.yml → .github/workflows/CI.yml

@@ -46,6 +46,24 @@ jobs:
             --no-default-features --features alloc
             --target x86_64-unknown-linux-gnu -Zbuild-std=core,alloc
 
+  # == Check formatting == #
+  check-formatting:
+    name: Check formatting
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: nightly-2025-01-03  # branch-from-master date of 1.85.0
+          override: true
+          components: rustfmt
+
+      - name: Clone repo
+        uses: actions/checkout@v2
+
+      - run: ./scripts/format.sh --check
+
   # == CHECK == #
   check:
     name: Check nightly stable and MSRV
@@ -204,6 +222,7 @@ jobs:
     needs:
       - check-nostd
       - check
+      - check-formatting
       - check-features
       - build-and-test
       # the proc-macro dep, when version-bumped, will make this fail.

.rustfmt.toml

@@ -0,0 +1,20 @@
+unstable_features = true
+
+comment_width = 100
+edition = "2024"
+fn_params_layout = "Vertical"
+format_code_in_doc_comments = true
+group_imports = "StdExternalCrate"
+imports_granularity = "Item"  # No more `git` conflicts around these.
+match_arm_leading_pipes = "Always"
+match_block_trailing_comma = true
+reorder_impl_items = false
+skip_macro_invocations = [
+    "quote", "quote_spanned",
+    "parse_quote", "parse_quote_spanned",
+    "squote", "squote_spanned",
+    "Quote",
+    "bail",
+]
+use_field_init_shorthand = true
+wrap_comments = true

.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "editor.formatOnSave": true,
+    "[toml]": {
+        "editor.formatOnSave": false
+    }
+}

Cargo.toml

@@ -28,8 +28,6 @@ nightly = []
 alloc = []
 std = ["alloc", "scopeguard/use_std", "stabby?/std"]
 
-proc_macros = [] # Deprecated
-
 async-fn = ["safer_ffi-proc_macros/async-fn"]
 
 debug_proc_macros = ["safer_ffi-proc_macros/verbose-expansions"]
@@ -70,6 +68,7 @@ internal-tests = [
     "headers",
     "python-headers",
     "dyn-traits",
+    "stabby",
     "tokio/rt-multi-thread",
 ]
 
@@ -152,6 +151,10 @@ members = [
     "napi-dispatcher/wasm",
     "napi-dispatcher/wasm/src/proc_macros",
     "safer-ffi-build",
+    "run-sh",
+]
+default-members = [
+    ".",
 ]
 exclude = ["examples/point"]
 

README.md

@@ -324,6 +324,8 @@ Point { x: 42.0, y: 42.0 }
 
 ## Development
 
+<details><summary>Click to see</summary>
+
 To test the code with a certain amount of FFI integration baked into the tests (since `safer-ffi`,
 alone, only _exports_ APIs to the FFI, so doesn't come with FFI callsites on its own), the
 `ffi_tests/` project directory is used to test against C, C#, and Lua callsites.
@@ -336,6 +338,34 @@ make -C ffi_tests
 
 or by adding `--features ffi-tests` to the `cargo test` command.
 
+### Formatting
+
+Code is formatted using the "`{MSRV}-nightly` toolchain". That is, formatting uses some `unstable`
+features of `rustfmt`, so we use a Versioned Nightly™ approach. For the sake of version consistency,
+we stick to that of our MSRV.
+
+But since it needs to be a genuine `nightly` toolchain, we are forced to pick an actual `nightly`
+toolchain, only one whose date matches the birth of the corresponding `MSRV`-stable toolchain.
+
+  - See [`./scripts/formatting/rust-toolchain.toml`](./scripts/formatting/rust-toolchain.toml).
+  - See also, w.r.t. versions and dates: https://releases.rs
+
+To format the code, you have three options:
+
+  - `./scripts/format.sh`
+
+  - `cargo fmt-nightly` (which is defined as an alias of the previous bullet)
+
+  - `cargo fmt` but only after having run `./scripts/formatting/setup_cargo_fmt_override.sh` at
+    least once.
+
+    This does mutate a bit your `rustup` setup, but in an unobservable way (but for allowing the
+    matching stable toolchain to use `unstable` features when running `cargo fmt`, the very point
+    of this maneuver).
+
+    This is probably the preferred approach for those with IDEs or whatnot which automagically runs
+    `cargo fmt`/`rustfmt` on save.
+
 ### Dependencies
 
   - #### Lua dependencies
@@ -380,3 +410,5 @@ make -C js_tests
 wasm-pack build --target web && python3 -m http.server 13337
 
 ```
+
+</details>

examples/point/src/lib.rs

@@ -12,21 +12,24 @@ pub struct Point {
 /* Export a Rust function to the C world. */
 /// Returns the middle point of `[a, b]`.
 #[ffi_export]
-fn mid_point(a: &Point, b: &Point) -> Point {
+fn mid_point(
+    a: &Point,
+    b: &Point,
+) -> Point {
     Point {
         x: (a.x + b.x) / 2.,
         y: (a.y + b.y) / 2.,
     }
 }
 
 /* Export a Rust enum to C */
-#[ffi_export] // directly exporting a type is only needed
-              // if no exported function mentions it
+#[ffi_export] /* directly exporting a type is only needed
+.                if no exported function mentions it */
 #[derive_ReprC]
 #[repr(u8)]
 pub enum Figure {
-	Circle,
-	Square
+    Circle,
+    Square,
 }
 
 /// Pretty-prints a point using Rust's formatting logic.