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

เผยแพร่เครตไปยัง Crates.io

ที่ผ่านมาเราเคยใช้แพ็กเกจ (packages) จาก crates.io เป็นดีเพนเดนซี (dependency) ในโปรเจกต์ของเรากันมาแล้ว แต่คุณเองก็สามารถแบ่งปันโค้ดของคุณให้กับผู้อื่นได้เช่นกันผ่านการเผยแพร่แพ็กเกจของคุณเอง ระบบเรจิสทรีของเครตที่ crates.io จะทำหน้าที่แจกจ่ายซอร์สโค้ดของแพ็กเกจของคุณ ดังนั้นมันจึงถูกออกแบบมาเพื่อโฮสต์โค้ดที่เป็นโอเพนซอร์ส (open source) เป็นหลัก

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

การเขียนคอมเมนต์เอกสารประกอบที่มีประโยชน์

การเขียนเอกสารประกอบ (documentation) ของแพ็กเกจอย่างถูกต้องและครบถ้วนจะช่วยให้ผู้ใช้คนอื่นเข้าใจได้ว่าควรนำแพ็กเกจของคุณไปใช้งานอย่างไรและในกรณีใดบ้าง จึงคุ้มค่าอย่างยิ่งที่คุณจะสละเวลาเขียนเอกสารประกอบ ในบทที่ 3 เราเคยพูดถึงการเขียนคอมเมนต์ในโค้ด Rust โดยใช้เครื่องหมายทับสองตัว // ไปแล้ว นอกจากนี้ Rust ยังมีคอมเมนต์รูปแบบพิเศษสำหรับทำเอกสารประกอบโดยเฉพาะ ซึ่งเรียกกันว่า คอมเมนต์เอกสารประกอบ (documentation comment หรือ doc comment) ที่จะถูกนำไปสร้างเป็นเอกสารเว็บแบบ HTML โดยเอกสาร HTML นี้จะนำเนื้อหาจากคอมเมนต์เอกสารประกอบของรายการใน API สาธารณะมาแสดง เพื่อให้โปรแกรมเมอร์ที่สนใจนำเครตของคุณไปใช้เข้าใจวิธี_เรียกใช้งาน_ แทนที่จะต้องไปแกะดูว่าเครตของคุณถูก_อิมพลีเมนต์_ ไว้อย่างไร

คอมเมนต์เอกสารประกอบจะใช้เครื่องหมายทับสามตัว /// แทนที่จะเป็นสองตัว และรองรับการจัดรูปแบบข้อความด้วยภาษา Markdown โดยเราจะวางคอมเมนต์เอกสารประกอบไว้หน้าบรรทัดของรายการที่เราต้องการอธิบายพอดี ลิสติ้ง 14-1 แสดงตัวอย่างคอมเมนต์เอกสารประกอบสำหรับฟังก์ชัน add_one ในเครตชื่อ my_crate

/// 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
}

ตรงนี้ เราเขียนคำอธิบายว่าฟังก์ชัน 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: อธิบายถึงสถานการณ์ที่อาจทำให้ฟังก์ชันเกิดการแพนิก (panic) เพื่อให้ผู้เรียกใช้งานฟังก์ชันระมัดระวังและหลีกเลี่ยงการเรียกใช้ในกรณีดังกล่าว
  • Errors: หากฟังก์ชันส่งคืนค่าเป็น Result การอธิบายถึงชนิดของข้อผิดพลาดที่อาจเกิดขึ้น รวมถึงเงื่อนไขที่จะทำให้เกิดข้อผิดพลาดเหล่านั้น จะมีประโยชน์อย่างยิ่งต่อผู้เรียกใช้งาน เพื่อให้พวกเขาสามารถเขียนโค้ดจัดการข้อผิดพลาดแต่ละรูปแบบได้อย่างถูกต้อง
  • Safety: หากฟังก์ชันนั้นเป็นฟังก์ชันแบบ unsafe (ซึ่งเราจะได้เรียนรู้เรื่อง unsafe ในบทที่ 20) ควรอธิบายเหตุผลว่าทำไมฟังก์ชันจึงไม่ปลอดภัย พร้อมระบุเงื่อนไขคงที่ (invariants) ที่ผู้เรียกใช้งานจำเป็นต้องรักษาความถูกต้องไว้

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

คอมเมนต์เอกสารประกอบในฐานะเทสต์

การเพิ่มบล็อกโค้ดตัวอย่างลงในคอมเมนต์เอกสารประกอบไม่เพียงแต่ช่วยสาธิตวิธีใช้งานไลบรารีของคุณเท่านั้น แต่ยังมีโบนัสพิเศษอีกด้วย: นั่นคือการรัน 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 อีกครั้ง เราจะเห็นว่าการทดสอบเอกสารประกอบ (documentation tests หรือ doc-tests) สามารถตรวจจับความไม่สอดคล้องกันระหว่างโค้ดตัวอย่างกับโค้ดจริงได้อย่างแม่นยำ!

คอมเมนต์ของรายการที่ครอบอยู่

รูปแบบคอมเมนต์เอกสารประกอบ //! จะทำหน้าที่เพิ่มคำอธิบายให้กับรายการที่ครอบคอมเมนต์นี้อยู่ แทนที่จะให้กับรายการที่ตามหลังคอมเมนต์ เรามักจะใช้คอมเมนต์รูปแบบนี้ไว้ที่ต้นไฟล์รากของเครต (ตามธรรมเนียมคือ src/lib.rs) หรือภายในมอดูล เพื่อเขียนคำอธิบายภาพรวมของเครตหรือมอดูลนั้นๆ

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

//! # 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
}

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

เมื่อเรารัน cargo doc --open คอมเมนต์เหล่านี้จะแสดงบนหน้าแรกของเอกสารประกอบสำหรับ my_crate เหนือรายการสาธารณะในเครต ดังที่แสดงในรูปที่ 14-2

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

เอกสารประกอบ HTML ที่เรนเดอร์แล้วพร้อมคอมเมนต์สำหรับเครตโดยรวม

รูปที่ 14-2: เอกสารประกอบที่เรนเดอร์แล้วสำหรับ my_crate รวมถึงคอมเมนต์ที่อธิบายเครตโดยรวม

การส่งออก API สาธารณะที่สะดวกต่อการใช้งาน

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

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

ข่าวดีก็คือ หากโครงสร้างนั้น_ไม่_สะดวกสำหรับผู้อื่นในการใช้จากไลบรารีอื่น คุณไม่จำเป็นต้องจัดเรียงโครงสร้างภายในของคุณใหม่: แต่คุณสามารถส่งออกรายการซ้ำ (re-export) เพื่อสร้างโครงสร้างสาธารณะที่แตกต่างจากโครงสร้างส่วนตัวของคุณได้โดยใช้ pub use การส่งออกซ้ำ (re-exporting) จะนำรายการสาธารณะจากตำแหน่งหนึ่งมาเปิดเผยเป็นสาธารณะในอีกตำแหน่งหนึ่ง ราวกับว่ามันถูกนิยามไว้ในตำแหน่งใหม่นั้นโดยตรง

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

//! # 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 แสดงว่าหน้าแรกของเอกสารประกอบสำหรับเครตนี้ที่สร้างโดย cargo doc จะมีหน้าตาอย่างไร

เอกสารประกอบที่เรนเดอร์แล้วสำหรับเครต `art` ที่แสดงรายการมอดูล `kinds` และ `utils`

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

โปรดสังเกตว่าชนิด PrimaryColor และ SecondaryColor ไม่ได้แสดงอยู่ในหน้าแรก และฟังก์ชัน mix ก็เช่นกัน เราต้องคลิก kinds และ utils เพื่อดูมัน

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

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

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

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

เพื่อขจัดการจัดระเบียบภายในออกจาก API สาธารณะ เราสามารถแก้ไขโค้ดเครต art ในลิสติ้ง 14-3 เพื่อเพิ่มคำสั่ง pub use ที่ส่งออกรายการอีกครั้งที่ระดับบนสุด ดังที่แสดงในลิสติ้ง 14-5

//! # 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
    }
}

เอกสาร API ที่ cargo doc สร้างให้กับเครตนี้จะแสดงรายการและลิงก์การส่งออกอีกครั้งบนหน้าแรก ดังที่แสดงในรูปที่ 14-4 ทำให้ชนิด PrimaryColor และ SecondaryColor กับฟังก์ชัน mix ค้นหาได้ง่ายขึ้น

เอกสารประกอบที่เรนเดอร์แล้วสำหรับเครต `art` โดยมีการส่งออกอีกครั้งบนหน้าแรก

รูปที่ 14-4: หน้าแรกของเอกสารประกอบสำหรับ art ที่แสดงรายการการส่งออกอีกครั้ง

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

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

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

ในกรณีที่มีมอดูลซ้อนกันหลายชั้น การส่งออกรายการอีกครั้งที่ระดับบนสุดด้วย 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

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

การเพิ่มเมทาดาทาให้เครตใหม่

สมมติว่าคุณมีเครตที่คุณต้องการเผยแพร่ ก่อนการเผยแพร่ คุณจะต้องเพิ่มข้อมูลเมทาดาทาบางอย่างในส่วน [package] ของไฟล์ Cargo.toml ของเครต

เครตของคุณจะต้องมีชื่อที่ไม่ซ้ำใคร ในขณะที่คุณทำงานกับเครตในเครื่อง คุณจะตั้งชื่อเครตอะไรก็ได้ตามใจ แต่ชื่อเครตบน crates.io ถูกจัดสรรตามหลักมาก่อนได้ก่อน เมื่อชื่อเครตถูกใช้ไปแล้ว ไม่มีใครอื่นสามารถเผยแพร่เครตด้วยชื่อนั้นได้ ก่อนพยายามเผยแพร่เครต โปรดค้นหาชื่อที่คุณต้องการใช้ หากชื่อนั้นถูกใช้ไปแล้ว คุณจะต้องหาชื่ออื่นและแก้ไขฟิลด์ name ในไฟล์ Cargo.toml ใต้ส่วน [package] เพื่อใช้ชื่อใหม่ในการเผยแพร่ เช่นนี้:

ชื่อไฟล์: Cargo.toml

[package]
name = "guessing_game"

แม้ว่าคุณจะเลือกชื่อที่ไม่ซ้ำใครแล้ว เมื่อคุณรัน cargo publish เพื่อเผยแพร่เครต ณ จุดนี้ คุณจะได้คำเตือน (warning) แล้วจึงได้ข้อผิดพลาด:

$ 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 คุณต้องระบุ_รหัสระบุสัญญาอนุญาต_ Linux Foundation’s Software Package Data Exchange (SPDX) แสดงรายการรหัสที่คุณใช้เป็นค่านี้ได้ ตัวอย่างเช่น หากต้องการระบุว่าคุณได้ให้สัญญาอนุญาตเครตของคุณภายใต้ MIT License ให้เพิ่มรหัส 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 ของคุณและเผยแพร่ใหม่ ใช้กฎการกำหนดเวอร์ชันเชิงความหมาย (semantic versioning) ในการตัดสินว่าเลขเวอร์ชันถัดไปที่เหมาะสมคืออะไร โดยอิงจากชนิดของการเปลี่ยนแปลงที่คุณได้ทำ จากนั้นรัน cargo publish เพื่ออัปโหลดเวอร์ชันใหม่

การเลิกใช้เวอร์ชันจาก Crates.io

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

การถอน (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

การถอน_ไม่ได้_ลบโค้ดใดๆ ตัวอย่างเช่น มันไม่สามารถลบความลับที่ถูกอัปโหลดไปโดยไม่ตั้งใจได้ หากสิ่งนั้นเกิดขึ้น คุณต้องรีเซ็ตความลับเหล่านั้นทันที