Publish crate ไปยัง Crates.io

เราใช้ package จาก crates.io เป็น dependency ของโปรเจกต์ของเรา แต่คุณยังแชร์โค้ดของคุณกับคนอื่นโดย publish package ของคุณเองได้ crate registry ที่ crates.io แจกจ่าย source code ของ package ของคุณ ดังนั้นมัน host โค้ดที่เป็น open source เป็นหลัก

Rust และ Cargo มีฟีเจอร์ที่ทำให้ package ที่คุณ publish ง่ายขึ้นที่ คนจะหาและใช้ เราจะพูดถึงฟีเจอร์เหล่านี้บางอย่างถัดไป แล้วอธิบายวิธี publish package

ทำ Documentation Comment ที่มีประโยชน์

การ document package ของคุณอย่างแม่นยำจะช่วยให้ user อื่นรู้วิธีและ เวลาที่ใช้พวกมัน ดังนั้นคุ้มค่าที่จะลงทุนเวลาเขียน documentation ใน บทที่ 3 เราพูดถึงวิธี comment โค้ด Rust โดยใช้สอง slash // Rust ยังมี comment ประเภทเฉพาะสำหรับ documentation ที่รู้จักกันในชื่อ documentation comment ซึ่งจะสร้าง documentation HTML HTML แสดง เนื้อหาของ documentation comment สำหรับ item ของ public API ที่มีไว้ สำหรับ programmer ที่สนใจรู้วิธี_ใช้_ crate ของคุณ ตรงข้ามกับวิธีที่ crate ของคุณ_ถูก implement_

Documentation comment ใช้สาม slash /// แทนสอง และสนับสนุน notation Markdown สำหรับ format text วาง documentation comment ก่อน item ที่ พวกมันกำลัง document Listing 14-1 แสดง documentation comment สำหรับ ฟังก์ชัน add_one ใน crate ชื่อ my_crate

Filename: 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
}

Listing 14-1: Documentation comment สำหรับฟังก์ชัน

ที่นี่ เราให้คำอธิบายของสิ่งที่ฟังก์ชัน add_one ทำ เริ่ม section ด้วย heading Examples แล้วให้โค้ดที่สาธิตวิธีใช้ฟังก์ชัน add_one เราสร้าง documentation HTML จาก documentation comment นี้โดยรัน cargo doc ได้ คำสั่งนี้รันเครื่องมือ rustdoc ที่ distribute พร้อม Rust และใส่ documentation HTML ที่สร้างใน directory target/doc

เพื่อความสะดวก การรัน cargo doc --open จะ build HTML สำหรับ documentation ของ crate ปัจจุบันของคุณ (รวม documentation สำหรับ dependency ทั้งหมดของ crate ของคุณ) และเปิดผลใน web browser นำทาง ไปที่ฟังก์ชัน add_one และคุณจะเห็นว่า text ใน documentation comment ถูก render อย่างไร ดังที่แสดงใน Figure 14-1

Rendered HTML documentation for the `add_one` function of `my_crate`

Figure 14-1: documentation HTML สำหรับฟังก์ชัน add_one

Section ที่ใช้บ่อย

เราใช้ heading Markdown # Examples ใน Listing 14-1 เพื่อสร้าง section ใน HTML ด้วยชื่อ “Examples” นี่คือ section อื่นที่ author ของ crate ใช้บ่อยใน documentation ของพวกเขา:

Panics — เหล่านี้เป็น scenario ที่ฟังก์ชันที่ถูก document panic ได้ Caller ของฟังก์ชันที่ไม่ต้องการให้โปรแกรมของพวกเขา panic ควร ทำให้แน่ใจว่าพวกเขาไม่เรียกฟังก์ชันในสถานการณ์เหล่านี้
Errors — ถ้าฟังก์ชัน return Result การอธิบายประเภทของ error ที่อาจเกิดขึ้นและเงื่อนไขใดอาจทำให้ error เหล่านั้นถูก return ได้ มีประโยชน์ต่อ caller เพื่อให้พวกเขาเขียนโค้ดเพื่อจัดการประเภท ต่างกันของ error ในวิธีต่างกันได้
Safety — ถ้าฟังก์ชันเป็น unsafe ที่เรียก (เราพูดถึง unsafety ในบทที่ 20) ควรมี section ที่อธิบายทำไมฟังก์ชันเป็น unsafe และครอบคลุม invariant ที่ฟังก์ชันคาดหวังให้ caller รักษาไว้

documentation comment ส่วนใหญ่ไม่ต้องการ section ทั้งหมดเหล่านี้ แต่นี่เป็น checklist ที่ดีเพื่อเตือนคุณถึงแง่มุมของโค้ดของคุณที่ user จะสนใจที่จะรู้

Documentation Comment เป็นเทส

การเพิ่ม block โค้ดตัวอย่างใน documentation comment ของคุณช่วยสาธิต วิธีใช้ library ของคุณและมีโบนัสเพิ่ม — การรัน cargo test จะรัน ตัวอย่างโค้ดใน documentation ของคุณเป็นเทส! ไม่มีอะไรดีกว่า documentation พร้อมตัวอย่าง แต่ไม่มีอะไรแย่กว่าตัวอย่างที่ไม่ทำงาน เพราะโค้ดเปลี่ยนตั้งแต่ documentation ถูกเขียน ถ้าเรารัน cargo test ด้วย documentation สำหรับฟังก์ชัน add_one จาก Listing 14-1 เรา จะเห็น section ในผลเทสที่ดูแบบนี้:

   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! ใน ตัวอย่าง panic และรัน cargo test อีกครั้ง เราจะเห็นว่า doc test จับว่าตัวอย่างและโค้ดไม่ sync กัน!

Comment Item ที่บรรจุ

สไตล์ doc comment //! เพิ่ม documentation ให้ item ที่ บรรจุ comment ไม่ใช่ให้ item ตามหลัง comment โดยทั่วไปเราใช้ doc comment เหล่านี้ภายในไฟล์ root ของ crate (src/lib.rs ตามธรรมเนียม) หรือภายในโมดูลเพื่อ document crate หรือโมดูลเป็นภาพรวม

ตัวอย่างเช่น เพื่อเพิ่ม documentation ที่อธิบายจุดประสงค์ของ crate my_crate ที่บรรจุฟังก์ชัน add_one เราเพิ่ม documentation comment ที่เริ่มด้วย //! ที่จุดเริ่มต้นของไฟล์ src/lib.rs ดังที่แสดงใน Listing 14-2

Filename: 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
}

Listing 14-2: Documentation สำหรับ crate my_crate ภาพรวม

สังเกตว่าไม่มีโค้ดใดหลังบรรทัดสุดท้ายที่เริ่มด้วย //! เพราะเรา เริ่ม comment ด้วย //! แทน /// เรากำลัง document item ที่บรรจุ comment นี้ ไม่ใช่ item ที่ตามหลัง comment นี้ ในกรณีนี้ item นั้น คือไฟล์ src/lib.rs ซึ่งเป็น root ของ crate comment เหล่านี้ อธิบาย crate ทั้งหมด

เมื่อเรารัน cargo doc --open comment เหล่านี้จะแสดงในหน้าแรกของ documentation สำหรับ my_crate เหนือ list ของ item public ใน crate ดังที่แสดงใน Figure 14-2

Documentation comment ภายใน item มีประโยชน์สำหรับอธิบาย crate และ โมดูลโดยเฉพาะ ใช้พวกมันเพื่ออธิบายจุดประสงค์ภาพรวมของ container เพื่อช่วยให้ user ของคุณเข้าใจการจัดระเบียบของ crate

Rendered HTML documentation with a comment for the crate as a whole

Figure 14-2: documentation ที่ render สำหรับ my_crate รวม comment ที่อธิบาย crate ทั้งภาพรวม

Export Public API ที่สะดวก

โครงสร้างของ public API ของคุณเป็นการพิจารณาหลักเมื่อ publish crate คนที่ใช้ crate ของคุณคุ้นเคยกับโครงสร้างน้อยกว่าคุณ และอาจมี ความยากในการหาชิ้นส่วนที่พวกเขาต้องการใช้ถ้า crate ของคุณมีลำดับ ชั้นโมดูลใหญ่

ในบทที่ 7 เราครอบคลุมวิธีทำให้ item เป็น public โดยใช้ keyword pub และวิธีนำ item เข้า scope ด้วย keyword use อย่างไรก็ตาม โครงสร้างที่สมเหตุสมผลกับคุณในขณะที่คุณพัฒนา crate อาจไม่สะดวกมาก สำหรับ user ของคุณ คุณอาจต้องการจัดระเบียบ struct ของคุณในลำดับ ชั้นที่บรรจุหลายระดับ แต่จากนั้นคนที่ต้องการใช้ type ที่คุณนิยาม ลึกในลำดับชั้นอาจมีปัญหาในการรู้ว่า type นั้นมีอยู่ พวกเขาอาจรำคาญ ที่ต้องใส่ use my_crate::some_module::another_module::UsefulType; แทน use my_crate::UsefulType;

ข่าวดีคือถ้าโครงสร้าง ไม่ สะดวกสำหรับคนอื่นใช้จาก library อื่น คุณ ไม่ต้องจัดระเบียบภายในใหม่ — แทน คุณ re-export item เพื่อสร้าง โครงสร้าง public ที่ต่างจากโครงสร้าง private ของคุณโดยใช้ pub use ได้ Re-export รับ item public ในที่หนึ่งและทำให้มัน public ในอีก ที่ เหมือนกับว่ามันถูกนิยามในอีกที่แทน

ตัวอย่างเช่น สมมติเราสร้าง library ชื่อ art สำหรับ model แนวคิด ศิลปะ ภายใน library นี้มีสองโมดูล — โมดูล kinds ที่บรรจุสอง enum ชื่อ PrimaryColor และ SecondaryColor และโมดูล utils ที่บรรจุ ฟังก์ชันชื่อ mix ดังที่แสดงใน Listing 14-3

Filename: 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!();
    }
}

Listing 14-3: Library art ที่มี item จัดระเบียบเข้าโมดูล kinds และ utils

Figure 14-3 แสดงว่าหน้าแรกของ documentation สำหรับ crate นี้ที่ สร้างโดย cargo doc จะดูเป็นยังไง

Rendered documentation for the `art` crate that lists the `kinds` and `utils` modules

Figure 14-3: หน้าแรกของ documentation สำหรับ art ที่ list โมดูล kinds และ utils

สังเกตว่า type PrimaryColor และ SecondaryColor ไม่ถูก list บน หน้าแรก และฟังก์ชัน mix ก็ไม่ เราต้อง click kinds และ utils เพื่อเห็นพวกมัน

crate อื่นที่ขึ้นกับ library นี้จะต้องการ statement use ที่นำ item จาก art เข้า scope ระบุโครงสร้างโมดูลที่นิยามปัจจุบัน Listing 14-4 แสดงตัวอย่างของ crate ที่ใช้ item PrimaryColor และ mix จาก crate art

Filename: src/main.rs

use art::kinds::PrimaryColor;
use art::utils::mix;

fn main() {
    let red = PrimaryColor::Red;
    let yellow = PrimaryColor::Yellow;
    mix(red, yellow);
}

Listing 14-4: Crate ที่ใช้ item ของ crate art ด้วยโครงสร้างภายในของมันที่ถูก export

ผู้เขียนของโค้ดใน Listing 14-4 ที่ใช้ crate art ต้องหาว่า PrimaryColor อยู่ในโมดูล kinds และ mix อยู่ในโมดูล utils โครงสร้างโมดูลของ crate art เกี่ยวข้องมากกว่าต่อ developer ที่ ทำงานบน crate art มากกว่าต่อคนที่ใช้มัน โครงสร้างภายในไม่บรรจุ ข้อมูลที่มีประโยชน์ใด ๆ สำหรับคนที่พยายามเข้าใจวิธีใช้ crate art แต่กลับทำให้สับสนเพราะ developer ที่ใช้มันต้องหาว่ามองที่ไหน และ ต้องระบุชื่อโมดูลใน statement use

เพื่อลบการจัดระเบียบภายในจาก public API เราแก้โค้ด crate art ใน Listing 14-3 เพื่อเพิ่ม statement pub use เพื่อ re-export item ที่ระดับสูง ดังที่แสดงใน Listing 14-5

Filename: 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
    }
}

Listing 14-5: เพิ่ม statement pub use เพื่อ re-export item

API documentation ที่ cargo doc สร้างสำหรับ crate นี้ตอนนี้จะ list และ link re-export บนหน้าแรก ดังที่แสดงใน Figure 14-4 ทำให้ type PrimaryColor และ SecondaryColor และฟังก์ชัน mix หาง่ายขึ้น

Rendered documentation for the `art` crate with the re-exports on the front page

Figure 14-4: หน้าแรกของ documentation สำหรับ art ที่ list re-export

User ของ crate art ยังเห็นและใช้โครงสร้างภายในจาก Listing 14-3 ดังที่สาธิตใน Listing 14-4 ได้ หรือพวกเขาใช้โครงสร้างที่สะดวกขึ้น ใน Listing 14-5 ดังที่แสดงใน Listing 14-6

Filename: src/main.rs

use art::PrimaryColor;
use art::mix;

fn main() {
    // --snip--
    let red = PrimaryColor::Red;
    let yellow = PrimaryColor::Yellow;
    mix(red, yellow);
}

Listing 14-6: โปรแกรมที่ใช้ item ที่ re-export จาก crate art

ในกรณีที่มีโมดูลซ้อนหลายตัว การ re-export type ที่ระดับสูงด้วย pub use ทำให้เกิดความแตกต่างที่สำคัญในประสบการณ์ของคนที่ใช้ crate การใช้ pub use อีกแบบที่ใช้บ่อยคือ re-export นิยามของ dependency ใน crate ปัจจุบันเพื่อทำให้นิยามของ crate นั้นเป็นส่วนหนึ่งของ public API ของ crate ของคุณ

การสร้างโครงสร้าง public API ที่มีประโยชน์เป็นศิลปะมากกว่าวิทยาศาสตร์ และคุณ iterate เพื่อหา API ที่ทำงานดีที่สุดสำหรับ user ของคุณได้ การเลือก pub use ให้คุณยืดหยุ่นในวิธีที่คุณจัดโครงสร้าง crate ภายในและ decouple โครงสร้างภายในนั้นจากสิ่งที่คุณแสดงต่อ user ของ คุณ ดูโค้ดบางส่วนของ crate ที่คุณติดตั้งเพื่อดูว่าโครงสร้างภายในของ พวกมันต่างจาก public API ของพวกมันไหม

ตั้งค่า Account Crates.io

ก่อนที่คุณจะ publish crate ใด คุณต้องสร้าง account บน crates.io และรับ API token เพื่อ ทำเช่นนั้น เยี่ยมชมหน้าหลักที่ crates.io และ log in ผ่าน GitHub account (GitHub account ปัจจุบันเป็นข้อกำหนด แต่ site อาจ สนับสนุนวิธีอื่นในการสร้าง account ในอนาคต) เมื่อคุณ log in แล้ว เยี่ยม account setting ของคุณที่ https://crates.io/me/ และดึง API key ของคุณ จากนั้น รันคำสั่ง cargo login และวาง API key เมื่อ ถูกแจ้ง แบบนี้:

$ cargo login
abcdefghijklmnopqrstuvwxyz012345

คำสั่งนี้จะแจ้ง Cargo เรื่อง API token ของคุณและเก็บมันใน local ที่ ~/.cargo/credentials.toml สังเกตว่า token นี้เป็น secret — อย่า แชร์มันกับใครอื่น ถ้าคุณแชร์มันกับใครด้วยเหตุผลใด คุณควร revoke มัน และสร้าง token ใหม่บน crates.io

เพิ่ม Metadata ให้ Crate ใหม่

สมมติว่าคุณมี crate ที่คุณต้องการ publish ก่อน publish คุณต้องเพิ่ม metadata ใน section [package] ของไฟล์ Cargo.toml ของ crate

crate ของคุณจะต้องการชื่อ unique ในขณะที่คุณทำงานบน crate ใน local คุณตั้งชื่อ crate อะไรก็ได้ที่คุณต้องการ อย่างไรก็ตาม ชื่อ crate บน crates.io ถูก allocate แบบ first-come, first-served เมื่อชื่อ crate ถูกใช้ ไม่มีใครอื่นที่ publish crate ด้วยชื่อนั้นได้ ก่อนพยายาม publish crate ค้นหาชื่อที่คุณต้องการ ใช้ ถ้าชื่อถูกใช้แล้ว คุณจะต้องหาชื่ออื่นและแก้ field name ในไฟล์ Cargo.toml ภายใต้ section [package] เพื่อใช้ชื่อใหม่สำหรับ publishing แบบนี้:

Filename: Cargo.toml

[package]
name = "guessing_game"

แม้คุณจะเลือกชื่อ unique เมื่อคุณรัน cargo publish เพื่อ publish crate ในจุดนี้ คุณจะได้ warning และตามด้วย error:

$ 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

นี่ส่งผลใน error เพราะคุณกำลังขาดข้อมูลสำคัญ — description และ license จำเป็นเพื่อให้คนรู้ว่า crate ของคุณทำอะไรและภายใต้เงื่อนไข ใดพวกเขาใช้มันได้ ใน Cargo.toml เพิ่ม description ที่เป็นแค่ประโยค หรือสอง เพราะมันจะปรากฏพร้อม crate ของคุณในผลค้นหา สำหรับ field license คุณต้องให้ ค่า license identifier Software Package Data Exchange (SPDX) ของ Linux Foundation list identifier ที่คุณใช้สำหรับค่านี้ได้ ตัวอย่างเช่น เพื่อระบุว่า คุณ license crate ของคุณโดยใช้ MIT License เพิ่ม identifier MIT:

Filename: Cargo.toml

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

ถ้าคุณต้องการใช้ license ที่ไม่ปรากฏใน SPDX คุณต้องวาง text ของ license นั้นในไฟล์ รวมไฟล์ในโปรเจกต์ของคุณ แล้วใช้ license-file เพื่อระบุชื่อของไฟล์นั้นแทนการใช้ key license

แนวทางว่า license ไหนเหมาะสมสำหรับโปรเจกต์ของคุณอยู่นอกเหนือ scope ของหนังสือเล่มนี้ คนหลายคนใน community Rust license โปรเจกต์ของพวก เขาในแบบเดียวกับ Rust โดยใช้ dual license ของ MIT OR Apache-2.0 การปฏิบัตินี้สาธิตว่าคุณยังระบุ license identifier หลายตัวคั่นด้วย OR เพื่อมี license หลายตัวสำหรับโปรเจกต์ของคุณได้

ด้วยชื่อ unique, version, description ของคุณ และ license ที่เพิ่ม ไฟล์ Cargo.toml สำหรับโปรเจกต์ที่พร้อม publish อาจดูแบบนี้:

Filename: 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]

Documentation ของ Cargo อธิบาย metadata อื่นที่คุณระบุได้เพื่อให้แน่ใจว่าคนอื่นค้นพบและใช้ crate ของคุณได้ง่ายขึ้น

Publish ไปยัง Crates.io

ตอนนี้คุณสร้าง account, บันทึก API token ของคุณ, เลือกชื่อสำหรับ crate ของคุณ และระบุ metadata ที่จำเป็น คุณพร้อม publish! การ publish crate อัพโหลด version เฉพาะไปยัง crates.io ให้คนอื่นใช้

ระวัง เพราะ publish เป็น ถาวร version ไม่เคยถูก overwrite ได้ และโค้ดลบไม่ได้ยกเว้นในบางสถานการณ์ เป้าหมายหลักหนึ่งของ Crates.io คือทำหน้าที่เป็น archive ถาวรของโค้ดเพื่อให้ build ของโปรเจกต์ ทั้งหมดที่ขึ้นกับ crate จาก crates.io จะทำงานต่อ การอนุญาต การลบ version จะทำให้บรรลุเป้าหมายนั้นเป็นไปไม่ได้ อย่างไรก็ตาม ไม่มีขีดจำกัดของจำนวน version ของ crate ที่คุณ publish ได้

รันคำสั่ง 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`

ยินดีด้วย! ตอนนี้คุณแชร์โค้ดของคุณกับ community Rust แล้ว และใคร ๆ เพิ่ม crate ของคุณเป็น dependency ของโปรเจกต์ของพวกเขาได้ง่าย

Publish Version ใหม่ของ Crate ที่มีอยู่

เมื่อคุณทำการเปลี่ยนแปลงให้ crate ของคุณและพร้อม release version ใหม่ คุณเปลี่ยนค่า version ที่ระบุในไฟล์ Cargo.toml ของคุณและ republish ใช้ กฎ Semantic Versioning เพื่อตัดสินว่าตัวเลข version ถัดไปที่เหมาะสมคืออะไร ตามประเภทของการเปลี่ยนแปลงที่คุณทำ จากนั้น รัน cargo publish เพื่ออัพโหลด version ใหม่

Deprecate Version จาก Crates.io

แม้คุณลบ version ก่อนหน้าของ crate ไม่ได้ คุณป้องกันโปรเจกต์ในอนาคต จากการเพิ่มพวกมันเป็น dependency ใหม่ได้ นี่มีประโยชน์เมื่อ version ของ crate ถูกพังด้วยเหตุผลใดเหตุผลหนึ่ง ในสถานการณ์เช่นนี้ Cargo สนับสนุนการ yank version ของ crate

Yank version ป้องกันโปรเจกต์ใหม่จากการขึ้นกับ version นั้นใน ขณะที่อนุญาตให้โปรเจกต์ที่มีอยู่ทั้งหมดที่ขึ้นกับมันดำเนินต่อ โดย หลัก yank แปลว่าโปรเจกต์ทั้งหมดที่มี Cargo.lock จะไม่พัง และไฟล์ Cargo.lock ในอนาคตที่สร้างจะไม่ใช้ version ที่ถูก yank

เพื่อ yank version ของ crate ใน directory ของ crate ที่คุณเคย publish ก่อนหน้า รัน cargo yank และระบุ version ที่คุณต้องการ yank ตัวอย่างเช่น ถ้าเราเคย publish crate ชื่อ guessing_game version 1.0.1 และเราต้องการ yank มัน เราจะรันต่อไปนี้ใน directory โปรเจกต์สำหรับ guessing_game:

$ cargo yank --vers 1.0.1
    Updating crates.io index
        Yank [email protected]

โดยเพิ่ม --undo ในคำสั่ง คุณยัง undo yank และอนุญาตให้โปรเจกต์ เริ่มขึ้นกับ version อีกได้:

$ cargo yank --vers 1.0.1 --undo
    Updating crates.io index
      Unyank [email protected]

Yank ไม่ ลบโค้ดใด ตัวอย่างเช่น มันไม่สามารถลบ secret ที่อัพโหลด โดยบังเอิญได้ ถ้าสิ่งนั้นเกิด คุณต้อง reset secret เหล่านั้นทันที

Keyboard shortcuts

The Rust Programming Language — ฉบับแปลภาษาไทย