From 53c55151e267475793c3cd161ecb8cc39e439cd9 Mon Sep 17 00:00:00 2001 From: Kenny Kerr Date: Tue, 5 Sep 2023 11:02:23 -0500 Subject: [PATCH] readme --- crates/libs/bindgen/Cargo.toml | 2 +- crates/libs/bindgen/readme.md | 88 +++++++++++++++++++++++++++++++++ crates/libs/core/Cargo.toml | 2 +- crates/libs/core/readme.md | 88 +++++++++++++++++++++++++++++++++ crates/libs/metadata/Cargo.toml | 1 + crates/libs/metadata/readme.md | 88 +++++++++++++++++++++++++++++++++ crates/libs/sys/Cargo.toml | 2 +- crates/libs/sys/readme.md | 88 +++++++++++++++++++++++++++++++++ crates/libs/targets/Cargo.toml | 2 +- crates/libs/targets/readme.md | 88 +++++++++++++++++++++++++++++++++ crates/libs/windows/Cargo.toml | 2 +- crates/libs/windows/readme.md | 88 +++++++++++++++++++++++++++++++++ crates/tests/readme/src/lib.rs | 7 ++- docs/readme.md | 83 +------------------------------ 14 files changed, 541 insertions(+), 88 deletions(-) create mode 100644 crates/libs/bindgen/readme.md create mode 100644 crates/libs/core/readme.md create mode 100644 crates/libs/metadata/readme.md create mode 100644 crates/libs/sys/readme.md create mode 100644 crates/libs/targets/readme.md create mode 100644 crates/libs/windows/readme.md diff --git a/crates/libs/bindgen/Cargo.toml b/crates/libs/bindgen/Cargo.toml index 88c160471a..f814d8bf66 100644 --- a/crates/libs/bindgen/Cargo.toml +++ b/crates/libs/bindgen/Cargo.toml @@ -7,7 +7,7 @@ rust-version = "1.56" license = "MIT OR Apache-2.0" description = "Windows metadata compiler" repository = "https://github.com/microsoft/windows-rs" -readme = "../../../docs/readme.md" +readme = "readme.md" [package.metadata.docs.rs] default-target = "x86_64-pc-windows-msvc" diff --git a/crates/libs/bindgen/readme.md b/crates/libs/bindgen/readme.md new file mode 100644 index 0000000000..0090ad77dc --- /dev/null +++ b/crates/libs/bindgen/readme.md @@ -0,0 +1,88 @@ +## Rust for Windows + +The [windows](https://crates.io/crates/windows) and [windows-sys](https://crates.io/crates/windows-sys) crates let you call any Windows API past, present, and future using code generated on the fly directly from the [metadata describing the API](https://github.com/microsoft/windows-rs/tree/master/crates/libs/bindgen/default) and right into your Rust package where you can call them as if they were just another Rust module. The Rust language projection follows in the tradition established by [C++/WinRT](https://github.com/microsoft/cppwinrt) of building language projections for Windows using standard languages and compilers, providing a natural and idiomatic way for Rust developers to call Windows APIs. + +* [Getting started](https://kennykerr.ca/rust-getting-started/) +* [Samples](https://github.com/microsoft/windows-rs/tree/0.52.0/crates/samples) +* [Releases](https://github.com/microsoft/windows-rs/releases) + +Start by adding the following to your Cargo.toml file: + +```toml +[dependencies.windows] +version = "0.51" +features = [ + "Data_Xml_Dom", + "Win32_Foundation", + "Win32_Security", + "Win32_System_Threading", + "Win32_UI_WindowsAndMessaging", +] +``` + +Make use of any Windows APIs as needed: + +```rust,no_run +use windows::{ + core::*, Data::Xml::Dom::*, Win32::Foundation::*, Win32::System::Threading::*, + Win32::UI::WindowsAndMessaging::*, +}; + +fn main() -> Result<()> { + let doc = XmlDocument::new()?; + doc.LoadXml(h!("hello world"))?; + + let root = doc.DocumentElement()?; + assert!(root.NodeName()? == "html"); + assert!(root.InnerText()? == "hello world"); + + unsafe { + let event = CreateEventW(None, true, false, None)?; + SetEvent(event)?; + WaitForSingleObject(event, 0); + CloseHandle(event)?; + + MessageBoxA(None, s!("Ansi"), s!("Caption"), MB_OK); + MessageBoxW(None, w!("Wide"), w!("Caption"), MB_OK); + } + + Ok(()) +} +``` + +## windows-sys + +The `windows-sys` crate is a zero-overhead fallback for the most demanding situations and primarily where the absolute best compile time is essential. It only includes function declarations (externs), structs, and constants. No convenience helpers, traits, or wrappers are provided. + +Start by adding the following to your Cargo.toml file: + +```toml +[dependencies.windows-sys] +version = "0.48" +features = [ + "Win32_Foundation", + "Win32_Security", + "Win32_System_Threading", + "Win32_UI_WindowsAndMessaging", +] +``` + +Make use of any Windows APIs as needed: + +```rust,no_run +use windows_sys::{ + core::*, Win32::Foundation::*, Win32::System::Threading::*, Win32::UI::WindowsAndMessaging::*, +}; + +fn main() { + unsafe { + let event = CreateEventW(std::ptr::null(), 1, 0, std::ptr::null()); + SetEvent(event); + WaitForSingleObject(event, 0); + CloseHandle(event); + + MessageBoxA(0, s!("Ansi"), s!("Caption"), MB_OK); + MessageBoxW(0, w!("Wide"), w!("Caption"), MB_OK); + } +} +``` diff --git a/crates/libs/core/Cargo.toml b/crates/libs/core/Cargo.toml index 702cb9b6b7..7c4a333c56 100644 --- a/crates/libs/core/Cargo.toml +++ b/crates/libs/core/Cargo.toml @@ -7,7 +7,7 @@ rust-version = "1.56" license = "MIT OR Apache-2.0" description = "Rust for Windows" repository = "https://github.com/microsoft/windows-rs" -readme = "../../../docs/readme.md" +readme = "readme.md" categories = ["os::windows-apis"] [package.metadata.docs.rs] diff --git a/crates/libs/core/readme.md b/crates/libs/core/readme.md new file mode 100644 index 0000000000..0090ad77dc --- /dev/null +++ b/crates/libs/core/readme.md @@ -0,0 +1,88 @@ +## Rust for Windows + +The [windows](https://crates.io/crates/windows) and [windows-sys](https://crates.io/crates/windows-sys) crates let you call any Windows API past, present, and future using code generated on the fly directly from the [metadata describing the API](https://github.com/microsoft/windows-rs/tree/master/crates/libs/bindgen/default) and right into your Rust package where you can call them as if they were just another Rust module. The Rust language projection follows in the tradition established by [C++/WinRT](https://github.com/microsoft/cppwinrt) of building language projections for Windows using standard languages and compilers, providing a natural and idiomatic way for Rust developers to call Windows APIs. + +* [Getting started](https://kennykerr.ca/rust-getting-started/) +* [Samples](https://github.com/microsoft/windows-rs/tree/0.52.0/crates/samples) +* [Releases](https://github.com/microsoft/windows-rs/releases) + +Start by adding the following to your Cargo.toml file: + +```toml +[dependencies.windows] +version = "0.51" +features = [ + "Data_Xml_Dom", + "Win32_Foundation", + "Win32_Security", + "Win32_System_Threading", + "Win32_UI_WindowsAndMessaging", +] +``` + +Make use of any Windows APIs as needed: + +```rust,no_run +use windows::{ + core::*, Data::Xml::Dom::*, Win32::Foundation::*, Win32::System::Threading::*, + Win32::UI::WindowsAndMessaging::*, +}; + +fn main() -> Result<()> { + let doc = XmlDocument::new()?; + doc.LoadXml(h!("hello world"))?; + + let root = doc.DocumentElement()?; + assert!(root.NodeName()? == "html"); + assert!(root.InnerText()? == "hello world"); + + unsafe { + let event = CreateEventW(None, true, false, None)?; + SetEvent(event)?; + WaitForSingleObject(event, 0); + CloseHandle(event)?; + + MessageBoxA(None, s!("Ansi"), s!("Caption"), MB_OK); + MessageBoxW(None, w!("Wide"), w!("Caption"), MB_OK); + } + + Ok(()) +} +``` + +## windows-sys + +The `windows-sys` crate is a zero-overhead fallback for the most demanding situations and primarily where the absolute best compile time is essential. It only includes function declarations (externs), structs, and constants. No convenience helpers, traits, or wrappers are provided. + +Start by adding the following to your Cargo.toml file: + +```toml +[dependencies.windows-sys] +version = "0.48" +features = [ + "Win32_Foundation", + "Win32_Security", + "Win32_System_Threading", + "Win32_UI_WindowsAndMessaging", +] +``` + +Make use of any Windows APIs as needed: + +```rust,no_run +use windows_sys::{ + core::*, Win32::Foundation::*, Win32::System::Threading::*, Win32::UI::WindowsAndMessaging::*, +}; + +fn main() { + unsafe { + let event = CreateEventW(std::ptr::null(), 1, 0, std::ptr::null()); + SetEvent(event); + WaitForSingleObject(event, 0); + CloseHandle(event); + + MessageBoxA(0, s!("Ansi"), s!("Caption"), MB_OK); + MessageBoxW(0, w!("Wide"), w!("Caption"), MB_OK); + } +} +``` diff --git a/crates/libs/metadata/Cargo.toml b/crates/libs/metadata/Cargo.toml index f40b7c2b2f..3ebc9d24b0 100644 --- a/crates/libs/metadata/Cargo.toml +++ b/crates/libs/metadata/Cargo.toml @@ -7,6 +7,7 @@ rust-version = "1.64" license = "MIT OR Apache-2.0" description = "Windows metadata reader" repository = "https://github.com/microsoft/windows-rs" +readme = "readme.md" [package.metadata.docs.rs] default-target = "x86_64-pc-windows-msvc" diff --git a/crates/libs/metadata/readme.md b/crates/libs/metadata/readme.md new file mode 100644 index 0000000000..0090ad77dc --- /dev/null +++ b/crates/libs/metadata/readme.md @@ -0,0 +1,88 @@ +## Rust for Windows + +The [windows](https://crates.io/crates/windows) and [windows-sys](https://crates.io/crates/windows-sys) crates let you call any Windows API past, present, and future using code generated on the fly directly from the [metadata describing the API](https://github.com/microsoft/windows-rs/tree/master/crates/libs/bindgen/default) and right into your Rust package where you can call them as if they were just another Rust module. The Rust language projection follows in the tradition established by [C++/WinRT](https://github.com/microsoft/cppwinrt) of building language projections for Windows using standard languages and compilers, providing a natural and idiomatic way for Rust developers to call Windows APIs. + +* [Getting started](https://kennykerr.ca/rust-getting-started/) +* [Samples](https://github.com/microsoft/windows-rs/tree/0.52.0/crates/samples) +* [Releases](https://github.com/microsoft/windows-rs/releases) + +Start by adding the following to your Cargo.toml file: + +```toml +[dependencies.windows] +version = "0.51" +features = [ + "Data_Xml_Dom", + "Win32_Foundation", + "Win32_Security", + "Win32_System_Threading", + "Win32_UI_WindowsAndMessaging", +] +``` + +Make use of any Windows APIs as needed: + +```rust,no_run +use windows::{ + core::*, Data::Xml::Dom::*, Win32::Foundation::*, Win32::System::Threading::*, + Win32::UI::WindowsAndMessaging::*, +}; + +fn main() -> Result<()> { + let doc = XmlDocument::new()?; + doc.LoadXml(h!("hello world"))?; + + let root = doc.DocumentElement()?; + assert!(root.NodeName()? == "html"); + assert!(root.InnerText()? == "hello world"); + + unsafe { + let event = CreateEventW(None, true, false, None)?; + SetEvent(event)?; + WaitForSingleObject(event, 0); + CloseHandle(event)?; + + MessageBoxA(None, s!("Ansi"), s!("Caption"), MB_OK); + MessageBoxW(None, w!("Wide"), w!("Caption"), MB_OK); + } + + Ok(()) +} +``` + +## windows-sys + +The `windows-sys` crate is a zero-overhead fallback for the most demanding situations and primarily where the absolute best compile time is essential. It only includes function declarations (externs), structs, and constants. No convenience helpers, traits, or wrappers are provided. + +Start by adding the following to your Cargo.toml file: + +```toml +[dependencies.windows-sys] +version = "0.48" +features = [ + "Win32_Foundation", + "Win32_Security", + "Win32_System_Threading", + "Win32_UI_WindowsAndMessaging", +] +``` + +Make use of any Windows APIs as needed: + +```rust,no_run +use windows_sys::{ + core::*, Win32::Foundation::*, Win32::System::Threading::*, Win32::UI::WindowsAndMessaging::*, +}; + +fn main() { + unsafe { + let event = CreateEventW(std::ptr::null(), 1, 0, std::ptr::null()); + SetEvent(event); + WaitForSingleObject(event, 0); + CloseHandle(event); + + MessageBoxA(0, s!("Ansi"), s!("Caption"), MB_OK); + MessageBoxW(0, w!("Wide"), w!("Caption"), MB_OK); + } +} +``` diff --git a/crates/libs/sys/Cargo.toml b/crates/libs/sys/Cargo.toml index 3381da4ae0..b09cad7ef5 100644 --- a/crates/libs/sys/Cargo.toml +++ b/crates/libs/sys/Cargo.toml @@ -7,7 +7,7 @@ rust-version = "1.56" license = "MIT OR Apache-2.0" description = "Rust for Windows" repository = "https://github.com/microsoft/windows-rs" -readme = "../../../docs/readme.md" +readme = "readme.md" categories = ["os::windows-apis"] [package.metadata.docs.rs] diff --git a/crates/libs/sys/readme.md b/crates/libs/sys/readme.md new file mode 100644 index 0000000000..0090ad77dc --- /dev/null +++ b/crates/libs/sys/readme.md @@ -0,0 +1,88 @@ +## Rust for Windows + +The [windows](https://crates.io/crates/windows) and [windows-sys](https://crates.io/crates/windows-sys) crates let you call any Windows API past, present, and future using code generated on the fly directly from the [metadata describing the API](https://github.com/microsoft/windows-rs/tree/master/crates/libs/bindgen/default) and right into your Rust package where you can call them as if they were just another Rust module. The Rust language projection follows in the tradition established by [C++/WinRT](https://github.com/microsoft/cppwinrt) of building language projections for Windows using standard languages and compilers, providing a natural and idiomatic way for Rust developers to call Windows APIs. + +* [Getting started](https://kennykerr.ca/rust-getting-started/) +* [Samples](https://github.com/microsoft/windows-rs/tree/0.52.0/crates/samples) +* [Releases](https://github.com/microsoft/windows-rs/releases) + +Start by adding the following to your Cargo.toml file: + +```toml +[dependencies.windows] +version = "0.51" +features = [ + "Data_Xml_Dom", + "Win32_Foundation", + "Win32_Security", + "Win32_System_Threading", + "Win32_UI_WindowsAndMessaging", +] +``` + +Make use of any Windows APIs as needed: + +```rust,no_run +use windows::{ + core::*, Data::Xml::Dom::*, Win32::Foundation::*, Win32::System::Threading::*, + Win32::UI::WindowsAndMessaging::*, +}; + +fn main() -> Result<()> { + let doc = XmlDocument::new()?; + doc.LoadXml(h!("hello world"))?; + + let root = doc.DocumentElement()?; + assert!(root.NodeName()? == "html"); + assert!(root.InnerText()? == "hello world"); + + unsafe { + let event = CreateEventW(None, true, false, None)?; + SetEvent(event)?; + WaitForSingleObject(event, 0); + CloseHandle(event)?; + + MessageBoxA(None, s!("Ansi"), s!("Caption"), MB_OK); + MessageBoxW(None, w!("Wide"), w!("Caption"), MB_OK); + } + + Ok(()) +} +``` + +## windows-sys + +The `windows-sys` crate is a zero-overhead fallback for the most demanding situations and primarily where the absolute best compile time is essential. It only includes function declarations (externs), structs, and constants. No convenience helpers, traits, or wrappers are provided. + +Start by adding the following to your Cargo.toml file: + +```toml +[dependencies.windows-sys] +version = "0.48" +features = [ + "Win32_Foundation", + "Win32_Security", + "Win32_System_Threading", + "Win32_UI_WindowsAndMessaging", +] +``` + +Make use of any Windows APIs as needed: + +```rust,no_run +use windows_sys::{ + core::*, Win32::Foundation::*, Win32::System::Threading::*, Win32::UI::WindowsAndMessaging::*, +}; + +fn main() { + unsafe { + let event = CreateEventW(std::ptr::null(), 1, 0, std::ptr::null()); + SetEvent(event); + WaitForSingleObject(event, 0); + CloseHandle(event); + + MessageBoxA(0, s!("Ansi"), s!("Caption"), MB_OK); + MessageBoxW(0, w!("Wide"), w!("Caption"), MB_OK); + } +} +``` diff --git a/crates/libs/targets/Cargo.toml b/crates/libs/targets/Cargo.toml index 77e1cf5d45..fbbe66fa6d 100644 --- a/crates/libs/targets/Cargo.toml +++ b/crates/libs/targets/Cargo.toml @@ -8,7 +8,7 @@ rust-version = "1.56" license = "MIT OR Apache-2.0" description = "Import libs for Windows" repository = "https://github.com/microsoft/windows-rs" -readme = "../../../docs/readme.md" +readme = "readme.md" [target.'cfg(all(target_arch = "x86", target_env = "msvc", not(windows_raw_dylib)))'.dependencies] windows_i686_msvc = { path = "../../targets/i686_msvc", version = "0.52.0" } diff --git a/crates/libs/targets/readme.md b/crates/libs/targets/readme.md new file mode 100644 index 0000000000..0090ad77dc --- /dev/null +++ b/crates/libs/targets/readme.md @@ -0,0 +1,88 @@ +## Rust for Windows + +The [windows](https://crates.io/crates/windows) and [windows-sys](https://crates.io/crates/windows-sys) crates let you call any Windows API past, present, and future using code generated on the fly directly from the [metadata describing the API](https://github.com/microsoft/windows-rs/tree/master/crates/libs/bindgen/default) and right into your Rust package where you can call them as if they were just another Rust module. The Rust language projection follows in the tradition established by [C++/WinRT](https://github.com/microsoft/cppwinrt) of building language projections for Windows using standard languages and compilers, providing a natural and idiomatic way for Rust developers to call Windows APIs. + +* [Getting started](https://kennykerr.ca/rust-getting-started/) +* [Samples](https://github.com/microsoft/windows-rs/tree/0.52.0/crates/samples) +* [Releases](https://github.com/microsoft/windows-rs/releases) + +Start by adding the following to your Cargo.toml file: + +```toml +[dependencies.windows] +version = "0.51" +features = [ + "Data_Xml_Dom", + "Win32_Foundation", + "Win32_Security", + "Win32_System_Threading", + "Win32_UI_WindowsAndMessaging", +] +``` + +Make use of any Windows APIs as needed: + +```rust,no_run +use windows::{ + core::*, Data::Xml::Dom::*, Win32::Foundation::*, Win32::System::Threading::*, + Win32::UI::WindowsAndMessaging::*, +}; + +fn main() -> Result<()> { + let doc = XmlDocument::new()?; + doc.LoadXml(h!("hello world"))?; + + let root = doc.DocumentElement()?; + assert!(root.NodeName()? == "html"); + assert!(root.InnerText()? == "hello world"); + + unsafe { + let event = CreateEventW(None, true, false, None)?; + SetEvent(event)?; + WaitForSingleObject(event, 0); + CloseHandle(event)?; + + MessageBoxA(None, s!("Ansi"), s!("Caption"), MB_OK); + MessageBoxW(None, w!("Wide"), w!("Caption"), MB_OK); + } + + Ok(()) +} +``` + +## windows-sys + +The `windows-sys` crate is a zero-overhead fallback for the most demanding situations and primarily where the absolute best compile time is essential. It only includes function declarations (externs), structs, and constants. No convenience helpers, traits, or wrappers are provided. + +Start by adding the following to your Cargo.toml file: + +```toml +[dependencies.windows-sys] +version = "0.48" +features = [ + "Win32_Foundation", + "Win32_Security", + "Win32_System_Threading", + "Win32_UI_WindowsAndMessaging", +] +``` + +Make use of any Windows APIs as needed: + +```rust,no_run +use windows_sys::{ + core::*, Win32::Foundation::*, Win32::System::Threading::*, Win32::UI::WindowsAndMessaging::*, +}; + +fn main() { + unsafe { + let event = CreateEventW(std::ptr::null(), 1, 0, std::ptr::null()); + SetEvent(event); + WaitForSingleObject(event, 0); + CloseHandle(event); + + MessageBoxA(0, s!("Ansi"), s!("Caption"), MB_OK); + MessageBoxW(0, w!("Wide"), w!("Caption"), MB_OK); + } +} +``` diff --git a/crates/libs/windows/Cargo.toml b/crates/libs/windows/Cargo.toml index f50e677f1d..1a45392ece 100644 --- a/crates/libs/windows/Cargo.toml +++ b/crates/libs/windows/Cargo.toml @@ -9,7 +9,7 @@ license = "MIT OR Apache-2.0" description = "Rust for Windows" repository = "https://github.com/microsoft/windows-rs" documentation = "https://microsoft.github.io/windows-docs-rs/" -readme = "../../../docs/readme.md" +readme = "readme.md" categories = ["os::windows-apis"] [package.metadata.docs.rs] diff --git a/crates/libs/windows/readme.md b/crates/libs/windows/readme.md new file mode 100644 index 0000000000..0090ad77dc --- /dev/null +++ b/crates/libs/windows/readme.md @@ -0,0 +1,88 @@ +## Rust for Windows + +The [windows](https://crates.io/crates/windows) and [windows-sys](https://crates.io/crates/windows-sys) crates let you call any Windows API past, present, and future using code generated on the fly directly from the [metadata describing the API](https://github.com/microsoft/windows-rs/tree/master/crates/libs/bindgen/default) and right into your Rust package where you can call them as if they were just another Rust module. The Rust language projection follows in the tradition established by [C++/WinRT](https://github.com/microsoft/cppwinrt) of building language projections for Windows using standard languages and compilers, providing a natural and idiomatic way for Rust developers to call Windows APIs. + +* [Getting started](https://kennykerr.ca/rust-getting-started/) +* [Samples](https://github.com/microsoft/windows-rs/tree/0.52.0/crates/samples) +* [Releases](https://github.com/microsoft/windows-rs/releases) + +Start by adding the following to your Cargo.toml file: + +```toml +[dependencies.windows] +version = "0.51" +features = [ + "Data_Xml_Dom", + "Win32_Foundation", + "Win32_Security", + "Win32_System_Threading", + "Win32_UI_WindowsAndMessaging", +] +``` + +Make use of any Windows APIs as needed: + +```rust,no_run +use windows::{ + core::*, Data::Xml::Dom::*, Win32::Foundation::*, Win32::System::Threading::*, + Win32::UI::WindowsAndMessaging::*, +}; + +fn main() -> Result<()> { + let doc = XmlDocument::new()?; + doc.LoadXml(h!("hello world"))?; + + let root = doc.DocumentElement()?; + assert!(root.NodeName()? == "html"); + assert!(root.InnerText()? == "hello world"); + + unsafe { + let event = CreateEventW(None, true, false, None)?; + SetEvent(event)?; + WaitForSingleObject(event, 0); + CloseHandle(event)?; + + MessageBoxA(None, s!("Ansi"), s!("Caption"), MB_OK); + MessageBoxW(None, w!("Wide"), w!("Caption"), MB_OK); + } + + Ok(()) +} +``` + +## windows-sys + +The `windows-sys` crate is a zero-overhead fallback for the most demanding situations and primarily where the absolute best compile time is essential. It only includes function declarations (externs), structs, and constants. No convenience helpers, traits, or wrappers are provided. + +Start by adding the following to your Cargo.toml file: + +```toml +[dependencies.windows-sys] +version = "0.48" +features = [ + "Win32_Foundation", + "Win32_Security", + "Win32_System_Threading", + "Win32_UI_WindowsAndMessaging", +] +``` + +Make use of any Windows APIs as needed: + +```rust,no_run +use windows_sys::{ + core::*, Win32::Foundation::*, Win32::System::Threading::*, Win32::UI::WindowsAndMessaging::*, +}; + +fn main() { + unsafe { + let event = CreateEventW(std::ptr::null(), 1, 0, std::ptr::null()); + SetEvent(event); + WaitForSingleObject(event, 0); + CloseHandle(event); + + MessageBoxA(0, s!("Ansi"), s!("Caption"), MB_OK); + MessageBoxW(0, w!("Wide"), w!("Caption"), MB_OK); + } +} +``` diff --git a/crates/tests/readme/src/lib.rs b/crates/tests/readme/src/lib.rs index 221a1018e8..c89354cbc3 100644 --- a/crates/tests/readme/src/lib.rs +++ b/crates/tests/readme/src/lib.rs @@ -1 +1,6 @@ -#![doc = include_str!("../../../../docs/readme.md")] +#![doc = include_str!("../../../../crates/libs/bindgen/readme.md")] +#![doc = include_str!("../../../../crates/libs/core/readme.md")] +#![doc = include_str!("../../../../crates/libs/metadata/readme.md")] +#![doc = include_str!("../../../../crates/libs/sys/readme.md")] +#![doc = include_str!("../../../../crates/libs/targets/readme.md")] +#![doc = include_str!("../../../../crates/libs/windows/readme.md")] diff --git a/docs/readme.md b/docs/readme.md index 0090ad77dc..a3b7a807f2 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -3,86 +3,5 @@ The [windows](https://crates.io/crates/windows) and [windows-sys](https://crates.io/crates/windows-sys) crates let you call any Windows API past, present, and future using code generated on the fly directly from the [metadata describing the API](https://github.com/microsoft/windows-rs/tree/master/crates/libs/bindgen/default) and right into your Rust package where you can call them as if they were just another Rust module. The Rust language projection follows in the tradition established by [C++/WinRT](https://github.com/microsoft/cppwinrt) of building language projections for Windows using standard languages and compilers, providing a natural and idiomatic way for Rust developers to call Windows APIs. * [Getting started](https://kennykerr.ca/rust-getting-started/) -* [Samples](https://github.com/microsoft/windows-rs/tree/0.52.0/crates/samples) +* [Samples](https://github.com/microsoft/windows-rs/tree/master/crates/samples) * [Releases](https://github.com/microsoft/windows-rs/releases) - -Start by adding the following to your Cargo.toml file: - -```toml -[dependencies.windows] -version = "0.51" -features = [ - "Data_Xml_Dom", - "Win32_Foundation", - "Win32_Security", - "Win32_System_Threading", - "Win32_UI_WindowsAndMessaging", -] -``` - -Make use of any Windows APIs as needed: - -```rust,no_run -use windows::{ - core::*, Data::Xml::Dom::*, Win32::Foundation::*, Win32::System::Threading::*, - Win32::UI::WindowsAndMessaging::*, -}; - -fn main() -> Result<()> { - let doc = XmlDocument::new()?; - doc.LoadXml(h!("hello world"))?; - - let root = doc.DocumentElement()?; - assert!(root.NodeName()? == "html"); - assert!(root.InnerText()? == "hello world"); - - unsafe { - let event = CreateEventW(None, true, false, None)?; - SetEvent(event)?; - WaitForSingleObject(event, 0); - CloseHandle(event)?; - - MessageBoxA(None, s!("Ansi"), s!("Caption"), MB_OK); - MessageBoxW(None, w!("Wide"), w!("Caption"), MB_OK); - } - - Ok(()) -} -``` - -## windows-sys - -The `windows-sys` crate is a zero-overhead fallback for the most demanding situations and primarily where the absolute best compile time is essential. It only includes function declarations (externs), structs, and constants. No convenience helpers, traits, or wrappers are provided. - -Start by adding the following to your Cargo.toml file: - -```toml -[dependencies.windows-sys] -version = "0.48" -features = [ - "Win32_Foundation", - "Win32_Security", - "Win32_System_Threading", - "Win32_UI_WindowsAndMessaging", -] -``` - -Make use of any Windows APIs as needed: - -```rust,no_run -use windows_sys::{ - core::*, Win32::Foundation::*, Win32::System::Threading::*, Win32::UI::WindowsAndMessaging::*, -}; - -fn main() { - unsafe { - let event = CreateEventW(std::ptr::null(), 1, 0, std::ptr::null()); - SetEvent(event); - WaitForSingleObject(event, 0); - CloseHandle(event); - - MessageBoxA(0, s!("Ansi"), s!("Caption"), MB_OK); - MessageBoxW(0, w!("Wide"), w!("Caption"), MB_OK); - } -} -```