Управление зависимостями в Rust с Cargo

Привет!

Cargo — это хороший менеджер пакетов Rust, который берет на себя тяжелую работу по управлению зависимостями, сборке проекта, тестированию и многому другому.

Cargo

Cargo – это официальный менеджер пакетов и система сборки для Rust. Он был разработан для упрощения работы с кодом на Rust, обеспечивая единообразную сборку проектов, управление зависимостями, ну и плюсом тестирование. Как npm для Node.js или Maven для Java – Cargo играет аналогичную роль для Rust.

Основные команды Cargo:

1. cargo new

   • Создает новый проект Rust.

   • Пример: cargo new my_project создает новый проект с именем my_project.

2. cargo build

   • Компилирует текущий проект и все его зависимости.

   • Варианты: cargo build --release для создания оптимизированной сборки.

3. cargo run

   • Компилирует и запускает исполняемый файл проекта.

   • Можно передать аргументы: cargo run -- arg1 arg2.

4. cargo test

   • Запускает тесты, определенные в проекте.

   • Можно запускать определенные тесты: cargo test test_name.

5. cargo check

   • Быстро проверяет код проекта на наличие ошибок, не производя полной компиляции.

6. cargo clean

   • Удаляет сгенерированные артефакты сборки.

7. cargo doc

   • Генерирует документацию для текущего проекта и его зависимостей.

8. cargo update

   • Обновляет зависимости проекта, указанные в Cargo.lock, до последних версий, совместимых с Cargo.toml.

9. cargo publish

   • Публикует пакет в crates.io, официальном реестре пакетов Rust.

Итак, основные возможности:

Cargo автоматически скачивает нужные библиотеки (которые называются «crates» в Rust) и их зависимости. Cargo компилирует код, используя правильные версии зависимостей и параметры сборки.

Cargo позволяет публиковать свои crates на crates.io.

Установим и настроим

Cargo поставляется вместе с Rust, поэтому, если уже установлен Rust, то Cargo уже установлен:

rustc --version

Если видно версию Rust, значит, все ок

Настроим рабочее окружение:

Создадим каталог, в котором будем работать (папку). Переходим в рабочий каталог с помощью терминала и выполняем команду инициализации проекта:

[dependencies] my_library = "^1.2.3"

Это крейтит файл Cargo.toml и каталог src с файлом main.rs, где в будущем будем писать код. Через консоль можно создать каталог таким образом:

$ cargo new hello_world --bin

Открываем файл Cargo.toml в текстовом редакторе. В этом файле будем указывать зависимости и настройки проекта.

Файл Cargo.toml

Секция [dependencies] используется для определения основных зависимостей проекта. Эти зависимости будут установлены при сборке проекта для всех конфигураций:

[package] name = "my_project" version = "0.1.0" edition = "2018" [dependencies] my_library = "1.2.3"

Секция [dev-dependencies] используется для зависимостей, которые нужны только во время разработки, например, для юнит-тестирования. Они не будут включены в финальную сборку проекта:

[dev-dependencies] test_framework = "0.5.0"

Секция [build-dependencies] используется для зависимостей, которые нужны только во время сборки проекта:

[build-dependencies] codegen_tool = "0.1.0"

Можно так же определить зависимость как optional. Например:

[dependencies] serde = { version = "1.0", optional = true }

serde — это сериализационная библиотека, которую мы хотим использовать только в определенных условиях.

Features представляют собой именованный набор зависимостей и настроек. В Cargo.toml можно определить features следующим образом:

[features] json-support = ["serde"]

feature, названная json-support, включает в себя опциональную зависимость serde.

Когда определена feature, можно использовать атрибуты условной компиляции в коде, чтобы включать или исключать части кода.

#[cfg(feature = "json-support")] fn parse_json(data: &str) -> Result<MyStruct, serde_json::Error> {     serde_json::from_str(data) }  #[cfg(not(feature = "json-support"))] fn parse_json(_data: &str) -> Result<MyStruct, ()> {     Err(()) }

Функция parse_json будет работать с сериализацией JSON только если включена feature json-support.

Можно создавать features, которые зависят от других features:

[features] better-logging = ["log", "json-support"]

better-logging включает себя зависимость log и feature json-support.

Иногда нужно, чтобы определенные features исключали друг друга:

#[cfg(all(feature = "use-mysql", not(feature = "use-postgres")))] fn setup_database() {     // Настройка для MySQL }  #[cfg(all(feature = "use-postgres", not(feature = "use-mysql")))] fn setup_database() {     // Настройка для PostgreSQL }

Этот код обеспечивает, что будет использоваться только одна из баз данных.

Cargo с CI/CD

В CI основной акцент на автоматизацию тестирования и сборки. CD фокусируется на автоматизации процесса развертывания после тестирования.

Файл Cargo.lock должен быть включен репозиторий, особенно для исполняемых проектов, чтобы гарантировать согласованность зависимостей на всех этапах CI/CD.

Настройка .gitlab-ci.yml для GitLab CI:

stages:   - build   - test  build_job:   stage: build   script:     - cargo build --release  test_job:   stage: test   script:     - cargo test

Настройка GitHub Actions

name: Rust CI  on:   push:     branches: [ master ]   pull_request:     branches: [ master ]  jobs:   build:     runs-on: ubuntu-latest     steps:     - uses: actions/checkout@v2     - name: Build       run: cargo build --verbose     - name: Run tests       run: cargo test --verbose

Интеграция с Docker в GitLab CI

deploy_job:   stage: deploy   script:     - cargo build --release     - docker build -t my-rust-app .     - docker push my-rust-app

Можно настроить автоматические проверки кода с использованием cargo clippy и cargo fmt, например файл будет определять процесс CI, который запускается при каждом push и pull request в master ветку:

name: Rust CI  on:   push:     branches: [ master ]   pull_request:     branches: [ master ]  jobs:   build-and-test:     runs-on: ubuntu-latest      steps:     - uses: actions/checkout@v2      - name: Install Rust       uses: actions-rs/toolchain@v1       with:         toolchain: stable         profile: minimal         override: true      - name: Cache Cargo dependencies       uses: actions/cache@v2       with:         path: |           ~/.cargo/bin/           ~/.cargo/registry/index/           ~/.cargo/registry/cache/           ~/.cargo/git/db/           target/         key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}      - name: Check Code Style with cargo fmt       uses: actions-rs/cargo@v1       with:         command: fmt         args: -- --check      - name: Lint with cargo clippy       uses: actions-rs/cargo@v1       with:         command: clippy         args: -- -D warnings      - name: Build       uses: actions-rs/cargo@v1       with:         command: build         args: --verbose      - name: Run tests       uses: actions-rs/cargo@v1       with:         command: test         args: --verbose

actions/checkout@v2позволяет workflow использовать код. actions-rs/toolchain@v1: устанавливает определенную версию Rust toolchain. actions-rs/cargo@v1 шаги используют cargo для выполнения различных команд: cargo fmt -- --checkпроверяет стиль кода. cargo clippy -- -D warningsзапускает linter clippy для выявления предупреждений и ошибок в коде. cargo build и cargo test собирают проект и выполняют тесты соответственно.

Ограничения на версии

Ограничения на версии позволяют указать диапазон версий, которые хотим использовать. Примеры ограничений:

• =: Использовать только конкретную версию.

  • Пример: my_library = "1.2.3"

• >=: Использовать версии, равные или новее указанной.

  • Пример: my_library >= "1.2.3"

• <=:Использовать версии, равные или старше указанной.

  • Пример: my_library <= "2.0.0"

• ~: Использовать версии, которые совместимы с указанной версией, но не изменяют MAJOR версию.

  • Пример: my_library = "~1.2.0"

• ^: Использовать версии, которые совместимы с указанной версией, но не изменяют MAJOR и MINOR версии.

  • Пример: my_library = "^1.2.0"

• !=: Исключить определенные версии.

  • Пример: my_library != "1.0.0"

SemVer — это соглашение о формате версий библиотек и зависимостей, которое позволяет определить, какие изменения были внесены в новой версии и какие возможности могут быть нарушены для разработчиков, использующих эту зависимость. SemVer включает в себя три компонента версии: MAJOR, MINOR и PATCH.

MAJOR (главный номер): увеличивается, когда вносятся обратно несовместимые изменения API.

MINOR (минорный номер): увеличивается, когда добавляются новые функциональные возможности, но с сохранением обратной совместимости. Новые функции могут быть добавлены, но существующий код должен продолжать работать.

PATCH (патч-номер): увеличивается, когда вносятся исправления ошибок или изменения, которые сохраняют обратную совместимость, означает, что внесенные изменения исправляют ошибки, но не меняют функциональность.

Предположим, у нас есть зависимость в файле Cargo.toml следующего вида:

[dependencies] my_library = "1.2.3"

MAJOR (главный номер) равен 1. Это означает, что мы используем главную версию этой библиотеки.

MINOR (минорный номер) равен 2. Это указывает на минорные обновления с новыми функциональными возможностями, но с обратной совместимостью.

PATCH (патч-номер) равен 3. Это обновление исправлений и изменений с обратной совместимостью.

Примеры ограничений:

Использовать версии от 1.2.3 до 2.0.0 (включительно):

my_library >= "1.2.3, <= 2.0.0"

Использовать версии совместимые с 1.2.0, но не изменяющие MAJOR версию:

my_library = "~1.2.0"

Использовать версии совместимые с 1.2.0, но не изменяющие MAJOR и MINOR версии:

my_library = "^1.2.0"

После указания зависимостей и их ограничений в Cargo.toml, можно выпнолить команду cargo update в командной строке в корневой директории проекта. Cargo обновит зависимости в соответствии с указанными ограничениями и загрузит подходящие версии.

---

В продолжение темы хочу напомнить про бесплатные вебинары от экспертов рынка про безопасный unsafe Rust и про то, как Rust побуждает использовать композицию.

А больше курсов от экспертов OTUS можно найти в полном каталоге.