| CARGO-BENCH(1) | General Commands Manual | CARGO-BENCH(1) |
نام (NAME)
cargo-bench - اجرای بنچمارکهای یک بسته
خلاصه دستور (SYNOPSIS)
cargo bench [options] [benchname] [-- bench-options]
توضیحات (DESCRIPTION)
کامپایل و اجرای بنچمارکها.
آرگومان فیلتر بنچمارک benchname و تمام آرگومانهای پس از دو خط تیره (--) به باینریهای بنچمارک و در نتیجه به libtest (چارچوب درونی rustc برای آزمون واحد و سنجش کارایی دقیق) ارسال میشوند. اگر آرگومانها را هم به Cargo و هم به باینری ارسال میکنید، آرگومانهای پس از -- به باینری و آرگومانهای پیش از آن به Cargo فرستاده میشوند. برای جزئیات درباره آرگومانهای libtest خروجی cargo bench -- --help را مشاهده کنید و فصل کتاب rustc درباره نحوه کارکرد آزمونها را در https://doc.rust-lang.org/rustc/tests/index.html بررسی نمایید.
بهعنوان مثال، دستور زیر فقط بنچمارکی با نام foo را اجرا میکند (و از سایر بنچمارکهای دارای نام مشابه مانند foobar صرفنظر میکند):
cargo bench -- foo --exact
بنچمارکها با گزینه --test در rustc ساخته میشوند که با پیوند دادن کد شما با libtest یک فایل اجرایی ویژه ایجاد میکند. این فایل اجرایی بهطور خودکار تمام توابعی را که با مشخصه #[bench] نشانهگذاری شدهاند اجرا میکند. Cargo پرچم --bench را به مهار آزمون (test harness) ارسال میکند تا مشخص سازد صرفنظر از اینکه مهار آزمون libtest باشد یا یک مهار سفارشی، تنها بنچمارکها اجرا شوند.
مهار آزمون libtest را میتوان با تنظیم harness = false در تنظیمات مانیفست هدف غیرفعال کرد؛ در این حالت، کد شما باید تابع main اختصاصی خود را برای مدیریت اجرای بنچمارکها ارائه دهد.
نکته:
مشخصه
#[bench]
https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html
در حال حاضر
ناپایدار (unstable)
بوده و تنها
در کانال nightly
https://doc.rust-lang.org/book/appendix-07-nightly-rust.html
در دسترس
است.
بستههایی
در crates.io
https://crates.io/keywords/benchmark
موجودند که
ممکن است به
اجرای
بنچمارکها
روی کانال
پایدار (stable)
کمک کنند،
مانند Criterion
https://crates.io/crates/criterion.
بهطور پیشفرض، cargo bench از پروفایل bench https://doc.rust-lang.org/cargo/reference/profiles.html#bench استفاده میکند که بهینهسازیها را فعال و اطلاعات اشکالزدایی را غیرفعال میسازد. اگر نیاز به اشکالزدایی یک بنچمارک دارید، میتوانید از گزینه خط فرمان --profile=dev برای جابهجایی به پروفایل dev استفاده کنید. سپس میتوانید بنچمارک با امکان اشکالزدایی فعال را درون یک اشکالزدا (debugger) اجرا نمایید.
دایرکتوری کاری بنچمارکها (Working directory of benchmarks)
دایرکتوری کاری هر بنچمارک روی دایرکتوری ریشه بستهای که بنچمارک به آن تعلق دارد تنظیم میشود. تنظیم دایرکتوری کاری بنچمارکها روی دایرکتوری ریشه بسته، این امکان را فراهم میآورد که بنچمارکها صرفنظر از اینکه cargo bench از کجا اجرا شده باشد، با استفاده از مسیرهای نسبی بهطور قابلاطمینان به فایلهای بسته دسترسی داشته باشند.
گزینهها (OPTIONS)
گزینههای بنچمارک (Benchmark Options)
--no-run
--no-fail-fast
اعضای پیشفرض یک فضای کاری را میتوان بهصراحت با کلید workspace.default-members در مانیفست ریشه تعیین کرد. اگر این مقدار تنظیم نشده باشد، یک فضای کاری مجازی شامل تمام اعضای فضای کاری خواهد بود (معادل ارسال --workspace)، و یک فضای کاری غیرمجازی فقط خودِ کریت ریشه را شامل میشود.
-p spec…, --package spec…
--workspace
--all
--exclude SPEC…
انتخاب هدف (Target Selection)
هنگامی که هیچ گزینهٔ انتخاب هدفی مشخص نشده باشد، cargo bench هدفهای زیر را از بستههای انتخابشده میسازد:
رفتار پیشفرض را میتوان با تنظیم پرچم bench برای آن هدف در تنظیمات مانیفست تغییر داد. تنظیم نمونهها به bench = true باعث ساخت و اجرای نمونه بهعنوان یک بنچمارک میشود و تابع main نمونه را با بستر آزمون libtest جایگزین میکند.
تنظیم هدفها به bench = false از سنجش کارایی آنها بهطور پیشفرض جلوگیری میکند. گزینههای انتخاب هدف که یک هدف را با نام مشخص میکنند (مانند --example foo) پرچم bench را نادیده گرفته و همیشه هدف مشخصشده را مورد سنجش کارایی قرار میدهند.
برای اطلاعات بیشتر دربارهٔ تنظیمات به ازای هر هدف، به Configuring a target https://doc.rust-lang.org/cargo/reference/cargo-targets.html#configuring-a-target مراجعه کنید.
هدفهای باینری در صورتی که یک آزمون یکپارچهسازی یا بنچمارک برای سنجش کارایی انتخاب شده باشد، بهطور خودکار ساخته میشوند. این به آزمون یکپارچهسازی اجازه میدهد تا فایل باینری را برای ارزیابی و آزمودن رفتار آن اجرا کند. متغیر محیطی CARGO_BIN_EXE_<name> https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates هنگام ساخت و اجرای آزمون یکپارچهسازی تنظیم میشود تا بتواند با استفاده از ماکروی env https://doc.rust-lang.org/std/macro.env.html یا تابع var https://doc.rust-lang.org/std/env/fn.var.html مکان فایل اجرایی را پیدا کند.
ارسال پرچمهای انتخاب هدف، تنها هدفهای مشخصشده را مورد سنجش کارایی قرار میدهد.
توجه داشته باشید که پرچمهای --bin، --example، --test و --bench نیز از الگوهای عمومی glob در یونیکس مانند *، ? و [] پشتیبانی میکنند. با این حال، برای جلوگیری از بسط تصادفی الگوهای glob توسط پوسته پیش از آنکه Cargo آنها را پردازش کند، باید پیرامون هر الگوی glob از نقلقول تکی یا جفتی استفاده کنید.
--lib
--bin name…
--bins
--example name…
--examples
--test name…
--tests
--bench name…
--benches
--all-targets
برای جزئیات بیشتر، مستندات ویژگیها https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options را ببینید.
-F features, --features features
--all-features
--no-default-features
گزینههای کامپایل (Compilation Options)
--target triple
مقادیر ممکن:
این مقدار همچنین میتواند با مقدار پیکربندی build.target https://doc.rust-lang.org/cargo/reference/config.html مشخص شود.
توجه داشته باشید که تعیین این پرچم باعث میشود Cargo در حالت متفاوتی اجرا شود که در آن مصنوعات هدف در یک دایرکتوری جداگانه قرار میگیرند. برای جزئیات بیشتر به مستندات حافظهٔ موقت ساخت https://doc.rust-lang.org/cargo/reference/build-cache.html مراجعه کنید.
--profile name
--timings
در پایان فرایند ساخت، فایلی به نام cargo-timing.html در دایرکتوری target/cargo-timings نوشته خواهد شد. در صورتی که بخواهید اجرای قبلی را بررسی کنید، یک گزارش اضافی با برچسب زمان در نام فایل آن نیز ذخیره میشود. این گزارشها صرفاً برای مطالعه توسط انسان مناسب هستند و دادههای زمانبندی ماشینخوان ارائه نمیدهند.
گزینههای خروجی (Output Options)
--target-dir directory
گزینههای نمایش (Display Options)
بهطور پیشفرض، بستر آزمایش Rust خروجی اجرای بنچمارک را پنهان میکند تا نتایج خوانا باقی بمانند. خروجی بنچمارک را میتوان (مثلاً برای اشکالزدایی) با ارسال --no-capture به باینریهای بنچمارک بازیابی کرد:
cargo bench -- --no-capture
-v, --verbose
-q, --quiet
--color when
همچنین میتواند با مقدار پیکربندی term.color https://doc.rust-lang.org/cargo/reference/config.html مشخص شود.
--message-format fmt
--manifest-path path
--ignore-rust-version
--locked
این گزینه ممکن است در محیطهایی که در آنها ساختهای قطعی (deterministic) مد نظر است، مانند خطوط لولهٔ CI، استفاده شود.
--offline
توجه داشته باشید که این کار ممکن است منجر به تفکیک وابستگیِ متفاوتی نسبت به حالت برخط (online) شود. Cargo خود را به crateهایی که بهصورت محلی دانلود شدهاند محدود میکند، حتی اگر طبق نسخهٔ محلی نمایه (index)، نسخهٔ جدیدتری موجود باشد. برای دانلود وابستگیها پیش از رفتن به حالت آفلاین، دستور cargo-fetch(1) را ببینید.
همچنین میتواند با مقدار پیکربندی net.offline https://doc.rust-lang.org/cargo/reference/config.html مشخص شود.
--frozen
گزینههای عمومی (Common Options)
+toolchain
--config KEY=VALUE یا PATH
-C PATH
این گزینه تنها در کانال nightly https://doc.rust-lang.org/book/appendix-07-nightly-rust.html در دسترس است و برای فعالسازی به پرچم -Z unstable-options نیاز دارد (ببینید: #10098 https://github.com/rust-lang/cargo/issues/10098).
-h, --help
-Z flag
-j N, --jobs N
اگرچه cargo bench شامل کامپایل میشود، اما گزینهٔ --keep-going را ارائه نمیدهد. از --no-fail-fast برای اجرای هرچه بیشتر بنچمارکها بدون توقف در نخستین شکست استفاده کنید. برای “کامپایل” کردن بیشترین بنچمارکهای ممکن، از --benches برای ساخت جداگانهٔ باینریهای بنچمارک استفاده کنید. برای نمونه:
cargo build --benches --release --keep-going cargo bench --no-fail-fast
محیط (ENVIRONMENT)
برای جزئیات دربارهٔ متغیرهای محیطی که Cargo میخواند، مرجع https://doc.rust-lang.org/cargo/reference/environment-variables.html را ببینید.
وضعیت خروج (EXIT STATUS)
مثالها (EXAMPLES)
cargo bench
cargo bench --bench bench_name -- modname::some_benchmark