0.2 The First Incantation

The workshop is ready. That barely matters - readiness only establishes the silence. Some things exist only when they are named; in this workshop, naming is creating. The first incantation is always too short and always exact - it is the one that turns possibility into presence.

What You Need

The workshop is equipped, but tq does not exist yet. Not as a file, not as a project - at all. Before anything can be built, there must be a place to build it. In the Rust world, that place is a package - a directory with source code and a manifest that describes what is being built and what it is called.

The Build

cargo new creates a package. One command, and the structure is ready:

cargo new tq

Cargo confirms success:

     Created binary (application) `tq` package

The current directory now contains:

tq/
├── Cargo.toml
└── src/
    └── main.rs

Two files. One describes the package, the other holds the code.

Cargo.toml is the manifest. Cargo reads it on every build:

[package]
name = "tq"
version = "0.1.0"
edition = "2024"

name is the artifact’s name. version is its version. edition is the language version; 2024 is current for new projects and there is no reason to change it.

Cargo generated src/main.rs itself:

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

fn main() is the entry point: every Rust program starts here. println! prints a line to the terminal. Run it:

cargo run

   Compiling tq v0.1.0 (.../tq)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.42s
     Running `target/debug/tq`
Hello, world!

Cargo compiled the code and ran the result. For now, tq speaks in someone else’s voice. Open src/main.rs and replace the line:

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

cargo run

   Compiling tq v0.1.0 (.../tq)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.38s
     Running `target/debug/tq`
Hello, tq!

The Result

tq exists. It has a name, a place, and a voice - modest for now, but real.

The tq code for this chapter is in 0-the-workshop/02-the-first-incantation/.

Lore: What cargo run Does

cargo run is three steps in sequence: check the code, compile it, run the result. If the code has not changed since the last build, Cargo skips compilation - the Finished line appears almost instantly, with no Compiling.

The compiled file lives at target/debug/tq. You can run it directly:

./target/debug/tq

Same result. cargo run just saves you from having to remember the path.

Lore: edition

Rust ships every six weeks, but the language syntax changes rarely and only through editions - declared points of incompatibility. edition = "2024" means the package uses the language rules of the 2024 edition; this is the default since Rust 1.85.

In older projects and most books you will encounter edition = "2021" - the previous edition, which remains fully supported. Different packages in the same project can use different editions; Cargo knows how to combine them without conflict. For a new project, 2024 is the right choice.