Cargo: Gerenciador de Build e Pacotes do Rust

Introdução

Bem-vindo(a) ao Hello, Cargo. Este laboratório faz parte do Livro de Rust. Você pode praticar suas habilidades em Rust no LabEx.

Neste laboratório, aprenderemos sobre o Cargo, o sistema de construção e gerenciador de pacotes do Rust, que simplifica tarefas como a construção de código, gerenciamento de dependências e download de bibliotecas para projetos Rust.

Hello, Cargo

Cargo é o sistema de construção e gerenciador de pacotes do Rust. A maioria dos Rustaceans usa esta ferramenta para gerenciar seus projetos Rust porque o Cargo lida com muitas tarefas para você, como construir seu código, baixar as bibliotecas das quais seu código depende e construir essas bibliotecas. (Chamamos as bibliotecas que seu código precisa de dependências.)

Os programas Rust mais simples, como o que escrevemos até agora, não têm nenhuma dependência. Se tivéssemos construído o projeto "Hello, world!" com o Cargo, ele usaria apenas a parte do Cargo que lida com a construção do seu código. À medida que você escreve programas Rust mais complexos, você adicionará dependências, e se você iniciar um projeto usando o Cargo, adicionar dependências será muito mais fácil de fazer.

Como a grande maioria dos projetos Rust usa o Cargo, o restante deste livro assume que você também está usando o Cargo. O Cargo vem instalado com o Rust se você usou os instaladores oficiais discutidos em "Instalação". Se você instalou o Rust por algum outro meio, verifique se o Cargo está instalado digitando o seguinte em seu terminal:

cargo --version

Se você vir um número de versão, você o tem! Se você vir um erro, como command not found, consulte a documentação do seu método de instalação para determinar como instalar o Cargo separadamente.

Criando um Projeto com Cargo

Vamos criar um novo projeto usando o Cargo e ver como ele difere do nosso projeto original "Hello, world!". Navegue de volta para o seu diretório project (ou onde quer que você tenha decidido armazenar seu código). Em seguida, em qualquer sistema operacional, execute o seguinte:

cd ~/project
cargo new hello_cargo
cd hello_cargo

O primeiro comando cria um novo diretório e projeto chamado hello_cargo. Nomeamos nosso projeto hello_cargo, e o Cargo cria seus arquivos em um diretório com o mesmo nome.

Entre no diretório hello_cargo e liste os arquivos. Você verá que o Cargo gerou dois arquivos e um diretório para nós: um arquivo Cargo.toml e um diretório src com um arquivo main.rs dentro.

Ele também inicializou um novo repositório Git junto com um arquivo .gitignore. Os arquivos Git não serão gerados se você executar cargo new dentro de um repositório Git existente; você pode substituir esse comportamento usando cargo new --vcs=git.

Nota: Git é um sistema de controle de versão comum. Você pode alterar cargo new para usar um sistema de controle de versão diferente ou nenhum sistema de controle de versão usando a flag --vcs. Execute cargo new --help para ver as opções disponíveis.

Abra Cargo.toml no seu editor de texto de sua escolha. Ele deve ser semelhante ao código na Listagem 1-2.

Nome do arquivo: Cargo.toml

[package]
name = "hello_cargo"
version = "0.1.0"
edition = "2021"

[dependencies]

Listagem 1-2: Conteúdo de Cargo.toml gerado por cargo new

Este arquivo está no formato TOML (Tom's Obvious, Minimal Language), que é o formato de configuração do Cargo.

A primeira linha, [package], é um cabeçalho de seção que indica que as instruções a seguir estão configurando um pacote. À medida que adicionamos mais informações a este arquivo, adicionaremos outras seções.

As três linhas seguintes definem as informações de configuração que o Cargo precisa para compilar seu programa: o nome, a versão e a edição do Rust a serem usados. Falaremos sobre a chave edition no Apêndice E.

A última linha, [dependencies], é o início de uma seção para você listar quaisquer dependências do seu projeto. Em Rust, pacotes de código são referidos como crates. Não precisaremos de nenhum outro crate para este projeto, mas precisaremos no primeiro projeto no Capítulo 2, então usaremos esta seção de dependências então.

Agora abra src/main.rs e dê uma olhada:

Nome do arquivo: src/main.rs

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

O Cargo gerou um programa "Hello, world!" para você, assim como o que escrevemos na Listagem 1-1! Até agora, as diferenças entre nosso projeto e o projeto que o Cargo gerou são que o Cargo colocou o código no diretório src e temos um arquivo de configuração Cargo.toml no diretório superior.

O Cargo espera que seus arquivos de origem residam dentro do diretório src. O diretório do projeto de nível superior é apenas para arquivos README, informações de licença, arquivos de configuração e qualquer outra coisa não relacionada ao seu código. Usar o Cargo ajuda você a organizar seus projetos. Há um lugar para tudo, e tudo está em seu lugar.

Se você iniciou um projeto que não usa o Cargo, como fizemos com o projeto "Hello, world!", você pode convertê-lo em um projeto que usa o Cargo. Mova o código do projeto para o diretório src e crie um arquivo Cargo.toml apropriado.

Construindo e Executando um Projeto Cargo

Agora, vamos ver o que é diferente quando construímos e executamos o programa "Hello, world!" com o Cargo! Do seu diretório hello_cargo, construa seu projeto digitando o seguinte comando:

$ cargo build
   Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 2.85 secs

Este comando cria um arquivo executável em target/debug/hello_cargo em vez de no seu diretório atual. Como a construção padrão é uma construção de depuração (debug), o Cargo coloca o binário em um diretório chamado debug. Você pode executar o executável com este comando:

$ ./target/debug/hello_cargo
Hello, world!

Se tudo correr bem, Hello, world! deve ser impresso no terminal. Executar cargo build pela primeira vez também faz com que o Cargo crie um novo arquivo no nível superior: Cargo.lock. Este arquivo acompanha as versões exatas das dependências em seu projeto. Este projeto não tem dependências, então o arquivo é um pouco esparso. Você nunca precisará alterar este arquivo manualmente; o Cargo gerencia seu conteúdo para você.

Acabamos de construir um projeto com cargo build e executamos com ./target/debug/hello_cargo, mas também podemos usar cargo run para compilar o código e, em seguida, executar o executável resultante, tudo em um único comando:

$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running `target/debug/hello_cargo`
Hello, world!

Usar cargo run é mais conveniente do que ter que se lembrar de executar cargo build e, em seguida, usar todo o caminho para o binário, então a maioria dos desenvolvedores usa cargo run.

Observe que desta vez não vimos a saída indicando que o Cargo estava compilando hello_cargo. O Cargo descobriu que os arquivos não foram alterados, então não reconstruiu, mas apenas executou o binário. Se você tivesse modificado seu código-fonte, o Cargo teria reconstruído o projeto antes de executá-lo, e você teria visto esta saída:

$ cargo run
   Compiling hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.33 secs
     Running `target/debug/hello_cargo`
Hello, world!

O Cargo também fornece um comando chamado cargo check. Este comando verifica rapidamente seu código para garantir que ele compile, mas não produz um executável:

$ cargo check
   Checking hello_cargo v0.1.0 (file:///projects/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs

Por que você não gostaria de um executável? Frequentemente, cargo check é muito mais rápido do que cargo build porque ele ignora a etapa de produção de um executável. Se você estiver continuamente verificando seu trabalho enquanto escreve o código, usar cargo check acelerará o processo de informá-lo se seu projeto ainda está compilando! Como tal, muitos Rustaceans executam cargo check periodicamente enquanto escrevem seu programa para garantir que ele compile. Então eles executam cargo build quando estão prontos para usar o executável.

Vamos recapitular o que aprendemos até agora sobre o Cargo:

• Podemos criar um projeto usando cargo new.
• Podemos construir um projeto usando cargo build.
• Podemos construir e executar um projeto em uma etapa usando cargo run.
• Podemos construir um projeto sem produzir um binário para verificar erros usando cargo check.
• Em vez de salvar o resultado da construção no mesmo diretório que nosso código, o Cargo o armazena no diretório target/debug.

Uma vantagem adicional de usar o Cargo é que os comandos são os mesmos, não importa em qual sistema operacional você esteja trabalhando. Portanto, neste ponto, não forneceremos mais instruções específicas para Linux e macOS versus Windows.

Construindo para Release

Quando seu projeto estiver finalmente pronto para lançamento (release), você pode usar cargo build --release para compilá-lo com otimizações.

cargo build --release

Este comando criará um executável em target/release em vez de target/debug. As otimizações fazem com que seu código Rust seja executado mais rapidamente, mas ativá-las aumenta o tempo que leva para seu programa compilar. É por isso que existem dois perfis diferentes: um para desenvolvimento, quando você deseja reconstruir de forma rápida e frequente, e outro para construir o programa final que você dará a um usuário que não será reconstruído repetidamente e que será executado o mais rápido possível. Se você estiver fazendo benchmarking do tempo de execução do seu código, certifique-se de executar cargo build --release e fazer o benchmarking com o executável em target/release.

Cargo como Convenção

Com projetos simples, o Cargo não oferece muito valor em comparação com o uso direto do rustc, mas provará seu valor à medida que seus programas se tornarem mais complexos. Uma vez que os programas crescem para múltiplos arquivos ou precisam de uma dependência, é muito mais fácil deixar o Cargo coordenar a construção.

Embora o projeto hello_cargo seja simples, ele agora usa grande parte das ferramentas reais que você usará no restante de sua carreira em Rust. Na verdade, para trabalhar em quaisquer projetos existentes, você pode usar os seguintes comandos para verificar o código usando o Git, mudar para o diretório desse projeto e construir:

git clone example.org/someproject
cd someproject
cargo build

Para mais informações sobre o Cargo, consulte sua documentação em https://doc.rust-lang.org/cargo.

Resumo

Parabéns! Você concluiu o laboratório Hello, Cargo. Você pode praticar mais laboratórios no LabEx para aprimorar suas habilidades.