Skip to content

Improve advice about installing a linker #2151

Closed
rust-lang/rust
#87312
@cormacrelf

Description

@cormacrelf

The book advises installing a linker. I would guess many new Rust users are unfamiliar with what a linker is, and unable to name one. Especially those coming from a dynamic language background. This paragraph stands out in the introductory chapters as by far the most jargony, and it's right near the beginning:

Additionally, you’ll need a linker of some kind. It’s likely one is already installed, but when you try to compile a Rust program and get errors indicating that a linker could not execute, that means a linker isn’t installed on your system and you’ll need to install one manually. C compilers usually come with the correct linker. Check your platform’s documentation for how to install a C compiler. Also, some common Rust packages depend on C code and will need a C compiler. Therefore, it might be worth installing one now.

Some issues:

  • Refers to the likelihood of errors while using Rust that are already incomprehensible if you don't know what a linker is
  • Does not name any linkers, or C compilers, that someone could actually act on this advice with. If they don't have one already, they probably can't name one, and will need this information to acquire one.
  • You shouldn't need to actually check your platform's documentation to accomplish this task. The information necessary for 99% of users to install a linker is shorter than this paragraph.
  • It pales in comparison to the Windows instructions, which links to the Build Tools for VS, and is done.
  • There is no code block after it, so readers are more likely to miss that it requires action on their part.

A suggested revision:

You will also need a linker, which is a program that Rust uses to join its compiled outputs into one file. It is likely you already have one, but to make sure, you should install a C compiler, which will typically include a linker. Also, some common Rust packages depend on C code and will need a C compiler. macOS users can acquire one with:

xcode-select --install

Linux users should generally install GCC or Clang, according to their distribution's documentation. For example, if you use Ubuntu, you can install the build-essential package.

Questions:

  • Does rustup run xcode-select --install?

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions