Installation and First Project

Purpose and Scope

This page orients a new Rust user who is following The Rust Programming Language from installation into their first local project. The repository itself points beginners to the Book’s Installation chapter as the quick-start path, rather than asking them to build this source tree. That distinction matters: rust-lang/rust is the implementation repository for the compiler, standard library, and documentation, while the beginner workflow starts with a released toolchain installed by rustup. Sources: README.md

The official Book describes rustup as the command-line tool for managing Rust versions and associated tools, and recommends installing the latest stable compiler for the examples in the Book. The Book also explains command-line notation: prompts such as $ or PowerShell’s > identify commands to type, while following lines show output. In practice, this means a first project begins in a terminal with the stable toolchain, then moves to a normal Cargo package rather than to this repository’s bootstrap system.

A beginner should treat the repository’s advanced documentation as a map for later, not as the first stop. The targeted source files in this page are from the Unstable Book, which documents nightly-only language features, compiler flags, and generated feature stubs. Those files are useful because they show the boundary between stable Rust used in the Book and specialized features that require explicit feature gates, target knowledge, or compiler flags. Sources: src/doc/unstable-book/src/language-features.md, src/tools/unstable-book-gen/src/main.rs

Beginner Workflow

Start by installing Rust through rustup. On Linux or macOS, the Book’s installation chapter uses the shell command below. The prompt character is shown for readability and is not typed as part of the command.

$ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh

After installation, use the stable toolchain for the Book unless you have a specific reason to do otherwise. The Book explicitly frames its examples around Rust’s stability guarantees: code that compiles in the tutorial should continue to compile on newer stable releases, even if diagnostics and warning text improve over time. This is the right mental model for a first project: learn language syntax, ownership, Cargo basics, and compiler feedback before reaching for nightly-only features.

The Book is also available offline when Rust is installed with rustup. Running rustup doc --book opens the local copy, which is useful when learning without relying on a browser session. The repository README reinforces this path by placing “Quick Start” before source-installation guidance and by linking directly to the Book’s Installation chapter. That ordering is intentional: installing a released toolchain is the supported first step for users, while building from source is a contributor or implementer task. Sources: README.md

Once the toolchain is installed, create a small package outside the compiler repository. A conventional first project is a Cargo binary package, because Cargo is Rust’s package manager and build tool and is the default way beginners compile, run, test, and later add dependencies. The current Book states that projects should use edition = "2024" in Cargo.toml for Rust 2024 idioms, so check the manifest that Cargo creates or update it when following the current text.

$ cargo new hello-rust
$ cd hello-rust
$ cargo run

The important first-project loop is edit, build, run, read diagnostics, and repeat. Cargo invokes rustc for you, so you do not need to learn every compiler flag on day one. When the compiler reports an error, treat the message as part of the learning interface; the repository README identifies “a compiler committed to providing great diagnostics” as one of Rust’s productivity advantages. This is why the first project should stay small: the beginner can connect source edits, compiler messages, and runtime output without also managing the compiler source tree. Sources: README.md

Core Primitives

The first primitive is the toolchain. In Rust documentation, this means the installed set of tools managed by rustup: the compiler, standard components, and related commands. The second primitive is the package, represented by a Cargo.toml manifest and a src directory in ordinary Rust projects. A beginner’s first project should be a package managed by Cargo, because that matches the Book’s workflow and gives a predictable structure for source files, builds, and examples.

The third primitive is the edition. Editions are compatibility boundaries that let Rust evolve while preserving older code. The Book version referenced by the official docs assumes Rust 1.90.0 or later and edition = "2024" in project manifests. For a first project, the edition is not a feature switch to experiment with; it is a declaration of which language idioms and compatibility mode the package uses. Keep it aligned with the tutorial you are reading.

The fourth primitive is stability. Stable Rust is the default channel for learning and production work, while nightly and unstable features are explicitly opt-in. The Unstable Book’s language-feature pages show what opt-in looks like: examples use crate attributes such as #![feature(...)], often alongside target-specific or no_std context. A beginner does not need these attributes to write a first program, and seeing them should be a signal that the page is documenting compiler experimentation rather than ordinary Book material. Sources: src/doc/unstable-book/src/language-features/abi-cmse-nonsecure-call.md, src/doc/unstable-book/src/language-features/abi-msp430-interrupt.md

Repository Signals for Stable Versus Advanced Rust

The README describes Rust as the main source repository containing the compiler, standard library, and documentation, and it points users to the website, Getting Started, Learn, Documentation, and Contributing. Its quick-start instruction is deliberately short: read “Installation” from the Book. That makes the README a routing document for beginners. It tells you where to start, and it prevents a common mistake: cloning rust-lang/rust and trying to build the compiler as if that were the normal way to install Rust. Sources: README.md

The Unstable Book sources show the other side of the documentation system. src/tools/unstable-book-gen/src/main.rs is a generator that collects language features, library features, compiler flags, and environment variables, then creates summary entries or stub pages for unstable features. This implementation detail explains why the unstable documentation has a catalog-like shape: it is synchronized with feature metadata and existing section files, not hand-maintained as a beginner tutorial. Sources: src/tools/unstable-book-gen/src/main.rs

The lang_items page is an advanced example of compiler-library cooperation. It explains that some operations are not hard-coded directly into the language but are provided by libraries with special #[lang = "..."] markers. The example implements pieces needed for Box in a freestanding #![no_std] program and defines panic and allocation hooks. This is valuable later for systems programming, but it is deliberately far beyond a first cargo run. Sources: src/doc/unstable-book/src/language-features/lang-items.md

The ABI feature pages make the same point through target-specific examples. abi_cmse_nonsecure_call documents an Arm TrustZone-M function ABI and shows assembly emitted for a thumbv8m target. abi_msp430_interrupt documents an MSP430 interrupt calling convention and an interrupt vector placement example. These are not installation prerequisites; they are specialized compiler capabilities for embedded and bare-metal work after the reader understands ordinary Rust packages. Sources: src/doc/unstable-book/src/language-features/abi-cmse-nonsecure-call.md, src/doc/unstable-book/src/language-features/abi-msp430-interrupt.md

Compact Reference

Relevant Source Files

• README.md — Routes new users to the official Book installation page, identifies this repository as the compiler, standard library, and documentation source tree, and distinguishes quick-start installation from source installation.
• src/doc/unstable-book/src/language-features/lang-items.md — Shows an advanced unstable language-feature topic involving #[lang = "..."], #![no_std], allocation, panic handling, and compiler-library integration.
• src/tools/unstable-book-gen/src/main.rs — Implements generation of Unstable Book summaries and stub pages from collected language features, library features, compiler flags, and environment variables.
• src/doc/unstable-book/src/compiler-flags/external-clangrt.md — Documents an unstable compiler flag affecting sanitizer runtime linking, illustrating that compiler flags are a later, specialized topic.
• src/doc/unstable-book/src/language-features.md — Provides the language-features section entry point for the Unstable Book.
• src/doc/unstable-book/src/language-features/abi-cmse-nonsecure-call.md — Documents the Arm TrustZone-M cmse-nonsecure-call ABI and includes a target-specific rustc assembly example.
• src/doc/unstable-book/src/language-features/abi-msp430-interrupt.md — Documents the MSP430 interrupt ABI and shows a target-specific interrupt handler placement example.

Next Steps

Follow the Book’s Chapter 1 installation flow first, then build and run a small Cargo package until the edit-compile-run loop feels routine. After that, continue through the Book for ownership, structs, enums, modules, and error handling. When you want to understand packages and manifests more deeply, move to the Cargo getting-started and manifests pages. When you are ready for embedded, no_std, custom ABIs, or nightly experiments, use the Unstable Book and embedded documentation as advanced companions rather than as the starting path.