.Dd December 29, 2024
.Dt SAMU 1
.Os
.Sh "نام (NAME)"
.Nm samu
.Nd ابزار ساخت سازگار با ninja
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Op Fl C Ar dir
.Op Fl d Ar debugflag
.Op Fl f Ar buildfile
.Op Fl j Ar maxjobs
.Op Fl k Ar maxfail
.Op Fl l Ar maxload
.Op Fl w Ar warnflag=action
.Op Fl nv
.Op Ar target...
.Nm
.Op Fl C Ar dir
.Op Fl f Ar buildfile
.Fl t Cm clean
.Op Fl gr
.Op Ar target...
.Nm
.Op Fl C Ar dir
.Op Fl f Ar buildfile
.Fl t Cm compdb
.Op Fl x
.Op Ar rule...
.Nm
.Op Fl C Ar dir
.Op Fl f Ar buildfile
.Fl t Cm commands
.Op Ar target...
.Nm
.Op Fl C Ar dir
.Op Fl f Ar buildfile
.Fl t Cm graph
.Op Ar target...
.Nm
.Op Fl C Ar dir
.Op Fl f Ar buildfile
.Fl t Cm query
.Op Ar target...
.Nm
.Op Fl C Ar dir
.Op Fl f Ar buildfile
.Fl t Cm targets
.Op Cm depth Op Ar maxdepth
.Nm
.Op Fl C Ar dir
.Op Fl f Ar buildfile
.Fl t Cm targets
.Cm rule
.Op Ar rulename
.Nm
.Op Fl C Ar dir
.Op Fl f Ar buildfile
.Fl t Cm targets
.Cm all
.Sh "توضیحات (DESCRIPTION)"
دستور
.Nm
یک مانیفست ساخت را از
.Ar buildfile
بارگیری کرده و در صورتی که
.Ar targets
قدیمی باشند، آن‌ها را دوباره می‌سازد.
اگر هیچ هدفی مشخص نشده باشد، هدف‌های پیش‌فرض مانیفست ساخته می‌شوند.
اگر هدف پیش‌فرضی وجود نداشته باشد، گره‌های برگ گراف وابستگی ساخته می‌شوند (خروجی‌هایی که هیچ عملیات مصرف‌کننده‌ای ندارند).
.Pp
هدف‌ها در صورتی قدیمی در نظر گرفته می‌شوند که از تازه‌ترین ورودی عملیات تولیدکننده قدیمی‌تر باشند، مدخلی در گزارش ساخت (build log) نداشته باشند، یا دستور ساخت هدف با آنچه پیش‌تر استفاده شده تفاوت داشته باشد.
هدف‌هایی که با قواعد
.Cm generator
ساخته شده‌اند، در صورت تغییر دستور دوباره ساخته نخواهند شد.
.Pp
اگر از ابزار فرعی
.Cm clean
استفاده شود، در عوض هدف‌ها پاک‌سازی می‌شوند.
هنگامی که یک هدف پاک‌سازی می‌شود، آن هدف حذف شده و تمام ورودی‌های آن نیز پاک‌سازی خواهند شد.
هدف‌هایی که هیچ عملیات تولیدکننده‌ای ندارند هرگز حذف نمی‌شوند.
هدف‌های ساخته‌شده با قواعد
.Sy generator
تنها در صورتی حذف می‌شوند که گزینهٔ
.Fl g
مشخص شده باشد.
.Pp
اگر از ابزار فرعی
.Cm commands
استفاده شود، فهرستی از دستورهای شل که برای ساخت هدف‌های مشخص‌شده (یا پیش‌فرض) استفاده شده‌اند، چاپ می‌شود.
.Pp
اگر از ابزار فرعی
.Cm compdb
استفاده شود، در عوض یک پایگاه‌داده همگردانی
.Pq Lk https://clang.llvm.org/docs/JSONCompilationDatabase.html
چاپ می‌شود.
.Pp
اگر از ابزار فرعی
.Cm graph
استفاده شود، در عوض یک فایل دات graphviz چاپ می‌شود.
.Pp
اگر از ابزار فرعی
.Cm query
استفاده شود، در عوض ورودی‌ها و خروجی‌های هدف‌ها چاپ می‌شوند.
.Pp
اگر از ابزار فرعی
.Cm targets
استفاده شود، فهرستی از هدف‌ها، بر اساس قاعده یا بر اساس عمق نمایش داده خواهد شد.
آرگومان نخست نحوهٔ نمایش هدف‌ها را تعیین می‌کند:
.Bl -tag -width Ds
.It Cm depth
یک درخت دندانه‌دار از هدف‌ها، با شروع از هدف‌های ریشه (آن‌هایی که هیچ هدف وابسته‌ای ندارند)، تا عمق مشخص‌شده توسط
.Ar maxdepth
(پیش‌فرض: 1) نمایش داده خواهد شد.
.It Cm rule
اگر
.Ar rulename
داده شود، فهرستی از هدف‌هایی که از قاعدهٔ داده‌شده استفاده می‌کنند نمایش داده خواهد شد.
در غیر این صورت، فهرستی از فایل‌های منبع نمایش می‌یابد.
.It Cm all
فهرستی از همهٔ هدف‌ها نمایش داده خواهد شد.
.El
.Sh "گزینه‌ها (OPTIONS)"
.Bl -tag -width Ds
.It Fl C
تغییر دایرکتوری کاری به
.Ar dir
پیش از ساخت.
.It Fl d
فعال کردن یک گزینهٔ اشکال‌زدایی.
این پرچم می‌تواند چندین بار مشخص شود تا چندین گزینهٔ اشکال‌زدایی فعال گردند.
مقادیر ممکن برای
.Ar debugflag
عبارتند از:
.Bl -tag -width keepdepfile
.It Cm explain
چاپ پیام‌هایی برای توضیح اینکه چرا خروجی‌ها نیازمند بازسازی (dirty) بودند.
.It Cm keepdepfile
عدم حذف فایل $depfile پس از تجزیه شدن آن.
.It Cm keeprsp
عدم حذف فایل $rspfile پس از تکمیل یا شکست وظیفه.
.El
.It Fl f
بارگیری مانیفست از
.Ar buildfile
به جای build.ninja.
.It Fl j
اجرای حداکثر
.Ar maxjobs
وظیفه به صورت موازی (پیش‌فرض بر اساس تعداد پردازنده‌ها تعیین می‌شود).
اگر صفر باشد، تعداد نامحدودی از وظایف همزمان مجاز خواهد بود.
.It Fl k
مجاز دانستن حداکثر تا
.Ar maxfail
شکست در وظایف.
اگر منفی یا صفر باشد، هر تعداد شکست در وظایف مجاز خواهد بود.
.It Fl l
عدم اجرای وظایف جدید در صورتی که درصد بار کاری سیستم بیشتر از
.Ar maxload
باشد.
اگر صفر باشد، وظایف در سریع‌ترین زمان ممکن اجرا می‌شوند.
.It Fl n
دستورها را عملاً اجرا نکرده و گزارش را به‌روزرسانی نکند.
.It Fl v
چاپ کامل دستورها به جای فقط
.Sy description .
.It Fl w
کنترل نحوهٔ مدیریت خطاهای خاص.
اگر
.Ar warnflag
برابر با
.Cm dupbuild
باشد،
.Ar action
تعیین می‌کند در صورتی که یک خروجی در چند یال ساخت فهرست شده باشد، چه اقدامی صورت گیرد.
اگر
.Ar action
برابر با
.Cm err
باشد، با آن مانند یک خطا رفتار کرده و عملیات متوقف می‌شود.
اگر
.Ar action
برابر با
.Cm warn
باشد، تنها یک پیام تشخیصی چاپ می‌کند.
.It Fl t
به جای ساختن، یک ابزار فرعی را فراخوانی می‌کند.
تمام آرگومان‌ها و پرچم‌های پس از ابزار فرعی، توسط همان ابزار فرعی تفسیر می‌شوند.
ابزارهای فرعی پشتیبانی‌شده در حال حاضر عبارتند از:
.Cm clean ،
.Cm commands ،
.Cm compdb ،
.Cm graph ،
.Cm query
و
.Cm targets .
.It Fl g
هنگام پاک‌سازی، خروجی‌های عملیات‌های
.Sy generator
را نیز پاک می‌کند.
.It Fl r
آرگومان‌های
.Ar targets
به عنوان قاعده تفسیر می‌شوند و در عوض، تمام خروجی‌های عملیات‌هایی با نوع قواعد مشخص‌شده پاک خواهند شد.
.It Fl x
هنگام چاپ پایگاه‌داده همگردانی، @$rspfile را با $rspfile_content (با قرار دادن <blank> به جای <newline>) جایگزین می‌کند.
.El
.Sh "محیط (ENVIRONMENT)"
.Bl -tag -width NINJA_STATUS
.It Ev SAMUFLAGS
گزینه‌هایی برای
.Nm
که پیش از گزینه‌های خط فرمان اعمال می‌شوند.
تنها گزینه‌های مجاز در
.Ev SAMUFLAGS
عبارتند از
.Fl v ،
.Fl j
و
.Fl l .
.It Ev NINJA_STATUS
خروجی وضعیتی که در سمت چپ توضیحات هر قاعده، با استفاده از مشخص‌کننده‌های تبدیل شبیه به printf چاپ می‌شود.
در صورت تنظیم نشدن، مقدار پیش‌فرض "[%s/%t] " است.
.Pp
مشخص‌کننده‌های تبدیلِ دردسترس:
.Bl -tag -width Ds
.It Cm %s
تعداد وظایف آغازشده.
.It Cm %f
تعداد وظایف پایان‌یافته.
.It Cm %t
تعداد کل وظایف.
.It Cm %r
تعداد وظایف در حال اجرا.
.It Cm %u
تعداد وظایف باقی‌مانده.
.It Cm %p
درصد وظایف تکمیل‌شده.
.It Cm %o
نرخ وظایف پایان‌یافته بر حسب ثانیه (با ۱ رقم اعشار).
.It Cm %e
زمان سپری‌شده به ثانیه (با ۳ رقم اعشار).
.It Cm %%
نویسهٔ '%'.
.El
.El
.Sh "همچنین ببینید (SEE ALSO)"
.Xr make 1