#[link] attribute should better describe platform specific handling

Open
#638 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
45/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
rust
Domain
documentation

Research direction

Start at the Rust Reference documentation for the #[link] attribute and compare its current platform-specific name-resolution wording with issue #62588. Document the Windows, macOS, and Linux cases, including Rust-produced library pairs, so the required name is clear for each platform.

Written by the indexing model from the issue text.

Description

E-Easy New Content

When working cross platform, in particular when producing a dylib from Rust and then again consuming it, the current resolution of #[link(name = "mylib"] is somewhat confusing.

  • If you start developing on Windows, Rust will produce a mylib.dll and mylib.dll.lib. To use this lib again from Rust you will have to specify #[link(name = "mylib.dll")], thus giving the impression that the full file name has to be specified. On Mac, however, #[link(name = "libmylib.dylib"] will fail (likewise Linux).

  • If you start developing on Mac and Linux, #[link(name = "mylib")] just works, giving you the impression Rust handles the name resolution (fully) automatically like other platforms that just require the base name.

In fact, the correct way to cross platform link against a dylib produced by Rust seems to be:

#[cfg_attr(all(target_os = "windows", target_env = "msvc"), link(name = "dylib.dll"))]
#[cfg_attr(not(all(target_os = "windows", target_env = "msvc")), link(name = "dylib"))]
extern "C" {}

Since according to this issue the current behavior can't be fixed and is "stable", I believe this should be documented somewhere. For me, the #[link] attribute was where I started my debug journey originally.

The documentation could be something like:

Note that on Mac and Linux name is the base name of the actual library (e.g., #[link(name = "mylib")] if you want to link against libmylib.so). On Windows, the base name of the .lib file has to be provided.

For 3rd party libraries such as mylib.dll and mylib.lib, this still equals #[link(name = "mylib")], but for Rust produced library pairs mylib.dll and mylib.dll.lib a #[link(name = "mylib.dll")] is needed instead.

Update - Changed #[cfg_attr] to be more correctish ...

Dominant language
Rust
Stars
1.6k
Forks
607
Avg merge
1d 1h
Merged PRs (30d)
12

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from rust-lang/reference

All issues in rust-lang/reference

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.