'\" t
.\"     Title: SCONS-TIME
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net>
.\"      Date: 08/26/2026
.\"    Manual: SCons 4.11.1
.\"    Source: SCons 4.11.1
.\"  Language: Persian
.\"
.TH "SCONS\-TIME" "1" "08/26/2026" "SCons 4\&.11\&.1" "SCons 4\&.11\&.1"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "نام (NAME)"
scons\-time \- تولید و نمایش اطلاعات زمان‌بندی SCons
.SH "خلاصه دستور (SYNOPSIS)"
.HP \w'\fBscons\-time\fR\ 'u
\fBscons\-time\fR \fIsubcommand\fR [\fIoptions\fR...] [\fIarguments\fR...]
.SH "تولید اطلاعات زمان‌بندی (GENERATING TIMING INFORMATION)"
.PP
\fBscons\-time run\fR
[\fB\-hnqv\fR] [\fB\-f \fR\fIFILE\fR] [\fB\-\-number=\fR\fINUMBER\fR] [\fB\-\-outdir=\fR\fIOUTDIR\fR] [\fB\-p \fR\fISTRING\fR] [\fB\-\-python=\fR\fIPYTHON\fR] [\fB\-s \fR\fIDIR\fR] [\fB\-\-scons=\fR\fISCONS\fR] [\fB\-\-svn=\fR\fIURL\fR] [\fIARGUMENTS\fR]
.SS "استخراج زمان‌بندی توابع (Extracting Function Timings)"
.PP
\fBscons\-time func\fR
[\fB\-h\fR] [\fB\-\-chdir=\fR\fIDIR\fR] [\fB\-f \fR\fIFILE\fR] [\fB\-\-fmt=\fR\fIFORMAT\fR] [\fB\-\-func=\fR\fINAME\fR] [\fB\-p \fR\fISTRING\fR] [\fB\-t \fR\fINUMBER\fR] [\fB\-\-title= TITLE\fR] [\fIARGUMENTS\fR]
.SS "استخراج آمار حافظه (Extracting Memory Statistics)"
.PP
\fBscons\-time mem\fR
[\fB\-h\fR] [\fB\-\-chdir=\fR\fIDIR\fR] [\fB\-f \fR\fIFILE\fR] [\fB\-\-fmt=\fR\fIFORMAT\fR] [\fB\-p \fR\fISTRING\fR] [\fB\-\-stage=\fR\fISTAGE\fR] [\fB\-t \fR\fINUMBER\fR] [\fB\-\-title=\fR\fITITLE\fR] [\fIARGUMENTS\fR]
.SS "استخراج شمارش اشیاء (Extracting Object Counts)"
.PP
\fBscons\-time obj\fR
[\fB\-h\fR] [\fB\-\-chdir=\fR\fIDIR\fR] [\fB\-f \fR\fIFILE\fR] [\fB\-\-fmt=\fR\fIFORMAT\fR] [\fB\-p \fR\fISTRING\fR] [\fB\-\-stage=\fR\fISTAGE\fR] [\fB\-t \fR\fINUMBER\fR] [\fB\-\-title=\fR\fITITLE\fR] [\fIARGUMENTS\fR]
.SS "استخراج زمان‌های اجرا (Extracting Execution Times)"
.PP
\fBscons\-time time\fR
[\fB\-h\fR] [\fB\-\-chdir=\fR\fIDIR\fR] [\fB\-f \fR\fIFILE\fR] [\fB\-\-fmt=\fR\fIFORMAT\fR] [\fB\-p \fR\fISTRING\fR] [\fB\-t \fR\fINUMBER\fR] [\fB\-\-title=\fR\fITITLE\fR] [\fB\-\-which=\fR\fIWHICH\fR] [\fIARGUMENTS\fR]
.SS "متن راهنما (Help Text)"
.PP
\fBscons\-time help\fR
\fISUBCOMMAND\fR
[\&.\&.\&.]
.SH "توضیحات (DESCRIPTION)"
.PP
دستور
\fBscons\-time\fR
یک پیکربندی SCons را در مجموعه‌ای استاندارد از زمان‌بندی‌های پروفایل‌شده اجرا می‌کند و می‌تواند اطلاعات حاصل از پروفایل‌ها و فایل‌های لاگ این زمان‌بندی‌ها را استخراج کرده و به صورت نمودار نمایش دهد\&. عملیاتی که باید توسط اسکریپت
\fBscons\-time\fR
انجام شود، با یک زیردستور مشخص می‌شود که نخستین آرگومان در خط فرمان است\&. برای اطلاعات بیشتر درباره نحوه عملکرد هر زیردستور، بخش
SUBCOMMANDS
در ادامه را ببینید\&.
.PP
روش پایه برای استفاده از
\fBscons\-time\fR
این است که زیردستور
\fBscons\-time run\fR
(احتمالاً چندین بار) برای تولید خروجی پروفایل و فایل لاگ اجرا شود، و سپس از یکی دیگر از زیردستورها برای نمایش نتایج ثبت‌شده در پروفایل‌ها و فایل‌های لاگ برای نوع خاصی از اطلاعات استفاده گردد: زمان‌بندی توابع (زیردستور
\fBscons\-time func\fR)،
کل حافظه مصرفی (زیردستور
\fBscons\-time mem\fR)،
تعداد اشیاء (زیردستور
\fBscons\-time obj\fR)
و زمان کل اجرا (زیردستور
\fBscons\-time time\fR)\&.
گزینه‌هایی برای قرار دادن و یافتن پروفایل‌ها و فایل‌های لاگ در دایرکتوری‌های جداگانه، تولید خروجی در قالبی مناسب جهت رسم نمودار با برنامه
\fBgnuplot\fR(1)
و مواردی از این دست وجود دارند\&.
.PP
دو روش اساسی برای استفاده از زیردستور
\fBscons\-time run\fR
جهت جمع‌آوری آمار زمان‌بندی برای یک پیکربندی در نظر گرفته شده است\&. یکی استفاده از گزینه
\fB\-\-svn=\fR
برای سنجش یک پیکربندی در برابر فهرستی از بازبینی‌ها (revisions) از مخزن Subversion مربوط به SCons است\&. این کار یک پروفایل و فایل لاگ زمان‌بندی برای هر بازبینی فهرست‌شده با گزینه
\fB\-\-number=\fR
تولید می‌کند، و می‌تواند برای مشاهده تأثیر تغییرات ثبت‌شده در پایه‌کد SCons بر روی یک پیکربندی خاص در طول زمان مورد استفاده قرار گیرد\&.
.PP
روش دیگر، پروفایل کردن تغییرات تدریجی روی یک پایه‌کد محلی SCons در طول چرخه توسعه است؛ یعنی بررسی تأثیر عملکردی تغییراتی که در درخت محلی ایجاد می‌کنید\&. در این حالت، شما زیردستور
\fBscons\-time run\fR
را
\fIبدون\fR
گزینه
\fB\-\-svn=\fR
اجرا می‌کنید؛ در این صورت، این دستور صرفاً دایرکتوری خروجی فایل‌های پروفایل/لاگ (به‌طور پیش‌فرض دایرکتوری جاری) را بررسی کرده و به‌طور خودکار شماره اجرای
\fIبعدی\fR
را برای پروفایل و فایل لاگ خروجی تعیین می‌کند\&. با استفاده از این روش، چرخه توسعه چیزی شبیه به این خواهد بود: اعمال تغییر در SCons؛ اجرای
\fBscons\-time run\fR
برای پروفایل کردن آن در برابر یک پیکربندی خاص؛ اعمال تغییری دیگر در SCons؛ اجرای دوباره
\fBscons\-time run\fR
برای پروفایل کردن آن؛ و غیره\&..SH "گزینه‌ها (OPTIONS)"
.PP
دستور
\fBscons\-time\fR
تنها از چند گزینهٔ سراسری پشتیبانی می‌کند:
.PP
\-h, \-\-help
.RS 4
متن راهنمای سراسری را نمایش داده و خارج می‌شود؛ دقیقاً مشابه زیرفرمان
\fBscons\-time help\fR
عمل می‌کند\&.
.RE
.PP
\-V, \-\-version
.RS 4
نسخهٔ
\fBscons\-time\fR
را نمایش داده و خارج می‌شود\&.
.RE
.PP
بخش عمدهٔ قابلیت‌ها توسط گزینه‌های زیرفرمان‌های مجزا کنترل می‌شوند\&. برای اطلاعات بیشتر دربارهٔ گزینه‌های هر زیرفرمان، بخش بعدی را ببینید\&.
.SH "زیرفرمان‌ها (SUBCOMMANDS)"
.PP
دستور
\fBscons\-time\fR
از زیرفرمان‌های مجزای زیر پشتیبانی می‌کند\&.
.SS "زیرفرمان func"
.PP
\fBscons\-time func\fR
[\fB\-h\fR] [\fB\-\-chdir=\fR\fIDIR\fR] [\fB\-f \fR\fIFILE\fR] [\fB\-\-fmt=\fR\fIFORMAT\fR] [\fB\-\-func=\fR\fINAME\fR] [\fB\-p \fR\fISTRING\fR] [\fB\-t \fR\fINUMBER\fR] [\fB\-\-title= TITLE\fR] [\fIARGUMENTS\fR]
.PP
زیرفرمان
\fBscons\-time func\fR
اطلاعات زمان‌بندی را برای یک تابع خاص پایتون در SCons نمایش می‌دهد\&. به‌طور پیش‌فرض، اطلاعات تابع
\fB_main\fR()
را استخراج می‌کند که شامل زمان‌بندی پروفایلر پایتون برای کل SCons است\&.
.PP
زیرفرمان
\fBscons\-time func\fR
اطلاعات زمان‌بندی تابع را از تمام آرگومان‌های فایل مشخص‌شده، که باید فایل‌های خروجی پروفایلر پایتون باشند، استخراج می‌کند\&. (به‌طور معمول، این‌ها فایل‌های
\fB*\&.prof\fR
هستند که توسط زیرفرمان
\fBscons\-time run\fR
تولید شده‌اند، اما در واقع می‌توانند با هر بار اجرای پروفایلر پایتون نیز تولید شوند\&.) تمام آرگومان‌های نام فایل برای یافتن فایل‌های روی دیسک، الگوگشایی (glob) می‌شوند\&.
.PP
اگر هیچ آرگومانی مشخص نشود، اطلاعات زمان‌بندی تابع از تمامی فایل‌های
\fB*\&.prof\fR
یا زیرمجموعه‌ای از آن‌ها با پیشوند مشخص‌شده توسط گزینهٔ
\fB\-p\fR
استخراج خواهد شد\&.
.PP
گزینه‌ها عبارت‌اند از:
.PP
\-C DIRECTORY, \-\-chdir=DIRECTORY
.RS 4
پیش از جستجو برای فایل‌های مشخص‌شده (یا فایل‌هایی که با الگوهای مشخص‌شده مطابقت دارند)، به
\fIDIRECTORY\fR
مشخص‌شده تغییر مسیر می‌دهد\&.
.RE
.PP
\-f FILE, \-\-file=FILE
.RS 4
اطلاعات پیکربندی را از
\fIFILE\fR
مشخص‌شده می‌خواند\&.
.RE
.PP
\-fmt=FORMAT, \-\-format=FORMAT
.RS 4
خروجی را در
\fIFORMAT\fR
مشخص‌شده گزارش می‌کند\&. قالب‌هایی که در حال حاضر پشتیبانی می‌شوند شامل
\fBascii\fR
(پیش‌فرض) و
\fBgnuplot\fR
هستند\&.
.RE
.PP
\-\-func=NAME
.RS 4
زمان‌بندی‌ها را برای تابع مشخص‌شدهٔ
\fINAME\fR
استخراج می‌کند\&. حالت پیش‌فرض، گزارش زمان‌بندی‌های تجمعی برای تابع
\fB_main\fR()
است که کل اجرای SCons را در بر می‌گیرد\&.
.RE
.PP
\-h, \-\-help
.RS 4
متن راهنما را برای زیرفرمان
\fBscons\-time func\fR
نمایش می‌دهد\&.
.RE
.PP
\-p STRING, \-\-prefix=STRING
.RS 4
رشتهٔ پیشوند را برای پروفایل‌هایی که قرار است اطلاعات زمان‌بندی تابع از آن‌ها استخراج شود، مشخص می‌کند\&. اگر هیچ آرگومانی در خط فرمان مشخص نشده باشد، این رشته برای جستجوی پروفایل‌ها به کار خواهد رفت\&.
.RE
.PP
\-t NUMBER, \-\-tail=NUMBER
.RS 4
تنها زمان‌بندی توابع را از آخرین
\fINUMBER\fR
فایل استخراج می‌کند\&.
.RE.SS "زیرفرمان help"
.PP
\fBscons\-time help\fR
\fISUBCOMMAND\fR
[\&.\&.\&.] زیرفرمان
\fBhelp\fR
متن راهنما را برای هر زیرفرمان دیگری که به عنوان آرگومان‌های بعدی در خط فرمان فهرست شده باشد، چاپ می‌کند\&.
.SS "زیرفرمان mem"
.PP
\fBscons\-time mem\fR
[\fB\-h\fR] [\fB\-\-chdir=\fR\fIDIR\fR] [\fB\-f \fR\fIFILE\fR] [\fB\-\-fmt=\fR\fIFORMAT\fR] [\fB\-p \fR\fISTRING\fR] [\fB\-\-stage=\fR\fISTAGE\fR] [\fB\-t \fR\fINUMBER\fR] [\fB\-\-title=\fR\fITITLE\fR] [\fIARGUMENTS\fR]
.PP
زیرفرمان
\fBscons\-time mem\fR
میزان حافظهٔ مصرفی توسط SCons را نمایش می‌دهد\&.
.PP
زیرفرمان
\fBscons\-time mem\fR
اطلاعات مصرف حافظه را از تمامی آرگومان‌های فایل مشخص‌شده استخراج می‌کند؛ این فایل‌ها باید فایل‌هایی حاوی خروجی حاصل از اجرای SCons با گزینهٔ
\fB\-\-debug=memory\fR
باشند\&. (به طور معمول، این‌ها همان فایل‌های
\fB*\&.log\fR
تولیدشده توسط زیرفرمان
\fBscons\-time run\fR
هستند\&.) تمامی آرگومان‌های نام فایل به منظور تطبیق با فایل‌های روی دیسک گسترش (glob) داده می‌شوند\&.
.PP
اگر هیچ آرگومانی مشخص نشود، اطلاعات حافظه از تمام فایل‌های
\fB*\&.log\fR
یا زیرمجموعه‌ای از آن‌ها با یک پیشوند مشخص‌شده توسط گزینهٔ
\fB\-p\fR
استخراج خواهد شد\&.
.PP
\-C DIR, \-\-chdir=DIR
.RS 4
قبل از جستجوی فایل‌های مشخص‌شده (یا فایل‌هایی که با الگوهای مشخص‌شده مطابقت دارند)، به
\fIDIRECTORY\fR
تعیین‌شده تغییر مسیر می‌دهد\&.
.RE
.PP
\-f FILE, \-\-file=FILE
.RS 4
اطلاعات پیکربندی را از
\fIFILE\fR
مشخص‌شده می‌خواند\&.
.RE
.PP
\-fmt=FORMAT, \-\-format=FORMAT
.RS 4
خروجی را در
\fIFORMAT\fR
مشخص‌شده گزارش می‌دهد\&. قالب‌های پشتیبانی‌شده در حال حاضر عبارتند از
\fBascii\fR
(پیش‌فرض) و
\fBgnuplot\fR\&.
.RE
.PP
\-h, \-\-help
.RS 4
متن راهنما را برای زیرفرمان
\fBscons\-time mem\fR
نمایش می‌دهد\&.
.RE
.PP
\-p STRING, \-\-prefix=STRING
.RS 4
رشتهٔ پیشوندی را برای فایل‌های لاگی که اطلاعات مصرف حافظه از آن‌ها استخراج می‌شود مشخص می‌کند\&. اگر هیچ آرگومانی در خط فرمان مشخص نشده باشد، از این مقدار برای جستجوی فایل‌های لاگ استفاده خواهد شد\&.
.RE
.PP
\-\-stage=STAGE
.RS 4
حافظهٔ مصرف‌شده در انتهای
\fISTAGE\fR
تعیین‌شده را چاپ می‌کند:
\fBpre\-read\fR
(قبل از خوانده شدن فایل‌های SConscript)،
\fBpost\-read ,\fR
(بعد از خوانده شدن فایل‌های SConscript)،
\fBpre\-build\fR
(قبل از ساخته شدن هر هدفی) یا
\fBpost\-build\fR
(بعد از ساخته شدن هر هدفی)\&. اگر هیچ گزینهٔ
\fB\-\-stage\fR
مشخص نشده باشد، رفتار پیش‌فرض
\fBpost\-build\fR
است که مقدار نهایی حافظهٔ مصرف‌شده توسط SCons در طول هر اجرا را گزارش می‌کند\&.
.RE
.PP
\-t NUMBER, \-\-tail=NUMBER
.RS 4
آمار حافظه را فقط از آخرین
\fINUMBER\fR
فایل گزارش می‌دهد\&.
.RE.SS "زیرفرمان obj"
.PP
\fBscons\-time obj\fR
[\fB\-h\fR] [\fB\-\-chdir=\fR\fIDIR\fR] [\fB\-f \fR\fIFILE\fR] [\fB\-\-fmt=\fR\fIFORMAT\fR] [\fB\-p \fR\fISTRING\fR] [\fB\-\-stage=\fR\fISTAGE\fR] [\fB\-t \fR\fINUMBER\fR] [\fB\-\-title=\fR\fITITLE\fR] [\fIARGUMENTS\fR]
.PP
زیرفرمان
\fBscons\-time obj\fR
تعداد اشیای ایجادشده از یک نوع مشخص توسط SCons را نمایش می‌دهد\&.
.PP
زیرفرمان
\fBscons\-time obj\fR
شمارش اشیاء را از تمام فایل‌های مشخص‌شده در آرگومان‌ها استخراج می‌کند؛ این فایل‌ها باید حاوی خروجی حاصل از اجرای SCons با گزینهٔ
\fB\-\-debug=count\fR
باشند\&. (به‌طور معمول، این‌ها فایل‌های
\fB*\&.log\fR
تولیدشده توسط زیرفرمان
\fBscons\-time run\fR
هستند\&.) تمام آرگومان‌های نام فایل با فایل‌های موجود روی دیسک تطبیق داده می‌شوند (globbed)\&.
.PP
اگر هیچ آرگومانی مشخص نشود، شمارش اشیاء از تمام فایل‌های
\fB*\&.log\fR
یا زیرمجموعه‌ای از آن‌ها با پیشوند مشخص‌شده توسط گزینهٔ
\fB\-p\fR
استخراج خواهد شد\&.
.PP
\-C DIR, \-\-chdir=DIR
.RS 4
قبل از جستجوی فایل‌های مشخص‌شده (یا فایل‌های منطبق با الگوهای مشخص‌شده)، به
\fIDIRECTORY\fR
مشخص‌شده تغییر مسیر می‌دهد\&.
.RE
.PP
\-f FILE, \-\-file=FILE
.RS 4
اطلاعات پیکربندی را از
\fIFILE\fR
مشخص‌شده می‌خواند\&.
.RE
.PP
\-fmt=FORMAT, \-\-format=FORMAT
.RS 4
خروجی را در
\fIFORMAT\fR
مشخص‌شده گزارش می‌دهد\&. قالب‌هایی که در حال حاضر پشتیبانی می‌شوند شامل
\fBascii\fR
(پیش‌فرض) و
\fBgnuplot\fR
هستند\&.
.RE
.PP
\-h, \-\-help
.RS 4
متن راهنما را برای زیرفرمان
\fBscons\-time obj\fR
نمایش می‌دهد\&.
.RE
.PP
\-p STRING, \-\-prefix=STRING
.RS 4
رشتهٔ پیشوند را برای فایل‌های لاگی که شمارش اشیاء باید از آن‌ها استخراج شود مشخص می‌کند\&. در صورتی که هیچ آرگومانی در خط فرمان مشخص نشده باشد، این رشته برای جستجوی فایل‌های لاگ استفاده خواهد شد\&.
.RE
.PP
\-\-stage=STAGE
.RS 4
تعداد اشیاء را در پایان
\fISTAGE\fR
مشخص‌شده چاپ می‌کند:
\fBpre\-read\fR
(پیش از خوانده شدن فایل‌های SConscript)،
\fBpost\-read\fR
(پس از خوانده شدن فایل‌های SConscript)،
\fBpre\-build\fR
(پیش از ساخت هر هدفی) یا
\fBpost\-build\fR
(پس از ساخت همهٔ اهداف)\&. اگر هیچ گزینهٔ
\fB\-\-stage\fR
مشخص نشود، رفتار پیش‌فرض
\fBpost\-build\fR
است که تعداد نهایی اشیاء را در طول هر اجرا گزارش می‌دهد\&.
.RE
.PP
\-t NUMBER, \-\-tail=NUMBER
.RS 4
تنها شمارش اشیاء را از آخرین
\fINUMBER\fR
فایل گزارش می‌دهد\&.
.RE.SS "زیرفرمان run"
.PP
\fBscons\-time run\fR
[\fB\-hnqv\fR] [\fB\-f \fR\fIFILE\fR] [\fB\-\-number=\fR\fINUMBER\fR] [\fB\-\-outdir=\fR\fIOUTDIR\fR] [\fB\-p \fR\fISTRING\fR] [\fB\-\-python=\fR\fIPYTHON\fR] [\fB\-s \fR\fIDIR\fR] [\fB\-\-scons=\fR\fISCONS\fR] [\fB\-\-svn=\fR\fIURL\fR] [\fIARGUMENTS\fR]
زیرفرمان
\fBscons\-time run\fR
زیرفرمان پایه‌ای برای ارزیابی کارایی (profiling) یک پیکربندی خاص در برابر نسخه‌ای از SCons است\&.
.PP
پیکربندی مورد آزمایش به‌صورت فهرستی از فایل‌ها یا دایرکتوری‌هایی مشخص می‌شود که در یک دایرکتوری موقت که SCons در آن فراخوانی خواهد شد، باز یا کپی می‌شوند\&. زیرفرمان
\fBscons\-time run\fR
پسوندهای فایلی مانند
\fB\&.tar\fR،
\fB\&.tar\&.gz\fR،
\fB\&.tgz\fR
و
\fB\&.zip\fR
را درک کرده و محتویات آن‌ها را در یک دایرکتوری موقت باز می‌کند\&. اگر بیش از یک آرگومان مشخص شده باشد، هر کدام «روی» بایگانی‌ها یا دایرکتوری‌های قبلی در دایرکتوری موقت باز یا کپی می‌شوند، بنابراین انتظار می‌رود که چندین بایگانی مشخص‌شده، ساختار دایرکتوری یکسانی داشته باشند\&.
.PP
به‌محض اینکه آرگومان‌های فایل یا دایرکتوری در دایرکتوری موقت باز یا کپی شدند، زیرفرمان
\fBscons\-time run\fR
نسخهٔ درخواستی SCons را سه بار روی این پیکربندی اجرا می‌کند:
.PP
راه‌اندازی (Startup)
.RS 4
دستور SCons با گزینهٔ
\fB\-\-help\fR
اجرا می‌شود تا تنها فایل‌های SConscript خوانده شوند و سپس متن راهنمای پیش‌فرض چاپ شود\&. این کار صرفاً «سربار» مشهودِ راه‌اندازی SCons و پردازش فایل‌های SConscript را ارزیابی و پروفایل می‌کند\&.
.RE
.PP
ساخت کامل (Full build)
.RS 4
دستور SCons برای ساخت هر آنچه در پیکربندی مشخص شده اجرا می‌شود\&. هدف‌های خاصی که باید از طریق خط فرمان ارسال شوند، می‌توانند توسط کلیدواژهٔ
\fBtargets\fR
در یک فایل پیکربندی تعیین شوند؛ برای جزئیات به بخش‌های زیر مراجعه کنید\&.
.RE
.PP
ساخت مجدد (Rebuild)
.RS 4
دستور SCons مجدداً روی همان دایرکتوری تازه ساخته‌شده اجرا می‌شود\&. اگر وابستگی‌ها در پیکربندی SCons درست باشند، این باید یک ساخت مجدد به‌روز و «بدون انجام کار» (do nothing) باشد\&.
.RE
.PP
هر فراخوانی، فایل گزارش خروجی و یک پروفایل را ثبت می‌کند\&.
.PP
زیرفرمان
\fBscons\-time run\fR
از گزینه‌های زیر پشتیبانی می‌کند:
.PP
\-f FILE, \-\-file=FILE
.RS 4
اطلاعات پیکربندی را از
\fIFILE\fR
مشخص‌شده می‌خواند\&. این کار اغلب روشی راحت‌تر نسبت به مشخص کردن پارامترها در خط فرمان، برای تعیین و گردآوری پارامترهای مرتبط با یک پیکربندی زمان‌سنجی خاص فراهم می‌کند\&. برای اطلاعات بیشتر دربارهٔ پارامترهای فایل پیکربندی، بخش
CONFIGURATION FILE
را در ادامه ببینید\&.
.RE
.PP
\-h, \-\-help
.RS 4
متن راهنما را برای زیرفرمان
\fBscons\-time run\fR
نمایش می‌دهد\&.
.RE
.PP
\-n, \-\-no\-exec
.RS 4
فرمان‌ها را اجرا نمی‌کند، بلکه صرفاً معادل‌های خط فرمانی آنچه که قرار بود اجرا شود را چاپ می‌کند\&. توجه داشته باشید که اسکریپت
\fBscons\-time\fR
در صورت امکان، برای قابلیت حمل، اقدامات خود را مستقیماً در Python اجرا می‌کند\&. دستورهای نمایش‌داده‌شده،
\fIمعادل‌های\fR
یونیکسیِ کاری هستند که این اسکریپت انجام می‌دهد\&.
.RE
.PP
\-\-number=NUMBER
.RS 4
شمارهٔ اجرا را مشخص می‌کند که در نام فایل‌های گزارش خروجی و پروفایل‌های تولیدشده توسط این اجرا استفاده می‌شود\&.
.RE
.PP
هنگامی که همراه با گزینهٔ
\fB\-\-svn=\fR\fIURL\fR
استفاده شود،
\fINUMBER\fR
یک یا چند شمارهٔ بازنگری (revision) در Subversion را که با کاما از هم جدا شده‌اند مشخص می‌کند که به‌طور خودکار از مخزن Subversion در
\fIURL\fR
مشخص‌شده دریافت خواهند شد\&. بازه‌ای از شماره‌های بازنگری یا دلتا را می‌توان با جدا کردن دو عدد با خط تیره (\fB\-\fR) مشخص کرد\&.
.PP
مثال:
.sp
.if n \{\
.RS 4
.\}
.nf
% scons\-time run \-\-svn=\m[blue]\fBhttp://scons\&.tigris\&.org/svn/trunk\fR\m[] \-\-num=1247,1249\-1252 \&.
.fi
.if n \{\
.RE
.\}
.PP
\-p STRING, \-\-prefix=STRING
.RS 4
رشتهٔ پیشوندی را مشخص می‌کند که برای تمام فایل‌های گزارش و پروفایل‌های تولیدشده توسط این اجرا استفاده خواهد شد\&. حالت پیش‌فرض از اولین آرگومان مشخص‌شده گرفته می‌شود: اگر آرگومان اول یک دایرکتوری باشد، پیشوند پیش‌فرض نام آن دایرکتوری است؛ اگر آرگومان اول یک بایگانی (فایل tar یا zip) باشد، پیشوند پیش‌فرض نام پایهٔ بایگانی است، یعنی آنچه که پس از حذف پسوند بایگانی (\fB\&.tgz\fR،
\fB\&.tar\&.gz\fR
یا
\fB\&.zip\fR)
باقی می‌ماند\&.
.RE
.PP
\-\-python=PYTHON
.RS 4
مسیری به فایل اجرایی Python را مشخص می‌کند که برای اجراهای زمان‌سنجی استفاده خواهد شد\&. حالت پیش‌فرض استفاده از همان فایل اجرایی پایتونی است که خود دستور
\fBscons\-time\fR
را اجرا می‌کند\&.
.RE
.PP
\-q, \-\-quiet
.RS 4
از نمایش خطوط فرمان در حال اجرا جلوگیری می‌کند\&.
.RE
.PP
\-s DIR, \-\-subdir=DIR
.RS 4
نام دایرکتوری یا زیردایرکتوری‌ای را که دستورها باید از داخل آن اجرا شوند مشخص می‌کند\&. مقدار پیش‌فرض XXX است\&.
.RE
.PP
\-\-scons=SCONS
.RS 4
مسیری را به اسکریپت SCons مشخص می‌کند که برای اجراهای زمان‌سنجی استفاده خواهد شد\&. مقدار پیش‌فرض XXX است\&.
.RE
.PP
\-\-svn=URL, \-\-subversion=URL
.RS 4
\fIURL\fR
مخزن Subversion را که نسخه(های) مورد آزمایش
\fBscons\fR
از آن استخراج خواهد شد مشخص می‌کند\&. هنگامی که
\fB\-\-svn\fR
تعیین شده باشد، گزینهٔ
\fB\-\-number=\fR\fINUMBER\fR
شماره‌های بازنگری که باید آزمایش شوند را تعیین می‌کند\&. خروجی هر فراخوانی در نام فایل‌هایی قرار خواهد گرفت که مطابق با شماره‌های بازنگری Subversion هستند\&. اگر گزینهٔ
\fB\-\-number=\fR
مشخص نشده باشد، رفتار پیش‌فرض اندازه‌گیری زمان بازنگری
\fBHEAD\fR
در
\fIURL\fR
مشخص‌شده است\&.
.RE
.PP
\-v, \-\-verbose
.RS 4
خروجی دستورهای جداگانه را روی صفحه نمایش می‌دهد (علاوه بر ذخیره کردن خروجی در فایل‌های گزارش)\&.
.RE.SS "زیرفرمان time"
.PP
\fBscons\-time time\fR
[\fB\-h\fR] [\fB\-\-chdir=\fR\fIDIR\fR] [\fB\-f \fR\fIFILE\fR] [\fB\-\-fmt=\fR\fIFORMAT\fR] [\fB\-p \fR\fISTRING\fR] [\fB\-t \fR\fINUMBER\fR] [\fB\-\-title=\fR\fITITLE\fR] [\fB\-\-which=\fR\fIWHICH\fR] [\fIARGUMENTS\fR]
.PP
زیرفرمان
\fBscons\-time time\fR
زمان‌های اجرای SCons را همان‌گونه که توسط گزینهٔ
\fBscons \-\-debug=time\fR
گزارش شده‌اند، نمایش می‌دهد\&.
.PP
زیرفرمان
\fBscons\-time time\fR
زمان‌بندی‌های SCons را از تمام آرگومان‌های فایل مشخص‌شده استخراج می‌کند؛ این فایل‌ها باید فایل‌هایی حاوی خروجی حاصل از اجرای SCons همراه با گزینهٔ
\fB\-\-debug=time\fR
باشند\&. (به طور معمول، این‌ها فایل‌های
\fB*\&.log\fR
تولید شده توسط زیرفرمان
\fBscons\-time run\fR
هستند\&.) تمام آرگومان‌های نام فایل برای تطبیق با فایل‌های روی دیسک بسط (glob) داده می‌شوند\&.
.PP
اگر هیچ آرگومانی مشخص نشود، زمان‌بندی‌های اجرا از تمام فایل‌های
\fB*\&.log\fR
یا زیرمجموعه‌ای از آن‌ها با پیشوند مشخص‌شده توسط گزینهٔ
\fB\-p\fR
استخراج خواهد شد\&.
.PP
\-C DIR, \-\-chdir=DIR
.RS 4
پیش از جستجو برای فایل‌های مشخص‌شده (یا فایل‌هایی که با الگوهای مشخص‌شده مطابقت دارند)، به
\fIDIRECTORY\fR
مشخص‌شده تغییر مسیر می‌دهد\&.
.RE
.PP
\-f FILE, \-\-file=FILE
.RS 4
اطلاعات پیکربندی را از
\fIFILE\fR
مشخص‌شده می‌خواند\&.
.RE
.PP
\-fmt=FORMAT, \-\-format=FORMAT
.RS 4
خروجی را در
\fIFORMAT\fR
مشخص‌شده گزارش می‌دهد\&. قالب‌هایی که در حال حاضر پشتیبانی می‌شوند عبارتند از
\fBascii\fR
(پیش‌فرض) و
\fBgnuplot\fR\&.
.RE
.PP
\-h, \-\-help
.RS 4
متن راهنما را برای زیرفرمان
\fBscons\-time time\fR
نمایش می‌دهد\&.
.RE
.PP
\-p STRING, \-\-prefix=STRING
.RS 4
رشتهٔ پیشوند را برای فایل‌های لاگی که باید زمان‌بندی‌های اجرا از آن‌ها استخراج شوند مشخص می‌کند\&. اگر هیچ آرگومانی در خط فرمان مشخص نشده باشد، این رشته برای جستجوی فایل‌های لاگ استفاده خواهد شد\&.
.RE
.PP
\-t NUMBER, \-\-tail=NUMBER
.RS 4
تنها تعداد اشیاء را از آخرین
\fINUMBER\fR
فایل گزارش می‌دهد\&.
.RE
.PP
\-\-which=WHICH
.RS 4
زمان اجرا را برای مقدار مشخص‌شده در
\fIWHICH\fR
چاپ می‌کند:
\fBtotal\fR
(کل زمان اجرا)،
\fBSConscripts\fR
(کل زمان اجرای خود فایل‌های SConscript)،
\fBSCons\fR
(زمان اجرای درون خود کد SCons) یا
\fBcommands\fR
(زمان اجرای دستورها و سایر کنش‌های استفاده‌شده برای ساخت هدف‌ها)\&. اگر هیچ گزینهٔ
\fB\-\-which\fR
مشخص نشود، رفتار پیش‌فرض
\fBtotal\fR
است که کل زمان اجرا را برای هر نوبت اجرا گزارش می‌دهد\&.
.RE.SH "فایل پیکربندی (CONFIGURATION FILE)"
.PP
زیردستورهای مختلف
\fBscons\-time\fR
می‌توانند در صورت دریافت گزینه‌های
\fB\-f\fR
یا
\fB\-\-file\fR،
اطلاعات را از یک فایل پیکربندی مشخص بخوانند\&. فایل پیکربندی در واقع به‌صورت یک اسکریپت Python اجرا می‌شود\&. مقداردهی متغیرهای Python در فایل پیکربندی، رفتار اسکریپت
\fBscons\-time\fR
را بسیار راحت‌تر از تعیین گزینه‌ها یا آرگومان‌های خط فرمان برای هر اجرا کنترل می‌کند، و روشی سودمند برای یکپارچه‌سازی و ذخیره اطلاعات لازم جهت تولید (و گزارش) اجراهای زمان‌سنجی پایدار برای یک پیکربندی مشخص فراهم می‌آورد\&.
.PP
\fBarchive_list\fR
.RS 4
فهرستی از بایگانی‌ها (فایل‌ها یا دایرکتوری‌ها) که به دایرکتوری موقتی که SCons در آن فراخوانی خواهد شد کپی می‌شوند\&.
محتوای فایل‌های
\fB\&.tar\fR،
\fB\&.tar\&.gz\fR،
\fB\&.tgz\fR
و
\fB\&.zip\fR
در دایرکتوری موقت استخراج خواهد شد\&. ساختارهای درختی دایرکتوری و فایل‌ها به‌همان شکل که هستند کپی خواهند شد\&.
.RE
.PP
\fBinitial_commands\fR
.RS 4
فهرستی از دستورها که پیش از اجراهای زمان‌سنجی‌شدهٔ واقعی
\fBscons\fR
اجرا خواهند شد\&. از این متغیر می‌توان برای دستورهایی استفاده کرد که برای آماده‌سازی درخت منبع لازم هستند؛ برای نمونه، ایجاد یک فایل پیکربندی که نباید بخشی از اجرای زمان‌سنجی‌شده باشد\&.
.RE
.PP
\fBkey_location\fR
.RS 4
محل قرارگیری کلید (راهنما) روی اطلاعات نموداری Gnuplot که با گزینهٔ
\fB\-\-format=gnuplot\fR
تولید می‌شود\&. مقدار پیش‌فرض
\fBbottom left\fR
است\&.
.RE
.PP
\fBprefix\fR
.RS 4
پیشوند نام فایل که هنگام اجرا یا استخراج زمان‌سنجی برای این پیکربندی استفاده می‌شود\&.
.RE
.PP
\fBpython\fR
.RS 4
مسیر نام فایل اجرایی Python که هنگام اجرا یا استخراج اطلاعات برای این پیکربندی استفاده می‌شود\&. مقدار پیش‌فرض همان نسخه از Python است که برای اجرای SCons استفاده شده است\&.
.RE
.PP
\fBscons\fR
.RS 4
مسیر نام اسکریپت SCons که هنگام اجرا یا استخراج اطلاعات برای این پیکربندی استفاده می‌شود\&. مقدار پیش‌فرض به‌سادگی
\fBscons\fR
است\&.
.RE
.PP
\fBscons_flags\fR
.RS 4
پرچم‌های
\fBscons\fR
که هنگام اجرای SCons برای جمع‌آوری اطلاعات زمان‌سنجی استفاده می‌شوند\&. مقدار پیش‌فرض
\fB\-\-debug=count \-\-debug=memory \-\-debug=time \-\-debug=memoizer\fR
است\&.
.RE
.PP
\fBscons_lib_dir\fR, \fBscons_wrapper\fR, \fBstartup_targets\fR, \fBsubdir\fR
.RS 4
زیردایرکتوری از پروژه که اسکریپت
\fBscons\-time\fR
باید پیش از اجرای دستورهای SCons برای زمان‌سنجی وارد آن شود\&.
.RE
.PP
\fBsubversion_url\fR
.RS 4
نشانی Subversion URL از
.RE
.PP
\fBsvn\fR
.RS 4
فایل اجرایی Subversion که برای واکشی (checkout) نگارش‌های SCons مورد زمان‌سنجی استفاده می‌شود\&. پیش‌فرض صرفاً
\fBsvn\fR
است\&.
.RE
.PP
\fBsvn_co_flag\fR, \fBtar\fR, \fBtargets\fR
.RS 4
رشته‌ای شامل هدف‌هایی که باید به خط فرمان هر اجرای زمان‌سنجی‌شدهٔ
\fBscons\fR
اضافه شوند\&. از این می‌توان برای محدود کردن موارد تحت زمان‌سنجی به زیرمجموعه‌ای از ساخت کامل پیکربندی استفاده کرد\&.
.RE
.PP
\fBtargets0\fR, \fBtargets1\fR, \fBtargets2\fR, \fBtitle\fR, \fBunzip\fR, \fBverbose\fR, \fBvertical_bars\fR
.RS 4
.RE.SS "مثال (EXAMPLE)"
.PP
در اینجا نمونه‌ای از فایل پیکربندی
\fBscons\-time\fR
برای یک پروژه فرضی آورده شده است:
.sp
.if n \{\
.RS 4
.\}
.nf
# The project doesn\*(Aqt use SCons natively (yet), so we\*(Aqre
# timing a separate set of SConscript files that we lay
# on top of the vanilla unpacked project tarball\&.
arguments = [\*(Aqproject\-1\&.2\&.tgz\*(Aq, \*(Aqproject\-SConscripts\&.tar\*(Aq]

# The subdirectory name contains the project version number,
# so tell scons\-time to chdir there before building\&.
subdir = \*(Aqproject\-1\&.2\*(Aq

# Set the prefix, so output log files and profiles are named:
#     project\-000\-[012]\&.{log,prof}
#     project\-001\-[012]\&.{log,prof}
# etc\&.
prefix = \*(Aqproject\*(Aq

# The SConscript files being tested don\*(Aqt do any SConf
# configuration, so run their normal \&./configure script
# before we invoke SCons\&.
initial_commands = [
    \*(Aq\&./configure\*(Aq,
]

# Only time building the bin/project executable\&.
targets = \*(Aqbin/project\*(Aq

# Time against SCons revisions of the branches/core branch
subversion_url = \*(Aq\m[blue]\fBhttp://scons\&.tigris\&.org/svn/scons/branches/core\fR\m[]\*(Aq
.fi
.if n \{\
.RE
.\}
.SH "محیط (ENVIRONMENT)"
.PP
اسکریپت
\fBscons\-time\fR
از متغیرهای محیطی زیر استفاده می‌کند:
.PP
\fBPRESERVE\fR
.RS 4
اگر این مقدار تنظیم شده باشد، اسکریپت
\fBscons\-time\fR
دایرکتوری یا دایرکتوری‌های موقتی را که در آن‌ها پیکربندی مشخص‌شده را می‌سازد یا نسخه خاصی از SCons را دانلود می‌کند، حذف
\fIنخواهد کرد\fR\&.
.RE
.SH "همچنین ببینید (SEE ALSO)"
.PP
\fBgnuplot\fR(1),
\fBscons\fR(1)
.SH "نویسندگان (AUTHORS)"
.PP
Steven Knight <knight at baldmt dot com>