Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Рабочие пространства Cargo

В главе 12 мы создали пакет, включавший бинарный крейт и библиотечный крейт. По мере развития проекта вы можете обнаружить, что библиотечный крейт продолжает расти, и вам захочется разделить пакет дальше на несколько библиотечных крейтов. Cargo предлагает функцию под названием рабочие пространства, которая может помочь управлять несколькими связанными пакетами, разрабатываемыми совместно.

Создание рабочего пространства

Рабочее пространство — это набор пакетов, которые используют общий файл Cargo.lock и общий выходной каталог. Давайте создадим проект с использованием рабочего пространства — мы будем использовать тривиальный код, чтобы можно было сосредоточиться на структуре рабочего пространства. Есть несколько способов структурировать рабочее пространство, поэтому мы просто покажем один распространённый способ. У нас будет рабочее пространство, содержащее бинарный крейт и две библиотеки. Бинарный крейт, который будет предоставлять основную функциональность, будет зависеть от двух библиотек. Одна библиотека будет предоставлять функцию add_one, а другая библиотека — функцию add_two. Эти три крейта будут частью одного рабочего пространства. Мы начнём с создания нового каталога для рабочего пространства:

$ mkdir add
$ cd add

Затем в каталоге add мы создаём файл Cargo.toml, который будет настраивать всё рабочее пространство. В этом файле не будет раздела [package]. Вместо этого он начнётся с раздела [workspace], который позволит нам добавлять члены в рабочее пространство. Мы также обратим внимание на использование последней и наилучшей версии алгоритма разрешения зависимостей Cargo в нашем рабочем пространстве, установив значение resolver в "3":

Имя файла: Cargo.toml

[workspace]
resolver = "3"

Затем мы создадим бинарный крейт adder, запустив cargo new в каталоге add:

$ cargo new adder
     Created binary (application) `adder` package
      Adding `adder` as member of workspace at `file:///projects/add`

Запуск cargo new внутри рабочего пространства также автоматически добавляет только что созданный пакет в ключ members в определении [workspace] в файле рабочего пространства Cargo.toml, вот так:

[workspace]
resolver = "3"
members = ["adder"]

На этом этапе мы можем собрать рабочее пространство, запустив cargo build. Файлы в вашем каталоге add должны выглядеть так:

├── Cargo.lock
├── Cargo.toml
├── adder
│   ├── Cargo.toml
│   └── src
│       └── main.rs
└── target

В рабочем пространстве есть один каталог target на верхнем уровне, в который будут помещаться скомпилированные артефакты; у пакета adder нет собственного каталога target. Даже если бы мы запустили cargo build изнутри каталога adder, скомпилированные артефакты всё равно оказались бы в add/target, а не в add/adder/target. Cargo структурирует каталог target в рабочем пространстве таким образом, потому что крейты в рабочем пространстве предназначены для того, чтобы зависеть друг от друга. Если бы каждый крейт имел собственный каталог target, каждый крейт пришлось бы перекомпилировать каждый из других крейтов в рабочем пространстве, чтобы поместить артефакты в собственный каталог target. Благодаря общему каталогу target крейты могут избежать ненужной пересборки.

Создание второго пакета в рабочем пространстве

Затем создадим ещё один член-пакет в рабочем пространстве и назовём его add_one. Создайте новый библиотечный крейт с именем add_one:

$ cargo new add_one --lib
     Created library `add_one` package
      Adding `add_one` as member of workspace at `file:///projects/add`

Теперь верхний файл Cargo.toml будет включать путь add_one в списке members:

Имя файла: Cargo.toml

[workspace]
resolver = "3"
members = ["adder", "add_one"]

Теперь в вашем каталоге add должны быть следующие каталоги и файлы:

├── Cargo.lock
├── Cargo.toml
├── add_one
│   ├── Cargo.toml
│   └── src
│       └── lib.rs
├── adder
│   ├── Cargo.toml
│   └── src
│       └── main.rs
└── target

В файле add_one/src/lib.rs давайте добавим функцию add_one:

Имя файла: add_one/src/lib.rs

pub fn add_one(x: i32) -> i32 {
    x + 1
}

Теперь мы можем заставить пакет adder с нашим бинарным крейтом зависеть от пакета add_one, содержащего нашу библиотеку. Сначала нам нужно добавить зависимость по пути add_one в adder/Cargo.toml.

Имя файла: adder/Cargo.toml

[dependencies]
add_one = { path = "../add_one" }

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

Затем давайте использовать функцию add_one (из крейта add_one) в крейте adder. Откройте файл adder/src/main.rs и измените функцию main, чтобы она вызывала функцию add_one, как в листинге 14-7.

Имя файла: adder/src/main.rs
fn main() {
    let num = 10;
    println!("Hello, world! {num} plus one is {}!", add_one::add_one(num));
}
Листинг 14-7: Использование библиотечного крейта add_one из крейта adder

Давайте соберём рабочее пространство, запустив cargo build в верхнем каталоге add!

$ cargo build
   Compiling add_one v0.1.0 (file:///projects/add/add_one)
   Compiling adder v0.1.0 (file:///projects/add/adder)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.22s

Чтобы запустить бинарный крейт из каталога add, мы можем указать, какой пакет в рабочем пространстве мы хотим запустить, используя аргумент -p и имя пакета с помощью cargo run:

$ cargo run -p adder
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/adder`
Hello, world! 10 plus one is 11!

Это запускает код в adder/src/main.rs, который зависит от крейта add_one.

Зависимость от внешнего пакета

Обратите внимание, что в рабочем пространстве есть только один файл Cargo.lock на верхнем уровне, а не по одному Cargo.lock в каталоге каждого крейта. Это гарантирует, что все крейты используют одну и ту же версию всех зависимостей. Если мы добавим пакет rand в файлы adder/Cargo.toml и add_one/Cargo.toml, Cargo разрешит обе эти зависимости в одну версию rand и запишет это в единственный Cargo.lock. Использование всеми крейтами рабочего пространства одних и тех же зависимостей означает, что крейты всегда будут совместимы друг с другом. Давайте добавим крейт rand в раздел [dependencies] файла add_one/Cargo.toml, чтобы можно было использовать крейт rand в крейте add_one:

Имя файла: add_one/Cargo.toml

[dependencies]
rand = "0.10.1"

Теперь мы можем добавить use rand; в файл add_one/src/lib.rs, и сборка всего рабочего пространства путём запуска cargo build в каталоге add приведёт к загрузке и компиляции крейта rand. Мы получим одно предупреждение, потому что мы не ссылаемся на rand, который мы ввели в область видимости:

$ cargo build
    Updating crates.io index
  Downloaded rand v0.10.1
   --snip--
   Compiling rand v0.10.1
   Compiling add_one v0.1.0 (file:///projects/add/add_one)
warning: unused import: `rand`
 --> add_one/src/lib.rs:1:5
  |
1 | use rand;
  |     ^^^^
  |
  = note: `#[warn(unused_imports)]` (part of `#[warn(unused)]`) on by default

warning: `add_one` (lib) generated 1 warning (run `cargo fix --lib -p add_one` to apply 1 suggestion)
   Compiling adder v0.1.0 (file:///projects/add/adder)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.95s

Теперь верхний файл Cargo.lock содержит информацию о зависимости add_one от rand. Однако, даже если rand используется где-то в рабочем пространстве, мы не можем использовать его в других крейтах рабочего пространства, если не добавим rand в их файлы Cargo.toml тоже. Например, если мы добавим use rand; в файл adder/src/main.rs для пакета adder, мы получим ошибку:

$ cargo build
  --snip--
   Compiling adder v0.1.0 (file:///projects/add/adder)
error[E0432]: unresolved import `rand`
 --> adder/src/main.rs:2:5
  |
2 | use rand;
  |     ^^^^ no external crate `rand`

Чтобы исправить это, отредактируйте файл Cargo.toml пакета adder и укажите, что rand также является для него зависимостью. Сборка пакета adder добавит rand в список зависимостей для adder в Cargo.lock, но никакие дополнительные копии rand не будут загружены. Cargo гарантирует, что каждый крейт в каждом пакете рабочего пространства, использующий пакет rand, будет использовать ту же версию, пока они указывают совместимые версии rand, экономя нам место и гарантируя, что крейты рабочего пространства будут совместимы друг с другом.

Если крейты в рабочем пространстве указывают несовместимые версии одной и той же зависимости, Cargo разрешит каждую из них, но всё равно попытается разрешить как можно меньше версий.

Добавление теста в рабочее пространство

В качестве ещё одного улучшения давайте добавим тест для функции add_one::add_one внутри крейта add_one:

Имя файла: add_one/src/lib.rs

pub fn add_one(x: i32) -> i32 {
    x + 1
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        assert_eq!(3, add_one(2));
    }
}

Теперь запустите cargo test в верхнем каталоге add. Запуск cargo test в рабочем пространстве, структурированном таким образом, запустит тесты для всех крейтов в рабочем пространстве:

$ cargo test
   Compiling add_one v0.1.0 (file:///projects/add/add_one)
   Compiling adder v0.1.0 (file:///projects/add/adder)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.20s
     Running unittests src/lib.rs (target/debug/deps/add_one-93c49ee75dc46543)

running 1 test
test tests::it_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

     Running unittests src/main.rs (target/debug/deps/adder-3a47283c568d2b6a)

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests add_one

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Первый раздел вывода показывает, что тест it_works в крейте add_one прошёл. Следующий раздел показывает, что в крейте adder не найдено ни одного теста, а затем последний раздел показывает, что документационные тесты в крейте add_one не найдены.

Мы также можем запускать тесты для одного конкретного крейта в рабочем пространстве из верхнего каталога, используя флаг -p и указывая имя крейта, который мы хотим протестировать:

$ cargo test -p add_one
    Finished `test` profile [unoptimized + debuginfo] target(s) in 0.00s
     Running unittests src/lib.rs (target/debug/deps/add_one-93c49ee75dc46543)

running 1 test
test tests::it_works ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests add_one

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

Этот вывод показывает, что cargo test запустил тесты только для крейта add_one и не запускал тесты крейта adder.

Если вы публикуете крейты из рабочего пространства на crates.io, каждый крейт в рабочем пространстве потребуется публиковать отдельно. Как и cargo test, мы можем опубликовать конкретный крейт в нашем рабочем пространстве, используя флаг -p и указывая имя крейта, который хотим опубликовать.

Для дополнительной практики добавьте крейт add_two в это рабочее пространство аналогичным образом, как крейт add_one!

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