เผยแพร่เครตไปยัง 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
รูปที่ 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
คอมเมนต์เอกสารประกอบภายในรายการมีประโยชน์โดยเฉพาะอย่างยิ่งสำหรับการอธิบายเครตและมอดูล ใช้มันเพื่ออธิบายจุดประสงค์โดยรวมของสิ่งที่บรรจุอยู่ เพื่อช่วยให้ผู้ใช้ของคุณเข้าใจการจัดระเบียบของเครต
รูปที่ 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 จะมีหน้าตาอย่างไร
รูปที่ 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 ค้นหาได้ง่ายขึ้น
รูปที่ 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
การถอน_ไม่ได้_ลบโค้ดใดๆ ตัวอย่างเช่น มันไม่สามารถลบความลับที่ถูกอัปโหลดไปโดยไม่ตั้งใจได้ หากสิ่งนั้นเกิดขึ้น คุณต้องรีเซ็ตความลับเหล่านั้นทันที