Remove `unimplemented!("Unsupported target OS");` to allow _running_ on Linux and WSL

[MarijnS95]

The "problem"

Currently the windows crate is allowed to compile on non-windows systems thanks to a rather large block of code, replicated across every function:

pub unsafe fn DxcCreateInstance2(...) -> Result {
    #[cfg(windows)]
    {
        #[link(name = "windows")]
        extern "system" {
            fn DxcCreateInstance2(...) -> ::windows::core::HRESULT;
        }
        let mut result__ = ::core::option::Option::None;
        DxcCreateInstance2(...).and_some(result__)
    }
    #[cfg(not(windows))]
    unimplemented!("Unsupported target OS");
}

I remember discussing this long ago: it was needed for CI but seems to have never been removed, as there wasn't much reason to run on non-windows anyway.

Rust is supposed to omit linkage when functions aren't used: any extern "system" { pub fn blah(); } doesn't show up in the symbol table if it isn't called into. However, this isn't the case for #[link]: -lwindows is added to the linker invocation even if no functions from the extern "system" block it is annotating are called.
That is evident in the windows-sys crate which doesn't carry any cfg(windows) around #[link] attributes: it is inconveniently used in the metadata crate that's subsequently used by all the tools, not allowing any of them to be ran on non-Windows (= note: mold: fatal: library not found: windows) even though they don't reference a single function, just some typedefs.

Proposed solution

Now, combine those two points and we can turn the above into:

pub unsafe fn DxcCreateInstance2(...) -> Result {
    #[cfg_attr(windows, link(name = "windows"))]
    extern "system" {
        fn DxcCreateInstance2(...) -> ::windows::core::HRESULT;
    }
    let mut result__ = ::core::option::Option::None;
    DxcCreateInstance2(...).and_some(result__)
}

(Dis)advantages

Disclaimer: most of the below applies to non-windows only, which perhaps still isn't "in scope" of the project - but I do hope we can discuss and consider this, especially in light of com-rs being officially deprecated! ¹

This is much shorter and simpler (multiplied by thousands of functions), but there's an obvious catch: whenever this function is used, even in conditional code (consider for example error.rs using various functions for retrieving and stringifying/prettifying Error), linking fails.

Perhaps that's (much) better than an unsuspecting unimplemented!() being reached in an optional codepath (e.g. Error handling).

However, there's an immediate solution too. And I've alluded to / requested this in earlier issues: define your own fallback.
(This goes anywhere in a user's codebase, could even be a dependent crate)

#[no_mangle]
pub extern "system" DxcCreateInstance2(...) -> ::windows::core::HRESULT {
    // My custom fallback implementation
}

(Badly chosen example, this'd be better on e.g. SysStringLen.)

Then the linker error is gone again, and the user has the ability to provide the necessary functions themselves at no additional design cost to windows-rs 🎉.

Proof of concept

You can find the end result here: https://github.com/MarijnS95/windows-rs/compare/simplify-cfg-windows (Showing 429 changed files with 71,379 additions and 157,268 deletions). As bonus this includes the same cfg_attr in windows-sys to allow running the tools on non-Windows.

Alternative (even smaller) approach

Perhaps this isn't necessary (read: remove the #[cfg(windows)] entirely) at all if a blanket libwindows.so is provided by the user, possibly built straight from a Rust crate with aforementioned fallback implementations. This can be done directly through cargo by providing a:

[package]
name = "windows-fallback"

[lib]
name = "windows"
crate-type = ["cdylib"]

Such a crate can be specified directly as a dependency in another crate even if no Rust symbols are referenced and it's not explicitly linked against: "windows-fallback" here still builds and its libwindows.so result ends up in a path that's already part of the search path to cover the automatically-inserted -lwindows 🎉 (may be a bit fragile to depend on though?).

That however doesn't provide a solution to the metadata/tools currently being only compilable on Windows, and I'm not suggesting to provide this crate within windows-rs!

Footnotes

1. I am of course again trying to find a proper, maintained, clean Rust alternative for DirectXShaderCompiler COM bindings. This is perhaps one of the few - or only? - binaries that has a functioning COM API outside of Windows. The proposed Quality-of-Life improvements will shorten generated code and allow me to use windows-rs outside of Windows at no additional maintenance cost here. ↩

[kennykerr]

I would love to simplify this. I think the current approach was originally proposed by @roblabla to support cross-compilation (e.g. targeting Windows from Linux) but if that still works with this change I'd love to go for it.

[MarijnS95]

It works, and I'm using it right now 🥳

@roblabla if you can test the linked branch and confirm whether this doesn't break your use-case, I'll wrap it up in a nice PR with the above summarized.

EDIT: That said we do have to think about the proposed "Alternative approach".
EDIT2: But as I mentioned there, it doesn't fix the tools not running outside Windows and that's a deal-breaker for me.

[riverar]

Hah, @kennykerr and I were talking about this during some recent GNU toolchain work. I don't think any of these configuration attributes are needed, for the reasons you stated (i.e. cross compilation targets windows).

[MarijnS95]

@riverar Right, @roblabla's case was cross-compiling IIRC, which does link against Windows libraries (how else can the cross-compiled result be functional?) so that'd warrant removal altogether? I'd have to re-read the original PR to understand what it was about again :)

[riverar]

EDIT2: But as I mentioned there, it doesn't fix the tools not running outside Windows and that's a deal-breaker for me.

What does this refer to? We support cross-compilation on macOS, Linux, and Windows today and those scenarios are tested in CI.

[kennykerr]

I think this is the original PR: #830

[MarijnS95]

@riverar The CI can build tests but it cannot run tool_sys, tool_bindings, or tool_windows, which is what my solution allows to do (== #[cfg_attr(windows, link(name = "windows"))]).

[riverar]

@MarijnS95 Oh those tools, got it. Thanks!

[MarijnS95]

I think this is the original PR: #830

It looks like this only moved the cfg from code-generation-time to runtime (more correct, yes); in reality this cfg shouldn't have been needed, do you know why it was in the generator back then?

Possibly for docs.rs? Perhaps this wasn't possible back then, but nowadays - and you're making use of it already:

windows-rs/crates/libs/windows/Cargo.toml

Lines 14 to 16 in b8d83c2

	[package.metadata.docs.rs]
	default-target = "x86_64-pc-windows-msvc"
	targets = []

[kennykerr]

It was to allow the Rust compiler devs (who didn't use Windows at the time) to build and profile the generated code. Specifically, profile the compiler while building and generating the code.

[MarijnS95]

@kennykerr Is that still ongoing? How do you think we should proceed?

1. #[cfg_attr(windows, link...)] everywhere, including windows-sys: that way compiler devs can test both crates especially given the "desire" to reuse windows-sys in windows (how most FFI crates are set up);
2. Drop the #[cfg(windows)] entirely; as long you're compiling but never linking (docs), or cross-compiling and linking for a target that's defined under crates/targets/ this'll work;
   • As mentioned above, running any tool_* requires linking!
   • As also mentioned above, this is the same lib I'd provide from user code to link my own "fallback implementations" in.
3. Do nothing, or perhaps only insert cfg_attr in windows-sys to be closer than windows.

In the end it comes down to what this project values most:

• For cross-compiling this #[cfg] isn't be necessary at all. It's only to build windows natively on/for a non-Windows OS.
• Help the few users who want to do exactly that: leverage windows-rs on non-Windows machines for their COM "infrastructure".
• Shorten the codebase a fair bit.

[kennykerr]

I suggest we just drop the cfg - thanks to @riverar we have cross compilation tests so that should be enough to validate we can target Windows, which is all that matters.

[MarijnS95]

I suggest we just drop the cfg

That seems reasonable, I can work around it with a custom library to link against. I can clean up the linked branch and open a PR with that.

which is all that matters.

Thanks (Microsoft in general) for trying so hard to make this crate unusable for me though, while at the same time pulling the plug on com-rs and deeming windows-rs to be its replacement.
While I can "work around" this library link "issue" (similar to how libwindows.a is provided currently - which is actually pretty neat) I'd like to open a followup issue to rediscuss possible minimal support for 32-bit widestrings in BSTR and P*WSTR but such statements make that attempt seem futile.

EDIT: IIRC the previous objection was the widestring crate (extra dependency in general and its dev-dependencies on winapi), but - also IIRC - there was still some leeway if the needed trivial functionality were implemented natively in windows-rs.

[kennykerr]

Thanks (Microsoft in general) for trying so hard to make this crate unusable for me though

I thought you said that would work for you. 😅 My understanding was that cross compilation was important to most folks and that dropping cfg wouldn't be a problem for you since the linker would only try to resolve imports for functions you're actually calling.

Perhaps I missed something, but its not because we're trying to make your life difficult. 😜