Skip to main content
May 6, 2021
Uncategorized

Announcing Rust for Windows v0.9

Rust for Windows v0.9 has recently been released and includes full consumption support, along with several other updates! With completed consumption support, you can now call any Windows APIs (past, present, and future) using the Rust language projection. Rust developers have access to the entire Windows API surface in a language-idiomatic way, allowing them to easily take advantage of the power and breadth of Windows development. 

Along with this latest release, we have added new content to Microsoft Docs on developing with Rust on Windows. There is also a new Getting Started video for those who want to dive in! For more information on the project, check out the Rust for Windows Github repo.

Updates and Improvements

We have made great progress since last year’s Rust/WinRT public preview announcement, with continued improvements and investment in the project. Some of the changes and updates since this last announcement include:

  • Added support for Win32 and COM APIs, unifying the Windows APIs available for consumption via the windows crate. The addition of these APIs is enabled by the win32metadata project. With this increased coverage and unification of Windows APIs, we changed the name of the project from “Rust/WinRT” to “Rust for Windows”.
  • Added several examples to the Rust for Windows repo, demonstrating how to call a wide range of Windows APIs (includes Win32, COM, and WinRT APIs).
  • The windows crate is published on crates.io and is now dual-licensed under MIT or Apache. 
  • The windows crate now uses generated bindings rather than hand-written bindings internally.
  • The windows crate now builds on Linux.
  • Many improvements and fixes for Win32 APIs, such as support for array types, a variety of string types, and updated metadata. 
  • Added more natural and idiomatic support for COM interfaces such as with return values, and support for additional APIs involving things like C-style unions and nested types. 
  • Improved build times and error handling.
  • Original API case is now preserved, which will affect existing code using the windows crate.
  • Transformed QueryInterface-like functions into generic functions, making it safer and more convenient to call many COM-related functions.

For more details and a more comprehensive list of updates, look at the changelog on the Rust for Windows repo.

A simple example: Win32 APIs in Rust

We have recently added support for calling Win32 APIs in Rust, so I will walk through a simple example calling the MessageBox function. First make sure you have your Rust development environment set up, which you can do by following these docs. The code for this example can also be found here. 

To begin, I created a new Rust project by running the following command in a command prompt: 

C:\sample>cargo new message_box

This creates a new directory with the starter files for my Rust project. Navigate to this new directory, and create a nested bindings crate using the command below to house the generated bindings. By doing this, the build can cache the results of any imported bindings. 

C:\sample\message_box>cargo new --lib bindings

Now opening my project in Visual Studio Code, the directory structure looks like this.

In the outer Cargo.toml file directly under the message_box directory, add the following dependency which tells Cargo that it now depends on the newly created bindings library.

[dependencies]
bindings = {path = "bindings"}

Now in the Cargo.toml file underneath the bindings folder, add the following dependencies to add the windows crate. This will allow Cargo to download, build, and cache Windows support as a package.

[dependencies]
windows = "0.9.1"

[build-dependencies]
windows = "0.9.1"

Next, in Visual Studio Code I created a new file directly under the bindings folder named build.rs. In this file, use the windows::build macro to specify the types that you want to use as shown below. You can list any additional APIs you want to use in this build script. The windows crate will then generate the necessary bindings directly from metadata.

// build.rs
fn main() {
    windows::build!(
    Windows::Win32::WindowsAndMessaging::MessageBoxA
    );
}

Next in the lib.rs file under bindings/src, remove the default code and add the following line, which includes the source code generated by build.rs.

windows::include_bindings!();

In the main.rs file, you can now make use of any of the specified Windows APIs. Paste the following code, which creates a message box with a “Hello World” message. Note that any Win32 functions and COM interface methods should be marked unsafe.

use bindings::Windows::Win32::WindowsAndMessaging::{MessageBoxA,  MESSAGEBOX_STYLE};
 
fn main() {
    unsafe {
        MessageBoxA(None, "Hello", "World", MESSAGEBOX_STYLE::MB_OK);
    }
}

Run cargo build and then cargo run on a command prompt from the root directory of the sample, and you will see the following output!

Get started today

We are excited about all the new improvements and capabilities with the latest Rust for Windows update. Get started today with developing Rust applications on Windows (and for Windows) with the latest documentation on Microsoft Docs. For a hands-on tutorial check out this Getting Started video created by Kenny Kerr.


Closing

We have made great progress with Rust for Windows over the last year, and we are continuing to invest in the project to make building Windows apps easy for Rust developers. Up next, we are working on Rust authoring support both for COM interfaces and WinRT components, so stay tuned. We encourage you to reach out with any issues, feedback, or questions on the Rust for Windows Github repo!