همه‌چیز درباره فایل Cargo.toml در Rust: راهنمای جامع

در زبان برنامه‌نویسی Rust، ابزار Cargo نقش کلیدی در مدیریت پروژه‌ها ایفا می‌کند. این ابزار قدرتمند به توسعه‌دهندگان کمک می‌کند تا فرآیند ساخت، مدیریت وابستگی‌ها و انتشار پروژه‌ها را به‌سادگی انجام دهند. در مرکز هر پروژه‌ای که با Cargo مدیریت می‌شود، فایلی به نام Cargo.toml قرار دارد. این فایل، که به نوعی تنظیمات اصلی پروژه را در خود جای داده، مشخص می‌کند که پروژه چگونه باید ساخته شود، چه وابستگی‌هایی دارد و چه ویژگی‌هایی باید فعال شوند. در این مقاله، قصد داریم به‌صورت جامع و دقیق تمام جنبه‌های فایل Cargo.toml را بررسی کنیم تا بتوانید با تسلط بیشتری از آن در پروژه‌های خود استفاده کنید.

فایل Cargo.toml چیست و چه اهمیتی دارد؟

فایل Cargo.toml در واقع فایل پیکربندی اصلی پروژه‌های Rust است که با استفاده از ابزار Cargo مدیریت می‌شوند. این فایل در ریشه پروژه قرار می‌گیرد و اطلاعاتی مانند نام پروژه، نسخه، وابستگی‌ها و تنظیمات مختلف را در خود نگه می‌دارد. فرمت این فایل بر پایه TOML (مخفف Tom's Obvious, Minimal Language) است که یک زبان ساده و خوانا برای تعریف تنظیمات محسوب می‌شود.

هر زمان که دستوری مانند cargo build یا cargo run اجرا می‌کنید، Cargo ابتدا به سراغ این فایل می‌رود تا اطلاعات لازم را از آن بخواند. به همین دلیل، درک ساختار و قابلیت‌های این فایل برای هر توسعه‌دهنده Rust ضروری است.

ساختار کلی فایل Cargo.toml

یک فایل Cargo.toml ساده ممکن است به این شکل باشد:

[package]
name = "my_project"
version = "0.1.0"
edition = "2021"

[dependencies]
serde = "1.0"

در این مثال، دو بخش اصلی دیده می‌شود: بخش [package] که اطلاعات پایه پروژه را مشخص می‌کند و بخش [dependencies] که وابستگی‌های پروژه را تعریف می‌کند. اما این تنها بخش کوچکی از قابلیت‌های این فایل است. در ادامه، تمام بخش‌ها و فیلدهای ممکن را به‌صورت دقیق بررسی خواهیم کرد.

بخش [package]: اطلاعات پایه پروژه

بخش [package] شامل اطلاعات اصلی پروژه است که برای شناسایی و مدیریت آن استفاده می‌شود. فیلدهای مهم این بخش عبارت‌اند از:

• name: نام پروژه را مشخص می‌کند. این نام باید منحصربه‌فرد باشد، به‌خصوص اگر قصد دارید پروژه را در crates.io منتشر کنید (مثال: "my_project").

• version: نسخه پروژه، که معمولاً از فرمت Semantic Versioning پیروی می‌کند (مثال: "0.1.0").

• edition: نسخه ادیشن Rust که پروژه از آن استفاده می‌کند (مانند "2021", "2018" یا "2015"). این فیلد مشخص می‌کند که کد شما با کدام مجموعه از قوانین و ویژگی‌های Rust سازگار است.

• authors: فهرست نویسندگان پروژه (مثال: ["Sina Jalalvandi <[email protected]>"]).

• description: توضیحی کوتاه درباره پروژه، که در صورت انتشار در crates.io نمایش داده می‌شود.

• license: نوع مجوز پروژه (مانند "MIT" یا "Apache-2.0").

• repository: آدرس مخزن پروژه (مثلاً لینک گیت‌هاب).

• homepage: آدرس وب‌سایت پروژه (در صورت وجود).

• keywords: کلمات کلیدی مرتبط با پروژه برای جستجو در crates.io (مثال: ["web", "rust", "api"]).

• categories: دسته‌بندی‌های پروژه (مثال: ["web-development", "data-structures"]).

• readme: مسیر فایل README پروژه (مثال: "README.md") که در زمان انتشار استفاده می‌شود.

• rust-version: حداقل نسخه Rust موردنیاز برای پروژه (مثال: "1.60")؛ این فیلد اختیاری است.

یک نمونه کامل‌تر از بخش [package]:

[package]
name = "cool_app"
version = "0.2.0"
edition = "2021"
authors = ["Sara Ahmadi <[email protected]>"]
description = "یه برنامه ساده برای تست Rust"
license = "MIT"
repository = "https://github.com/sara/cool_app"
homepage = "https://sara.example.com/cool_app"
keywords = ["rust", "test", "app"]
categories = ["development-tools"]
rust-version = "1.65"

بخش [dependencies]: تعریف وابستگی‌ها

بخش [dependencies] برای مشخص کردن پکیج‌های خارجی (crates) موردنیاز پروژه استفاده می‌شود. می‌توانید نسخه دقیق یا بازه‌ای از نسخه‌ها را برای هر وابستگی تعیین کنید. چند روش رایج برای تعریف وابستگی‌ها:

• نسخه ساده: مانند serde = "1.0" که نسخه 1.0 از crate موردنظر را مشخص می‌کند.

• بازه نسخه: مانند serde = ">1.0, <2.0" که هر نسخه‌ای بین 1.0 و 2.0 را شامل می‌شود.

• با ویژگی‌ها (features): اگر crate موردنظر قابلیت‌های اختیاری داشته باشد، می‌توانید آن‌ها را فعال کنید:

[dependencies]
serde = { version = "1.0", features = ["derive"] }

مسیر محلی: اگر crate در سیستم شما باشد:

[dependencies]
my_local_crate = { path = "../my_local_crate" }

مخزن گیت: برای استفاده مستقیم از یک مخزن گیت:

[dependencies]
some_crate = { git = "https://github.com/user/some_crate" }

بخش [dev-dependencies]: وابستگی‌های توسعه

این بخش برای وابستگی‌هایی است که فقط در مرحله توسعه و تست استفاده می‌شوند و در نسخه نهایی پروژه (هنگام اجرای cargo build --release) وارد نمی‌شوند. مثال:

[dev-dependencies]
assert_approx_eq = "1.1"

بخش [build-dependencies]: وابستگی‌های ساخت

اگر پروژه شما از اسکریپت ساخت (build script) استفاده می‌کند، وابستگی‌های موردنیاز آن را می‌توانید در این بخش تعریف کنید:

[build-dependencies]
cc = "1.0"

بخش [features]: قابلیت‌های اختیاری

بخش [features] به شما امکان می‌دهد قابلیت‌های اختیاری برای پروژه تعریف کنید که کاربران بتوانند آن‌ها را فعال یا غیرفعال کنند. مثال:

[features]
default = ["logging"]
logging = ["log"]
extra = []

در این مثال، default مشخص می‌کند که ویژگی logging به‌صورت پیش‌فرض فعال باشد. ویژگی extra نیز تعریف شده اما فعلاً وابستگی‌ای ندارد.

بخش [lib]: تنظیمات کتابخانه

اگر پروژه شما یک کتابخانه (library) است، می‌توانید تنظیمات آن را در این بخش مشخص کنید:

• name: نام کتابخانه (در صورتی که با نام پکیج متفاوت باشد).

• path: مسیر فایل اصلی کتابخانه (پیش‌فرض: src/lib.rs).

• crate-type: نوع خروجی کتابخانه (مانند "cdylib" برای کتابخانه‌های سازگار با C).

مثال:

[lib]
name = "my_lib"
path = "src/my_lib.rs"
crate-type = ["rlib"]

بخش [[bin]]: تنظیمات فایل‌های اجرایی

اگر پروژه شما شامل برنامه‌های اجرایی (binary) است، می‌توانید چندین فایل اجرایی را در این بخش تعریف کنید:

[[bin]]
name = "my_app"
path = "src/main.rs"

[[bin]]
name = "another_app"
path = "src/another.rs"

بخش [profile]: تنظیمات بهینه‌سازی

این بخش برای تنظیم نحوه بهینه‌سازی پروژه در مراحل مختلف ساخت استفاده می‌شود. سه پروفایل اصلی وجود دارد:

• [profile.dev]: برای مرحله توسعه (با دیباگ فعال).

• [profile.release]: برای نسخه نهایی (بهینه‌سازی بالا).

• [profile.test]: برای تست‌ها.

مثال:

[profile.release]
opt-level = 3  # حداکثر بهینه‌سازی
debug = false

بخش [workspace]: مدیریت چند پروژه

اگر چندین پروژه مرتبط دارید، می‌توانید آن‌ها را در یک Workspace مدیریت کنید:

[workspace]
members = ["crate1", "crate2"]

بخش [badges]: نمایش وضعیت پروژه

بخش [badges] در فایل Cargo.toml به شما امکان می‌دهد وضعیت پروژه را به‌صورت بصری و با استفاده از برچسب‌های کوچک (badges) نمایش دهید. این برچسب‌ها معمولاً در صفحه پروژه در crates.io یا در مستندات (مثلاً README گیت‌هاب) نشان داده می‌شوند و اطلاعاتی درباره وضعیت توسعه، تست‌ها یا کیفیت پروژه به کاربران ارائه می‌دهند. استفاده از بج‌ها می‌تواند پروژه شما را حرفه‌ای‌تر نشان دهد و اعتماد کاربران را جلب کند.

بج‌های رایج

در ادامه، چند نمونه از بج‌های رایجی که می‌توانید در این بخش تعریف کنید، آورده شده است:

• maintenance: این بج وضعیت نگهداری پروژه را نشان می‌دهد. مقادیر ممکن برای آن عبارت‌اند از:

  • "actively-developed": پروژه در حال توسعه فعال است.

  • "passively-maintained": پروژه به‌صورت غیرفعال نگهداری می‌شود.

  • "as-is": پروژه بدون تغییر ارائه شده است.

  • "experimental": پروژه آزمایشی است.

  • "deprecated": پروژه منسوخ شده است.

مثال:

[badges]
maintenance = { status = "actively-developed" }

• codecov: برای نمایش پوشش تست (code coverage) پروژه، اگر از سرویسی مثل Codecov استفاده می‌کنید.

مثال:

[badges]
codecov = { repository = "user/repo", branch = "main", service = "github" }

بج‌های دیگر: بج‌های دیگری مانند travis-ci (برای Travis CI)، circle-ci (برای CircleCI)، یا is-it-maintained-issue-resolution (برای نمایش میانگین زمان حل مسائل) نیز وجود دارند که بسته به نیاز پروژه می‌توانید از آن‌ها استفاده کنید.

نکات مهم درباره بج‌ها

• محدودیت نمایش: همه بج‌ها در crates.io نمایش داده نمی‌شوند. برای مثال، بج maintenance در crates.io نشان داده می‌شود، اما بج‌های مربوط به CI/CD (مانند github-actions) بیشتر در README گیت‌هاب استفاده می‌شوند.

• تنظیمات اضافی: برای بج‌های مربوط به CI/CD یا پوشش تست، باید ابتدا سرویس مربوطه (مثلاً GitHub Actions یا Codecov) را در پروژه خود تنظیم کرده باشید.

• نمایش در README: برای نمایش بج‌ها در README، می‌توانید از لینک‌های مستقیم بج (مثلاً از shields.io یا خود سرویس) استفاده کنید. به‌عنوان مثال:

![CI](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)

استفاده از بج‌ها نه‌تنها اطلاعات مفیدی به کاربران ارائه می‌دهد، بلکه نشان‌دهنده توجه شما به کیفیت و نگهداری پروژه است.

نکات تکمیلی و کاربردی

• فایل Cargo.lock: این فایل همراه با Cargo.toml ایجاد می‌شود و نسخه دقیق وابستگی‌ها را قفل می‌کند. برای پروژه‌های اجرایی توصیه می‌شود آن را در گیت نگه دارید، اما برای کتابخانه‌ها معمولاً نیازی نیست.

• دستورات مفید: می‌توانید از cargo check برای بررسی سریع پروژه یا از cargo update برای به‌روزرسانی وابستگی‌ها استفاده کنید.

• فیلدهای سفارشی: امکان افزودن فیلدهای سفارشی با پیشوند metadata وجود دارد (مثال: [package.metadata.docs]).

حرف آخر

فایل Cargo.toml یکی از مهم‌ترین اجزای هر پروژه Rust است که با ابزار Cargo مدیریت می‌شود. این فایل با ساختار ساده اما قدرتمند خود، امکان مدیریت پروژه، وابستگی‌ها و تنظیمات مختلف را فراهم می‌کند. در این مقاله، تمام بخش‌ها و قابلیت‌های این فایل را بررسی کردیم تا بتوانید با اطمینان بیشتری از آن در پروژه‌های خود استفاده کنید. اگر سؤال یا نکته‌ای در این زمینه دارید، خوشحال می‌شوم در بخش نظرات با شما در میان بگذارم.