Skip to content

Improve advice about installing a linker #2151

Closed
rust-lang/rust
#87312

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?

Activity

  1. carols10cents commented on Jul 17, 2021

    @carols10cents
    Member

    Thanks! I've decided to largely take your suggestions, thank you.

  2. added a commit that references this issue on Jul 20, 2021
    b41936b
  3. added a commit that references this issue on Mar 11, 2024
    dd76781
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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