Рабочие пространства 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.
fn main() {
let num = 10;
println!("Hello, world! {num} plus one is {}!", add_one::add_one(num));
}
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!
По мере роста проекта рассмотрите возможность использования рабочего пространства: оно позволяет работать с меньшими, более простыми для понимания компонентами, чем один большой блок кода. Кроме того, хранение крейтов в рабочем пространстве может упростить координацию между крейтами, если они часто изменяются одновременно.