Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
89b43dc
feat: Implement support for link type 'raw-dylib' on Windows
konradkoschel Jul 30, 2025
ab95fd0
chore: allow both wasm_import and raw-dylib
konradkoschel Aug 18, 2025
c86bcad
Merge branch 'main' into main
doxblek Aug 18, 2025
6d1c15e
chore: cargo fmt
konradkoschel Aug 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions bindgen-tests/tests/expectations/tests/windows-raw-dylib-verbatim.rs
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 5 additions & 0 deletions bindgen-tests/tests/expectations/tests/windows-raw-dylib.rs
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions bindgen-tests/tests/headers/windows-raw-dylib-verbatim.h
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
// bindgen-flags: --windows-link-as-raw-dylib foo.exe --windows-link-as-raw-dylib-verbatim

void test_function();
3 changes: 3 additions & 0 deletions bindgen-tests/tests/headers/windows-raw-dylib.h
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
// bindgen-flags: --windows-link-as-raw-dylib foolib

void test_function();
24 changes: 19 additions & 5 deletions bindgen/codegen/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4717,10 +4717,24 @@ impl CodeGenerator for Function {
// Unfortunately this can't piggyback on the `attributes` list because
// the #[link(wasm_import_module)] needs to happen before the `extern
// "C"` block. It doesn't get picked up properly otherwise
let wasm_link_attribute =
ctx.options().wasm_import_module_name.as_ref().map(|name| {
quote! { #[link(wasm_import_module = #name)] }
});
let link_attribute = match (
ctx.options().wasm_import_module_name.as_ref(),
&ctx.options().windows_link_as_raw_dylib,
) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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) = ... {
  ...
}

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

(Some(_), (Some(_), _)) => {
panic!("Cannot link against a wasm import module and a raw dylib at the same time");
}
(Some(name), (None, _)) => {
Some(quote! { #[link(wasm_import_module = #name)] })
}
(None, (Some(name), false)) => Some(
quote! { #[cfg_attr(windows, link(name = #name, kind = "raw-dylib"))] },
),
(None, (Some(name), true)) => Some(
quote! { #[cfg_attr(windows, link(name = #name, kind = "raw-dylib", modifiers = "+verbatim"))] },
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What other modifiers are there? Should we support them?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, so I guess my biggest concern is that this is a bit of a whack-a-mole. Looking at the link attr docs, it seems there could be use cases for virtually any link attribute (or combinations of them).

As such, maybe we could make this a bit more general?

Maybe extern_fn_block_attrs: Vec<String> or so? Then we'd just convert wasm_import_module_name() into this new model by using self.extern_fn_block_attrs.push(format!("#[wasm_import_module_name=\"{name}\"]")) or so, wdyt?

And accomplishing what you want can be done by using this new API.

),
_ => None,
};

let should_wrap = is_internal &&
ctx.options().wrap_static_fns &&
Expand Down Expand Up @@ -4774,7 +4788,7 @@ impl CodeGenerator for Function {
.then(|| quote!(unsafe));

let tokens = quote! {
#wasm_link_attribute
#link_attribute
#safety extern #abi {
#(#attributes)*
pub fn #ident ( #( #args ),* ) #ret;
Expand Down
15 changes: 15 additions & 0 deletions bindgen/options/cli.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -420,6 +420,12 @@ struct BindgenCommand {
/// The NAME to be used in a #[link(wasm_import_module = ...)] statement
#[arg(long, value_name = "NAME")]
wasm_import_module_name: Option<String>,
/// On Windows, link against NAME with kind `raw-dylib`.
#[arg(long, value_name = "NAME")]
windows_link_as_raw_dylib: Option<String>,
/// Do not append `.dll` suffix to the NAME provided to `--windows-link-as-raw-dylib`.
#[arg(long, requires = "windows_link_as_raw_dylib")]
windows_link_as_raw_dylib_verbatim: bool,
/// Use dynamic loading mode with the given library NAME.
#[arg(long, value_name = "NAME")]
dynamic_loading: Option<String>,
Expand Down Expand Up @@ -643,6 +649,8 @@ where
enable_function_attribute_detection,
use_array_pointers_in_arguments,
wasm_import_module_name,
windows_link_as_raw_dylib,
windows_link_as_raw_dylib_verbatim,
dynamic_loading,
dynamic_link_require_all,
prefix_link_name,
Expand Down Expand Up @@ -1083,6 +1091,13 @@ where
builder = builder.emit_diagnostics();
}

if let Some(windows_link_as_raw_dylib) = windows_link_as_raw_dylib {
builder = builder.windows_link_as_raw_dylib(
windows_link_as_raw_dylib,
windows_link_as_raw_dylib_verbatim,
);
}

Ok((builder, output, verbose))
}

Expand Down
28 changes: 28 additions & 0 deletions bindgen/options/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1908,6 +1908,34 @@ options! {
},
as_args: "--wasm-import-module-name",
},
/// On Windows, link with kind `raw-dylib`
windows_link_as_raw_dylib: (Option<String>, bool) {
methods: {
/// Adds the `#[cfg_attr(windows, link(name = "<dylib>", kind = "raw-dylib"))]` attribute to all the `extern`
/// blocks generated by `bindgen`.
///
/// This attribute is not added by default.
///
/// If `verbatim` is set to `true`, instead `#[cfg_attr(windows, link(name = "<dylib>", kind = "raw-dylib", modifiers = "+verbatim"))]` is used.
pub fn windows_link_as_raw_dylib<T: Into<String>>(
mut self,
dylib: T,
verbatim: bool,
) -> Self {
self.options.windows_link_as_raw_dylib = (Some(dylib.into()), verbatim);
self
}
},
as_args: |(dylib, verbatim), args| {
if let Some(dylib) = dylib {
args.push("--windows-link-as-raw-dylib".to_owned());
args.push(dylib.into());
if *verbatim {
args.push("--windows-link-as-raw-dylib-verbatim".to_owned());
}
}
},
},
/// The name of the dynamic library (if we are generating bindings for a shared library).
dynamic_library_name: Option<String> {
methods: {
Expand Down
Loading