rustup, cargo e o primeiro projeto na sua máquina

ENTENDA A IDEIA

A ideia central

Em muitos ecossistemas, montar o ambiente de trabalho é um projeto em si: um instalador para o compilador, outro para o gerenciador de pacotes, um terceiro para o executor de testes, e um arquivo de configuração diferente para cada um. Rust tomou a decisão oposta: uma ferramenta instala tudo, e outra faz todo o resto. A primeira é o rustup — instalador oficial e gerenciador de versões da toolchain. A segunda é o cargo — e a lista do que ele faz explica por que você vai digitá-lo dezenas de vezes por dia: cria projetos, compila, executa, baixa e gerencia dependências (as crates), roda testes, formata código com o rustfmt e aponta melhorias com o clippy.

Exemplo Rust

// um único comando cria projeto, compila, baixa dependências e executa:
// $ cargo run
//    Compiling oficina v0.1.0 (/home/dev/oficina)
//     Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.54s
//      Running `target/debug/oficina`

ENTENDA A IDEIA

A ideia central

Essa centralização não é conveniência cosmética; é o que torna o ecossistema coerente. Todo projeto Rust do planeta tem a mesma estrutura de pastas, o mesmo Cargo.toml descrevendo o pacote e responde aos mesmos comandos. Você pode clonar qualquer repositório Rust hoje e rodar cargo build sabendo o que vai acontecer — não existe a pergunta “qual sistema de build este projeto usa?”. Para um curso que pede que você rode cada exemplo na sua máquina, isso importa: os comandos desta aula são os mesmos que você usará em produção daqui a alguns anos.

ENTENDA A IDEIA

A ideia central

O rustup completa o quadro cuidando do que o cargo não cuida: qual versão do compilador está instalada. Rust lança uma versão estável a cada seis semanas, e rustup update atualiza tudo — compilador, cargo e componentes — sem cerimônia. Ele também permite manter várias toolchains lado a lado (estável, beta, nightly), o que você não precisa agora, mas explica por que instalar Rust “na mão”, pelo gerenciador de pacotes do sistema, é o caminho menos recomendado: você abriria mão do gerenciador de versões que o ecossistema inteiro assume presente.

Nesta aula você instala a toolchain, cria seu primeiro projeto, disseca cada arquivo gerado e aprende os quatro comandos do ciclo diário — cargo new, cargo run, cargo check e cargo build, incluindo a diferença entre os perfis debug e release que aparece no diretório target/. No fim, os exercícios cobram exatamente o que o cargo gera e onde ele grava o resultado.

ENTENDA A IDEIA

A ideia central

O mapa mental de quem vem do Node é quase direto: cargo está para o Rust como npm está para o JavaScript, o Cargo.toml é o package.json, o Cargo.lock é o package-lock.json e o crates.io é o registro público, como o npmjs.com. Duas diferenças importam. Primeiro: as dependências compiladas vão para target/, que é por projeto como o node_modules, mas o código-fonte baixado das crates fica em um cache global (~/.cargo) compartilhado entre projetos — clonar dez projetos não baixa dez cópias de cada crate. Segundo: não existe separação entre “linguagem” e “gerenciador” instalados por caminhos diferentes, como node + npm + nvm; o rustup faz o papel do nvm e já traz o resto.

ENTENDA A IDEIA

Instalando a toolchain

No Linux e no macOS, um comando instala tudo:

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

Pressione Enter para aceitar a instalação padrão. Ao final, carregue o ambiente na sessão atual do terminal (as próximas sessões já vêm configuradas):

source "$HOME/.cargo/env"

No Windows, baixe e execute o rustup-init.exe a partir de https://rustup.rs. O instalador exige as Build Tools do Visual Studio com o componente “Desenvolvimento para desktop com C++” — ele avisa e indica o link se faltarem. Alternativa comum: instalar o WSL e seguir o caminho do Linux dentro dele.

Em um terminal novo, confirme as três ferramentas:

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

ENTENDA A IDEIA

Cada comando deve imprimir uma linha com a versão — algo como rustc 1.98.0 (88d9e12ae 2026-08-18). Este curso usa a 1.98; qualquer estável igual ou mais recente serve, e rustup update atualiza quando você quiser. Se aparecer command not found, o PATH da sessão ainda não inclui ~/.cargo/bin — rode o source acima ou abra outro terminal. Se o Linux reclamar de linker 'cc' not found, instale as ferramentas de compilação do sistema (sudo apt install build-essential no Ubuntu/Debian, sudo dnf install gcc no Fedora).

Com a toolchain pronta, crie e execute o projeto desta aula:

cargo new oficina
cd oficina
cargo run

CÓDIGO ANOTADO

Código anotado

O cargo new oficina gerou três coisas: o manifesto Cargo.toml, um .gitignore (o cargo já inicializa o diretório como repositório git) e a pasta src/ com um main.rs mínimo. O manifesto merece leitura linha a linha, porque você vai editá-lo em todo projeto:

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

[dependencies]

A seção [package] identifica o pacote: name é o nome do projeto (e do binário compilado), version segue o versionamento semântico e edition fixa a edição da linguagem — 2024 é a atual, e edições permitem que Rust evolua a sintaxe sem quebrar código antigo, porque cada crate declara a sua. A seção [dependencies], vazia por enquanto, é onde as crates externas entram; quando você adicionar a primeira, o cargo cria também o Cargo.lock, registrando as versões exatas resolvidas para builds reproduzíveis.

Agora substitua o conteúdo de src/main.rs pelo programa da aula. Ele usa o que a toolchain oferece para responder uma pergunta concreta: em qual perfil este binário foi compilado, e onde ele está?

src/main.rs

// profile_name devolve o nome do perfil de compilação usado pelo cargo.
fn profile_name(debug: bool) -> &'static str {
    if debug { "debug" } else { "release" }
}

CÓDIGO ANOTADO

Código anotado

A função recebe um booleano e devolve o nome do perfil. O tipo de retorno &'static str é uma fatia de texto que vive pelo programa inteiro — é o tipo dos literais de string, e o apóstrofo do 'static é um lifetime, assunto de um módulo futuro; por ora, leia como “texto fixo embutido no binário”. Repare também no if sem parênteses e com valor: os dois ramos são expressões, e o resultado do if inteiro é o retorno da função. A próxima aula de fluxo explora essa ideia a fundo.

A macro cfg! consulta a configuração de compilação e vira um booleano fixo no código gerado: debug_assertions é verdadeiro no perfil de desenvolvimento e falso no release. Ou seja — este programa imprime uma coisa quando compilado com cargo run e outra com cargo run --release, e é exatamente esse contraste que você vai provocar a seguir. A saída esperada com cargo run:

perfil: debug
binário em: target/debug/oficina

Os quatro comandos do ciclo diário, agora que há um projeto para aplicá-los. cargo run compila (se algo mudou) e executa. cargo build só compila, gravando o executável em target/debug/oficina — o perfil de desenvolvimento compila rápido e inclui informações de depuração, mas não otimiza. cargo build --release compila com otimizações e grava em target/release/oficina; use para distribuir ou medir desempenho, nunca para o ciclo de desenvolvimento, porque é sensivelmente mais lento. E cargo check é o segredo de produtividade da toolchain: verifica se o código compila sem gerar o executável, em uma fração do tempo do build — durante o desenvolvimento, é o comando que você mais roda.

Dois componentes completam o kit e já vêm com a instalação padrão do rustup: cargo fmt formata o projeto inteiro no estilo oficial (sem debates de estilo em revisão de código — a ferramenta decide), e cargo clippy roda o linter que sugere código mais idiomático. Este curso assume os dois: todo exercício deve passar cargo clippy -- -D warnings limpo, e é um hábito que vale instalar no primeiro dia.

Uma última palavra sobre target/: é a pasta de artefatos — binários, dependências compiladas, caches incrementais. Ela cresce, pode ser apagada sem perda (cargo clean a recria do zero na próxima compilação) e o .gitignore gerado pelo cargo já a exclui do repositório. O que se versiona é o código, o Cargo.toml e o Cargo.lock; o que se recompila, não.

src/main.rs

fn main() {
    let debug = cfg!(debug_assertions);
    let profile = profile_name(debug);
    println!("perfil: {profile}");
    println!("binário em: target/{profile}/oficina");
}

PRÁTICA LOCAL

Pratique no seu computador

Com o projeto oficina criado e o main.rs da aula no lugar, rode a sequência e preveja a saída de cada passo antes de executar:

cargo run e depois cargo run --release. As duas saídas diferem em quê? Depois confirme que os dois binários existem, em target/debug/oficina e target/release/oficina — execute cada um diretamente pelo caminho e compare.
Rode cargo run duas vezes seguidas sem alterar nada. Na segunda, a linha Compiling desaparece — o cargo detecta que nada mudou e só executa. Agora salve o arquivo com um espaço a mais e rode de novo: o que volta?
Quebre o programa de propósito: remova o ! de um println! e rode cargo check. A mensagem diz que println não existe como função e sugere a macro. Meça a diferença: cargo check respondeu mais rápido que um cargo build completo? Esse é o ciclo de feedback que você vai usar o curso inteiro.

A pergunta central: em que situações do seu dia cargo check substitui cargo build — e em qual momento ele não basta?

Adapte o trecho no projeto local da aula. Confira a saída esperada no enunciado.

O navegador não executa Rust. O registro abaixo confirma seu estudo, não um resultado de teste.

Pratique no seu computador

fn profile_name(debug: bool) -> &'static str {
    if debug { "debug" } else { "release" }
}

fn main() {
    let debug = cfg!(debug_assertions);
    let profile = profile_name(debug);
    println!("perfil: {profile}");
    println!("binário em: target/{profile}/oficina");
}

Comandos locais

cargo new --bin --edition 2024 exemplo-rust
cd exemplo-rust
# Use o código no projeto da aula.
cargo run
cargo clippy -- -D warnings

Rust Playground (opcional)

DESAFIO LOCAL

Gere a seção [package] do Cargo.toml

Escreva a função manifest_package, que gera a seção [package] de um Cargo.toml exatamente como o cargo new geraria:

pub fn manifest_package(name: &str, version: &str, edition: &str) -> String

Entrada: o nome do projeto, a versão e a edição.
Saída: quatro linhas separadas por \n, sem quebra de linha final: [package], name = "{name}", version = "{version}" e edition = "{edition}" — valores entre aspas duplas, como no TOML real.
Exemplo: manifest_package("oficina", "0.1.0", "2024") devolve:

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

Restrições: a comparação é byte a byte; espaços em volta do = e as aspas fazem parte do contrato.

O objetivo é fixar a anatomia do manifesto escrevendo-a — depois deste exercício, você lê qualquer Cargo.toml sabendo o que cada campo significa.

O navegador não executa Rust. O registro abaixo confirma seu estudo, não um resultado de teste.

Exercício 1

Gere a seção [package] do Cargo.toml

stub.rs

// manifest_package gera a seção [package] de um Cargo.toml: quatro linhas
// separadas por \n, sem quebra final, com os valores entre aspas duplas.
pub fn manifest_package(name: &str, version: &str, edition: &str) -> String {
    // implemente:
    format!("{name} {version} {edition}")
}

harness.rs

fn json_escape(value: &str) -> String {
    value
        .replace('\\', "\\\\")
        .replace('"', "\\\"")
        .replace('\n', "\\n")
}

fn print_result(case: usize, pass: bool, input: &str, want: &str, got: &str) {
    println!(
        "RESULT {{\"case\":{case},\"pass\":{pass},\"input\":\"{}\",\"want\":\"{}\",\"got\":\"{}\"}}",
        json_escape(input),
        json_escape(want),
        json_escape(got)
    );
}

fn main() {
    let cases = [
        (
            ("oficina", "0.1.0", "2024"),
            "[package]\nname = \"oficina\"\nversion = \"0.1.0\"\nedition = \"2024\"",
        ),
        (
            ("servidor-web", "1.2.3", "2024"),
            "[package]\nname = \"servidor-web\"\nversion = \"1.2.3\"\nedition = \"2024\"",
        ),
        (
            ("cli", "0.0.1", "2021"),
            "[package]\nname = \"cli\"\nversion = \"0.0.1\"\nedition = \"2021\"",
        ),
    ];
    for (index, ((name, version, edition), want)) in cases.iter().enumerate() {
        let got = manifest_package(name, version, edition);
        let pass = got == *want;
        print_result(
            index + 1,
            pass,
            &format!("({name:?}, {version:?}, {edition:?})"),
            want,
            &got,
        );
    }
}

cases.json

[
  {
    "case": 1,
    "input": "(\"oficina\", \"0.1.0\", \"2024\")",
    "want": "[package]\nname = \"oficina\"\nversion = \"0.1.0\"\nedition = \"2024\""
  },
  {
    "case": 2,
    "input": "(\"servidor-web\", \"1.2.3\", \"2024\")",
    "want": "[package]\nname = \"servidor-web\"\nversion = \"1.2.3\"\nedition = \"2024\""
  },
  {
    "case": 3,
    "input": "(\"cli\", \"0.0.1\", \"2021\")",
    "want": "[package]\nname = \"cli\"\nversion = \"0.0.1\"\nedition = \"2021\""
  }
]

Casos e valores esperados

Caso	Entrada	Valor esperado
1	`("oficina", "0.1.0", "2024")`	`[package] name = "oficina" version = "0.1.0" edition = "2024"`
2	`("servidor-web", "1.2.3", "2024")`	`[package] name = "servidor-web" version = "1.2.3" edition = "2024"`
3	`("cli", "0.0.1", "2021")`	`[package] name = "cli" version = "0.0.1" edition = "2021"`

Execute com o Cargo local

Execute os comandos de preparação.
Copie os arquivos acima para os arquivos vazios com os mesmos nomes.
Execute a verificação de base. O stub deve mostrar o comportamento atual.

Comandos de preparação

cargo new --bin --edition 2024 imersao-02-instalacao-e-cargo-exercicio-1
cd imersao-02-instalacao-e-cargo-exercicio-1
touch stub.rs harness.rs cases.json
printf 'include!("../stub.rs");\ninclude!("../harness.rs");\n' > src/main.rs

Verificação de base — confirme o comportamento atual antes da mudança

cargo fmt --check
cargo run --bin imersao-02-instalacao-e-cargo-exercicio-1
cargo clippy -- -D warnings

Abrir o Rust Playground (opcional)

Mostrar dicas

A saída tem quatro linhas fixas: o cabeçalho [package] e os três campos name, version e edition — cada valor entre aspas duplas.
format! aceita \n para quebra de linha e \" para aspas dentro do molde; monte as quatro linhas em uma única chamada, sem \n no final.

Revelar solução

solution.rs

// manifest_package gera a seção [package] de um Cargo.toml: quatro linhas
// separadas por \n, sem quebra final, com os valores entre aspas duplas.
pub fn manifest_package(name: &str, version: &str, edition: &str) -> String {
    format!("[package]\nname = \"{name}\"\nversion = \"{version}\"\nedition = \"{edition}\"")
}

Um único format! com \n entre as linhas reproduz o arquivo que o cargo new gera; a armadilha é esquecer as aspas em volta dos valores ou acrescentar uma quebra de linha final que os casos não esperam.

Um único molde com as quatro linhas resolve:

pub fn manifest_package(name: &str, version: &str, edition: &str) -> String {
    format!("[package]\nname = \"{name}\"\nversion = \"{version}\"\nedition = \"{edition}\"")
}

O \n separa as linhas e o \" insere as aspas literais dentro do molde — os dois escapes que você mais usa em strings Rust. O custo é uma única alocação, O(n) no tamanho do texto final, e o compilador verifica em compilação que name, version e edition existem.

Duas armadilhas concentram os erros. A primeira é a quebra de linha final: format! com \n no fim do molde produz uma quinta linha vazia que os casos rejeitam — o contrato pede as quatro linhas e nada mais. A segunda é esquecer as aspas em volta dos valores: name = oficina não é TOML válido, e o exercício compara com o formato real que o cargo entende. A alternativa de concatenar com + linha a linha funciona, mas realoca a String a cada pedaço e espalha a estrutura do arquivo por várias expressões; o molde único mostra o formato inteiro de uma vez, que é como você vai lê-lo nos manifestos reais.

DESAFIO LOCAL

Calcule o caminho do binário compilado

Escreva a função binary_path, que devolve onde o cargo grava o executável de um projeto, dado o nome e o perfil de compilação:

pub fn binary_path(name: &str, release: bool) -> String

Entrada: o nome do projeto e um booleano — true se a compilação usou --release.
Saída: "target/release/{name}" quando release é true; "target/debug/{name}" caso contrário.
Exemplo: binary_path("oficina", false) devolve "target/debug/oficina"; binary_path("servidor", true) devolve "target/release/servidor".
Restrições: sem barras duplicadas nem barra final; o caminho é relativo à raiz do projeto, exatamente como o cargo imprime na linha Running.

Este exercício cobra o mapa mental do diretório target/: se você sabe onde o binário está, sabe o que cada perfil produz — e nunca mais distribui um binário de debug por engano.

O navegador não executa Rust. O registro abaixo confirma seu estudo, não um resultado de teste.

Exercício 2

Calcule o caminho do binário compilado

stub.rs

// binary_path devolve o caminho do executável que o cargo grava:
// "target/debug/{name}" por padrão, "target/release/{name}" com --release.
pub fn binary_path(name: &str, release: bool) -> String {
    // implemente:
    let _ = release;
    format!("target/{name}")
}

harness.rs

fn json_escape(value: &str) -> String {
    value
        .replace('\\', "\\\\")
        .replace('"', "\\\"")
        .replace('\n', "\\n")
}

fn print_result(case: usize, pass: bool, input: &str, want: &str, got: &str) {
    println!(
        "RESULT {{\"case\":{case},\"pass\":{pass},\"input\":\"{}\",\"want\":\"{}\",\"got\":\"{}\"}}",
        json_escape(input),
        json_escape(want),
        json_escape(got)
    );
}

fn main() {
    let cases = [
        ("oficina", false, "target/debug/oficina"),
        ("oficina", true, "target/release/oficina"),
        ("servidor", true, "target/release/servidor"),
        ("cli-tool", false, "target/debug/cli-tool"),
    ];
    for (index, (name, release, want)) in cases.iter().enumerate() {
        let got = binary_path(name, *release);
        let pass = got == *want;
        print_result(
            index + 1,
            pass,
            &format!("({name:?}, {release})"),
            want,
            &got,
        );
    }
}

cases.json

[
  {
    "case": 1,
    "input": "(\"oficina\", false)",
    "want": "target/debug/oficina"
  },
  {
    "case": 2,
    "input": "(\"oficina\", true)",
    "want": "target/release/oficina"
  },
  {
    "case": 3,
    "input": "(\"servidor\", true)",
    "want": "target/release/servidor"
  },
  {
    "case": 4,
    "input": "(\"cli-tool\", false)",
    "want": "target/debug/cli-tool"
  }
]

Casos e valores esperados

Caso	Entrada	Valor esperado
1	`("oficina", false)`	`target/debug/oficina`
2	`("oficina", true)`	`target/release/oficina`
3	`("servidor", true)`	`target/release/servidor`
4	`("cli-tool", false)`	`target/debug/cli-tool`

Execute com o Cargo local

Execute os comandos de preparação.
Copie os arquivos acima para os arquivos vazios com os mesmos nomes.
Execute a verificação de base. O stub deve mostrar o comportamento atual.

Comandos de preparação

cargo new --bin --edition 2024 imersao-02-instalacao-e-cargo-exercicio-2
cd imersao-02-instalacao-e-cargo-exercicio-2
touch stub.rs harness.rs cases.json
printf 'include!("../stub.rs");\ninclude!("../harness.rs");\n' > src/main.rs

Verificação de base — confirme o comportamento atual antes da mudança

cargo fmt --check
cargo run --bin imersao-02-instalacao-e-cargo-exercicio-2
cargo clippy -- -D warnings

Abrir o Rust Playground (opcional)

Mostrar dicas

O caminho tem três partes: o diretório target, o nome do perfil (debug ou release) e o nome do projeto — o perfil depende do booleano release.
Use if/else para escolher "release" ou "debug" e um format!("target/{profile}/{name}") para montar o caminho.

Revelar solução

solution.rs

// binary_path devolve o caminho do executável que o cargo grava:
// "target/debug/{name}" por padrão, "target/release/{name}" com --release.
pub fn binary_path(name: &str, release: bool) -> String {
    let profile = if release { "release" } else { "debug" };
    format!("target/{profile}/{name}")
}

Escolher o perfil com if/else como expressão e interpolar no molde reproduz exatamente onde o cargo grava o executável; a armadilha é inverter os perfis — cargo build sem flag é debug, e --release é a exceção otimizada.

O if/else como expressão escolhe o perfil, e o molde monta o caminho:

pub fn binary_path(name: &str, release: bool) -> String {
    let profile = if release { "release" } else { "debug" };
    format!("target/{profile}/{name}")
}

A primeira linha é o mesmo padrão do profile_name do programa da aula: o if devolve um valor, os dois ramos têm o mesmo tipo (&str) e o resultado vai direto para a variável — sem variável mutável, sem atribuição em dois lugares. O custo é O(n) no tamanho do caminho, uma alocação.

A armadilha clássica é inverter a correspondência: associar true a debug “porque debug é o padrão”. O booleano não pergunta qual é o padrão — pergunta se a flag --release foi usada. Vale conferir contra a realidade: rode cargo build e cargo build --release no seu projeto e compare os caminhos que o cargo imprime com o que sua função devolve. A alternativa de montar o caminho com concatenação condicional em cada ramo (format! duplicado dentro do if) também funciona, mas repete o molde e cria dois pontos de manutenção para uma única estrutura — extrair só a parte que varia é o hábito que escala.

ENTENDA A IDEIA

A ideia central

Use o cargo desde o primeiro arquivo, mesmo em experimentos de dez linhas. O capítulo 1.3 do The Rust Book (“Hello, Cargo!”) estabelece a convenção: rustc direto serve para entender o que existe por baixo, mas o fluxo real é cargo new → editar → cargo check no ciclo curto → cargo run para ver a saída → cargo clippy e cargo fmt antes de compartilhar. Projetos que começam “sem cargo por enquanto” pagam a migração depois; projetos que começam com cargo ganham de graça a estrutura que todo dev Rust reconhece, o lockfile reproduzível e o caminho pavimentado para adicionar testes e dependências quando chegar a hora.

RESUMO DA AULA

O que você leva desta aula

rustup instala e atualiza a toolchain inteira (rustc, cargo, rustfmt, clippy); rustup update acompanha as versões estáveis lançadas a cada seis semanas.
cargo new gera a estrutura universal de projetos Rust: Cargo.toml com [package] (name, version, edition) e [dependencies], mais src/main.rs — e todo projeto do ecossistema responde aos mesmos comandos.
O ciclo diário é cargo check (verifica sem gerar binário, rápido) → cargo run (compila e executa) → cargo build --release só para distribuir ou medir.
Artefatos vivem em target/debug/ ou target/release/ conforme o perfil; a pasta é descartável (cargo clean) e fica fora do repositório.
cargo fmt e cargo clippy -- -D warnings fazem parte do contrato deste curso — rode nos exercícios desde já.
Na próxima aula, variáveis e tipos primitivos: o que let realmente declara, por que a imutabilidade é padrão e como os inteiros, floats, bool e char do Rust ocupam a memória — com o primeiro diagrama de pilha do curso.

+155 XPpossíveis nesta aula

A ideia central

A ideia central

A ideia central

A ideia central

Instalando a toolchain

Código anotado

Código anotado

Pratique no seu computador

Gere a seção [package] do Cargo.toml

Casos e valores esperados

Execute com o Cargo local

Calcule o caminho do binário compilado

Casos e valores esperados

Execute com o Cargo local

A ideia central

O que você leva desta aula

Você transformou esta ideia em prática.