• Feature Name: raw_dylib_kind
• Start Date: 2019-01-22
• RFC PR: rust-lang/rfcs#2627
• Rust Issue: rust-lang/rust#58713

Summary

Extend

Motivation

Traditionally, to link against a dll, the program must actually link against an import library. For example to depend on some symbols from kernel32.dll the program links to kernel32.lib. However, this requires that the correct import libraries be available to link against, and for third party libraries that are only distributed as a dll creating an import library can be quite difficult, especially given

A real advantage of this feature, however, is the fact that symbols will be guaranteed

Sometimes, a crate may know exactly

This would also allow

Guide-level explanation

When trying to link to a Windows dll, the dylib kind may sometimes be unsuitable, and kind="raw-dylib" can be used instead. A central requirement of kind="raw-dylib" is that the dll has a stable ABI. Here are some examples of valid

• You've had it up to here with trying to create an import library for a dll that has stdcall functions.
• You're in linking hell with multiple
  複数の
  import libraries providing
  与える
  the same symbol but from different dlls.
• You know exactly
  正確に
  which dll you need a symbol from, but you don't know which version of the dll the import library is going to give you.
• You maintain winapi.

Here is an example of usage:

#![allow(unused)]
fn main() {
#[cfg(windows)]
#[link(name = "kernel32.dll", kind = "raw-dylib")]
#[allow(non_snake_case)]
extern "system" {
    fn GetStdHandle(nStdHandle: u32) -> *mut u8;
}
}

Some symbols are only exported by ordinal from the dll in which case #[link_ordinal(..)] may be used:

#![allow(unused)]
fn main() {
#[cfg(windows)]
#[link(name = "ws2_32.dll", kind = "raw-dylib")]
#[allow(non_snake_case)]
extern "system" {
    #[link_ordinal(116)]
    fn WSACleanup() -> i32;
}
}

Reference-level explanation

Add a new attribute #[link_ordinal] taking

Add a new possible value raw-dylib to the kind property

• If #[link_ordinal] is specified
  特定する、指定する、規定する
  the idata section
  節
  will map from the mangled symbol to the ordinal specified
  特定する、指定する、規定する
  in the dll.
• If #[link_name] is specified
  特定する、指定する、規定する
  the idata section
  節
  will map from the mangled symbol to the name specified
  特定する、指定する、規定する
  in the dll, without any calling
  呼び出し
  convention decorations added.
  たす
  If calling
  呼び出し
  convention decorations are desired they must be specified
  特定する、指定する、規定する
  explicitly
  明示的に
  in the value of the #[link_name] attribute.
• If both #[link_ordinal] and #[link_name] are specified,
  特定する、指定する、規定する
  an error will be emitted.
• If neither #[link_ordinal] nor #[link_name] are specified,
  特定する、指定する、規定する
  the idata section
  節
  will map from the mangled symbol to its unmangled equivalent
  等価
  in the dll. The unmangled symbol will not have calling
  呼び出し
  convention decorations.
• If #[no_mangle] is specified
  特定する、指定する、規定する
  an error will be emitted.

The idata section

Drawbacks

Additional

Rationale and alternatives

代わりのもの、選択肢

The RFC as proposed would allow

No alternatives

Prior art

Many non-native languages

Delphi is a native language

Unresolved questions

Whether there are any unresolved questions is an unresolved question.

Future possibilities

• With the features described
  記述する
  in this RFC, we would be one step closer towards a fully
  完全に
  standalone pure Rust target for Windows that does not rely on any external libraries (aside from the obvious and unavoidable runtime dependence on system libraries), allowing
  許可する、可能にする
  for easy installation and easy cross compilation.
  • If that were to happen, we'd no longer need to pretend the pc-windows-gnu toolchain is standalone, and we'd be able to stop bundling MinGW bits entirely in favor of the user's own MinGW installation, thereby resolving a bunch of issues such as rust-lang/rust#53454.
  • Also with that pure Rust target users would stop complaining about having to install several gigabytes of VC++ just to link their Rust binaries.
    ２進数
• A future extension of this feature would be the ability to optionally lazily load such external functions, since Rust would naturally have all the information required to do so. This would allow
  許可する、可能にする
  users to use functions that may not exist, and be able to write fallback code for older versions.
• Another future extension would be to extend
  拡張する
  this feature to support shared libraries on other platform, as they could also benefit from the ability to be more precise about linking. For example, on Linux and other platforms using ELF shared libraries, the compiler would emit an ELF NEEDED entry
  項目
  for the specified
  特定する、指定する、規定する
  shared library name, and an undefined symbol for each function declared.
  宣言
  (On ELF platforms, using the link_ordinal attribute would produce
  産出する
  an error.) On such platforms, the link_name attribute may also specify
  特定する、指定する、規定する
  a symbol name that includes a symbol version, including the @@.
  • Windows, however, should be the priority and figuring out details of support for other platforms should not block implementation
    実装
    and stabilization of this feature on Windows.