Creating and Running a Rust Project with Cargo on macOS

Hello! This first module establishes the Rust tools and language features you will use throughout the course. Later modules will put them to work in a local backend API; for now, the aim is more concrete: create a binary project on macOS, compile it, and run it from the shell.

By the end of this lesson, you should know which files Cargo creates, where the executable goes, and what changes when you edit the source code. Allow roughly 40 minutes, though installing the toolchain can take longer.

Install the toolchain

Rust programs are compiled: your source code must be turned into an executable before the shell can run it. The tools you need are rustc, the compiler; Cargo, which creates projects and coordinates builds; and rustup, which installs and updates the toolchain.

In macOS Terminal, run the installation command from that page and follow its prompts:

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

The command downloads an installer and passes it to the shell, so use the official page above to confirm the command before running it. When installation finishes, open a new Terminal window and check the tools:

rustc --version
cargo --version
rustup --version

Each command should print a version. If Terminal reports command not found, first reopen Terminal: the installer’s change to your shell’s PATH may not have taken effect in the old session. If you later encounter a macOS error about missing developer tools while building, install Apple’s command-line tools with xcode-select --install, then retry.

Create a binary project

Cargo gives a program a predictable layout. Watch this short demonstration for the relationship between the command you type, the directory it creates, and the files inside that directory. The presenter’s project name and operating system differ from yours; follow the macOS commands below for your own project.

Choose a directory for your practice projects. These commands create one under your home directory, create a Rust project inside it, and enter that project:

mkdir -p ~/rust-practice
cd ~/rust-practice
cargo new hello_cargo
cd hello_cargo
ls -a

cargo new hello_cargo creates a binary project by default: a program with an executable entry point. You should see Cargo.toml and src; you may also see Git files. Inspect the two files that matter immediately:

cat Cargo.toml
cat src/main.rs

Cargo.toml is the project’s manifest. It records the package name, version, Rust edition, and a place for dependencies; you do not need to change it yet. src/main.rs contains the program’s entry point. Its generated code should resemble:

fn main() {
    println!("Hello, world!");
}

For now, read fn main() as “the function where this program starts.” println! prints a line to the terminal; the exclamation mark is part of its name because it is a Rust macro. We will examine Rust syntax more carefully in the next lesson.

Build, then run

From inside hello_cargo, Cargo can compile the source into a macOS executable. The Rust book shows both the direct executable path and the shorter everyday command.

Now build the project:

cargo build

Cargo should report a successful build. It places the development executable at target/debug/hello_cargo, not alongside Cargo.toml. Run that compiled file directly:

./target/debug/hello_cargo

You should see Hello, world!. The leading ./ tells the shell to run a file at the specified relative path.

Most of the time, you will use one command instead of building and running separately:

cargo run

Cargo builds if necessary and then runs the executable. If nothing has changed since the last build, it can reuse the existing build. You may also notice a new Cargo.lock file in the project root: Cargo generates it to record exact dependency versions. Leave it to Cargo to manage.

See the edit–compile–run cycle

Open src/main.rs in any text editor and change only the printed message:

fn main() {
    println!("Hello from Cargo!");
}

Save the file, then run:

cargo check
cargo run

cargo check asks whether the updated source can compile, without producing a new executable. cargo run then compiles the change and executes it, so the terminal should print Hello from Cargo!. If you ran the old file in target/debug after cargo check but before cargo run, it would still print the old message: checking source code does not update a compiled binary.

That distinction is the core workflow. When editing, use cargo check for quick compiler feedback. Use cargo run when you want to see the program behave, or cargo build when you specifically want an up-to-date executable to run yourself.

Where this leaves you

You can now install and verify Rust’s tools on macOS, create a Cargo binary project, locate its source and manifest, and compile and run its executable. Cargo will remain the standard way you build the command-line programs in this module and, later, the local API server.

Next, you will start changing more than a printed message: you will declare values using Rust’s immutable and mutable bindings, with both inferred and explicit types.