Rollup merge of rust-lang#118749 - ChrisDenton:winsys, r=cuviper

Make contributing to windows bindings easier

This PR does three things:

- Automatically sorts bindings so contributors don't have to. I should have done this to begin with but was lazy.
- Renames `windows_sys.lst` to `bindings.txt`. This [matches the windows-rs repository](https://github.com/microsoft/windows-rs/blob/8e71051ea8a57594478e585d2740126893f9dbb7/crates/tools/sys/bindings.txt) (and repos that copy it). I believe consistency with other projects helps get people orientated.
- Adds a `README.md` file explaining what this is about and how to add bindings. This has the benefit of being directly editable and it's rendered when viewed online. Also people are understandably jumping right into the `windows_sys.rs` file via ripgrep or github search and so missing that it's generated. A `README.md` alongside it is at least slightly more obvious in that case. There is still a small note at the top of `windows_sys` in case people do read from the beginning.

None of this has any impact on the actual code generated. It's purely to make the new contributors workflow a bit nicer.

Author: matthiaskrgr

library/std/src/sys/pal/windows/c/README.md

@@ -0,0 +1,9 @@
+The `windows_sys.rs` file is autogenerated from `bindings.txt` and must not
+be edited manually.
+
+To add bindings, edit `bindings.txt` then regenerate using the following command:
+
+    ./x run generate-windows-sys && ./x fmt library/std
+
+If you need to override generated functions or types then add them to
+`library/std/src/sys/pal/windows/c.rs`.

library/std/src/sys/pal/windows/c/windows_sys.lst renamed to library/std/src/sys/pal/windows/c/bindings.txt

@@ -1,7 +1,6 @@
 --out windows_sys.rs
 --config flatten std
 --filter
-// tidy-alphabetical-start
 !Windows.Win32.Foundation.INVALID_HANDLE_VALUE
 Windows.Wdk.Storage.FileSystem.FILE_COMPLETE_IF_OPLOCKED
 Windows.Wdk.Storage.FileSystem.FILE_CONTAINS_EXTENDED_CREATE_INFORMATION
@@ -2592,5 +2591,3 @@ Windows.Win32.System.Threading.WakeAllConditionVariable
 Windows.Win32.System.Threading.WakeConditionVariable
 Windows.Win32.System.WindowsProgramming.PROGRESS_CONTINUE
 Windows.Win32.UI.Shell.GetUserProfileDirectoryW
-// tidy-alphabetical-end
-

library/std/src/sys/pal/windows/c/windows_sys.rs

@@ -1,9 +1,3 @@
-// This file is autogenerated.
-//
-// To add bindings, edit windows_sys.lst then use `./x run generate-windows-sys` to
-// regenerate the bindings.
-//
-// ignore-tidy-filelength
 // Bindings generated by `windows-bindgen` 0.52.0
 
 #![allow(non_snake_case, non_upper_case_globals, non_camel_case_types, dead_code, clippy::all)]
@@ -4351,3 +4345,4 @@ impl ::core::clone::Clone for XSAVE_FORMAT {
         *self
     }
 }
+// ignore-tidy-filelength

src/tools/generate-windows-sys/src/main.rs

@@ -1,34 +1,49 @@
 use std::env;
 use std::error::Error;
 use std::fs;
-use std::io::{self, Read, Seek, Write};
+use std::io::{Read, Seek, SeekFrom, Write};
 use std::path::PathBuf;
 
-/// This is printed to the file before the rest of the contents.
-const PRELUDE: &str = r#"// This file is autogenerated.
-//
-// To add bindings, edit windows_sys.lst then use `./x run generate-windows-sys` to
-// regenerate the bindings.
-//
-// ignore-tidy-filelength
-"#;
-
 fn main() -> Result<(), Box<dyn Error>> {
     let mut path: PathBuf =
         env::args_os().nth(1).expect("a path to the rust repository is required").into();
     path.push("library/std/src/sys/pal/windows/c");
     env::set_current_dir(&path)?;
 
-    let info = windows_bindgen::bindgen(["--etc", "windows_sys.lst"])?;
+    sort_bindings("bindings.txt")?;
+
+    let info = windows_bindgen::bindgen(["--etc", "bindings.txt"])?;
     println!("{info}");
 
-    // add some gunk to the output file.
-    let mut f = fs::File::options().read(true).write(true).open("windows_sys.rs")?;
+    let mut f = std::fs::File::options().append(true).open("windows_sys.rs")?;
+    writeln!(&mut f, "// ignore-tidy-filelength")?;
+
+    Ok(())
+}
+
+fn sort_bindings(file_name: &str) -> Result<(), Box<dyn Error>> {
+    let mut f = fs::File::options().read(true).write(true).open(file_name)?;
     let mut bindings = String::new();
     f.read_to_string(&mut bindings)?;
-    f.seek(io::SeekFrom::Start(0))?;
-    f.write_all(PRELUDE.as_bytes())?;
-    f.write_all(bindings.as_bytes())?;
+    f.set_len(0)?;
+    f.seek(SeekFrom::Start(0))?;
 
+    let mut lines = bindings.split_inclusive('\n');
+    for line in &mut lines {
+        f.write(line.as_bytes())?;
+        if line.contains("--filter") {
+            break;
+        }
+    }
+    let mut bindings = Vec::new();
+    for line in &mut lines {
+        if !line.trim().is_empty() {
+            bindings.push(line);
+        }
+    }
+    bindings.sort_by(|a, b| a.to_lowercase().cmp(&b.to_lowercase()));
+    for line in bindings {
+        f.write(line.as_bytes())?;
+    }
     Ok(())
 }