feat: Implement support for link type 'raw-dylib' on Windows

[doxblek]

Hi,

I am creating a Node Addon in Rust. For several reasons, I don't want to use a sophisticated solution like napi.rs, but generate Rust bindings for the Node API using bindgen on my own.

To make it run on Windows, it is necessary to provide an import library for symbols that are resolved only at runtime (such as the napi_* functions and types of the Node API.
In the Rust documentation, I noticed the raw-dylib kind of the #[link] attribute, which in addition to the +verbatim modifier (which allows me to set the library to link against "node.exe" instead of "node.dll") perfectly fits to my use case, because it auto-generates the needed import library. By that I don't need to deal will linker flags etc.

Unfortunately, bindgen currently does not support to emit #[link] attributes of that kind – though I found a related issue.

Therefore, I decided to contribute the feature. As I am new to the code base of bindgen, I closely related my feature to the existing --wasm-import-module-name flag which similarly provides a #[link] attribute.

Changes

Builder

I added a function windows_link_as_raw_dylib() to the builder, that takes the module name (similar to --wasm-import-module-name) and a boolean flag whether the module name should be treated verbatim.

The unsafe extern "C" block of a function is then provided with the attribute depending on the value of verbatim:

// verbatim == false
#[cfg_attr(windows, link(name = "<name>", kind = "raw-dylib"))]
unsafe extern "C" {
    pub fn my_function();
}

// verbatim == true
#[cfg_attr(windows, link(name = "<name>", kind = "raw-dylib", modifiers = "+verbatim"))]
unsafe extern "C" {
    pub fn my_function();
}

The attribute is set to only affect builds on Windows, because the "raw-dylib" feature is only supported on Windows (see Rust Documentation

Commandline Options

I added two options:

• --windows-link-as-raw-dylib enables the linking with the "raw-dylib" kind and takes the name of the DLL/EXE. By its own, it does not treat the name verbatim
• --windows-link-as-raw-dylib-verbatim can be set in addition to make the name specified in --windows-link-as-raw-dylib be treated verbatim. The flag must not be set without --windows-link-as-raw-dylib. This is ensure via clap.

Tests

I added two tests:

• windows-raw-dylib tests the new feature with verbatim set to false
• windows-raw-dylib-verbatim tests the new feature with verbatim set to true

I am happy about your feedback and look forward to get this landed :)

resolves #2833

[doxblek]

r? @emilio @pvdrz

[rustbot]

Error: The feature assign is not enabled in this repository.
To enable it add its section in the triagebot.toml in the root of the repository.

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #t-infra on Zulip.

[emilio]

Thanks, looks reasonable. A couple questions :)

[emilio]

Let's just add both attributes rather than panicking if the user requests it. It also makes the code simpler.

So:

let mut link_attribute = quote!{};
if let Some(ref wasm_name) = ctx.options.wasm_import_module_name {
  link_attribute.extend(quote! { #[link(...)] });
}
if let Some(ref win_raw_dylib) = ... {
  ...
}

[doxblek]

Hi Emilio,

I agree! In retrospective, the generated bindings may be wanted to be used both on WASM and Windows. This would not be possible with my original proposal.

ab95fd0

[emilio]

What other modifiers are there? Should we support them?

[doxblek]

Hi Emilio,

thank you for the feedback! Referring to the Rust Documentation for External Blocks, there are three modifiers that can be set:

1. +verbatim instructs the linker to treat the specified link name "as is". This means, that no platform-specific pre- or postfixes are added (e.g. "foo" would remain "foo" instead of being transformed into "libfoo.so" on Linux). As described in the PR description, this is especially handy, when attempting to link against an executable where the default semantics are not desired. verbatim is generally relevant for all platforms and build output types (staticlib, dylib, executable).
2. -bundle is only relevant for static linking. It prevents the Rust linker to directly attempt to link a library. Instead, a higher order build system at a later stage of the overall build must provide the static library. If this modifier is used in a non-static-linking context, a compilation error is thrown.
3. +whole-archive instructs the linker to not only include the symbols required via the extern block, but all. So for example, if a library provides the symbols Foo, Bar and Baz, and in my extern block I only declare Foo and Bar, without the modifier, Baz would be left out, whereas with the modifier, Baz would be part of the binary. It is only relevant for static linking, therefore, a compilation error is thrown if it is used in a non-static-linking context as well.

With this PR, I want to specifically improve the dynamic linking use case on Windows. Therefore, I would not include modifier 2 and 3 (at least in this PR).
Now that I think about it, I am however not opposed to generalize the support for the verbatim modifier, as this is probably not exclusively relevant for Windows.

Now that you have a bit more context, what is your opinion on moving ahead?