rust-lang / rust-lang/reference

Incorrect information about `link` attribute on `extern` blocks

Open
#1,986 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-attributes
Dominant language
Rust
Stars
1.6k
Forks
607
PR merge metrics
PR metrics pending

Description

[items.extern.attributes.link.intro] states:

The link attribute specifies the name of a native library that the compiler should link with for the items within an extern block.

The incorrect part of this statement is for the items within an extern block. The link attribute seems to behave exactly like rustc-link-lib which just adds a linker argument to link against another library. The current wording in the reference implies that it will only try to link the items within that specific extern block to the library, but any external symbol could be resolved by that library.

Example

/// Empty extern block
#[link(name = "foo")]
unsafe extern "C" {}

/// Extern block with no `link`
unsafe extern "C" {
    /// This is a function in `libfoo`
    fn bar();
}

bar will be resolved with its implementation in the foo library, despite the link attribute being on a different extern block

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.

Research direction

Open the Rust Reference section linked at items.extern.attributes.link.intro and review the wording about the link attribute applying to items within an extern block. Use the provided empty extern-block example as the behavioral context; done means the reference no longer implies that linking is limited to symbols from that block.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.