Сочетания клавиш

Нажмите ← или → для навигации между главами

Нажмите S или / для поиска по книге

Нажмите ? для отображения этой справки

Нажмите Esc, чтобы скрыть эту справку

Публикация крейта на Crates.io

Мы использовали пакеты с crates.io в качестве зависимостей нашего проекта, но вы также можете делиться своим кодом с другими людьми, публикуя собственные пакеты. Реестр крейтов на crates.io распространяет исходный код ваших пакетов, поэтому в основном он размещает код с открытым исходным кодом.

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

Написание полезных комментариев документации

Точное документирование ваших пакетов поможет другим пользователям узнать, как и когда их использовать, поэтому стоит потратить время на написание документации. В главе 3 мы обсуждали, как комментировать код на Rust с помощью двух косых черт, //. В Rust также есть особый вид комментариев для документации, известный как комментарий документации, который генерирует HTML-документацию. HTML отображает содержимое комментариев документации для элементов публичного API, предназначенных для программистов, интересующихся тем, как использовать ваш крейт, а не тем, как ваш крейт реализован.

Комментарии документации используют три косые черты, ///, вместо двух и поддерживают нотацию Markdown для форматирования текста. Размещайте комментарии документации непосредственно перед элементом, который они документируют. В листинге 14-1 показаны комментарии документации для функции add_one в крейте с именем my_crate.

Имя файла: src/lib.rs
/// Adds one to the number given.
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}
Листинг 14-1: Комментарий документации для функции

Здесь мы даём описание того, что делает функция add_one, начинаем раздел с заголовком Examples, а затем предоставляем код, демонстрирующий, как использовать функцию add_one. Мы можем сгенерировать HTML-документацию из этого комментария документации, запустив cargo doc. Эта команда запускает инструмент rustdoc, поставляемый с Rust, и помещает сгенерированную HTML-документацию в каталог target/doc.

Для удобства запуск cargo doc --open соберёт HTML для документации текущего крейта (а также документацию для всех зависимостей вашего крейта) и откроет результат в веб-браузере. Перейдите к функции add_one, и вы увидите, как отображается текст в комментариях документации, как показано на рис. 14-1.

Отрендеренная HTML-документация для функции add_one крейта my_crate

Рисунок 14-1: HTML-документация для функции add_one

Часто используемые разделы

Мы использовали заголовок Markdown # Examples в листинге 14-1, чтобы создать раздел в HTML с заголовком «Examples». Вот некоторые другие разделы, которые авторы крейтов обычно используют в своей документации:

  • Panics: это сценарии, в которых документируемая функция может вызвать панику. Вызывающие функцию, которые не хотят, чтобы их программы паниковали, должны убедиться, что они не вызывают функцию в этих ситуациях.
  • Errors: если функция возвращает Result, описание видов ошибок, которые могут возникнуть, и условий, которые могут вызвать возврат этих ошибок, может быть полезно вызывающим, чтобы они могли написать код для обработки различных видов ошибок разными способами.
  • Safety: если функцию unsafe вызывать (мы обсуждаем небезопасность в главе 20), должен быть раздел, объясняющий, почему функция небезопасна, и описывающий инварианты, которые функция ожидает от вызывающих.

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

Комментарии документации как тесты

Добавление блоков примера кода в ваши комментарии документации может помочь продемонстрировать, как использовать вашу библиотеку, и имеет дополнительный бонус: запуск cargo test запустит примеры кода в вашей документации как тесты! Нет ничего лучше документации с примерами. Но нет ничего хуже, чем примеры, которые не работают, потому что код изменился с момента написания документации. Если мы запустим cargo test с документацией для функции add_one из листинга 14-1, мы увидим в результатах тестов раздел, который выглядит так:

   Doc-tests my_crate

running 1 test
test src/lib.rs - add_one (line 5) ... ok

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

Теперь, если мы изменим функцию или пример так, что assert_eq! в примере вызовет панику, и снова запустим cargo test, мы увидим, что doc-тесты поймают, что пример и код рассинхронизированы друг с другом!

Комментарии содержащих элементов

Стиль doc-комментария //! добавляет документацию к элементу, который содержит комментарии, а не к элементам, следующим за комментариями. Обычно мы используем эти doc-комментарии внутри корневого файла крейта (src/lib.rs по соглашению) или внутри модуля, чтобы документировать крейт или модуль целиком.

Например, чтобы добавить документацию, описывающую назначение крейта my_crate, содержащего функцию add_one, мы добавляем комментарии документации, которые начинаются с //!, в начало файла src/lib.rs, как показано в листинге 14-2.

Имя файла: src/lib.rs
//! # My Crate
//!
//! `my_crate` is a collection of utilities to make performing certain
//! calculations more convenient.

/// Adds one to the number given.
// --snip--
///
/// # Examples
///
/// ```
/// let arg = 5;
/// let answer = my_crate::add_one(arg);
///
/// assert_eq!(6, answer);
/// ```
pub fn add_one(x: i32) -> i32 {
    x + 1
}
Листинг 14-2: Документация для крейта my_crate в целом

Обратите внимание, что после последней строки, начинающейся с //!, нет кода. Поскольку мы начали комментарии с //!, а не с ///, мы документируем элемент, который содержит этот комментарий, а не элемент, следующий за этим комментарием. В этом случае этим элементом является файл src/lib.rs, который является корнем крейта. Эти комментарии описывают весь крейт.

Когда мы запустим cargo doc --open, эти комментарии отобразятся на главной странице документации для my_crate над списком публичных элементов в крейте, как показано на рис. 14-2.

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

Отрендеренная HTML-документация с комментарием ко всему крейту

Рисунок 14-2: Отрисованная документация для my_crate, включая комментарий, описывающий крейт в целом

Экспорт удобного публичного API

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

В главе 7 мы рассмотрели, как делать элементы публичными с помощью ключевого слова pub, и как вводить элементы в область видимости с помощью ключевого слова use. Однако структура, которая кажется вам логичной во время разработки крейта, может быть не очень удобной для ваших пользователей. Вы можете захотеть организовать свои структуры в иерархию, содержащую несколько уровней, но тогда люди, желающие использовать тип, который вы определили глубоко в иерархии, могут испытывать трудности с обнаружением этого типа. Их также может раздражать необходимость вводить use my_crate::some_module::another_module::UsefulType; вместо use my_crate::UsefulType;.

Хорошая новость в том, что если структура не удобна для использования другими из другой библиотеки, вам не нужно перестраивать свою внутреннюю организацию: вместо этого вы можете реэкспортировать элементы, чтобы создать публичную структуру, отличную от вашей приватной структуры, используя pub use. Реэкспорт берёт публичный элемент в одном месте и делает его публичным в другом месте, как если бы он был определён в другом месте.

Например, скажем, мы создали библиотеку с именем art для моделирования художественных концепций. Внутри этой библиотеки два модуля: модуль kinds, содержащий два перечисления с именами PrimaryColor и SecondaryColor, и модуль utils, содержащий функцию с именем mix, как показано в листинге 14-3.

Имя файла: src/lib.rs
//! # Art
//!
//! A library for modeling artistic concepts.

pub mod kinds {
    /// The primary colors according to the RYB color model.
    pub enum PrimaryColor {
        Red,
        Yellow,
        Blue,
    }

    /// The secondary colors according to the RYB color model.
    pub enum SecondaryColor {
        Orange,
        Green,
        Purple,
    }
}

pub mod utils {
    use crate::kinds::*;

    /// Combines two primary colors in equal amounts to create
    /// a secondary color.
    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
        // --snip--
        unimplemented!();
    }
}
Листинг 14-3: Библиотека art с элементами, организованными в модули kinds и utils

На рис. 14-3 показано, как будет выглядеть главная страница документации для этого крейта, сгенерированной cargo doc.

Отрендеренная документация крейта art со списком модулей kinds и utils

Рисунок 14-3: Главная страница документации для art, на которой перечислены модули kinds и utils

Обратите внимание, что типы PrimaryColor и SecondaryColor не перечислены на главной странице, как и функция mix. Нам нужно щёлкнуть kinds и utils, чтобы увидеть их.

Другому крейту, который зависит от этой библиотеки, понадобятся операторы use, которые вводят элементы из art в область видимости, с указанием структуры модулей, которая сейчас определена. В листинге 14-4 показан пример крейта, который использует элементы PrimaryColor и mix из крейта art.

Имя файла: src/main.rs
use art::kinds::PrimaryColor;
use art::utils::mix;

fn main() {
    let red = PrimaryColor::Red;
    let yellow = PrimaryColor::Yellow;
    mix(red, yellow);
}
Листинг 14-4: Крейт, использующий элементы крейта art с экспортированной внутренней структурой

Автору кода в листинге 14-4, который использует крейт art, пришлось выяснить, что PrimaryColor находится в модуле kinds, а mix — в модуле utils. Структура модулей крейта art более релевантна разработчикам, работающим над крейтом art, чем тем, кто его использует. Внутренняя структура не содержит никакой полезной информации для тех, кто пытается понять, как использовать крейт art, а скорее вызывает путаницу, потому что разработчикам, использующим его, приходится выяснять, где искать, и указывать имена модулей в операторах use.

Чтобы убрать внутреннюю организацию из публичного API, мы можем изменить код крейта art в листинге 14-3, добавив операторы pub use для реэкспорта элементов на верхнем уровне, как показано в листинге 14-5.

Имя файла: src/lib.rs
//! # Art
//!
//! A library for modeling artistic concepts.

pub use self::kinds::PrimaryColor;
pub use self::kinds::SecondaryColor;
pub use self::utils::mix;

pub mod kinds {
    // --snip--
    /// The primary colors according to the RYB color model.
    pub enum PrimaryColor {
        Red,
        Yellow,
        Blue,
    }

    /// The secondary colors according to the RYB color model.
    pub enum SecondaryColor {
        Orange,
        Green,
        Purple,
    }
}

pub mod utils {
    // --snip--
    use crate::kinds::*;

    /// Combines two primary colors in equal amounts to create
    /// a secondary color.
    pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor {
        SecondaryColor::Orange
    }
}
Листинг 14-5: Добавление операторов pub use для реэкспорта элементов

Документация API, которую cargo doc генерирует для этого крейта, теперь будет перечислять и ссылаться на реэкспорты на главной странице, как показано на рис. 14-4, что делает типы PrimaryColor и SecondaryColor и функцию mix более удобными для поиска.

Отрендеренная документация крейта art с реэкспортами на главной странице

Рисунок 14-4: Главная страница документации для art, на которой перечислены реэкспорты

Пользователи крейта art по-прежнему могут видеть и использовать внутреннюю структуру из листинга 14-3, как показано в листинге 14-4, или они могут использовать более удобную структуру из листинга 14-5, как показано в листинге 14-6.

Имя файла: src/main.rs
use art::PrimaryColor;
use art::mix;

fn main() {
    // --snip--
    let red = PrimaryColor::Red;
    let yellow = PrimaryColor::Yellow;
    mix(red, yellow);
}
Листинг 14-6: Программа, использующая реэкспортированные элементы из крейта art

В случаях, когда есть много вложенных модулей, реэкспорт типов на верхнем уровне с помощью pub use может существенно повлиять на опыт людей, использующих крейт. Другое распространённое использование pub use — реэкспорт определений зависимости в текущем крейте, чтобы сделать определения этого крейта частью публичного API вашего крейта.

Создание полезной структуры публичного API — скорее искусство, чем наука, и вы можете итеративно найти API, который лучше всего подходит для ваших пользователей. Выбор pub use даёт вам гибкость в том, как вы структурируете свой крейт внутренне, и отделяет эту внутреннюю структуру от того, что вы представляете пользователям. Посмотрите на некоторый код установленных вами крейтов, чтобы увидеть, отличается ли их внутренняя структура от их публичного API.

Настройка учётной записи на Crates.io

Прежде чем вы сможете публиковать какие-либо крейты, вам нужно создать учётную запись на crates.io и получить API-токен. Для этого посетите главную страницу crates.io и войдите через учётную запись GitHub. (Учётная запись GitHub в настоящее время является требованием, но сайт может поддерживать другие способы создания учётной записи в будущем.) После входа посетите настройки своей учётной записи по адресу https://crates.io/me/ и получите свой API-ключ. Затем запустите команду cargo login и вставьте свой API-ключ, когда будет предложено, вот так:

$ cargo login
abcdefghijklmnopqrstuvwxyz012345

Эта команда сообщит Cargo ваш API-токен и сохранит его локально в ~/.cargo/credentials.toml. Обратите внимание, что этот токен является секретом: не делитесь им ни с кем. Если вы по какой-либо причине поделитесь им с кем-либо, вам следует отозвать его и сгенерировать новый токен на crates.io.

Добавление метаданных в новый крейт

Скажем, у вас есть крейт, который вы хотите опубликовать. Перед публикацией вам нужно будет добавить некоторые метаданные в секцию [package] файла Cargo.toml крейта.

Вашему крейту понадобится уникальное имя. Пока вы работаете над крейтом локально, вы можете назвать крейт как угодно. Однако имена крейтов на crates.io распределяются по принципу «первым пришёл — первым обслужен». Как только имя крейта занято, никто больше не может опубликовать крейт с таким именем. Перед попыткой опубликовать крейт поищите имя, которое хотите использовать. Если имя уже использовалось, вам нужно будет найти другое имя и отредактировать поле name в файле Cargo.toml в секции [package], чтобы использовать новое имя для публикации, вот так:

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

[package]
name = "guessing_game"

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

$ cargo publish
    Updating crates.io index
warning: manifest has no description, license, license-file, documentation, homepage or repository.
See https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata for more info.
--snip--
error: failed to publish to registry at https://crates.io

Caused by:
  the remote server responded with an error (status 400 Bad Request): missing or empty metadata fields: description, license. Please see https://doc.rust-lang.org/cargo/reference/manifest.html for more information on configuring these fields

Это приводит к ошибке, потому что вам не хватает некоторой важной информации: требуются описание и лицензия, чтобы люди знали, что делает ваш крейт и на каких условиях они могут его использовать. В Cargo.toml добавьте описание, состоящее всего из одного-двух предложений, потому что оно будет отображаться с вашим крейтом в результатах поиска. Для поля license вам нужно указать значение идентификатора лицензии. Software Package Data Exchange (SPDX) Linux Foundation перечисляет идентификаторы, которые вы можете использовать для этого значения. Например, чтобы указать, что вы лицензировали свой крейт по лицензии MIT, добавьте идентификатор MIT:

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

[package]
name = "guessing_game"
license = "MIT"

Если вы хотите использовать лицензию, которой нет в SPDX, вам нужно поместить текст этой лицензии в файл, включить файл в свой проект, а затем использовать license-file для указания имени этого файла вместо использования ключа license.

Рекомендации о том, какая лицензия подходит для вашего проекта, выходят за рамки этой книги. Многие люди в сообществе Rust лицензируют свои проекты так же, как Rust, используя двойную лицензию MIT OR Apache-2.0. Эта практика демонстрирует, что вы также можете указать несколько идентификаторов лицензий, разделённых OR, чтобы иметь несколько лицензий для вашего проекта.

С уникальным именем, версией, вашим описанием и добавленной лицензией файл Cargo.toml для проекта, готового к публикации, может выглядеть так:

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

[package]
name = "guessing_game"
version = "0.1.0"
edition = "2024"
description = "A fun game where you guess what number the computer has chosen."
license = "MIT OR Apache-2.0"

[dependencies]

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

Публикация на Crates.io

Теперь, когда вы создали учётную запись, сохранили свой API-токен, выбрали имя для своего крейта и указали необходимые метаданные, вы готовы к публикации! Публикация крейта загружает определённую версию на crates.io для использования другими.

Будьте осторожны, потому что публикация постоянна. Версия никогда не может быть перезаписана, и код не может быть удалён, кроме определённых обстоятельств. Одна из главных целей Crates.io — служить постоянным архивом кода, чтобы сборки всех проектов, зависящих от крейтов с crates.io, продолжали работать. Разрешение удаления версий сделало бы достижение этой цели невозможным. Однако нет ограничений на количество версий крейта, которые вы можете опубликовать.

Снова запустите команду cargo publish. Теперь она должна успешно выполниться:

$ cargo publish
    Updating crates.io index
   Packaging guessing_game v0.1.0 (file:///projects/guessing_game)
    Packaged 6 files, 1.2KiB (895.0B compressed)
   Verifying guessing_game v0.1.0 (file:///projects/guessing_game)
   Compiling guessing_game v0.1.0
(file:///projects/guessing_game/target/package/guessing_game-0.1.0)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.19s
   Uploading guessing_game v0.1.0 (file:///projects/guessing_game)
    Uploaded guessing_game v0.1.0 to registry `crates-io`
note: waiting for `guessing_game v0.1.0` to be available at registry
`crates-io`.
You may press ctrl-c to skip waiting; the crate should be available shortly.
   Published guessing_game v0.1.0 at registry `crates-io`

Поздравляем! Теперь вы поделились своим кодом с сообществом Rust, и любой может легко добавить ваш крейт в качестве зависимости своего проекта.

Публикация новой версии существующего крейта

Когда вы внесли изменения в свой крейт и готовы выпустить новую версию, вы меняете значение version, указанное в вашем файле Cargo.toml, и публикуете заново. Используйте правила семантического версионирования, чтобы решить, какой следующий номер версии уместен, исходя из типов внесённых вами изменений. Затем запустите cargo publish, чтобы загрузить новую версию.

Устаревание версий на Crates.io

Хотя вы не можете удалить предыдущие версии крейта, вы можете предотвратить добавление их в качестве новой зависимости будущими проектами. Это полезно, когда версия крейта по той или иной причине сломана. В таких ситуациях Cargo поддерживает отзыв (yanking) версии крейта.

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

Чтобы отозвать версию крейта, в каталоге крейта, который вы ранее опубликовали, запустите cargo yank и укажите, какую версию вы хотите отозвать. Например, если мы опубликовали крейт с именем guessing_game версии 1.0.1 и хотим его отозвать, мы запустим следующее в каталоге проекта guessing_game:

$ cargo yank --vers 1.0.1
    Updating crates.io index
        Yank guessing_game@1.0.1

Добавив --undo к команде, вы также можете отменить отзыв и позволить проектам снова начать зависеть от версии:

$ cargo yank --vers 1.0.1 --undo
    Updating crates.io index
      Unyank guessing_game@1.0.1

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