.TH HYPERFINE 1
.SH "نام (NAME)"
hyperfine \- ابزار محک‌زنی خط فرمان
.SH "خلاصه دستور (SYNOPSIS)"
.B hyperfine
.RB [ \-ihVN ]
.RB [ \-\-warmup
.IR NUM ]
.RB [ \-\-min\-runs
.IR NUM ]
.RB [ \-\-max\-runs
.IR NUM ]
.RB [ \-\-runs
.IR NUM ]
.RB [ \-\-setup
.IR CMD ]
.RB [ \-\-prepare
.IR CMD ]
.RB [ \-\-conclude
.IR CMD ]
.RB [ \-\-cleanup
.IR CMD ]
.RB [ \-\-parameter\-scan
.IR VAR
.IR MIN
.IR MAX ]
.RB [ \-\-parameter\-step\-size
.IR DELTA ]
.RB [ \-\-parameter\-list
.IR VAR
.IR VALUES ]
.RB [ \-\-shell
.IR SHELL ]
.RB [ \-\-style
.IR TYPE ]
.RB [ \-\-sort
.IR METHOD ]
.RB [ \-\-time-unit
.IR UNIT ]
.RB [ \-\-export\-asciidoc
.IR FILE ]
.RB [ \-\-export\-csv
.IR FILE ]
.RB [ \-\-export\-json
.IR FILE ]
.RB [ \-\-export\-markdown
.IR FILE ]
.RB [ \-\-export\-orgmode
.IR FILE ]
.RB [ \-\-output
.IR WHERE ]
.RB [ \-\-input
.IR WHERE ]
.RB [ \-\-command\-name
.IR NAME ]
.RI [ COMMAND... ]
.SH "توضیحات (DESCRIPTION)"
ابزاری برای محک‌زنی (بنچمارک) در خط فرمان که شامل موارد زیر است:
.LP
.RS
* تحلیل آماری در چندین اجرای مختلف
.RE
.RS
* پشتیبانی از دستورهای دلخواه پوسته (shell)
.RE
.RS
* بازخورد پیوسته دربارهٔ پیشرفت محک‌زنی و برآوردهای فعلی
.RE
.RS
* امکان اجرای مراحل گرم‌کردن (warmup) پیش از محک‌زنی اصلی
.RE
.RS
* قابلیت تنظیم دستورهای پاک‌سازی کَش پیش از هر دور زمان‌سنجی
.RE
.RS
* تشخیص آماری داده‌های پرت جهت شناسایی اثرات تداخل برنامه‌های دیگر و کَش
.RE
.RS
* برون‌ریزی نتایج به قالب‌های گوناگون: CSV، JSON، Markdown، AsciiDoc
.RE
.RS
* محک‌زنی با پارامترهای متغیر (برای مثال تغییر تعداد ریسه‌ها)
.RE.SH "گزینه‌ها (OPTIONS)"
.HP
\fB\-w\fR, \fB\-\-warmup\fR \fINUM\fP
.IP
اجرای \fINUM\fP بار گرم‌کردن پیش از بنچمارک اصلی. این گزینه می‌تواند برای پر کردن حافظه‌های موقت (دیسک) برای برنامه‌های سنگین از نظر ورودی/خروجی (I/O) استفاده شود.
.HP
\fB\-m\fR, \fB\-\-min\-runs\fR \fINUM\fP
.IP
اجرای دست‌کم \fINUM\fP بار برای هر دستور. پیش‌فرض: 10.
.HP
\fB\-M\fR, \fB\-\-max\-runs\fR \fINUM\fP
.IP
اجرای حداکثر \fINUM\fP بار برای هر دستور. به‌طور پیش‌فرض هیچ محدودیتی وجود ندارد.
.HP
\fB\-r\fR, \fB\-\-runs\fR \fINUM\fP
.IP
اجرای دقیقاً \fINUM\fP بار برای هر دستور. اگر این گزینه مشخص نشود، \fBhyperfine\fR تعداد دفعات اجرا را به‌طور خودکار تعیین می‌کند.
.HP
\fB\-s\fR, \fB\-\-setup\fR \fICMD...\fP
.IP
اجرای \fICMD\fP یک بار پیش از هر مجموعه از اجراهای زمان‌سنجی. این گزینه برای کامپایل کردن نرم‌افزار شما یا با پارامترهای ارائه‌شده مفید است، یا برای انجام هر کار دیگری که باید یک بار پیش از یک سری از اجراهای بنچمارک انجام شود، نه هر بار مانند آنچه با گزینهٔ \fB\-\-prepare\fR رخ می‌دهد.
.HP
\fB\-p\fR, \fB\-\-prepare\fR \fICMD...\fP
.IP
اجرای \fICMD\fP پیش از هر اجرای زمان‌سنجی. این گزینه برای نمونه جهت پاک‌سازی حافظه‌های موقت دیسک مفید است.
گزینهٔ \fB\-\-prepare\fR می‌تواند یک بار برای همهٔ دستورها یا چند بار، یک بار برای هر دستور مشخص شود. در حالت دوم، هر دستور آماده‌سازی پیش از دستور بنچمارک متناظر با آن اجرا خواهد شد.
.HP
\fB\-\-conclude\fR \fICMD...\fP
.IP
اجرای \fICMD\fP پس از هر اجرای زمان‌سنجی. این گزینه برای نمونه جهت پاک‌سازی حافظه‌های موقت دیسک مفید است.
گزینهٔ \fB\-\-conclude\fR می‌تواند یک بار برای همهٔ دستورها یا چند بار، یک بار برای هر دستور مشخص شود. در حالت دوم، هر دستور پایانی پس از دستور بنچمارک متناظر با آن اجرا خواهد شد.
.HP
\fB\-c\fR, \fB\-\-cleanup\fR \fICMD...\fP
.IP
اجرای \fICMD\fP پس از اتمام تمامی اجراهای بنچمارک برای هر دستور جداگانهٔ تحت بنچمارک. این گزینه زمانی مفید است که دستورهای تحت بنچمارک آثاری ایجاد کنند که نیاز به پاک‌سازی داشته باشند. این دستور برخلاف گزینهٔ \fB\-\-conclude\fR که پس از هر بار اجرا اجرا می‌شود، تنها یک بار برای هر سری از اجراهای بنچمارک اجرا خواهد شد.
.HP
\fB\-P\fR, \fB\-\-parameter\-scan\fR \fIVAR\fP \fIMIN\fP \fIMAX\fP
.IP
اجرای بنچمارک برای هر مقدار در بازهٔ \fIMIN..MAX\fP. رشتهٔ '{\fIVAR\fP}' در هر دستور با مقدار کنونی پارامتر جایگزین می‌شود.
.IP
.RS
مثال:
.RS
\fBhyperfine\fR \fB\-P\fR threads 1 8 'make \-j {threads}'
.RE
.RE
.IP
این دستور بنچمارک‌ها را برای 'make \-j 1'، 'make \-j 2'، ...، 'make \-j 8' اجرا می‌کند.
.IP
برای افزایش مقدار بر اساس الگوهای مختلف، از محاسبات حسابی پوسته استفاده کنید.
.IP
.RS
مثال:
.RS
\fBhyperfine\fR \fB\-P\fR size 0 3 'sleep $((2**{size}))'
.RE
.RE
.IP
این دستور بنچمارک‌ها را با افزایش‌های توان ۲ اجرا می‌کند: 'sleep 1'، 'sleep 2'، 'sleep 4'، ...
.IP
نحو دقیق ممکن است بسته به پوسته و سیستم‌عامل شما متفاوت باشد.
.HP
\fB\-D\fR, \fB\-\-parameter\-step\-size\fR \fIDELTA\fP
.IP
این آرگومان نیازمند این است که \fB\-\-parameter\-scan\fR نیز مشخص شده باشد. پیمایش بازهٔ \fIMIN..MAX\fP با گام‌های \fIDELTA\fP.
.IP
.RS
مثال:
.RS
\fBhyperfine\fR \fB\-P\fR delay 0.3 0.7 \fB\-D\fR 0.2 'sleep {delay}'
.RE
.RE
.IP
این دستور بنچمارک‌ها را برای 'sleep 0.3'، 'sleep 0.5' و 'sleep 0.7' اجرا می‌کند.
.HP
\fB\-L\fR, \fB\-\-parameter\-list\fR \fIVAR\fP \fIVALUES\fP
.IP
اجرای بنچمارک برای هر مقدار در فهرست جداشده با کامای \fIVALUES\fP. رشتهٔ '{\fIVAR\fP}' در هر دستور با مقدار کنونی پارامتر جایگزین می‌شود.
.IP
.RS
مثال:
.RS
\fBhyperfine\fR \fB\-L\fR compiler gcc,clang '{compiler} \-O2 main.cpp'
.RE
.RE
.IP
این دستور بنچمارک‌ها را برای 'gcc \-O2 main.cpp' و 'clang \-O2 main.cpp' اجرا می‌کند.
.IP
این گزینه می‌تواند چندین بار مشخص شود تا بنچمارک‌ها برای تمام ترکیب‌های ممکن پارامتر اجرا شوند.
.HP
\fB\-S\fR, \fB\-\-shell\fR \fISHELL\fP
.IP
تنظیم پوستهٔ مورد استفاده برای اجرای دستورهای تحت بنچمارک. این مقدار می‌تواند نام یا مسیر فایل اجرایی پوسته باشد، یا یک خط فرمان کامل مانند "bash \fB\-\-norc\fR". همچنین می‌تواند روی "default" تنظیم شود تا پوستهٔ پیش‌فرض روی این پلتفرم به‌طور صریح انتخاب گردد. در نهایت، می‌تواند روی "none" نیز تنظیم شود تا پوسته غیرفعال شود. در این حالت، دستورها مستقیماً اجرا خواهند شد. آن‌ها همچنان می‌توانند آرگومان داشته باشند، اما کارهای پیچیده‌تر مانند "sleep 0.1; sleep 0.2" بدون پوسته امکان‌پذیر نیستند.
.HP
\fB\-N\fR
.IP
یک نام مستعار برای '\-\-shell=none'.
.HP
\fB\-i\fR, \fB\-\-ignore\-failure\fR
.IP
نادیده گرفتن کدهای خروج غیرصفر برنامه‌های تحت بنچمارک.
.HP
\fB\-\-style\fR \fITYPE\fP
.IP
تنظیم سبک خروجی \fITYPE\fP (پیش‌فرض: auto). این گزینه را روی 'basic' تنظیم کنید تا رنگ‌بندی خروجی و عناصر تعاملی غیرفعال شوند. آن را روی 'full' تنظیم کنید تا تمام جلوه‌ها حتی در صورت شناسایی نشدن ترمینال تعاملی فعال شوند. آن را روی 'nocolor' تنظیم کنید تا خروجی تعاملی بدون هیچ رنگی باقی بماند. آن را روی 'color' تنظیم کنید تا رنگ‌ها بدون خروجی تعاملی حفظ شوند. آن را روی 'none' تنظیم کنید تا تمام خروجی‌های ابزار غیرفعال شوند.
.HP
\fB\-\-sort\fR \fIMETHOD\fP
.IP
مشخص کردن ترتیب مرتب‌سازی خلاصهٔ مقایسهٔ سرعت و جدول‌های صادرشده برای قالب‌های نشانه‌گذاری (Markdown، AsciiDoc، org\-mode):
.RS
.IP "auto (پیش‌فرض)"
مقایسهٔ سرعت بر اساس زمان مرتب می‌شود و جدول‌های نشانه‌گذاری بر اساس دستور (ترتیب ورودی) مرتب خواهند شد.
.IP "command"
مرتب‌سازی بنچمارک‌ها به همان روشی که مشخص شده بودند
.IP "mean\-time"
مرتب‌سازی بنچمارک‌ها بر اساس میانگین زمان اجرا
.RE
.HP
\fB\-u\fR, \fB\-\-time\-unit\fR \fIUNIT\fP
.IP
تنظیم واحد زمان مورد استفاده. مقادیر ممکن: microsecond، millisecond، second. اگر این گزینه داده نشود، واحد زمان به‌طور خودکار تعیین می‌شود.
این گزینه هم بر خروجی استاندارد و هم بر تمامی قالب‌های خروجی به‌جز CSV و JSON تأثیر می‌گذارد.
.HP
\fB\-\-export\-asciidoc\fR \fIFILE\fP 
.IP
صادر کردن آمار خلاصهٔ زمان‌سنجی به صورت یک جدول AsciiDoc به \fIFILE\fP داده‌شده. واحد زمان خروجی می‌تواند با استفاده از گزینهٔ \fB\-\-time\-unit\fR تغییر یابد.
.HP
\fB\-\-export\-csv\fR \fIFILE\fP
.IP
صادر کردن آمار خلاصهٔ زمان‌سنجی در قالب CSV به \fIFILE\fP داده‌شده. اگر به نتایج زمان‌سنجی هر اجرای جداگانه نیاز دارید، از قالب خروجی JSON استفاده کنید. واحد زمان خروجی همواره ثانیه است.
.HP
\fB\-\-export\-json\fR \fIFILE\fP
.IP
صادر کردن آمار خلاصهٔ زمان‌سنجی و زمان‌های اجراهای تکی در قالب JSON به \fIFILE\fP داده‌شده. واحد زمان خروجی همواره ثانیه است.
.HP
\fB\-\-export\-markdown\fR \fIFILE\fP
.IP
صادر کردن آمار خلاصهٔ زمان‌سنجی به صورت یک جدول Markdown به \fIFILE\fP داده‌شده. واحد زمان خروجی می‌تواند با استفاده از گزینهٔ \fB\-\-time\-unit\fR تغییر یابد.
.HP
\fB\-\-export\-orgmode\fR \fIFILE\fP.IP
صادر کردن آمار خلاصهٔ زمان‌بندی در قالب یک جدول org\-mode ایمکس به \fIFILE\fP مشخص‌شده. یکای زمان خروجی را می‌توان با استفاده از گزینهٔ \fB\-\-time\-unit\fR تغییر داد.
.HP
\fB\-\-show\-output\fR
.IP
چاپ stdout و stderr محک به جای سرکوب کردن آن. این کار زمان مورد نیاز برای اجرای محک‌ها را افزایش می‌دهد، بنابراین تنها باید برای اهداف اشکال‌زدایی یا هنگام ارزیابی سرعت خروجی استفاده شود.
.HP
\fB\-\-output\fR \fIWHERE\fP
.IP
کنترل محل بازهدایت خروجی محک. توجه داشته باشید که برخی برنامه‌ها مانند 'grep' تشخیص می‌دهند که خروجی استاندارد \fI\,/dev/null\/\fP است و بهینه‌سازی‌های خاصی را اعمال می‌کنند. برای جلوگیری از این موضوع، استفاده از \-\-output=pipe را در نظر بگیرید.
.IP
\fIWHERE\fP می‌تواند یکی از موارد زیر باشد:
.RS
.IP null
بازهدایت خروجی به \fI\,/dev/null\/\fP (پیش‌فرض).
.IP pipe
فرستادن خروجی به درون یک pipe پیش از دور انداختن آن.
.IP inherit
عدم بازهدایت خروجی (مشابه \&'\-\-show\-output').
.IP "<FILE>"
نوشتن خروجی در فایل مشخص‌شده.
.RE
.IP
این گزینه می‌تواند یک‌بار برای همهٔ دستورها یا چندبار، یک‌بار به ازای هر دستور مشخص شود. نکته: اگر می‌خواهید خروجی تک‌تک تکرارها را ثبت کنید، می‌توانید از بازهدایت پوسته و متغیر محیطی $HYPERFINE_ITERATION استفاده کنید: 'my-command > output-${HYPERFINE_ITERATION}.log'
.HP
\fB\-\-input\fR \fIWHERE\fP
.IP
کنترل این‌که ورودی محک از کجا تأمین شود.
.IP
\fIWHERE\fP می‌تواند یکی از موارد زیر باشد:
.RS
.IP null
خواندن از \fI\,/dev/null\/\fP (پیش‌فرض).
.IP "<FILE>"
خواندن ورودی از فایل مشخص‌شده.
.RE
.HP
\fB\-n\fR, \fB\-\-command\-name\fR \fiNAME\fP
.IP
اختصاص دادن یک \fiNAME\fP معنادار به یک دستور. در صورتی که چند دستور محک زده شوند، این گزینه می‌تواند چندین بار مشخص شود.
.HP
\fB\-h\fR, \fB\-\-help\fR
.IP
چاپ راهنما
.HP
\fB\-V\fR, \fB\-\-version\fR
.IP
چاپ نسخه
.SH "مثال‌ها (EXAMPLES)"
.LP
محک پایه از 'find . -name todo.txt':
.RS
.nf
\fBhyperfine\fR 'find . -name todo.txt'
.fi
.RE
.LP
انجام محک‌ها برای 'sleep 0.2' و 'sleep 3.2' با حداقل ۵ بار اجرا برای هرکدام:
.RS
.nf
\fBhyperfine\fR \fB\-\-min\-runs\fR 5 'sleep 0.2' 'sleep 3.2'
.fi
.RE
.LP
انجام محک 'grep' با حافظهٔ نهان دیسک گرم‌شده از طریق ۳ بار اجرای اولیه که بخشی از سنجش نیستند:
.RS
.nf
\fBhyperfine\fR \fB\-\-warmup\fR 3 'grep -R TODO *'
.fi
.RE
.LP
صادر کردن نتایج محک پیمایش پارامتر به یک جدول markdown:
.RS
.nf
\fBhyperfine\fR \fB\-\-export\-markdown\fR output.md \fB\-\-parameter-scan\fR time 1 5 'sleep {time}'
.fi
.RE
.LP
نمایش این‌که هر کدام از \fB\-\-setup\fR، \fB\-\-prepare\fR، \fB\-\-conclude\fR، \fIcmd\fP و \fB\-\-cleanup\fR چه زمانی اجرا خواهند شد:
.RS
.nf
\fBhyperfine\fR \fB\-L\fR n 1,2 \fB\-r\fR 2 \fB\-\-show-output\fR \\
	\fB\-\-setup\fR 'echo setup n={n}' \\
	\fB\-\-prepare\fR 'echo prepare={n}' \\
	\fB\-\-conclude\fR 'echo conclude={n}' \\
	\fB\-\-cleanup\fR 'echo cleanup n={n}' \\
	'echo command n={n}'
.fi
.RE
.RE.SH "نویسنده (AUTHOR)"
.LP
David Peter <mail@david-peter.de>
.LP
کد منبع، سامانه پیگیری باگ و اطلاعات تکمیلی را می‌توان در GitHub یافت:
.I https://github.com/sharkdp/hyperfine