Ferramentas do Rust: rustup, cargo, editores e mais

Quando você começa com Rust, ouve um monte de nomes novos de uma vez: rustup, rustc, cargo, clippy, rustfmt, rust-analyzer. Parece que você precisa de dez ferramentas antes de escrever uma única linha. A boa notícia: um só instalador traz quase todas elas, e cada ferramenta tem uma função bem clara.

Pense numa cozinha. O rustup é a loja que entrega e troca os seus equipamentos. O cargo é o chef que comanda tudo. O clippy é o professor gente boa que olha por cima do seu ombro, e o rustfmt mantém a bancada arrumada. Esta página explica cada ferramenta, o que você precisa no seu sistema operacional e como quem programa em Rust usa tudo isso no dia a dia.

Se você ainda não instalou o Rust, a instalação passo a passo e o seu primeiro projeto estão em Começando com Rust. O básico do cargo (cargo new, cargo add, Cargo.toml) está em Cargo e crates. Esta página parte dessas duas.

A visão geral

Aqui está a caixa de ferramentas inteira numa tabela:

Ferramenta	O que faz	Vem com o rustup?
`rustup`	Instala o Rust, atualiza e troca entre versões	Ele é o instalador
`rustc`	O compilador: transforma seus arquivos `.rs` em um programa	Sim
`cargo`	Compila, executa, testa e adiciona crates. Você usa para quase tudo	Sim
`rustup doc`	Abre a documentação da biblioteca padrão e o Rust Book offline no navegador	Sim (perfil padrão)
`clippy`	Um linter: aponta bugs e jeitos mais simples de escrever o seu código	Sim (perfil padrão)
`rustfmt`	Um formatador: reescreve o seu código no estilo padrão	Sim (perfil padrão)
`rust-analyzer`	O “cérebro do editor”: autocompletar, erros na linha, dicas de tipo, ir para a definição	Não por padrão. A extensão do VS Code traz a própria cópia
Um debugger	Pausa o programa numa linha para você olhar as variáveis	Não. Você instala o LLDB ou o GDB (ou uma extensão de editor que já inclua um)

Um perfil (profile) é um grupo de componentes que o rustup instala. A instalação normal usa o perfil default, que adiciona a documentação, o clippy e o rustfmt além do compilador e do cargo. Se alguém configurou a sua máquina com o perfil minimal, o cargo clippy vai dizer que não está instalado. Um comando resolve: rustup component add clippy rustfmt.

Experimente rustup doc --std uma vez. Ele abre a documentação completa da biblioteca padrão direto do seu disco, então funciona até no avião ou com internet lenta. Para a documentação do seu próprio projeto e de cada crate que ele usa, rode cargo doc --open (mais sobre isso em Documentação).

Antes de instalar: o que cada sistema precisa

O Rust compila o seu código, mas bem no final ele precisa de um linker: um programa que junta as partes compiladas em um único arquivo executável. O Rust usa o linker que vem com as ferramentas de C do seu sistema. Por isso cada sistema operacional precisa de um pequeno passo extra.

Sistema	O que instalar	Como
Windows (recomendado)	As ferramentas de C++ do Visual Studio: o linker do MSVC e o Windows SDK	Escolha a carga de trabalho Desktop development with C++ (Desenvolvimento para desktop com C++) no instalador do Visual Studio
Windows (alternativa)	A toolchain GNU (MinGW)	`rustup toolchain install stable-gnu`
Windows (outra opção)	WSL, um Linux de verdade dentro do Windows	`wsl --install`, depois siga os passos do Linux
macOS	As ferramentas de linha de comando da Apple (incluem um compilador C e um linker)	`xcode-select --install`
Debian / Ubuntu	Um compilador C e um linker	`sudo apt install build-essential`
Fedora	Um compilador C e um linker	`sudo dnf install gcc`

Algumas observações sinceras:

Windows e Visual Studio. Você não precisa ir atrás disso sozinho: se o Visual Studio estiver faltando, o rustup-init.exe oferece instalá-lo para você. Ele instala o Visual Studio Community, que é gratuito para pessoas físicas, estudantes e projetos open source, mas não para qualquer empresa. Se for instalar no trabalho, pergunte qual edição a sua empresa usa. Marcar a carga de trabalho “Desktop development with C++” já traz tudo o que o Rust precisa.
Windows e GNU. A toolchain MSVC é a padrão e funciona melhor com outros programas do Windows. A toolchain GNU não precisa do Visual Studio para programas simples, mas muitos crates que incluem código C só compilam depois que você instala também o MSYS2 com MinGW. A maioria das pessoas deve ficar com o MSVC.
WSL é uma ótima escolha se você quer um ambiente Linux no Windows (por exemplo, porque o seu servidor roda Linux). Dentro do WSL, você instala o Rust com o comando normal do Linux, separado de qualquer instalação no Windows.
Extras no Linux. Alguns crates populares conversam com bibliotecas do sistema. Se a compilação falhar com uma mensagem sobre pkg-config ou OpenSSL, no Ubuntu instale também pkg-config e libssl-dev.

Depois disso, siga os passos de instalação em Começando com Rust.

O rustup na prática

Com o Rust instalado, o rustup é a ferramenta que você usa para cuidar dele. Uma nova versão estável do Rust sai a cada seis semanas, então atualizar é um hábito normal:

rustup update     # atualiza todas as toolchains instaladas (e o próprio rustup)
rustup show       # o que está instalado, e qual toolchain está ativa aqui

O rustup show mostra algo assim (resumido):

Default host: x86_64-unknown-linux-gnu

installed toolchains
--------------------
stable-x86_64-unknown-linux-gnu (active, default)

active toolchain
----------------
name: stable-x86_64-unknown-linux-gnu
active because: it's the default toolchain

Stable, beta e nightly

Uma toolchain é um conjunto completo de rustc, cargo e companhia. O Rust tem três canais de lançamento:

Canal	O que é	Quando usar
stable	A versão oficial, a cada seis semanas	Quase sempre. É esta que você quer
beta	A próxima versão estável, em fase de testes	Você quer testar o seu projeto antes do próximo lançamento
nightly	Gerada toda noite, com recursos experimentais	Uma ferramenta ou crate pede por ela, ou você quer testar um recurso novo

Você pode ter várias toolchains instaladas lado a lado:

rustup toolchain install nightly   # instala a nightly ao lado da stable
cargo +nightly build               # usa a nightly só neste comando
rustup default stable              # escolhe a toolchain usada em todo lugar

Fixando uma toolchain por projeto

Às vezes um projeto precisa de uma versão específica do Rust. Coloque um arquivo chamado rust-toolchain.toml na pasta do projeto, e o rustup troca de versão sozinho sempre que você trabalha nessa pasta:

[toolchain]
channel = "1.97.0"
components = ["clippy", "rustfmt"]
targets = ["wasm32-unknown-unknown"]

Faça commit desse arquivo no git. Assim, todo mundo do time (e o seu CI) usa exatamente o mesmo compilador, e o rustup instala essa versão para quem não a tiver. A maioria dos projetos pequenos nem precisa desse arquivo; eles simplesmente usam a stable mais recente.

Componentes e targets

Componentes são peças extras de uma toolchain. Targets (alvos) permitem compilar para outro tipo de máquina:

rustup component add clippy rustfmt rust-src   # rust-src: código-fonte da std, usado pelo rust-analyzer
rustup component list --installed              # veja o que você tem
rustup target add wasm32-unknown-unknown       # compile Rust para o navegador

O target wasm32-unknown-unknown é o que você precisa para WebAssembly.

Editores e IDEs

Você pode escrever Rust em qualquer editor de texto, mas um editor com o rust-analyzer (ou um motor parecido) faz uma diferença enorme. Você vê os erros enquanto digita, os tipos das variáveis aparecem ao lado delas, e você pode pular para a definição de qualquer função. Para quem está começando, esse retorno é como ter um professor paciente do lado.

Editor	Preço	Suporte a Rust	Bom para
VS Code + rust-analyzer	Gratuito	Extensão oficial do rust-analyzer	A maioria das pessoas. É a escolha mais popular, e a maioria dos guias parte dela
RustRover (JetBrains)	Gratuito para uso não comercial (estudo, projetos pessoais, open source não remunerado). Uso comercial exige uma assinatura paga	Embutido, com o motor de Rust próprio da JetBrains e um debugger integrado	Quem gosta de uma IDE completa com tudo incluído
Zed	Gratuito, open source	Embutido (usa o rust-analyzer, e o CodeLLDB para depurar)	Um editor moderno e muito rápido
Neovim / Helix	Gratuitos, open source	Pelo rust-analyzer. O Helix funciona quase sem configurar; o Neovim precisa de um pouco de configuração	Quem adora trabalhar no terminal
Visual Studio	Edições pagas, mais a Community gratuita	Sem suporte oficial a Rust	Não combina bem com Rust. Você só precisa das C++ Build Tools dele para o linker

As condições de licença do RustRover podem mudar, então confira a página do RustRover (em inglês) para ver as regras atuais antes de usar no trabalho.

Para Neovim, Helix e outros editores, instale o próprio programa rust-analyzer com rustup component add rust-analyzer.

Extensões recomendadas para o VS Code

Se você usa o VS Code, estas quatro cobrem quase tudo:

rust-analyzer: a essencial. Autocompletar, erros, dicas, refatoração.
CodeLLDB: um debugger para breakpoints e para executar o código passo a passo. Já vem com a própria cópia do LLDB.
Even Better TOML: colore e verifica o seu Cargo.toml.
Error Lens (opcional): mostra as mensagens de erro direto na linha, e não só quando você passa o mouse. Tem gente que ama, tem gente que acha poluído.

Depuração

Breakpoints com o CodeLLDB

Com o rust-analyzer e o CodeLLDB instalados no VS Code, você vai ver pequenos links Run | Debug acima de fn main e acima de cada teste. Clique na margem esquerda, ao lado do número de uma linha, para colocar um ponto vermelho de breakpoint, e depois clique em Debug. O programa para no breakpoint, e você pode olhar cada variável e avançar pelo código linha por linha.

Se você quer uma configuração reutilizável (por exemplo, para passar argumentos de linha de comando), crie o arquivo .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "lldb",
      "request": "launch",
      "name": "Debug task_queue",
      "cargo": {
        "args": ["build", "--bin=task_queue"]
      },
      "args": [],
      "cwd": "${workspaceFolder}"
    }
  ]
}

A parte cargo diz ao CodeLLDB para compilar o seu programa com o cargo primeiro e depois iniciá-lo no debugger. Troque task_queue pelo nome do seu pacote e coloque os argumentos do programa em "args". Aperte F5 para começar.

Olhadas rápidas com `dbg!`

Nem sempre você precisa de um debugger completo. A macro dbg! mostra uma expressão, o valor dela, e o arquivo e a linha onde você a escreveu. Ela também devolve o valor, então você pode colocá-la em volta de quase qualquer coisa sem mudar o que o seu código faz:

fn apply_discount(price: u32, percent: u32) -> u32 {
    price - price * percent / 100
}

fn main() {
    let prices = [120, 45, 80];

    let total: u32 = dbg!(prices.iter().sum());
    let final_price = dbg!(apply_discount(total, 10));

    println!("Total com 10% de desconto: {final_price}");
}

Saída:

Total com 10% de desconto: 221

▶ Experimente você mesmo

Cadê as linhas do dbg!? O dbg! escreve no stderr (a saída de erros), e não no stdout como o println!. Isso mantém as suas anotações de depuração separadas da saída de verdade. No terminal, ou na seção “Standard Error” do Playground, você também vai ver:

[src/main.rs:8:22] prices.iter().sum() = 245
[src/main.rs:9:23] apply_discount(total, 10) = 221

Tire as chamadas de dbg! quando terminar. Elas são para você, não para os seus usuários.

Qualidade de código todo dia

Três comandos mantêm o seu código saudável. Eles são rápidos, então rode sempre.

`cargo check`: retorno rápido

O cargo check encontra erros de compilação sem gerar um programa executável, por isso é bem mais rápido que o cargo build. Muita gente roda ele a cada poucos minutos. (O rust-analyzer do seu editor já faz uma verificação dessas toda vez que você salva.)

`cargo fmt`: nunca mais discuta estilo

O cargo fmt reescreve todos os arquivos do projeto no estilo padrão do Rust. Ninguém do time precisa mais pensar em espaços ou quebras de linha. Ele transforma isto:

struct Player{name:String,score:u32}
fn top(players:&[Player])->Option<&Player>{players.iter().max_by_key(|p|p.score)}

nisto:

struct Player {
    name: String,
    score: u32,
}
fn top(players: &[Player]) -> Option<&Player> {
    players.iter().max_by_key(|p| p.score)
}

A maioria dos editores consegue rodar o formatador toda vez que você salva. No VS Code, ative a configuração “Format On Save”.

`cargo clippy`: uma revisão de código amigável

O Clippy conhece centenas de padrões que estão errados, são lentos ou simplesmente são mais difíceis de ler do que precisariam ser. Aqui está um programinha que funciona direitinho:

fn main() {
    let tasks: Vec<&str> = vec!["escrever a documentação", "corrigir um bug"];

    if tasks.len() == 0 {
        println!("Nada para fazer!");
    } else {
        println!("{} tarefas esperando", tasks.len());
    }
}

Mas o cargo clippy tem uma sugestão:

warning: length comparison to zero
 --> src/main.rs:4:8
  |
4 |     if tasks.len() == 0 {
  |        ^^^^^^^^^^^^^^^^ help: using `is_empty` is clearer and more explicit: `tasks.is_empty()`
  |
  = note: `#[warn(clippy::len_zero)]` on by default

O aviso está em inglês, porque é isso que o Clippy imprime: “comparar o tamanho com zero; usar is_empty é mais claro e explícito”. Todo aviso tem um nome (aqui, len_zero) que você pode procurar na lista de lints do Clippy (em inglês) para ler uma explicação mais longa. Esta é a versão corrigida:

fn main() {
    let tasks: Vec<&str> = vec!["escrever a documentação", "corrigir um bug"];

    if tasks.is_empty() {
        println!("Nada para fazer!");
    } else {
        println!("{} tarefas esperando", tasks.len());
    }
}

Saída:

2 tarefas esperando

▶ Experimente você mesmo

O cargo clippy --fix consegue aplicar muitas sugestões para você. O Clippy nem sempre acerta para o seu caso, mas acerta com tanta frequência que ler cada aviso é um jeito rápido de aprender Rust idiomático.

Ferramentas extras úteis para o cargo

Qualquer pessoa pode criar novos subcomandos para o cargo. Você os instala com cargo install, que baixa o código-fonte, compila e coloca o programa em ~/.cargo/bin (no Windows, %USERPROFILE%\.cargo\bin). Você não precisa de nenhum deles no primeiro dia, mas vale a pena conhecer:

Ferramenta	O que faz	Instalar	Rodar
bacon	Roda de novo o check, o clippy ou os testes toda vez que você salva, num terminal ao lado	`cargo install --locked bacon`	`bacon`, `bacon clippy`, `bacon test`
cargo-watch	Roda qualquer comando do cargo ao salvar. Ainda funciona, mas não recebe mais atualizações; o próprio autor recomenda o bacon	`cargo install --locked cargo-watch`	`cargo watch -x check`
cargo-nextest	Um executor de testes mais rápido, com saída mais clara	`cargo install --locked cargo-nextest`	`cargo nextest run`
cargo-audit	Compara o seu `Cargo.lock` com alertas de segurança conhecidos	`cargo install cargo-audit`	`cargo audit`
cargo-outdated	Lista as dependências que têm versões mais novas	`cargo install --locked cargo-outdated`	`cargo outdated`
cargo-edit	Adiciona o `cargo upgrade`, que sobe as versões no `Cargo.toml` (o `cargo add` já vem embutido)	`cargo install cargo-edit`	`cargo upgrade`
cargo-expand	Mostra o código em que as suas macros e os `#[derive]` se transformam	`cargo install cargo-expand`	`cargo expand`
cargo-binstall	Baixa binários prontos em vez de compilar, então a instalação leva segundos	`cargo install cargo-binstall`	`cargo binstall bacon`

O cargo install compila a partir do código-fonte, então a primeira instalação de uma ferramenta grande pode levar alguns minutos. Isso é normal. Para atualizar uma ferramenta depois, rode o mesmo comando de instalação de novo. Para ver o que você já instalou, rode cargo install --list. Para ferramentas focadas em velocidade, como profilers e benchmarks, veja Desempenho.

Sem instalar nada: o Rust Playground

O Rust Playground roda Rust no seu navegador. Todo botão “Experimente você mesmo” deste site abre o Playground. Ele é perfeito para experimentos rápidos, para compartilhar um trecho de código quando você pede ajuda, ou para estudar num computador em que você não pode instalar nada.

O que ele consegue fazer:

Rodar o seu código na stable, na beta ou na nightly, em modo debug ou release.
Usar os 100 crates mais baixados do crates.io (mais os crates usados pelo Rust Cookbook e as dependências deles), como serde, rand, regex e tokio.
Rodar o rustfmt e o Clippy pelo menu Tools.
Compartilhar o seu código como um link.

O que ele não consegue fazer:

Ter mais de um arquivo. Não existe Cargo.toml, então você não pode escolher outros crates nem outras versões.
Acessar a rede. Um código que baixa uma página da web vai falhar.
Trabalhar com os seus próprios arquivos, ou rodar por muito tempo. Tempo e memória são limitados.
Ser confortável para programas interativos. Enquanto o programa roda, uma caixinha deixa você digitar a entrada, mas isso é desajeitado para qualquer coisa além de um teste rápido. Os exemplos deste site nunca leem entrada, então rodam com um clique.

Quando ele ficar pequeno para você, um projeto local com cargo new está a um minuto de distância.

Checklist para uma máquina nova

Vai configurar um computador novo? Passe por esta lista uma vez:

Instale os pré-requisitos do seu sistema: as ferramentas de C++ do Visual Studio (Windows), xcode-select --install (macOS) ou build-essential / gcc (Linux).
Instale o Rust pelo rustup.rs e depois abra um terminal novo.
Confira: rustc --version e cargo --version.
Garanta que as ferramentas do dia a dia estão lá: rustup component add clippy rustfmt.
Instale um editor com rust-analyzer. No VS Code, adicione as extensões rust-analyzer e CodeLLDB.
Ative a formatação ao salvar no seu editor.
Crie um projeto de teste com cargo new hello e rode cargo run, cargo clippy e cargo fmt nele.
Coloque um lembrete para rodar rustup update a cada um ou dois meses.
Opcional: cargo install --locked bacon para ter retorno instantâneo enquanto programa.

Prática

1. Confira a sua caixa de ferramentas

Na sua máquina, rode cada um destes comandos e confirme que nenhum deles diz “not installed” (não instalado): rustup show, cargo clippy --version, cargo fmt --version. Depois abra a documentação offline da biblioteca padrão e encontre a página de Vec. Dica: o rustup doc aceita um tópico, como o caminho completo de um tipo.

Ver solução

rustup show
cargo clippy --version
cargo fmt --version
rustup doc std::vec::Vec

Cada comando --version mostra um número de versão. Se algum mostrar um erro, instale a peça que falta com rustup component add clippy ou rustup component add rustfmt. O último comando abre a página de Vec no navegador, direto do seu disco. Se ele disser que o rust-docs não está instalado, rode rustup component add rust-docs antes.

2. Deixe o Clippy ensinar você

Num projeto novo, cole em src/main.rs a primeira versão do programa de tarefas da seção do Clippy. Rode cargo clippy, leia o aviso e depois deixe o próprio Clippy corrigir. Dica: existe uma flag que aplica as sugestões automaticamente.

Ver solução

cargo new task_queue
cd task_queue
# cole o programa em src/main.rs e depois:
cargo clippy
cargo clippy --fix --allow-dirty
cargo clippy

O primeiro cargo clippy mostra o aviso len_zero. O cargo clippy --fix reescreve tasks.len() == 0 como tasks.is_empty(). A flag --allow-dirty deixa ele alterar arquivos que você ainda não commitou no git. A última execução não mostra nenhum aviso.

Resumo

O rustup instala e atualiza o Rust e troca de toolchain; o cargo compila, executa, testa e adiciona crates; o rustc é o compilador por baixo de tudo.
Cada sistema precisa de um linker primeiro: as ferramentas de C++ do Visual Studio no Windows, xcode-select --install no macOS, build-essential ou gcc no Linux.
Fique na stable. Use o rust-toolchain.toml só quando um projeto precisar fixar uma versão, e cargo +nightly para comandos avulsos na nightly.
Use um editor com rust-analyzer. VS Code com rust-analyzer e CodeLLDB é a configuração mais comum.
Rode cargo check com frequência, e cargo fmt mais cargo clippy antes de cada commit. Use dbg! para olhadas rápidas e um debugger para bugs mais difíceis.
O Playground é ótimo para experimentar e compartilhar, mas é um arquivo só, sem rede, e só com os crates mais populares.

Teste o que aprendeu

1. Qual ferramenta você usaria para instalar a toolchain nightly ao lado da stable?

2. A compilação no Windows falha porque nenhum linker foi encontrado. O que provavelmente está faltando?

3. Onde o dbg! escreve a saída dele?

4. Qual destas coisas o Rust Playground NÃO consegue fazer?

Pontuação: 0 / 4

Para saber mais

Install Rust — rust-lang.org (em inglês): o instalador oficial para todas as plataformas, com observações sobre Windows, PATH e desinstalação.
The rustup book (em inglês): toolchains, canais, componentes, perfis, rust-toolchain.toml e targets de compilação cruzada.
The Cargo Book (em inglês): tudo sobre o cargo, incluindo o cargo install e as opções de cada comando.
Manual do rust-analyzer (em inglês): como configurar o rust-analyzer no VS Code, Neovim, Helix, Emacs e outros, e todas as configurações dele.
Documentação do Clippy (em inglês): como rodar e configurar o Clippy, com um link para a lista completa de lints e o que cada um significa.