'\" t
.\"     Title: ccache
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.26
.\"      Date: 2026-09-04
.\"    Manual: \ \&
.\"    Source: Ccache 4.14
.\"  Language: English
.\"
.TH "CCACHE" "1" "2026-09-04" "Ccache 4.14" "\ \&"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "نام (NAME)"
ccache \- یک حافظهٔ نهان سریع برای کامپایلرهای C/C++
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fBccache\fP [\fIccache options\fP]
\fBccache\fP [\fIKEY\fP=\fIVALUE\fP .\|.\|.] \fIcompiler\fP [\fIcompiler options\fP]
\fIcompiler\fP [\fIcompiler options\fP]
.fi
.br
.sp
شکل نخست، گزینه‌های شرح داده‌شده در بخش گزینه‌های خط فرمان در ادامه را می‌پذیرد. شکل دوم کامپایلر را فراخوانی می‌کند که به صورت اختیاری می‌تواند از گزینه‌های پیکربندی به عنوان آرگومان‌های \fIKEY\fP=\fIVALUE\fP استفاده کند. در شکل سوم، ccache مطابق آنچه در بخش حالت‌های اجرا شرح داده شده است، در نقش کامپایلر ظاهر می‌شود.
.SH "توضیحات (DESCRIPTION)"
.sp
ابزار Ccache یک حافظهٔ نهان (cache) برای کامپایلر است که با ذخیره کردن نتایج کامپایل‌های پیشین و استفادهٔ مجدد از آن‌ها در زمان اجرای دوبارهٔ همان کامپایل، سرعت کامپایل مجدد را به‌طور چشمگیری افزایش می‌دهد.
.sp
ابزار Ccache به گونه‌ای طراحی شده است که دقیقاً همان خروجی کامپایلر را در یک کامپایل عادی تولید کند. تنها تفاوتی که باید احساس کنید، زمان ساخت (build) سریع‌تر است. هرگونه استثنای شناخته‌شده برای این رفتار در بخش \fICAVEATS\fP مستند شده است. اگر با موردی مواجه شدید که ccache خروجی متفاوتی نسبت به آنچه انتظار می‌رفت تولید کرد، لطفاً آن را گزارش دهید.
.SH "حالت‌های اجرا (RUN MODES)"
.sp
دو راه برای استفاده از ccache جهت ذخیره‌سازی کامپایل‌ها در حافظهٔ نهان وجود دارد:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 1." 4.2
.\}
\fBروش پیشوند (Prefix method)\fP: عبارت \f(CRccache\fP را پیش از دستور کامپایل خود اضافه کنید. این ساده‌ترین رویکرد برای زمانی است که می‌خواهید ccache را آزمایش کرده یا از آن برای پروژه‌های خاصی استفاده کنید. مثال:
.sp
.if n .RS 4
.nf
.fam C
ccache gcc \-c example.c
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 2." 4.2
.\}
\fBروش تغییر چهره (Masquerade method)\fP: با ایجاد یک پیوند نمادین (symbolic link) به ccache با نام کامپایلر، کاری کنید که ccache در نقش کامپایلر ظاهر شود. این روش زمانی کاربرد دارد که می‌خواهید از ccache برای تمامی کامپایل‌ها استفاده کنید. برای تنظیم ccache جهت جا زدن خود به جای \f(CRgcc\fP و \f(CRg++\fP:
.sp
.if n .RS 4
.nf
.fam C
cp ccache /usr/local/bin/
ln \-s ccache /usr/local/bin/gcc
ln \-s ccache /usr/local/bin/g++
.fam
.fi
.if n .RE
.sp
در سیستم‌هایی که از پیوندهای نمادین پشتیبانی نمی‌کنند، می‌توانید به جای آن ccache را کپی کنید:
.sp
.if n .RS 4
.nf
.fam C
cp ccache /usr/local/bin/gcc
cp ccache /usr/local/bin/g++
.fam
.fi
.if n .RE
.sp
این روش تا زمانی کار می‌کند که دایرکتوری حاوی پیوندهای نمادین یا نسخه‌های کپی‌شدهٔ ccache، پیش از دایرکتوری کامپایلر واقعی (به‌طور معمول \f(CR/usr/bin\fP) در متغیر محیطی \f(CRPATH\fP شما قرار گرفته باشد.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B هشدار (Warning)
.ps -1
.br
.sp
روش تغییر چهره به‌خوبی کار می‌کند، اما ممکن است با ابزارهای دیگری که از همین تکنیک استفاده می‌کنند تداخل داشته باشد. برای اطلاعات بیشتر بخش \fIUSING CCACHE WITH OTHER COMPILER WRAPPERS\fP را ببینید.
.sp .5v
.RE
.RE.SH "گزینه‌های خط فرمان (COMMAND LINE OPTIONS)"
.sp
این گزینه‌های خط فرمان تنها زمانی اعمال می‌شوند که ccache را مستقیماً به‌صورت \(lqccache\(rq فراخوانی کنید.
هنگامی که ccache در نقش یک کامپایلر عمل می‌کند (همان‌طور که در بخش پیشین توضیح داده شد)،
باید از گزینه‌های معمولی کامپایلر استفاده کرده و به مستندات کامپایلر خود مراجعه کنید.
.SS "گزینه‌های عمومی (Common options)"
.sp
\fB\-c\fP, \fB\-\-cleanup\fP
.RS 4
پاک‌سازی حافظهٔ پنهان (cache) با حذف فایل‌های اخیراً استفاده‌نشده تا زمانی که
از محدودیت‌های مشخص‌شده برای تعداد فایل‌ها و اندازهٔ حافظهٔ پنهان فراتر نرود. این کار
همچنین تعداد کل فایل‌ها و اندازهٔ کلی حافظهٔ پنهان را مجدداً محاسبه می‌کند. به طور معمول،
نیازی به شروع دستی پاک‌سازی نیست، چرا که ccache در زمان اجرا حافظهٔ پنهان را کمتر از
محدودیت‌های تعیین‌شده نگه می‌دارد و آمارها را با هر کامپایل به‌روز می‌کند. پاک‌سازی اجباری
بیشتر زمانی مفید است که محتویات حافظهٔ پنهان را به‌صورت دستی تغییر داده باشید یا احساس
کنید که آمارهای اندازهٔ حافظهٔ پنهان ممکن است نادرست باشند.
.RE
.sp
\fB\-C\fP, \fB\-\-clear\fP
.RS 4
پاک کردن تمام حافظهٔ پنهان، با حذف کلیهٔ فایل‌های ذخیره‌شده، در حالی که فایل
پیکربندی حفظ می‌شود.
.RE
.sp
\fB\-\-config\-path\fP \fIPATH\fP
.RS 4
اعمال گزینه‌های خط فرمان روی فایل پیکربندی \fIPATH\fP به‌جای مسیر پیش‌فرض. استفاده
از این گزینه اثری یکسان با مقداردهی (بازنویسی) موقت متغیر محیطی
\f(CRCCACHE_CONFIGPATH\fP دارد.
.RE
.sp
\fB\-d\fP, \fB\-\-dir\fP \fIPATH\fP
.RS 4
اعمال گزینه‌های خط فرمان روی دایرکتوری حافظهٔ پنهان \fIPATH\fP به‌جای مسیر پیش‌فرض. برای
مثال، جهت نمایش آمار یک دایرکتوری حافظهٔ پنهان در \f(CR/shared/ccache\fP می‌توانید دستور
\f(CRccache \-d /shared/ccache \-s\fP را اجرا کنید. استفاده از این گزینه اثری یکسان با
مقداردهی موقت متغیر محیطی \f(CRCCACHE_DIR\fP دارد.
.RE
.sp
\fB\-\-dry\-run\fP
.RS 4
هیچ عملیات نوشتنی انجام نده.
.RE
.sp
\fB\-\-evict\-namespace\fP \fINAMESPACE\fP
.RS 4
فایل‌های ایجادشده در \fBnamespace\fP داده‌شده را از حافظهٔ پنهان حذف کن.
.RE
.sp
\fB\-\-evict\-older\-than\fP \fIAGE\fP
.RS 4
حذف فایل‌هایی از حافظهٔ پنهان که قدیمی‌تر از \fIAGE\fP استفاده شده‌اند. \fIAGE\fP باید یک عدد
صحیح بدون علامت همراه با پسوند \f(CRd\fP (روز) یا \f(CRs\fP (ثانیه) باشد. در صورت ترکیب با
\f(CR\-\-evict\-namespace\fP، تنها فایل‌های درون آن namespace حذف می‌شوند.
.RE
.sp
\fB\-h\fP, \fB\-\-help\fP
.RS 4
چاپ خلاصه‌ای از گزینه‌های خط فرمان.
.RE
.sp
\fB\-F\fP \fINUM\fP, \fB\-\-max\-files\fP \fINUM\fP
.RS 4
تنظیم حداکثر تعداد فایل‌های مجاز در حافظهٔ پنهان روی \fINUM\fP. مقدار 0 را برای بدون
محدودیت به کار ببرید. این مقدار در یک فایل پیکربندی درون دایرکتوری حافظهٔ پنهان ذخیره
می‌شود و برای تمامی کامپایل‌های بعدی اعمال خواهد شد.
.RE
.sp
\fB\-M\fP \fISIZE\fP, \fB\-\-max\-size\fP \fISIZE\fP
.RS 4
تنظیم حداکثر اندازهٔ فایل‌های ذخیره‌شده در حافظهٔ پنهان. \fISIZE\fP باید یک عدد همراه
با یک پسوند اختیاری باشد: kB، MB، GB، TB (ده‌دهی)، KiB، MiB، GiB یا TiB (دودویی).
پسوند پیش‌فرض GiB است. برای بدون محدودیت از 0 استفاده کنید. این مقدار در یک فایل پیکربندی
در دایرکتوری حافظهٔ پنهان ذخیره می‌شود و برای تمامی کامپایل‌های بعدی اعمال می‌گردد.
.RE
.sp
\fB\-X\fP \fILEVEL\fP, \fB\-\-recompress\fP \fILEVEL\fP
.RS 4
فشرده‌سازی مجدد حافظهٔ پنهان به سطح \fILEVEL\fP با استفاده از الگوریتم Zstandard.
سطح می‌تواند یک عدد صحیح باشد (با همان مفاهیم گزینهٔ پیکربندی \fBcompression_level\fP)
یا مقدار ویژهٔ \fBuncompressed\fP برای بدون فشرده‌سازی. برای اطلاعات بیشتر، بخش
\fICACHE COMPRESSION\fP را ببینید. این عملیات می‌تواند زمان زیادی ببرد، چرا که تمام
فایل‌های حافظهٔ پنهان باید پیمایش شوند. تنها فایل‌هایی که در حال حاضر با سطحی متفاوت
از \fILEVEL\fP فشرده شده‌اند مجدداً فشرده خواهند شد.
.RE
.sp
\fB\-o\fP \fIKEY=VALUE\fP, \fB\-\-set\-config\fP \fIKEY\fP=\fIVALUE\fP
.RS 4
تنظیم گزینهٔ پیکربندی \fIKEY\fP به \fIVALUE\fP در فایل پیکربندی. برای اطلاعات بیشتر، بخش
\fICONFIGURATION\fP را ببینید.
.RE
.sp
\fB\-x\fP, \fB\-\-show\-compression\fP
.RS 4
چاپ آمار فشرده‌سازی حافظهٔ پنهان. برای اطلاعات بیشتر، بخش \fICACHE COMPRESSION\fP را
ببینید. این عملیات می‌تواند زمان زیادی ببرد، زیرا تمام فایل‌های حافظهٔ پنهان باید پیمایش
شوند.
.RE
.sp
\fB\-p\fP, \fB\-\-show\-config\fP
.RS 4
چاپ گزینه‌های پیکربندی فعلی و خاستگاه آن‌ها (متغیر محیطی، فایل پیکربندی، یا پیش‌فرض
زمان کامپایل) در قالبی خوانا برای انسان.
.RE
.sp
\fB\-\-show\-log\-stats\fP
.RS 4
چاپ شمارنده‌های آماری از لاگ آمار در قالبی خوانا برای انسان. بخش \fBstats_log\fP را ببینید.
برای جزئیات بیشتر، یک یا دو بار از \f(CR\-v\fP/\f(CR\-\-verbose\fP استفاده کنید.
.RE
.sp
\fB\-s\fP, \fB\-\-show\-stats\fP
.RS 4
چاپ خلاصه‌ای از پیکربندی و شمارنده‌های آماری در قالبی خوانا برای انسان. برای جزئیات
بیشتر، یک یا دو بار از \f(CR\-v\fP/\f(CR\-\-verbose\fP استفاده کنید. برای اطلاعات بیشتر
بخش Cache statistics را ببینید.
.RE
.sp
\fB\-\-stop\-storage\-helpers\fP
.RS 4
برنامه‌های کمکی ذخیره‌سازی معمولاً پس از مدتی عدم فعالیت کلاینت متوقف می‌شوند، اما این
گزینه می‌تواند برای متوقف کردن فوری تمام برنامه‌های کمکی در حال اجرا استفاده شود.
.RE
.sp
\fB\-\-threads\fP \fITHREADS\fP
.RS 4
استفاده از حداکثر \fITHREADS\fP ریسه برای عملیات چندریسمانی. پیش‌فرض، استفاده از
یک ریسه به ازای هر پردازنده (CPU) است.
.RE
.sp
\fB\-v\fP, \fB\-\-verbose\fP
.RS 4
افزایش پرگویی (جزئیات پیام‌ها). این گزینه را می‌توان چندین بار مشخص کرد.
.RE
.sp
\fB\-V\fP, \fB\-\-version\fP
.RS 4
چاپ اطلاعات نسخه و کپی‌رایت.
.RE
.sp
\fB\-z\fP, \fB\-\-zero\-stats\fP
.RS 4
صفر کردن آمارهای حافظهٔ پنهان (بدون تغییر گزینه‌های پیکربندی).
.RE.SS "گزینه‌های ذخیره‌سازی دوردست مبتنی بر فایل (Options for remote file\-based storage)"
.sp
\fB\-\-trim\-dir\fP \fIPATH\fP
.RS 4
فایل‌هایی را که اخیراً استفاده نشده‌اند از دایرکتوری \fIPATH\fP حذف می‌کند تا زمانی که اندازهٔ آن حداکثر به مقدار مشخص‌شده توسط \f(CR\-\-trim\-max\-size\fP برسد.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B هشدار
.ps -1
.br
.sp
از این گزینه برای هرس کردن کَش محلی استفاده نکنید. برای هرس کردن دایرکتوری کَش محلی به یک اندازهٔ مشخص، از \f(CRCCACHE_MAXSIZE=\fISIZE\fP ccache \-c\fP استفاده کنید.
.sp .5v
.RE
.RE
.sp
\fB\-\-trim\-max\-size\fP \fISIZE\fP
.RS 4
حداکثر اندازه را برای \f(CR\-\-trim\-dir\fP تعیین می‌کند. \fISIZE\fP باید یک عدد به همراه یک پسوند اختیاری باشد: kB، MB، GB، TB (ده‌دهی)، KiB، MiB، GiB یا TiB (دودویی). پسوند پیش‌فرض GiB است. از 0 برای حالت بدون محدودیت استفاده کنید.
.RE
.sp
\fB\-\-trim\-method\fP \fIMETHOD\fP
.RS 4
روش هرس کردن دایرکتوری با \f(CR\-\-trim\-dir\fP را تعیین می‌کند. مقادیر ممکن عبارتند از:
.sp
\fBatime\fP
.RS 4
روش LRU (کمتر استفاده‌شده در این اواخر) با استفاده از برچسب زمان دسترسی به فایل. این مقدار پیش‌فرض است.
.RE
.sp
\fBmtime\fP
.RS 4
روش LRU (کمتر استفاده‌شده در این اواخر) با استفاده از برچسب زمان تغییر فایل.
.RE
.RE
.sp
\fB\-\-trim\-recompress\fP \fILEVEL\fP
.RS 4
هنگام استفاده از \f(CR\-\-trim\-dir\fP، فشرده‌سازی مجدد را با استفاده از الگوریتم Zstandard تا سطح \fILEVEL\fP انجام می‌دهد. این سطح می‌تواند یک عدد صحیح با همان مفاهیم گزینهٔ پیکربندی \fBcompression_level\fP، یا مقدار ویژهٔ \fBuncompressed\fP برای بدون فشرده‌سازی باشد. برای اطلاعات بیشتر \fICACHE COMPRESSION\fP را ببینید. این عملیات بالقوه ممکن است زمان زیادی ببرد، زیرا تمام فایل‌های موجود در کَش باید بررسی شوند. تنها فایل‌هایی که در حال حاضر با سطحی متفاوت از \fILEVEL\fP فشرده شده‌اند، مجدداً فشرده‌سازی خواهند شد.
.RE
.SS "گزینه‌های اسکریپت‌نویسی یا اشکال‌زدایی (Options for scripting or debugging)"
.sp
\fB\-\-checksum\-file\fP \fIPATH\fP
.RS 4
چک‌سام (128 بیتی XXH3) فایل موجود در \fIPATH\fP را چاپ می‌کند (\f(CR\-\fP برای ورودی استاندارد).
.RE
.sp
\fB\-\-extract\-result\fP \fIPATH\fP
.RS 4
داده‌های ذخیره‌شده در فایل نتیجه در \fIPATH\fP را استخراج می‌کند (\f(CR\-\fP برای ورودی استاندارد). داده‌ها در فایل‌های \f(CRccache\-result.*\fP درون دایرکتوری کاری جاری نوشته خواهند شد. این گزینه تنها هنگام اشکال‌زدایی ccache و رفتارهای آن مفید است.
.RE
.sp
\fB\-\-format\fP \fIFORMAT\fP
.RS 4
قالب خروجی را برای \f(CR\-\-print\-log\-stats\fP و \f(CR\-\-print\-stats\fP تعیین می‌کند. مقادیر ممکن عبارتند از:
.sp
\fBtab\fP
.RS 4
جداسازی با تب (Tab-separated). این مقدار پیش‌فرض است.
.RE
.sp
\fBjson\fP
.RS 4
قالب‌بندی‌شده به صورت JSON.
.RE
.RE
.sp
\fB\-k\fP \fIKEY\fP, \fB\-\-get\-config\fP \fIKEY\fP
.RS 4
مقدار گزینهٔ پیکربندی \fIKEY\fP را چاپ می‌کند. برای اطلاعات بیشتر \fICONFIGURATION\fP را ببینید.
.RE
.sp
\fB\-\-hash\-file\fP \fIPATH\fP
.RS 4
هش (160 بیتی BLAKE3) فایل در \fIPATH\fP را چاپ می‌کند (\f(CR\-\fP برای ورودی استاندارد). این گزینه تنها هنگام اشکال‌زدایی ccache و رفتارهای آن کاربرد دارد.
.RE
.sp
\fB\-\-inspect\fP \fIPATH\fP
.RS 4
محتوای یک فایل نتیجه یا مانیفست در \fIPATH\fP را (\f(CR\-\fP برای ورودی استاندارد) در قالبی انسان‌خوان در خروجی استاندارد چاپ می‌کند. با این حال، محتوای فایلِ تعبیه‌شده در یک فایل نتیجه چاپ نخواهد شد؛ برای استخراج محتوای فایل از \f(CR\-\-extract\-result\fP استفاده کنید. این گزینه تنها هنگام اشکال‌زدایی ccache و رفتار آن مفید است.
.RE
.sp
\fB\-\-print\-log\-stats\fP
.RS 4
شمارنده‌های آماری را از گزارش لاگ آمار (stats log) در قالبی قابل پردازش توسط ماشین (جداسازی با تب یا JSON) چاپ می‌کند. \fBstats_log\fP و \f(CR\-\-format\fP را ببینید.
.RE
.sp
\fB\-\-print\-stats\fP
.RS 4
شناسه‌های شمارندهٔ آمار و مقادیر متناظر آن‌ها را در قالبی قابل پردازش توسط ماشین (جداسازی با تب یا JSON) چاپ می‌کند. \f(CR\-\-format\fP را ببینید.
.RE
.sp
\fB\-\-print\-version\fP
.RS 4
نسخه را چاپ می‌کند و کار دیگری انجام نمی‌دهد.
.RE.SS "گزینه‌های اضافی"
.sp
هنگامی که ccache به عنوان یک کامپایلر اجرا می‌شود، معمولاً همان گزینه‌های خط فرمانی را دریافت می‌کند
که کامپایلرِ مورد استفادهٔ شما می‌گیرد. تنها استثنا در این مورد، گزینهٔ
\f(CR\-\-ccache\-skip\fP است. از این گزینه می‌توان برای واداشتن ccache به پرهیز از تفسیر
گزینهٔ بعدی به هر نحو و ارسال مستقیم و دست‌نخوردهٔ آن به کامپایلر استفاده کرد.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B نکته
.ps -1
.br
.sp
گزینهٔ \f(CR\-\-ccache\-skip\fP در حال حاضر تنها به ccache می‌گوید که گزینهٔ بعدی
را به عنوان یک گزینهٔ ویژهٔ کامپایلر تفسیر نکند \(em این گزینه همچنان در
هش حالت مستقیم (direct mode hash) گنجانده خواهد شد.
.sp .5v
.RE
.sp
دلیل اهمیت این موضوع این است که ccache باید خط فرمان را تجزیه کرده و
مشخص کند چه چیزی نام فایل ورودی و چه چیزی گزینهٔ کامپایلر است، زیرا برای تعیین
نام فایل شیء (object file) حاصل (از میان موارد دیگر) به نام فایل ورودی نیاز دارد. روش اکتشافی
که ccache هنگام تجزیهٔ خط فرمان استفاده می‌کند این است که با هر آرگومانی که به عنوان یک فایل
وجود داشته باشد، به عنوان نام فایل ورودی برخورد می‌شود. با استفاده از \f(CR\-\-ccache\-skip\fP
می‌توانید اجبار کنید که با یک گزینه به عنوان نام فایل ورودی برخورد نشود و در عوض به عنوان یک
گزینهٔ خط فرمان به کامپایلر فرستاده شود.
.sp
مورد دیگری که \f(CR\-\-ccache\-skip\fP می‌تواند مفید باشد زمانی است که ccache
یک گزینه را به طور ویژه تفسیر می‌کند در حالی که نباید چنین کند، چرا که آن گزینه برای کامپایلر شما
معنایی متفاوت از آنچه ccache می‌پندارد دارد.
.sp
همچنین نگاه کنید به \fBignore_options\fP.
.SH "پیکربندی (CONFIGURATION)"
.sp
می‌توانید رفتار ccache را با استفاده از فایل‌های پیکربندی و متغیرهای محیطی
سفارشی‌سازی کنید. گزینه‌های پیکربندی به ترتیب اولویت زیر پردازش می‌شوند
(بالاترین اولویت در ابتدا):
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 1." 4.2
.\}
تنظیمات خط فرمان در قالب \fIKEY\fP=\fIVALUE\fP. مثال:
.sp
.if n .RS 4
.nf
.fam C
ccache debug=true compiler_check="%compiler% \-\-version" gcc \-c example.c
.fam
.fi
.if n .RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 2." 4.2
.\}
متغیرهای محیطی که با \f(CRCCACHE_\fP آغاز می‌شوند.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 3." 4.2
.\}
فایل پیکربندی ویژهٔ دایرکتوری.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 4." 4.2
.\}
فایل پیکربندی اختصاصی حافظهٔ پنهان (cache).
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 5." 4.2
.\}
فایل پیکربندی سراسری سیستم \f(CR<sysconfdir>/ccache.conf\fP
(معمولاً \f(CR/etc/ccache.conf\fP یا \f(CR/usr/local/etc/ccache.conf\fP).
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 6." 4.2
.\}
پیش‌فرض‌های زمان کامپایل.
.RE
.sp
استثنا: اگر متغیر محیطی \f(CRCCACHE_CONFIGPATH\fP تنظیم شده باشد، مشخص‌کنندهٔ
تنها فایل پیکربندی‌ای خواهد بود که خوانده می‌شود (متغیرهای محیطی و تنظیمات
خط فرمان همچنان اعمال خواهند شد)..SS "فایل پیکربندی اختصاصی حافظهٔ نهان (Cache\-specific configuration file)"
.sp
مکان فایل پیکربندی اختصاصی حافظهٔ نهان در سیستم‌های غیرویندوزی به این صورت تعیین می‌شود:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 1." 4.2
.\}
اگر \f(CRCCACHE_CONFIGPATH\fP تنظیم شده باشد، از آن مسیر استفاده می‌شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 2." 4.2
.\}
در غیر این صورت، اگر متغیر محیطی \f(CRCCACHE_DIR\fP تنظیم شده باشد، از
\f(CR$CCACHE_DIR/ccache.conf\fP استفاده می‌شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 3." 4.2
.\}
در غیر این صورت، اگر \fBcache_dir\fP در فایل پیکربندی سیستم
تنظیم شده باشد، از \f(CR<cache_dir>/ccache.conf\fP استفاده می‌شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 4." 4.2
.\}
در غیر این صورت، اگر دایرکتوری قدیمی \f(CR$HOME/.ccache\fP وجود داشته باشد، از
\f(CR$HOME/.ccache/ccache.conf\fP استفاده می‌شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 5." 4.2
.\}
در غیر این صورت، اگر \f(CRXDG_CONFIG_HOME\fP تنظیم شده باشد، از
\f(CR$XDG_CONFIG_HOME/ccache/ccache.conf\fP استفاده می‌شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 6." 4.2
.\}
در غیر این صورت، از
\f(CR$HOME/Library/Preferences/ccache/ccache.conf\fP (در macOS) یا
\f(CR$HOME/.config/ccache/ccache.conf\fP (در سایر سیستم‌ها) استفاده می‌شود.
.RE
.sp
در ویندوز، روش مورد استفاده برای یافتن فایل پیکربندی بدین صورت است:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 1." 4.2
.\}
اگر \f(CRCCACHE_CONFIGPATH\fP تنظیم شده باشد، از آن مسیر استفاده می‌شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 2." 4.2
.\}
در غیر این صورت، اگر متغیر محیطی \f(CRCCACHE_DIR\fP تنظیم شده باشد، از
\f(CR%CCACHE_DIR%/ccache.conf\fP استفاده می‌شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 3." 4.2
.\}
در غیر این صورت، اگر \fBcache_dir\fP در فایل پیکربندی سیستم
تنظیم شده باشد، از \f(CR<cache_dir>\(rsccache.conf\fP استفاده می‌شود. پیکربندی
سراسری سیستم در ویندوز به‌طور پیش‌فرض
\f(CR%ALLUSERSPROFILE%\(rsccache\(rsccache.conf\fP است. متغیر محیطی \f(CRALLUSERSPROFILE\fP
معمولاً \f(CRC:\(rsProgramData\fP می‌باشد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 4." 4.2
.\}
در غیر این صورت، اگر دایرکتوری قدیمی \f(CR%USERPROFILE%\(rs.ccache\fP وجود داشته باشد، از
\f(CR%USERPROFILE%\(rs.ccache\(rsccache.conf\fP استفاده می‌شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 5." 4.2
.\}
در غیر این صورت، چنانچه وجود داشته باشد، از \f(CR%LOCALAPPDATA%\(rsccache\(rsccache.conf\fP استفاده می‌شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 6." 4.2
.\}
در غیر این صورت، از \f(CR%APPDATA%\(rsccache\(rsccache.conf\fP استفاده می‌شود.
.RE
.sp
همچنین برای چگونگی تعیین مکان دایرکتوری حافظهٔ نهان، گزینهٔ پیکربندی \fBcache_dir\fP را ببینید..SS "فایل پیکربندی ویژه دایرکتوری"
.sp
دستور Ccache برای یافتن فایل \f(CRccache.conf\fP (جدا از فایل پیکربندی ویژه کش که در بالا شرح داده شد) در دایرکتوری کاری فعلی یا هر دایرکتوری والد جستجو می‌کند. مالک فایل پیداشده باید کاربر مؤثر باشد و فایل نباید برای همه قابل نوشتن باشد؛ در غیر این صورت ccache با یک خطا متوقف خواهد شد. جستجو با رسیدن به موارد زیر متوقف می‌شود:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
دایرکتوری فهرست‌شده در یک «دایرکتوری سقف» (به‌طور پیش‌فرض دایرکتوری خانگی کاربر)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
دایرکتوری دارای یک «نشانگر سقف» (به‌طور پیش‌فرض \f(CR.git\fP)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
دایرکتوری متعلق به کاربری دیگر
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
مرز یک سیستم‌فایل (نقطه پیوند)
.RE
.sp
به‌طور پیش‌فرض، این فایل نمی‌تواند «گزینه‌های ناامن» را تنظیم کند، یعنی گزینه‌هایی که بر تعیین اینکه چه دستورهایی اجرا شوند، چه فایل‌هایی (به‌جز ورودی‌های کش) نوشته شوند و از کدام فضای ذخیره‌سازی راه‌دور استفاده شود اثر می‌گذارند. می‌توان با افزودن یک ورودی به \fBsafe_dirs\fP، گزینه‌های ناامن را مجاز کرد.
.SS "ساختار مقادیر پیکربندی"
.sp
تمام مقادیر پیکربندی از بسط متغیرهای محیطی پشتیبانی می‌کنند. ساختار آن شبیه به ساختار پوسته POSIX است: \f(CR$VAR\fP یا \f(CR${VAR}\fP. هر دو نگارش به مقدار متغیر محیطی \f(CRVAR\fP بسط می‌یابند.
.sp
دو علامت دلار متوالی (\f(CR$$\fP) به یک علامت دلار تکی (\f(CR$\fP) بسط می‌یابند.
.SS "ساختار فایل پیکربندی"
.sp
فایل‌های پیکربندی در قالب سادهٔ \(lqkey = value\(rq هستند، یک گزینه در هر خط. خطوطی که با علامت هش (#) آغاز می‌شوند، توضیح هستند. خطوط خالی و همچنین فاصله‌های خالی پیرامون کلیدها و مقادیر نادیده گرفته می‌شوند. مثال:
.sp
.if n .RS 4
.nf
.fam C
# Set maximum cache size to 10 GB:
max_size = 10GB
.fam
.fi
.if n .RE
.SS "مقادیر چندخطی"
.sp
مقادیر می‌توانند با استفاده از ادامه بر پایهٔ تورفتگی، چند خط را در بر بگیرند. خطوطی که با نویسهٔ فاصله (فاصله یا تب) آغاز می‌شوند به‌عنوان خطوط ادامه در نظر گرفته شده و با یک فاصلهٔ تکی به مقدار قبلی متصل می‌شوند. توضیحات و خطوط خالی درون یک مقدار چندخطی نادیده گرفته می‌شوند. برای مثال:
.sp
.if n .RS 4
.nf
.fam C
ignore_options =
  \-Wall
  \-Wextra
  # This is a comment within the value
  \-pedantic
# This ends the multi\-line value
compiler = gcc
.fam
.fi
.if n .RE
.sp
این معادل است با:
.sp
.if n .RS 4
.nf
.fam C
ignore_options = \-Wall \-Wextra \-pedantic
compiler = gcc
.fam
.fi
.if n .RE
.sp
مقادیر چندخطی به‌ویژه برای گزینه‌هایی که چندین مورد را می‌پذیرند مفید هستند.
.SS "مقادیر بولی"
.sp
برخی از گزینه‌های پیکربندی مقادیر بولی (یعنی مقادیر درستی) هستند. در یک فایل پیکربندی، چنین مقادیری باید روی رشتهٔ \fBtrue\fP یا \fBfalse\fP تنظیم شوند. برای متغیرهای محیطی متناظر، معناشناسی کمی متفاوت است:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
یک متغیر محیطی مقداردهی‌شده به معنای \(lqtrue\(rq است (حتی اگر روی رشتهٔ خالی تنظیم شده باشد).
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
مقادیر منفی زیر (بدون حساسیت به بزرگی و کوچکی حروف) به‌جای سردرگم کردن کاربر، خطا در نظر گرفته می‌شوند: \fB0\fP، \fBfalse\fP، \fBdisable\fP و \fBno\fP.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
یک متغیر محیطی مقداردهی‌نشده به معنای \(lqfalse\(rq است.
.RE
.sp
هر متغیر محیطی بولی همچنین دارای یک شکل نفی‌شده است که با \f(CRCCACHE_NO\fP آغاز می‌شود. برای نمونه، \f(CRCCACHE_COMPRESS\fP می‌تواند برای اجبار فشرده‌سازی تنظیم شود و \f(CRCCACHE_NOCOMPRESS\fP می‌تواند برای اجبار عدم فشرده‌سازی تنظیم گردد..SS "فهرست‌های مسیر (Path lists)"
.sp
گزینه‌هایی که فهرستی از مسیرها را تعریف می‌کنند، ورودی‌هایشان با \f(CR;\fP در
Windows و \f(CR:\fP در سایر سیستم‌ها از یکدیگر جدا می‌شوند.
.SS "گزینه‌های پیکربندی (Configuration options)"
.sp
در زیر فهرستی از گزینه‌های پیکربندی موجود آورده شده است. نام متغیر محیطی
متناظر در پرانتز پس از کلید هر گزینهٔ پیکربندی مشخص شده است.
.sp
\fBabsolute_paths_in_stderr\fP (\fBCCACHE_ABSSTDERR\fP)
.RS 4
این گزینه مشخص می‌کند که آیا ccache باید مسیرهای نسبی را در خروجی متنی کامپایلر
(خطای استاندارد و خروجی استاندارد) به مسیرهای مطلق بازنویسی کند یا خیر. این
قابلیت زمانی می‌تواند مفید باشد که از \fBbase_dir\fP به همراه یک سیستم ساخت
(مانند CMake با مولد "Unix Makefiles") استفاده کنید که کامپایلر را در دایرکتوری
کاری متفاوتی اجرا می‌کند، امری که باعث نادرست شدن مسیرهای نسبی در خطاها یا
هشدارهای کامپایلر می‌شود. مقدار پیش‌فرض false است.
.RE
.sp
\fBbase_dir\fP (\fBCCACHE_BASEDIR\fP)
.RS 4
این گزینه فهرستی از مسیرهای مطلق را تعیین می‌کند. در صورت تنظیم،
ccache مسیرهای مطلق را قبل از ارسال به کامپایلر (یا گنجاندن در هش ورودی) به
مسیرهای نسبی تبدیل می‌کند، اما تنها برای مسیرهایی که با یکی از دایرکتوری‌های پایهٔ
مشخص‌شده آغاز می‌شوند. در اینجا منظور از «نسبی»، «نسبت به دایرکتوری کاری فعلی»
است.
.sp
این قابلیت اشتراک‌گذاری کَش را بین کامپایل‌ها در دایرکتوری‌های مختلف امکان‌پذیر
می‌سازد، حتی اگر پروژه از مسیرهای مطلق استفاده کند. برای جزئیات بیشتر به بخش
COMPILING IN DIFFERENT DIRECTORIES_ مراجعه کنید. در صورت خالی بودن (حالت پیش‌فرض)،
هیچ بازنویسی مسیری رخ نمی‌دهد.
.sp
از به‌کارگیری \f(CR/\fP به عنوان دایرکتوری پایه خودداری کنید، چرا که این کار مسیرهای
سرایند سیستمی را نیز بازنویسی می‌کند که معمولاً نتیجه‌ای معکوس دارد.
.sp
سناریوی نمونه: Alice در \f(CR/home/alice/project1/build\fP کار می‌کند و فرایند کامپایل را
به این صورت انجام می‌دهد:
.sp
.if n .RS 4
.nf
.fam C
ccache gcc \-I/usr/include/example \-I/home/alice/project2/include \-c /home/alice/project1/src/example.c
.fam
.fi
.if n .RE
.sp
در اینجا آنچه ccache واقعاً برای تنظیمات مختلف \fBbase_dir\fP اجرا خواهد کرد آورده شده است:
.sp
.if n .RS 4
.nf
.fam C
# Current working directory: /home/alice/project1/build

# With "base_dir = /":
gcc \-I../../../../usr/include/example \-I../../project2/include \-c ../src/example.c

# With "base_dir = /home" or "base_dir = /home/alice":
gcc \-I/usr/include/example \-I../../project2/include \-c ../src/example.c

# With "base_dir = /home/alice/project1" or "base_dir = /home/alice/project1/src":
gcc \-I/usr/include/example \-I/home/alice/project2/include \-c ../src/example.c
.fam
.fi
.if n .RE
.sp
اگر Bob همان پروژه‌ها را در \f(CR/home/bob/stuff\fP ذخیره کند و هر دو کاربر
\fBbase_dir\fP را روی \f(CR/home\fP یا \f(CR/home/$USER\fP تنظیم نمایند، به دلیل
یکسان بودن خطوط فرمان بازنویسی‌شده، از اصابت‌های کَش (cache hits) مشترک بهره‌مند خواهند شد:
.sp
.if n .RS 4
.nf
.fam C
# Current working directory: /home/bob/stuff/project1/build

# With "base_dir = /home" or "base_dir = /home/bob":
gcc \-I/usr/include/example \-I../../project2/include \-c ../src/example.c
.fam
.fi
.if n .RE
.sp
بدون \fBbase_dir\fP، به دلیل تفاوت در مسیرهای مطلق، عدم اصابت کَش (cache miss) رخ
خواهد داد. با تنظیم \fBbase_dir\fP روی \f(CR/\fP، به دلیل تفاوت در مسیر نسبی به
\f(CR/usr/include/example\fP عدم اصابت کَش پیش می‌آید. با تنظیم \fBbase_dir\fP روی
\f(CR/home/bob/stuff/project1\fP نیز عدم اصابت رخ می‌دهد زیرا مسیر به project2 یک
مسیر مطلق متفاوت خواهد بود.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B هشدار
.ps -1
.br
.sp
بازنویسی مسیرهای مطلق به نسبی تا حدی یک راهکار شکننده (brittle hack) است.
این روش در بسیاری از موارد به خوبی کار می‌کند، اما ممکن است شرایطی پیش بیاید که
کار مختل شود. یک مشکل شناخته‌شده این است که مسیرهای مطلق در فایل‌های وابستگی
بازتولید نمی‌شوند، که این امر می‌تواند تشخیص وابستگی را در ابزارهایی مانند Make و
Ninja به هم بریزد. در صورت امکان، از همان ابتدا به جای استفاده از \fBbase_dir\fP
از مسیرهای نسبی استفاده کنید.
.sp .5v
.RE
.RE
.sp
\fBcache_dir\fP (\fBCCACHE_DIR\fP)
.RS 4
این گزینه مشخص می‌کند که ccache خروجی‌های کَش‌شدهٔ کامپایلر را در کجا نگهداری کند.
.sp
در سیستم‌های غیر Windows، در صورت وجود چنین دایرکتوری‌ای مقدار پیش‌فرض
\f(CR$HOME/.ccache\fP است؛ در غیر این صورت اگر \f(CRXDG_CACHE_HOME\fP تنظیم شده باشد
\f(CR$XDG_CACHE_HOME/ccache\fP، وگرنه \f(CR$HOME/Library/Caches/ccache\fP (در macOS)
یا \f(CR$HOME/.cache/ccache\fP (در سایر سیستم‌ها) خواهد بود.
.sp
در Windows، پیش‌فرض \f(CR%USERPROFILE%\(rs.ccache\fP است اگر چنین دایرکتوری‌ای وجود
داشته باشد، در غیر این صورت \f(CR%LOCALAPPDATA%\(rsccache\fP خواهد بود.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B هشدار
.ps -1
.br
.sp
نسخه‌های پیشین ccache به طور پیش‌فرض در Windows کَش را در \f(CR%APPDATA%\(rsccache\fP
ذخیره می‌کردند. این امر می‌تواند منجر به انتقال فایل‌های حجیم کَش از طریق شبکه در
محیط‌های دامنه‌ای (domain) و مشکلات مشابه شود. لطفاً این دایرکتوری را برای دایرکتوری‌های
کَش بررسی کرده و آن‌ها یا کل دایرکتوری را حذف کنید، یا آن‌ها را به دایرکتوری
\f(CR%LOCALAPPDATA%\(rsccache\fP منتقل نمایید.
.sp .5v
.RE
.sp
همچنین بخش \fICache\-specific configuration file\fP را ببینید.
.RE
.sp
\fBceiling_dirs\fP (\fBCCACHE_CEILING_DIRS\fP)
.RS 4
این گزینه دایرکتوری‌های مطلقی را مشخص می‌کند که ccache در آن‌ها جستجو برای یافتن
فایل پیکربندی ویژهٔ دایرکتوری را متوقف خواهد کرد. اگر دسترسی به فایل‌ها در دایرکتوری‌های
والد بسیار کُند است (مثلاً در سیستم‌های فایل شبکه‌ای)، ممکن است بخواهید این گزینه را
تنظیم کنید. حالت پیش‌فرض، توقف جستجو هنگام رسیدن به دایرکتوری خانگی (home) کاربر است.
.RE
.sp
\fBceiling_markers\fP (\fBCCACHE_CEILING_MARKERS\fP)
.RS 4
این گزینه یک یا چند نام فایل یا دایرکتوری را مشخص می‌کند (با \f(CR;\fP در Windows
و \f(CR:\fP در سایر سیستم‌ها جدا می‌شوند). هنگام جستجو برای فایل پیکربندی ویژهٔ
دایرکتوری، ccache با رسیدن به دایرکتوری‌ای که حاوی هر یک از نام‌های مشخص‌شده باشد،
جستجو در دایرکتوری‌های والد را متوقف خواهد کرد. مقدار پیش‌فرض \f(CR.git\fP است.
.RE
.sp
\fBcompiler\fP (\fBCCACHE_COMPILER\fP or (منسوخ‌شده) \fBCCACHE_CC\fP)
.RS 4
این گزینه می‌تواند برای اجبار نام کامپایلرِ مورد استفاده به کار رود. اگر روی یک
رشتهٔ خالی (که حالت پیش‌فرض است) تنظیم شود، ccache آن را از خط فرمان استخراج می‌کند.
.RE
.sp
\fBcompiler_check\fP (\fBCCACHE_COMPILERCHECK\fP)
.RS 4
به‌طور پیش‌فرض، ccache زمان تغییر (\(lqmtime\(rq) و اندازهٔ کامپایلر را در هش
می‌گنجاند تا اطمینان حاصل شود که نتایج بازیابی‌شده از کَش دقیق هستند. در صورت استفاده
از افزونه‌های کامپایلر، این افزونه‌ها نیز به هش اضافه خواهند شد. این گزینه می‌تواند
برای انتخاب یک راهبرد دیگر به کار رود. مقادیر ممکن عبارتند از:
.sp
\fBcontent\fP
.RS 4
هش کردن محتوای باینری کامپایلر. این کار سرعت ccache را در مقایسه با \fBmtime\fP بسیار
اندک کاهش می‌دهد، اما باعث سازگاری بهتر با ارتقای کامپایلر در طول فرایند خودراه‌اندازی
(bootstrapping) ساخت می‌شود.
.RE
.sp
\fBmtime\fP
.RS 4
هش کردن mtime و اندازهٔ کامپایلر، که سریع است. این حالت پیش‌فرض است.
.RE
.sp
\fBnone\fP
.RS 4
هیچ چیزی هش نمی‌شود. این حالت ممکن است برای شرایطی مناسب باشد که می‌توانید با
اطمینان خاطر از نتایج کَش‌شده استفاده کنید، حتی اگر mtime یا اندازهٔ کامپایلر تغییر کرده
باشد (مثلاً اگر کامپایلر به عنوان بخشی از سیستم ساخت شما ساخته می‌شود و سورس کامپایلر
تغییر نکرده است، یا اگر کامپایلر تنها تغییراتی داشته که بر تولید کد تأثیر نمی‌گذارند).
تنها در صورتی باید از \fBnone\fP استفاده کنید که دقیقاً بدانید چه کاری انجام می‌دهید.
.RE
.sp
\fBstring:value\fP
.RS 4
مقدار \fBvalue\fP هش می‌شود. این می‌تواند برای نمونه یک شماره بازنگری (revision)
کامپایلر یا رشتهٔ دیگری باشد که سیستم ساخت برای شناسایی کامپایلر تولید می‌کند.
.RE
.sp
\fIa command string\fP
.RS 4
خروجی استاندارد و خروجی خطای استاندارد دستور مشخص‌شده را هش می‌کند. رشته با
استفاده از فاصله‌های خالی (whitespace) برای یافتن دستور و آرگومان‌های اجرایی
تفکیک می‌شود. هیچ تفسیر دیگری روی رشتهٔ دستور انجام نخواهد شد، به جز اینکه عبارت
ویژهٔ \fB%compiler%\fP با مسیر کامپایلر جایگزین می‌شود. می‌توان چندین دستور را با
استفاده از \f(CR;\fP به عنوان جداکننده تعیین کرد. مثال‌ها:
.sp
.if n .RS 4
.nf
.fam C
%compiler% \-v
.fam
.fi
.if n .RE
.sp
.if n .RS 4
.nf
.fam C
%compiler% \-dumpmachine; %compiler% \-dumpversion
.fam
.fi
.if n .RE
.sp
باید اطمینان حاصل کنید که دستور مشخص‌شده تا حد امکان سریع باشد زیرا برای هر بار
فراخوانی ccache یک بار اجرا خواهد شد.
.sp
شناسایی کامپایلر با استفاده از یک دستور در صورتی مفید است که بخواهید از عدم اصابت‌های
کَش در شرایطی که کامپایلر بازسازی شده اما تغییر نکرده است، جلوگیری نمایید.
.sp
حالت دیگر زمانی است که کامپایلر (از دید ccache) در واقع کامپایلر واقعی نبوده بلکه یک
پوشش‌دهندهٔ دیگر کامپایلر (compiler wrapper) است \(em در این صورت، روش پیش‌فرض
\fBmtime\fP مقدار mtime و اندازهٔ پوشش‌دهندهٔ دیگر را هش می‌کند، بدین معنا که ccache
قادر به تشخیص ارتقای کامپایلر نخواهد بود. بنابراین استفاده از یک دستور مناسب برای شناسایی
کامپایلر امن‌تر است، اما کُندتر نیز خواهد بود؛ از این رو باید در صورت امکان، ادامهٔ
استفاده از روش \fBmtime\fP در ترکیب با گزینهٔ \fBprefix_command\fP را مد نظر قرار دهید.
بخش \fIUSING CCACHE WITH OTHER COMPILER WRAPPERS\fP را ببینید.
.RE
.RE
.sp
\fBcompiler_type\fP (\fBCCACHE_COMPILERTYPE\fP)
.RS 4
سی‌کَش معمولاً نوع کامپایلر را بر اساس نام کامپایلر حدس می‌زند. گزینهٔ
\fBcompiler_type\fP به شما امکان می‌دهد نوع کامپایلر را اجبار کنید. این در حالتی
مفید است که کامپایلر نام غیر استانداردی دارد اما در واقع یکی از انواع شناخته‌شدهٔ
کامپایلر است. مقادیر ممکن عبارتند از:
.sp
\fBauto\fP
.RS 4
یکی از انواع زیر را بر اساس نام کامپایلر (با دنبال کردن پیوندهای نمادین) حدس می‌زند.
این مقدار پیش‌فرض است.
.RE
.sp
\fBclang\fP
.RS 4
کامپایلر مبتنی بر Clang.
.RE
.sp
\fBclang\-cl\fP
.RS 4
کامپایلر clang\-cl.
.RE
.sp
\fBgcc\fP
.RS 4
کامپایلر مبتنی بر GCC.
.RE
.sp
\fBicl\fP
.RS 4
کامپایلر Intel در Windows.
.RE
.sp
\fBicx\fP
.RS 4
کامپایلر مبتنی بر LLVM شرکت Intel.
.RE
.sp
\fBicx\-cl\fP
.RS 4
کامپایلر سازگار با MSVC مبتنی بر LLVM شرکت Intel.
.RE
.sp
\fBmsvc\fP
.RS 4
کامپایلر Microsoft Visual C++ (MSVC).
.RE
.sp
\fBnvcc\fP
.RS 4
کامپایلر NVCC (CUDA).
.RE
.sp
\fBqcc\fP
.RS 4
کامپایلر QCC (QNX).
.RE
.sp
\fBother\fP
.RS 4
هر کامپایلری غیر از انواع شناخته‌شده.
.RE
.RE
.sp
\fBcompression\fP (\fBCCACHE_COMPRESS\fP یا \fBCCACHE_NOCOMPRESS\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
اگر true باشد، ccache داده‌هایی را که در کَش قرار می‌دهد فشرده‌سازی می‌کند. با این
حال، این گزینه تأثیری بر نحوهٔ بازیابی فایل‌ها از کَش ندارد؛ نتایج فشرده‌شده و فشرده‌نشده
بدون در نظر گرفتن این گزینه همچنان قابل استفاده خواهند بود. مقدار پیش‌فرض true است.
.sp
فشرده‌سازی با استفاده از الگوریتم Zstandard انجام می‌شود. این الگوریتم به اندازهٔ کافی
سریع است و دلیل چندانی برای غیرفعال کردن فشرده‌سازی جهت دستیابی به عملکرد بیشتر وجود
ندارد. یک استثنا زمانی است که کَش روی یک سیستم فایل فشرده‌شده قرار دارد، که در این حالت
مسلماً فشرده‌سازی انجام‌شده توسط ccache تکراری و زائد است.
.sp
در صورت فعال بودن شبیه‌سازی فایل (گزینهٔ \fBfile_clone\fP) یا پیوند سخت (گزینهٔ
\fBhard_link\fP)، فشرده‌سازی غیرفعال خواهد شد.
.RE
.sp
\fBcompression_level\fP (\fBCCACHE_COMPRESSLEVEL\fP)
.RS 4
این گزینه سطحی را تعیین می‌کند که ccache در آن فایل‌های شیء را با استفاده از الگوریتم
فشرده‌سازی بی‌درنگ Zstandard فشرده می‌کند. این گزینه تنها در صورتی تأثیر دارد که
\fBcompression\fP فعال باشد (که به طور پیش‌فرض فعال است). الگوریتم Zstandard برای
خروج از حالت فشرده (decompression) فوق‌العاده سریع و برای فشرده‌سازی در سطوح پایین
بسیار سریع است. مقدار پیش‌فرض 0 است.
.sp
معناشناسی \fBcompression_level\fP:
.sp
\fB> 0\fP
.RS 4
یک مقدار مثبت متناظر با سطوح فشرده‌سازی عادی Zstandard است. سطوح پایین‌تر (مانند \fB1\fP)
به معنای فشرده‌سازی سریع‌تر اما ضریب فشرده‌سازی ضعیف‌تر است. سطوح بالاتر (مانند \fB19\fP)
به معنای فشرده‌سازی کُندتر اما ضریب فشرده‌سازی بهتر است. حداکثر مقدار ممکن به نسخهٔ
libzstd بستگی دارد، اما حداقل تا سطح 19 برای همهٔ نسخه‌ها در دسترس است. سرعت خروج از
فشرده‌سازی اساساً برای تمام سطوح یکسان است. به عنوان یک قاعدهٔ تجربی، از سطح 5 یا
پایین‌تر استفاده کنید زیرا سطوح بالاتر ممکن است فرایند کامپایل را به طرز محسوسی کُند
کنند. با این حال سطوح بالاتر هنگام فشرده‌سازی مجدد کَش با گزینهٔ خط فرمان
\f(CR\-X\fP/\f(CR\-\-recompress\fP مفید هستند.
.RE
.sp
\fB< 0\fP
.RS 4
یک مقدار منفی با سطوح فشرده‌سازی «فوق سریع» (ultra\-fast) در Zstandard مطابقت دارد
که حتی از سطح 1 سریع‌تر هستند اما نسبت فشرده‌سازی پایین‌تری دارند. برای نمونه، سطح
\fB\-3\fP متناظر با \f(CR\-\-fast=3\fP برای ابزار خط فرمان \f(CRzstd\fP است. در عمل،
کاربرد چندانی برای سطوح پایین‌تر از حدود \fB\-5\fP وجود ندارد.
.RE
.sp
\fB0\fP (پیش‌فرض)
.RS 4
مقدار \fB0\fP بدین معناست که ccache یک سطح مناسب را انتخاب خواهد کرد که در حال
حاضر \fB1\fP است.
.RE
.sp
برای اطلاعات بیشتر \c
.URL "https://facebook.github.io/zstd" "مستندات Zstandard" ""
را ببینید.
.RE
.sp
\fBdebug\fP (\fBCCACHE_DEBUG\fP یا \fBCCACHE_NODEBUG\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
اگر true باشد، حالت اشکال‌زدایی (debug) فعال می‌شود. حالت اشکال‌زدایی فایل‌های
اشکال‌زدایی مجزایی به ازای هر شیء (per\-object) ایجاد می‌کند که هنگام اشکال‌زدایی از
عدم اصابت‌های غیرمنتظره در کَش مفید هستند. با این حال توجه داشته باشید که کارایی
ccache اندکی کاهش می‌یابد. برای اطلاعات بیشتر بخش \fICACHE DEBUGGING\fP را ببینید.
پیش‌فرض false است.
.RE
.sp
\fBdebug_dir\fP (\fBCCACHE_DEBUGDIR\fP)
.RS 4
مشخص می‌کند که در صورت فعال بودن حالت اشکال‌زدایی، فایل‌های اشکال‌زدایی به ازای هر شیء
در کجا نوشته شوند. در صورت تنظیم روی رشتهٔ خالی، فایل‌ها در کنار فایل شیء نوشته خواهند
شد. در صورت تنظیم روی یک دایرکتوری، فایل‌های اشکال‌زدایی با مسیرهای کامل و مطلق در آن
دایرکتوری نوشته می‌شوند و در صورت نیاز آن دایرکتوری ایجاد می‌گردد. پیش‌فرض رشتهٔ خالی است.
.sp
به عنوان مثال، اگر \fBdebug_dir\fP روی \f(CR/example\fP تنظیم شده باشد، دایرکتوری کاری
فعلی \f(CR/home/user\fP باشد و فایل شیء \f(CRbuild/output.o\fP باشد، گزارش اشکال‌زدایی
در \f(CR/example/home/user/build/output.o.ccache\-log\fP نوشته خواهد شد. همچنین بخش
\fICACHE DEBUGGING\fP را ببینید.
.RE
.sp
\fBdebug_level\fP (\fBCCACHE_DEBUGLEVEL\fP)
.RS 4
میزان اطلاعاتی را که هنگام فعال بودن حالت اشکال‌زدایی نوشته می‌شود تعیین می‌کند.
برای اطلاعات بیشتر بخش \fICACHE DEBUGGING\fP را ببینید. پیش‌فرض 2 است.
.RE
.sp
\fBdepend_mode\fP (\fBCCACHE_DEPEND\fP یا \fBCCACHE_NODEPEND\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
اگر true باشد، از حالت وابستگی (depend mode) استفاده خواهد شد. پیش‌فرض false است. بخش
\fIThe depend mode\fP را ببینید.
.RE
.sp
\fBdirect_mode\fP (\fBCCACHE_DIRECT\fP یا \fBCCACHE_NODIRECT\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
اگر true باشد، از حالت مستقیم (direct mode) استفاده خواهد شد. پیش‌فرض true است. بخش
\fIThe direct mode\fP را ببینید.
.RE
.sp
\fBdisable\fP (\fBCCACHE_DISABLE\fP یا \fBCCACHE_NODISABLE\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
هنگامی که true باشد، ccache صرفاً کامپایلر واقعی را فراخوانی می‌کند و کَش را کاملاً
دور می‌زند. پیش‌فرض false است.
.sp
همچنین می‌توان با افزودن رشتهٔ \f(CRccache:disable\fP در یک کامنت درون 4096 بایت نخست
فایل سورس کد، ccache را برای یک فایل سورس کد مشخص غیرفعال کرد.
.RE
.sp
\fBextra_files_to_hash\fP (\fBCCACHE_EXTRAFILES\fP)
.RS 4
این گزینه فهرستی از مسیرهای فایل‌هایی است که ccache در مجموع هشِ (hash sum)
شناساگر ساخت می‌گنجاند.
.RE
.sp
\fBfile_clone\fP (\fBCCACHE_FILECLONE\fP یا \fBCCACHE_NOFILECLONE\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
اگر true باشد، ccache تلاش می‌کند از شبیه‌سازی فایل (معروف به «رونوشت هنگام نوشتن»،
«CoW» یا «reflinks») برای ذخیره و واکشی نتایج کَش‌شدهٔ کامپایلر استفاده کند.
\fBfile_clone\fP بر \fBhard_link\fP اولویت دارد. مقدار پیش‌فرض false است.
.sp
فایل‌های ذخیره‌شده از طریق شبیه‌سازی را نمی‌توان فشرده کرد، بنابراین در صورت فعال
بودن این گزینه احتمالاً اندازهٔ کَش به میزان چشمگیری بزرگ‌تر خواهد بود. با این حال،
بسته به مورد کاربرد، عملکرد ممکن است بهبود یابد.
.sp
برخلاف گزینهٔ \fBhard_link\fP، استفاده از \fBfile_clone\fP کاملاً امن است، اما همهٔ
سیستم‌های فایل از این ویژگی پشتیبانی نمی‌کنند. برای چنین سیستم‌های فایلی، ccache
به کپی کردن معمولی (یا پیوندهای سخت در صورت فعال بودن \fBhard_link\fP) بازمی‌گردد.
.RE
.sp
\fBhard_link\fP (\fBCCACHE_HARDLINK\fP یا \fBCCACHE_NOHARDLINK\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
اگر true باشد، ccache تلاش خواهد کرد تا از پیوندهای سخت برای ذخیره و واکشی فایل‌های
شیء کَش‌شده استفاده کند. پیش‌فرض false است.
.sp
فایل‌های ذخیره‌شده از طریق پیوندهای سخت را نمی‌توان فشرده کرد، بنابراین در صورت
فعال بودن این گزینه به احتمال قوی اندازهٔ کَش به طرز چشمگیری بزرگ‌تر خواهد بود. با
این حال، بسته به مورد کاربرد، کارایی ممکن است بهبود پیدا کند.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B هشدار
.ps -1
.br
.sp
این گزینه را فعال نکنید مگر اینکه از این نکات آگاه باشید:
.sp .5v
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اگر فایل حاصل ویرایش شود، فایل موجود در کَش نیز به دلیل محتوای اشتراکی ویرایش خواهد
شد، که این امر باعث خرابی ورودی کَش می‌گردد. از نسخهٔ 4.0، ccache به عنوان یک تدبیر
ایمنی، فایل‌های شیء ذخیره‌شده و واکشی‌شده را فقط‌خواندنی می‌کند. علاوه بر این، یک بررسی
جامعیت ساده برای فایل‌های شیء کَش‌شده با تأیید صحت اندازهٔ آن‌ها انجام می‌پذیرد. این بدان
معناست که اشتباهاتی نظیر \f(CRstrip file.o\fP یا \f(CRecho >file.o\fP حتی در صورت
قابل‌نوشتن بودن فایل شیء شناسایی خواهند شد، اما تغییری که اندازهٔ فایل را دگرگون نسازد
تشخیص داده نخواهد شد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
برنامه‌هایی که انتظار ندارند فایل‌های حاصل از دو کامپایل یکسان به صورت پیوندهای سخت به
یکدیگر باشند، ممکن است دچار خطا شوند.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
برنامه‌هایی که به زمان‌های تغییر اتکا دارند (مانند \f(CRmake\fP)، اگر چندین کاربر
(یا یک کاربر با چند درخت ساخت مختلف) از یک دایرکتوری کَش مشترک استفاده کنند، ممکن است
به اشتباه بیفتند. دلیل این امر این است که فایل‌های شیء دارای اینودهای (i-nodes) مشترک
و در نتیجه برچسب زمانی تغییر یکسانی هستند. اگر \f(CRfile.o\fP در درخت ساخت \fBA\fP
(با پیوند سخت از کَش) وجود داشته باشد و سپس \f(CRfile.o\fP در درخت ساخت \fBB\fP توسط
ccache با پیوند سخت از کَش ایجاد گردد، برچسب زمانی تغییر برای \f(CRfile.o\fP در درخت
ساخت \fBA\fP نیز به‌روزرسانی خواهد شد. این امر می‌تواند موجب اجرای مجدد مرحلهٔ پیونددهی
(relinking) در درخت ساخت \fBA\fP شود، حتی اگر در واقع چیزی تغییر نکرده باشد.
.RE
.RE
.sp
\fBhash_dir\fP (\fBCCACHE_HASHDIR\fP یا \fBCCACHE_NOHASHDIR\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
اگر true باشد (که پیش‌فرض است)، ccache هنگام تولید اطلاعات اشکال‌زدایی (گزینهٔ کامپایلر
\f(CR\-g\fP با مشتقات آن)، دایرکتوری کاری فعلی (CWD) را در هشی که برای تفکیک دو کامپایل
استفاده می‌شود می‌گنجاند. استثنا: اگر گزینه‌های کامپایلر \f(CR\-fdebug\-prefix\-map\fP یا
\f(CR\-fdebug\-compilation\-dir\fP به درستی به کار برده شوند، CWD در هش گنجانده نخواهد
شد. همچنین به بحث در بخش \fICOMPILING IN DIFFERENT DIRECTORIES\fP مراجعه کنید.
.sp
دلیل گنجاندن CWD در هش به طور پیش‌فرض، جلوگیری از بروز مشکل در ذخیره‌سازی دایرکتوری کاری
فعلی در اطلاعات اشکال‌زدایی یک فایل شیء است، که می‌تواند باعث شود ccache فایل شیء
کَش‌شده‌ای را بازگرداند که دایرکتوری کاری در اطلاعات اشکال‌زدایی آن به اشتباه تنظیم شده است.
.sp
اگر برایتان مهم نیست که CWD در اطلاعات اشکال‌زدایی ممکن است نادرست باشد، می‌توانید این
گزینه را غیرفعال کنید تا هنگام کامپایل یک سورس کد یکسان در دایرکتوری‌های متفاوت، اصابت‌های
کَش دریافت نمایید.
.RE
.sp
\fBignore_headers_in_manifest\fP (\fBCCACHE_IGNOREHEADERS\fP)
.RS 4
این گزینه فهرستی از مسیرها به فایل‌ها (یا دایرکتوری‌های حاوی سرایندها) است که ccache
آن‌ها را در فهرست مانیفستِ تشکیل‌دهندهٔ حالت مستقیم \fBنمی‌گنجاند\fP. توجه داشته باشید
که اگر این سرایندها واقعاً تغییر کنند، این امر می‌تواند منجر به اصابت‌های کهنه در کَش شود.
.RE
.sp
\fBignore_options\fP (\fBCCACHE_IGNOREOPTIONS\fP)
.RS 4
این گزینه فهرستی با جداکنندهٔ فاصله از گزینه‌های کامپایلر است که ccache آن‌ها را نادیده
می‌گیرد. ورودی‌های این فهرست به صورت اختیاری می‌توانند با یک ستاره (\f(CR*\fP) خاتمه
یابند تا با هر پسوندی از گزینه مطابقت داشته باشند. به عنوان مثال، \f(CR\-fmessage\-length=*\fP
هم با \f(CR\-fmessage\-length=20\fP و هم با \f(CR\-fmessage\-length=70\fP مطابقت خواهد
داشت. گزینهٔ کامپایلر منطبق‌شده نه به طور خاص تفسیر می‌شود و نه بخشی از هش ورودی خواهد
بود. نادیده گرفتن یک گزینهٔ کامپایلر از هش زمانی مفید است که می‌دانید آن گزینه بر نتیجه
تأثیری ندارد (و ccache این را نمی‌داند)، یا زمانی که تأثیر می‌گذارد اما برای شما اهمیتی
ندارد. همچنین بخش \fIExtra options\fP را ببینید.
.RE
.sp
\fBinode_cache\fP (\fBCCACHE_INODECACHE\fP یا \fBCCACHE_NOINODECACHE\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
اگر true باشد، ccache هش‌های فایل سورس را بر اساس دستگاه، اینود و برچسب‌های زمانی کَش
می‌کند. این امر زمان صرف‌شده برای هش کردن فایل‌های ضمیمه‌شده (include) را کاهش می‌دهد چرا
که نتیجه می‌تواند بین کامپایل‌ها مجدداً مورد استفاده قرار گیرد. پیش‌فرض true است. این
ویژگی نیازمند آن است که \fBtemporary_dir\fP روی یک سیستم فایل محلی با نوع پشتیبانی‌شده
قرار داشته باشد.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B نکته
.ps -1
.br
.sp
پشتیبانی از ویژگی کَش اینود در Windows آزمایشی است. در Windows مقدار پیش‌فرض false است.
.sp .5v
.RE
.RE
.sp
\fBkeep_comments_cpp\fP (\fBCCACHE_COMMENTS\fP یا \fBCCACHE_NOCOMMENTS\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
اگر true باشد، ccache پیش از هش کردن خروجی پیش‌پردازنده، کامنت‌ها را دور نمی‌ریزد.
پیش‌فرض false است. این گزینه می‌تواند برای بررسی مستندات با \f(CR\-Wdocumentation\fP
استفاده شود.
.RE
.sp
\fBlibexec_dirs\fP (\fBCCACHE_LIBEXEC_DIRS\fP)
.RS 4
در صورت تنظیم، ccache برنامه‌های کمکی را به جای مسیر پیش‌فرض در این دایرکتوری‌ها جستجو
خواهد کرد.
.RE
.sp
\fBlog_file\fP (\fBCCACHE_LOGFILE\fP)
.RS 4
اگر روی یک مسیر فایل تنظیم شود، ccache اطلاعات مربوط به کارهایی را که انجام می‌دهد در فایل
مشخص‌شده می‌نویسد. این امر برای ردیابی و بررسی مشکلات مفید است.
.sp
اگر روی \fBsyslog\fP تنظیم شود، ccache به جای فایل، گزارش‌ها را با استفاده از \f(CRsyslog()\fP
ثبت می‌کند. اگر از rsyslogd استفاده می‌کنید، می‌توانید موردی مانند این را به \f(CR/etc/rsyslog.conf\fP
یا فایلی درون \f(CR/etc/rsyslog.d\fP اضافه کنید:
.sp
.if n .RS 4
.nf
.fam C
# log ccache to file
:programname, isequal, "ccache"\&         /var/log/ccache
# remove from syslog
& ~
.fam
.fi
.if n .RE
.RE
.sp
\fBmax_files\fP (\fBCCACHE_MAXFILES\fP)
.RS 4
این گزینه حداکثر تعداد فایل‌ها را برای نگهداری در کَش مشخص می‌کند. از 0 برای بدون محدودیت
بودن استفاده کنید (که حالت پیش‌فرض است). همچنین بخش \fICACHE SIZE MANAGEMENT\fP را ببینید.
.RE
.sp
\fBmax_size\fP (\fBCCACHE_MAXSIZE\fP)
.RS 4
این گزینه حداکثر اندازهٔ کَش را مشخص می‌کند. برای عدم اعمال محدودیت، 0 را به کار ببرید.
مقدار پیش‌فرض 5GiB است. پسوندهای در دسترس: kB، MB، GB، TB (ده‌دهی) و KiB، MiB، GiB، TiB
(دودویی). پسوند پیش‌فرض GiB است. همچنین بخش \fICACHE SIZE MANAGEMENT\fP را ببینید.
.RE
.sp
\fBmsvc_dep_prefix\fP (\fBCCACHE_MSVC_DEP_PREFIX\fP)
.RS 4
این گزینه پیشوند خروجی فایل‌های ضمیمه‌شده را برای کامپایلر MSVC مشخص می‌کند. پیشوند
پیش‌فرض \(lqNote: including file:\(rq است. اگر از کامپایلر بومی‌سازی‌شده استفاده
می‌کنید، این مقدار باید بر همان اساس تنظیم شود.
.RE
.sp
\fBmsvc_utf8\fP (\fBCCACHE_MSVC_UTF8\fP)
.RS 4
این گزینه هنگام اجرای پیش‌پردازنده، \f(CR/utf\-8\fP را به خط فرمان msvc می‌افزاید تا اطمینان
حاصل شود که نام فایل‌ها برای نویسه‌های غیر ascii مخدوش نمی‌شوند. این کار به طور ضمنی
\f(CR/validate\-charset\fP را فعال کرده و با سورس کد همانند utf\-8 رفتار می‌کند که ممکن
است در صورت وجود نویسه‌هایی در بازهٔ [128, 255] در کامنت‌های کد شما بر اساس جدول کد سیستم
Windows (که توالی نامعتبر utf\-8 ایجاد می‌کند)، خطاهای کامپایل ایجاد کند. پیش‌فرض true است.
.RE
.sp
\fBnamespace\fP (\fBCCACHE_NAMESPACE\fP)
.RS 4
در صورت تنظیم، رشتهٔ فضای نام برای هر فرایند کامپایل به داده‌های هش‌شده افزوده خواهد شد.
این کار ورودی‌های کَش مرتبط را از نظر منطقی از ورودی‌های کَش با سایر فضاهای نام تفکیک می‌کند،
اما آن‌ها همچنان از یک فضای ذخیره‌سازی مشترک استفاده خواهند کرد. ورودی‌های کَش را می‌توان
همچنین به طور گزینشی با گزینهٔ خط فرمان \f(CR\-\-evict\-namespace\fP، احتمالاً در ترکیب با
\f(CR\-\-evict\-older\-than\fP، از کَش محلی پاک‌سازی کرد.
.sp
به عنوان مثال، اگر از یک کَش محلی یکسان برای چندین پروژهٔ مجزا استفاده می‌کنید، می‌توانید
برای هر کدام یک رشتهٔ فضای نام منحصر‌به‌فرد اختصاص دهید. این امر به شما امکان می‌دهد در
صورت متوقف کردن کار بر روی یک پروژهٔ خاص، ورودی‌های کَش متعلق به آن را حذف کنید.
.RE
.sp
\fBpath\fP (\fBCCACHE_PATH\fP)
.RS 4
در صورت تنظیم، ccache هنگام جستجو برای کامپایلر واقعی، دایرکتوری‌های موجود در این فهرست را
بررسی خواهد کرد. در صورت عدم تنظیم، ccache اولین فایل اجرایی مطابق با نام کامپایلر را در
\f(CRPATH\fP عادی جستجو می‌کند که یک پیوند نمادین به خود ccache نباشد.
.RE
.sp
\fBpch_external_checksum\fP (\fBCCACHE_PCH_EXTSUM\fP یا \fBCCACHE_NOPCH_EXTSUM\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
هنگامی که این گزینه تنظیم شده باشد و ccache یک فایل سرایند از پیش‌کامپایل‌شده را بیابد، به
دنبال فایلی با پسوند افزودهٔ \(lq.sum\(rq می‌گردد (مثلاً \(lqpre.h.gch.sum\(rq)، و در صورت
یافتن، به جای خود سرایند از پیش‌کامپایل‌شده، این فایل را هش می‌کند تا افت کارایی ناشی از هش
کردن فایل‌های بسیار بزرگ برطرف گردد.
.RE
.sp
\fBprefix_command\fP (\fBCCACHE_PREFIX\fP)
.RS 4
این گزینه فهرستی از پیشوندها (جداشده با فاصله) را به خط فرمانی که ccache هنگام فراخوانی
کامپایلر به کار می‌گیرد اضافه می‌کند. همچنین بخش \fIUSING CCACHE WITH OTHER COMPILER WRAPPERS\fP
را ببینید.
.RE
.sp
\fBprefix_command_cpp\fP (\fBCCACHE_PREFIX_CPP\fP)
.RS 4
این گزینه فهرستی از پیشوندها (جداشده با فاصله) را به خط فرمانی که ccache هنگام فراخوانی
پیش‌پردازنده به کار می‌گیرد اضافه می‌کند.
.RE
.sp
\fBread_only\fP (\fBCCACHE_READONLY\fP یا \fBCCACHE_NOREADONLY\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
اگر true باشد، ccache تلاش می‌کند از نتایج کَش‌شدهٔ موجود استفاده کند، اما نتایج جدیدی را
به هیچ پیشانهٔ (backend) کَشی اضافه نخواهد کرد. با این وجود شمارنده‌های آمار همچنان به‌روزرسانی
خواهند شد، مگر اینکه گزینهٔ \fBstats\fP روی \fBfalse\fP تنظیم شده باشد.
.sp
اگر به این دلیل از این گزینه استفاده می‌کنید که دایرکتوری ccache شما فقط‌خواندنی است، باید
\fBtemporary_dir\fP را تنظیم نمایید چرا که در غیر این صورت ccache در ایجاد فایل‌های موقت
با شکست مواجه خواهد شد. همچنین ممکن است مایل باشید \fBstats\fP را روی \fBfalse\fP بگذارید
تا ccache حتی برای به‌روزرسانی فایل‌های آمار تلاشی نکند.
.RE
.sp
\fBread_only_direct\fP (\fBCCACHE_READONLY_DIRECT\fP یا \fBCCACHE_NOREADONLY_DIRECT\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
دقیقاً مانند \fBread_only\fP است با این تفاوت که ccache تنها تلاش می‌کند تا نتایج را با
استفاده از حالت مستقیم از کَش بازیابی کند، نه حالت پیش‌پردازنده. مستندات مربوط به
\fBread_only\fP را در رابطه با به‌کارگیری یک دایرکتوری فقط‌خواندنی ccache مشاهده فرمایید.
.RE
.sp
\fBrecache\fP (\fBCCACHE_RECACHE\fP یا \fBCCACHE_NORECACHE\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
اگر true باشد، ccache از هیچ نتیجهٔ ذخیره‌شدهٔ قبلی استفاده نخواهد کرد. نتایج جدید همچنان
کَش خواهند شد، و احتمالاً بر روی هر نتیجهٔ از پیش موجودی بازنویسی می‌شوند.
.RE
.sp
\fBremote_only\fP (\fBCCACHE_REMOTE_ONLY\fP یا \fBCCACHE_NOREMOTE_ONLY\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
اگر true باشد، ccache تنها از فضای ذخیره‌سازی دوردست (remote) استفاده خواهد کرد. مقدار
پیش‌فرض false است. توجه داشته باشید که شمارنده‌های آمار کَش همچنان در دایرکتوری کَش محلی
نگهداری خواهند شد مگر اینکه \fBstats\fP برابر با false باشد. همچنین بخش \fIStorage interaction\fP
را ببینید.
.RE
.sp
\fBremote_storage\fP (\fBCCACHE_REMOTE_STORAGE\fP)
.RS 4
این گزینه یک یا چند پیشانهٔ ذخیره‌سازی (جداشده با فاصلهٔ خالی) را برای پرس‌وجو پس از
بررسی کَش محلی مشخص می‌کند (مگر اینکه \fBremote_only\fP روی true باشد). برای اطلاع از
نحو و پیشانه‌های موجود به \fIREMOTE STORAGE BACKENDS\fP مراجعه نمایید.
.sp
مثال‌ها:
.sp
.if n .RS 4
.nf
.fam C
remote_storage = file:/shared/nfs/directory+`
remote_storage =
  file:///shared/nfs/one read\-only
  file:///shared/nfs/two
remote_storage = file:///Z:/example/windows/folder
remote_storage = http://example.com/cache
remote_storage = redis://example.com
.fam
.fi
.if n .RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B نکته
.ps -1
.br
.sp
در نسخه‌های پیشین ccache، این گزینه \fBsecondary_storage\fP (\fBCCACHE_SECONDARY_STORAGE\fP)
نامیده می‌شد که هنوز هم می‌تواند به عنوان یک نام مستعار به کار رود.
.sp .5v
.RE
.RE
.sp
\fBreshare\fP (\fBCCACHE_RESHARE\fP یا \fBCCACHE_NORESHARE\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
اگر true باشد، ccache حتی برای اصابت‌های کَش محلی نیز نتایج را در فضای ذخیره‌سازی دوردست
می‌نویسد. مقدار پیش‌فرض false است.
.RE
.sp
\fBresponse_file_format\fP (\fBCCACHE_RESPONSE_FILE_FORMAT\fP)
.RS 4
سی‌کَش معمولاً قالب فایل پاسخ (response file) را بر اساس نوع کامپایلر حدس می‌زند.
گزینهٔ \fBresponse_file_format\fP به شما اجازه می‌دهد رفتار نقل‌قول (quoting) فایل
پاسخ را اجبار کنید. این در حالتی کاربرد دارد که کامپایلر از هر دو روش نقل‌قول POSIX و
Windows پشتیبانی نماید. مقادیر ممکن عبارتند از:
.sp
\fBauto\fP
.RS 4
یکی از قالب‌های زیر را بر اساس نوع کامپایلر حدس می‌زند. این مقدار پیش‌فرض است.
.RE
.sp
\fBposix\fP
.RS 4
رفتار نقل‌قول POSIX.
.RE
.sp
\fBwindows\fP
.RS 4
رفتار نقل‌قول Windows.
.RE
.RE
.sp
\fBsafe_dirs\fP (\fBCCACHE_SAFE_DIRS\fP)
.RS 4
فهرستی از دایرکتوری‌های مورد اعتماد که فایل‌های پیکربندی ویژهٔ دایرکتوری در آن‌ها مجاز
به تعیین «گزینه‌های ناامن» هستند (بخش Directory\-specific configuration file را ببینید).
پیش‌فرض خالی است.
.sp
مقادیر مجاز فهرست: \f(CR*\fP با هر دایرکتوری مطابقت دارد. یک مسیر مطلق که با \f(CR/*\fP
خاتمه یابد با تمام زیردایرکتوری‌های (در هر عمقی) زیر آن مسیر منطبق است. یک مسیر مطلق که
به \f(CR/*\fP ختم نشود تنها با همان دایرکتوری مطابقت دارد.
.RE
.sp
\fBsloppiness\fP (\fBCCACHE_SLOPPINESS\fP)
.RS 4
به‌طور پیش‌فرض، ccache تلاش می‌کند تا حد ممکن کمترین اصابت‌های نادرست در کَش (false cache hits)
رخ دهد. با این حال، در برخی شرایط ممکن است شما از مواردی مطلع باشید که ccache نمی‌تواند
آن‌ها را بدیهی فرض کند. این گزینه امکان می‌دهد تا به ccache اعلام کنید برخی از بررسی‌ها را
آسان‌تر بگیرد تا نرخ اصابت افزایش یابد. مقادیر در دسترس (جداشده با فاصله یا ویرگول):
.sp
\fBclang_index_store\fP
.RS 4
\fBمورد کاربرد\fP: پروژه‌های Xcode با مسیرهای متغیر index store.
.br
\fBاثر\fP: گزینه‌های \f(CR\-index\-store\-path\fP و \f(CR\-index\-unit\-output\-path\fP
را هنگام هش کردن نادیده می‌گیرد.
.br
\fBبده‌بستان\fP: نمایه (Index) در صورت اصابت کَش به درستی به‌روزرسانی نخواهد شد.
.RE
.sp
\fBfile_stat_matches\fP
.RS 4
\fBمورد کاربرد\fP: هنگامی که بررسی محتوای فایل بیش از حد کُند است.
.br
\fBاثر\fP: از برچسب‌های زمانی فایل به جای محتوا برای اعتبارسنجی کَش استفاده می‌کند.
.br
\fBبده‌بستان\fP: ممکن است تغییرات محتوا با برچسب‌های زمانی یکسان نادیده گرفته شوند.
.RE
.sp
\fBfile_stat_matches_ctime\fP
.RS 4
\fBمورد کاربرد\fP: هنگامی که برچسب‌های زمانی فایل به صورت دستی کنترل می‌شوند.
.br
\fBاثر\fP: در صورت فعال بودن \f(CRfile_stat_matches\fP، زمان تغییر وضعیت (ctime) را
نادیده می‌گیرد.
.br
\fBبده‌بستان\fP: ممکن است برخی از تغییرات سیستم فایل از دست بروند.
.RE
.sp
\fBgcno_cwd\fP
.RS 4
\fBمورد کاربرد\fP: ساخت‌های پوشش کد (code coverage) در دایرکتوری‌های مختلف.
.br
\fBاثر\fP: دایرکتوری فعلی را هنگام ایجاد فایل‌های \f(CR.gcno\fP نادیده می‌گیرد
(\f(CR\-ftest\-coverage\fP). همچنین در صورت استفاده از \f(CR\-fprofile\-abs\-path\fP،
هش کردن دایرکتوری کاری فعلی را غیرفعال می‌سازد.
.br
\fBبده‌بستان\fP: اطلاعات دایرکتوری در فایل‌های پوشش کد ممکن است نادرست باشد.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B نکته
.ps -1
.br
.sp
روی \f(CR\-\-coverage\fP بی‌تأثیر است (زیرا متضمن \f(CR\-fprofile\-arcs\fP است).
.sp .5v
.RE
.RE
.sp
\fBincbin\fP
.RS 4
\fBمورد کاربرد\fP: پروژه‌هایی که از دستورات اسمبلی \f(CR.incbin\fP استفاده می‌کنند.
.br
\fBاثر\fP: امکان کَش کردن فایل‌های حاوی دستورات \f(CR.incbin\fP را فراهم می‌کند.
.br
\fBبده‌بستان\fP: تغییرات در فایل‌های باینری ضمیمه‌شده شناسایی نخواهد شد.
.RE
.sp
\fBinclude_file_ctime\fP
.RS 4
\fBمورد کاربرد\fP: سیستم‌های ساختی که برچسب‌های زمانی فایل را به طور مکرر تغییر می‌دهند.
.br
\fBاثر\fP: هنگام بررسی تغییرات اخیر، زمان تغییر وضعیت فایل را نادیده می‌گیرد.
.br
\fBبده‌بستان\fP: ممکن است تغییرات اخیر در فایل‌های سورس نادیده گرفته شوند.
.RE
.sp
\fBinclude_file_mtime\fP
.RS 4
\fBمورد کاربرد\fP: سیستم‌های ساختی که برچسب‌های زمانی فایل را به طور مداوم تغییر می‌دهند.
.br
\fBاثر\fP: هنگام بررسی تغییرات اخیر، زمان ویرایش فایل را نادیده می‌گیرد.
.br
\fBبده‌بستان\fP: ممکن است ویرایش‌های اخیر در فایل‌های سورس نادیده گرفته شوند.
.RE
.sp
\fBivfsoverlay\fP
.RS 4
\fBمورد کاربرد\fP: پروژه‌های Xcode که کدهای Objective\-C و Swift را ترکیب می‌کنند.
.br
\fBاثر\fP: گزینهٔ سیستم فایل مجازی \f(CR\-ivfsoverlay\fP را نادیده می‌گیرد.
.br
\fBبده‌بستان\fP: ممکن است تغییرات مربوط به VFS شناسایی نشوند.
.RE
.sp
\fBlocale\fP
.RS 4
\fBمورد کاربرد\fP: ساخت در محیط‌هایی با تنظیمات متغیر محلی‌سازی (locale).
.br
\fBاثر\fP: متغیرهای محیطی locale را نادیده می‌گیرد (\f(CRLANG\fP، \f(CRLC_ALL\fP،
\f(CRLC_CTYPE\fP، \f(CRLC_MESSAGES\fP).
.br
\fBبده‌بستان\fP: پیام‌های هشدار کامپایلر ممکن است بین ساخت‌های کَش‌شده و تازه تفاوت داشته باشند.
.RE
.sp
\fBmodules\fP
.RS 4
\fBمورد کاربرد\fP: ساخت‌های Clang با استفاده از \f(CR\-fmodules\fP.
.br
\fBاثر\fP: هنگام استفاده از ماژول‌های C++ امکان کَش کردن را فراهم می‌آورد.
.br
\fBبده‌بستان\fP: ممکن است تغییرات در وضعیت درونی ماژول تشخیص داده نشود.
.sp
برای جزئیات بیشتر بخش \fIC++ MODULES\fP را ببینید.
.RE
.sp
\fBpch_defines\fP
.RS 4
\fBمورد کاربرد\fP: پروژه‌های دارای سرایندهای از پیش‌کامپایل‌شده.
.br
\fBاثر\fP: بررسی دستورات \f(CR#define\fP در سرایندهای از پیش‌کامپایل‌شده را آسان‌تر می‌گیرد.
.br
\fBبده‌بستان\fP: ممکن است برخی از تغییرات در تعاریف ماکرو شناسایی نشوند.
.sp
برای جزئیات بیشتر بخش \fIPRECOMPILED HEADERS\fP را ببینید.
.RE
.sp
\fBrandom_seed\fP
.RS 4
\fBمورد کاربرد\fP: ساخت‌هایی با مقادیر متغیر \f(CR\-frandom\-seed\fP.
.br
\fBاثر\fP: مقادیر تصادفی seed را در هش کامپایل نادیده می‌گیرد.
.br
\fBبده‌بستان\fP: ساخت‌ها ممکن است کاملاً بازتولیدپذیر نباشند.
.RE
.sp
\fBsystem_headers\fP
.RS 4
\fBمورد کاربرد\fP: سیستم‌هایی با سرایندهای سیستمی که به طور مکرر تغییر می‌کنند.
.br
\fBاثر\fP: در حالت مستقیم تنها سرایندهای غیر سیستمی را ردیابی می‌کند.
.br
\fBبده‌بستان\fP: تغییرات سرایندهای سیستمی را که بر کامپایل اثر می‌گذارند تشخیص نمی‌دهد.
.br
\fBمحدودیت‌ها\fP: تنها برای کامپایلرهای مشابه GCC پشتیبانی می‌شود (نه MSVC). سرایندهای
سیستمی همچنان در حالت پیش‌پردازنده بررسی می‌شوند.
.sp
همچنین گزینهٔ \fBignore_headers_in_manifest\fP را ببینید.
.RE
.sp
\fBtime_macros\fP
.RS 4
\fBمورد کاربرد\fP: کدهایی که از ماکروهای زمان استفاده می‌کنند اما مقادیر آن‌ها اهمیتی ندارد.
.br
\fBاثر\fP: ماکروهای \f(CR__DATE__\fP، \f(CR__TIME__\fP و \f(CR__TIMESTAMP__\fP
را در سورس کد نادیده می‌گیرد.
.br
\fBبده‌بستان\fP: مقادیر زمانی در خروجی متعلق به کامپایل کَش‌شده خواهند بود.
.RE
.RE
.sp
\fBstats\fP (\fBCCACHE_STATS\fP یا \fBCCACHE_NOSTATS\fP، بخش \fIBoolean values\fP در بالا را ببینید)
.RS 4
اگر true باشد، ccache در هر کامپایل شمارنده‌های آمار را به‌روزرسانی می‌کند. پیش‌فرض
true است. اگر false باشد، \fIپاک‌سازی خودکار\fP نیز غیرفعال خواهد شد.
.RE
.sp
\fBstats_log\fP (\fBCCACHE_STATSLOG\fP)
.RS 4
اگر روی یک مسیر فایل تنظیم شود، ccache به‌روزرسانی‌های شمارندهٔ آمار را در فایل
مشخص‌شده ثبت می‌کند. این امر برای به دست آوردن آمار برای ساخت‌های مجزا کاربرد دارد.
برای مشاهدهٔ خلاصه‌ای از گزارش آمار فعلی، از دستور \f(CRccache \-\-show\-log\-stats\fP
استفاده کنید.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B نکته
.ps -1
.br
.sp
سطرهایی در گزارش آمار که با علامت هش (\f(CR#\fP) آغاز می‌شوند، کامنت هستند.
.sp .5v
.RE
.RE
.sp
\fBtemporary_dir\fP (\fBCCACHE_TEMPDIR\fP)
.RS 4
این گزینه مشخص می‌کند که ccache فایل‌های موقت را در کجا قرار دهد. پیش‌فرض
\f(CR$XDG_RUNTIME_DIR/ccache\-tmp\fP (معمولاً \f(CR/run/user/<UID>/ccache\-tmp\fP)
است در صورتی که \f(CRXDG_RUNTIME_DIR\fP تنظیم شده و دایرکتوری موجود باشد؛ در غیر این صورت
\f(CR<cache_dir>/tmp\fP خواهد بود.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B نکته
.ps -1
.br
.sp
در نسخه‌های پیشین ccache، مقدار \fBCCACHE_TEMPDIR\fP باید روی همان سیستم فایلِ مسیر
\f(CRCCACHE_DIR\fP قرار می‌داشت، اما این محدودیت برطرف شده است.
.sp .5v
.RE
.RE
.sp
\fBumask\fP (\fBCCACHE_UMASK\fP)
.RS 4
این گزینه (یک عدد صحیح در مبنای هشت) مقدار umask را برای فایل‌ها و دایرکتوری‌های درون
دایرکتوری کَش مشخص می‌کند. این گزینه عمدتاً زمانی مفید است که بخواهید کَش خود را با سایر
کاربران به اشتراک بگذارید.
.RE.SS "غیرفعال‌سازی ccache (Disabling ccache)"
.sp
برای غیرفعال‌کردن کامل ccache برای همهٔ فراخوانی‌ها،
\fBdisable = true\fP (\f(CRCCACHE_DISABLE=1\fP) را تنظیم کنید. همچنین می‌توانید با
افزودن رشتهٔ \f(CRccache:disable\fP در یک توضیح (کامنت) در ۴۰۹۶ بایت نخست فایل،
ccache را برای یک فایل کد منبع خاص غیرفعال کنید. در حالت اخیر، شمارندهٔ آماری
\f(CRCcache disabled\fP افزایش خواهد یافت.
.SH "پشت‌بانه‌های ذخیره‌سازی دوردست (REMOTE STORAGE BACKENDS)"
.sp
گزینهٔ \fBremote_storage\fP به شما امکان می‌دهد ccache را برای استفاده از یک یا چند
پشت‌بانهٔ ذخیره‌سازی دوردست پیکربندی کنید. به‌طور پیش‌فرض، دایرکتوری محلی حافظهٔ پنهان واقع در
\fBcache_dir\fP در ابتدا و ذخیره‌سازی دوردست در اولویت بعدی پرس‌وجو می‌شوند،
اما می‌توان \fBremote_only\fP را روی true تنظیم کرد تا ذخیره‌سازی محلی
غیرفعال شود. توجه داشته باشید که شمارنده‌های آماری حافظهٔ پنهان همچنان در دایرکتوری محلی حافظهٔ پنهان نگه‌داری
خواهند شد \(em پشت‌بانه‌های ذخیره‌سازی دوردست تنها نتایج کامپایل و مانیفست‌ها را ذخیره می‌کنند.
.SS "فرایند کمکی ذخیره‌سازی (Storage helper process)"
.sp
ccache می‌تواند یک فرایند محلی کمکی ذخیره‌سازیِ طولانی‌زیست (که جداگانه نصب می‌شود)
برای مدیریت ارتباط با ذخیره‌سازی دوردست ایجاد کند. کمکی‌های ذخیره‌سازی برای بهره‌وری اتصالات دوردست را
باز نگه می‌دارند و پس از مدتی عدم فعالیت خاتمه می‌یابند. برای فهرستی از
کمکی‌های شناخته‌شده، \c
.URL "https://ccache.dev/storage\-helpers.html" "Storage helpers" ""
را ببینید.
.sp
برنامهٔ کمکی ذخیره‌سازی \f(CRccache\-storage\-<scheme>\fP نام دارد، که در آن \f(CR<scheme>\fP
بخش طرح‌وارهٔ یک URL است، مانند \f(CRhttps\fP. این برنامه می‌تواند در این مکان‌ها قرار گیرد
(به ترتیب اولویت):
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 1." 4.2
.\}
در مکانی که با ویژگی \fBhelper\fP مشخص شده است (پایین را ببینید).
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 2." 4.2
.\}
در یک دایرکتوری libexec.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 3." 4.2
.\}
در کنار فایل اجرایی ccache.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 4." 4.2
.\}
در \f(CR$PATH\fP.
.RE
.sp
اگر برنامه پیدا نشود، ccache در صورت دردسترس بودن به یکی از پشت‌بانه‌های توکار (builtin)
بازمی‌گردد؛ در غیر این صورت ccache با یک خطا خارج می‌شود.
.SS "ساختار پیکربندی (Configuration syntax)"
.sp
یک پشت‌بانهٔ ذخیره‌سازی دوردست با یک URL مشخص می‌شود و می‌تواند به دنبال آن فهرستی از ویژگی‌ها
(\f(CR\fIkey\fP=\fIvalue\fP\fP) و صفت‌های سفارشی (\f(CR@\fIkey\fP=\fIvalue\fP\fP) که با نویسه‌های فاصله‌ساز (whitespace)
از هم جدا شده‌اند قرار گیرد. نبود \f(CR=\fIvalue\fP\fP کوتاه‌نوشتی برای تنظیم مقدار روی
\fBtrue\fP است. در صورتی که مقادیر شامل نویسه‌های \f(CR%\fP، \f(CR|\fP یا نویسه‌های فاصله‌ساز باشند،
باید به‌صورت
.URL "https://en.wikipedia.org/wiki/Percent\-encoding" "percent\-encoded" ""
باشند. برای سازگاری با نسخه‌های قدیمی‌تر ccache، با نویسه‌های \f(CR|\fP مانند فاصله رفتار می‌شود.
.SS "ویژگی‌ها (Properties)"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBdata\-timeout\fP: مهلت زمانی انتقال داده برای ارسال/دریافت. هر زمان که داده‌ای
دریافت شود یا امکان ارسال داشته باشد، بازنشانی می‌شود. پیش‌فرض: 10s.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBhelper\fP: بازتعریف این‌که کدام کمکی ذخیره‌سازی اجرا شود (یک نام فایل یا یک مسیر کامل).
این گزینه عمدتاً هنگام توسعه یا آزمایش کمکی‌های جدید کاربرد دارد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBidle\-timeout\fP: مهلت زمانی انتظار فرایند کمکی پیش از خروج پس از
عدم فعالیت کلاینت (0s: برای همیشه فعال بماند). پیش‌فرض: 10m.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBread\-only\fP: در صورت \fBtrue\fP بودن، تنها از این پشت‌بانه می‌خواند و در آن نمی‌نویسد. پیش‌فرض
\fBfalse\fP است.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBrequest\-timeout\fP: مهلت زمانی برای کل درخواست. پیش‌فرض: 1m.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBshards\fP: فهرستی از نام‌ها که با کاما از هم جدا شده‌اند برای قطعه‌بندی (sharding / افراز)
مدخل‌های حافظهٔ پنهان با استفاده از
.URL "https://en.wikipedia.org/wiki/Rendezvous_hashing" "Rendezvous hashing" "،"
که معمولاً برای توزیع حافظهٔ پنهان بر روی یک خوشه از سرورها به کار می‌رود. در صورت تنظیم، URL ذخیره‌سازی
باید شامل یک ستاره (\f(CR*\fP) باشد، که با یکی از نام‌های shard برای ساخت یک URL واقعی
جایگزین خواهد شد. یک نام shard می‌تواند به‌صورت اختیاری یک وزن الحاق‌شده داخل پرانتز داشته باشد تا مشخص کند
چه مقدار از فضای کلید باید به آن shard اختصاص یابد. یک shard با وزن \fBw\fP شامل \fBw\fP/\fBS\fP از حافظهٔ پنهان
خواهد بود، که در آن \fBS\fP مجموع وزن‌های همهٔ shardها است. برای نمونه می‌توان یک وزن را طوری تنظیم کرد
که نشان‌دهندهٔ حافظهٔ دردسترس برای یک حافظهٔ پنهان در حافظه روی یک سرور خاص باشد.
وزن پیش‌فرض \fB1\fP است.
.sp
مثال‌ها:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRhttp://cache\-*.example.com shards=a(3),b(1),c(1.5)\fP مقدار ۵۵٪ (۳/۵٫۵)
از حافظهٔ پنهان را روی \f(CRhttp://cache\-a.example.com\fP، مقدار ۱۸٪ (۱/۵٫۵) را روی
\f(CRhttp://cache\-b.example.com\fP و مقدار ۲۷٪ (۱٫۵/۵٫۵) را روی
\f(CRhttp://cache\-c.example.com\fP قرار خواهد داد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRhttp://example.com/* shards=alpha,beta\fP مقدار ۵۰٪ از حافظهٔ پنهان را روی
\f(CRhttp://example.com/alpha\fP و ۵۰٪ را روی \f(CRhttp://example.com/beta\fP قرار خواهد داد.
.RE
.RE
.sp
مهلت‌های زمانی را می‌توان با پسوند ms (میلی‌ثانیه)، s (ثانیه)، m (دقیقه)، h
(ساعت) یا d (روز) مشخص کرد..SS "ویژگی‌های سفارشی (Custom attributes)"
.sp
ویژگی‌های سفارشی در قالب \f(CR\fI@key\fP=\fIvalue\fP\fP مختص پیاده‌سازی هر storage
helper هستند. برای آگاهی از ویژگی‌های دردسترس به مستندات backend مراجعه کنید. مثال‌ها:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRfile:///example/directory @umask=002 @update\-mtime=true\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRhttps://example.com/path @bearer\-token=deadbeef\fP
.RE
.SS "تعامل فضای ذخیره‌سازی (Storage interaction)"
.sp
جدول زیر تعامل میان فضای ذخیره‌سازی محلی و دوردست را هنگام یافت‌شدن (hit) و
یافت‌نشدن (miss) در حافظهٔ نهان در صورتی که \fBremote_only\fP برابر false
باشد (که پیش‌فرض است) شرح می‌دهد:
.TS
allbox tab(:);
ltB ltB ltB.
T{
.sp
\fBفضای ذخیره‌سازی محلی\fP
T}:T{
.sp
\fBفضای ذخیره‌سازی دوردست\fP
T}:T{
.sp
\fBآنچه رخ می‌دهد\fP
T}
.T&
lt lt lt.
T{
.sp
یافت‌نشدن (miss)
T}:T{
.sp
یافت‌نشدن (miss)
T}:T{
.sp
کامپایل، نوشتن در محلی، نوشتن در دوردست[1]
T}
T{
.sp
یافت‌نشدن (miss)
T}:T{
.sp
یافت‌شدن (hit)
T}:T{
.sp
خواندن از دوردست، نوشتن در محلی
T}
T{
.sp
یافت‌شدن (hit)
T}:T{
.sp
\-
T}:T{
.sp
خواندن از محلی، بدون نوشتن در دوردست[2]
T}
.TE
.sp
.sp
[1] مگر این‌که فضای ذخیره‌سازی دوردست دارای ویژگی \f(CRread\-only=true\fP باشد.
.br
[2] مگر این‌که فضای ذخیره‌سازی محلی طوری تنظیم شده باشد که موارد یافت‌شده در حافظهٔ نهان را با
گزینهٔ \fBreshare\fP به اشتراک بگذارد.
.sp
اگر \fBremote_only\fP برابر true باشد:
.TS
allbox tab(:);
ltB ltB ltB.
T{
.sp
\fBفضای ذخیره‌سازی محلی\fP
T}:T{
.sp
\fBفضای ذخیره‌سازی دوردست\fP
T}:T{
.sp
\fBآنچه رخ می‌دهد\fP
T}
.T&
lt lt lt.
T{
.sp
\-
T}:T{
.sp
یافت‌نشدن (miss)
T}:T{
.sp
کامپایل، نوشتن در دوردست، بدون نوشتن در محلی
T}
T{
.sp
\-
T}:T{
.sp
یافت‌شدن (hit)
T}:T{
.sp
خواندن از دوردست، بدون نوشتن در محلی
T}
.TE
.sp.SS "پشت‌بند ذخیره‌سازی فایل (File storage backend)"
.sp
قالب URL: \f(CRfile:DIRECTORY\fP یا \f(CRfile://[HOST]DIRECTORY\fP
.sp
این پشت‌بند داده‌ها را به صورت فایل‌های مجزا در یک ساختار دایرکتوری زیر
\fBDIRECTORY\fP ذخیره می‌کند، مشابه (اما نه یکسان) با ذخیره‌سازی کَش محلی. یک کاربرد رایج
برای این پشت‌بند، اشتراک‌گذاری کَش در یک دایرکتوری NFS است.
\fBDIRECTORY\fP باید با یک اسلش آغاز شود. \fBHOST\fP می‌تواند رشته‌ای خالی یا
localhost باشد. در Windows، همچنین \fBHOST\fP می‌تواند نام سروری باشد که یک پوشهٔ
اشتراکی را میزبانی می‌کند.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B مهم
.ps -1
.br
.sp
ccache هیچ‌گونه پاک‌سازی در فضای ذخیره‌سازی انجام نخواهد داد \(em این کار باید
از روش‌های دیگر انجام شود، به عنوان مثال با اجرای دوره‌ای \f(CRccache \-\-trim\-dir\fP.
.sp .5v
.RE
.sp
مثال‌ها:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRfile:/shared/nfs/directory\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRfile:///shared/nfs/directory @umask=002 @update\-mtime=true\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRfile:///Z:/example/windows/folder\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRfile://example.com/shared/ccache%20folder\fP
.RE
.sp
ویژگی‌های اختیاری:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB@layout\fP: نحوهٔ ذخیره فایل‌ها در دایرکتوری کَش. مقادیر موجود:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBflat\fP: ذخیرهٔ همهٔ فایل‌ها مستقیماً زیر دایرکتوری کَش.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBlocal\fP: خواندن فایل‌ها با استفاده از چیدمان دایرکتوری پویای کَش محلی.
این چیدمان برای یک رونوشت یک‌طرفه یا سوار کردن (mount) فقط‌خواندنی یک دایرکتوری
کَش محلی در نظر گرفته شده است و پشت‌بند ذخیره‌سازی فایل را فقط‌خواندنی می‌کند. این دایرکتوری
باید شامل ورودی‌های خودکفا باشد (\fBfile_clone\fP یا
\fBhard_link\fP پشتیبانی نمی‌شوند).
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBsubdirs\fP: ذخیرهٔ فایل‌ها در 256 زیردایرکتوری از دایرکتوری کَش.
.RE
.sp
پیش‌فرض \fBsubdirs\fP است.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB@umask\fP: این ویژگی (یک عدد صحیح در مبنای هشت) مقدار umask مورد استفاده برای
فایل‌ها و دایرکتوری‌ها را در دایرکتوری کَش بازنویسی می‌کند.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB@update\-mtime\fP: اگر \fBtrue\fP باشد، زمان ویرایش (mtime) ورودی‌های کَش
خوانده‌شده را به‌روزرسانی می‌کند. مقدار پیش‌فرض \fBfalse\fP است.
.RE.SS "بک‌اند ذخیره‌سازی CRSH"
.sp
قالب URL: \f(CRcrsh:IPC_ENDPOINT\fP
.sp
این بک‌اند به یک فرایند دستیار ذخیره‌سازی ccache‏ (CRSH) که در حال حاضر در حال اجرا است و روی \f(CRIPC_ENDPOINT\fP (مسیر سوکت یونیکس یا پایپ نام‌گذاری‌شدهٔ ویندوز) گوش می‌دهد، متصل می‌شود. کاربرد این بخش عمدتاً هنگام توسعه یا اشکال‌زدایی یک دستیار ذخیره‌سازی، یا در برپاسازی‌های خاصی است که برنامهٔ دستیار به صورت خارجی اجرا و مدیریت می‌شود.
.sp
مثال‌ها:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRcrsh:/path/to/your.sock\fP (سوکت یونیکس)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRcrsh:name\-of\-your\-pipe\fP (پایپ نام‌گذاری‌شدهٔ ویندوز)
.RE
.SS "بک‌اند ذخیره‌سازی HTTP"
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B هشدار
.ps -1
.br
.sp
پشتیبانی توکار از پروتکل HTTP منسوخ شده است و در نسخهٔ بعدی ccache (که صرفاً رفع باگ نباشد) حذف خواهد شد. به جای آن از یک دستیار ذخیره‌سازی راه دور استفاده کنید.
.sp .5v
.RE
.sp
قالب URL: \f(CRhttp://HOST[:PORT][/PATH]\fP
.sp
این بک‌اند داده‌ها را در یک سرور سازگار با HTTP ذخیره می‌کند. متدهای HTTP مورد نیاز شامل \f(CRGET\fP، \f(CRPUT\fP و \f(CRDELETE\fP هستند.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B مهم
.ps -1
.br
.sp
برنامه ccache هیچ‌گونه پاک‌سازی‌ای روی فضای ذخیره‌سازی انجام نخواهد داد \(em این کار باید به روش‌های دیگر انجام شود، به عنوان مثال با اجرای دوره‌ای \f(CRccache \-\-trim\-dir\fP.
.sp .5v
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B نکته
.ps -1
.br
.sp
پروتکل HTTPS پشتیبانی نمی‌شود.
.sp .5v
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B توصیه
.ps -1
.br
.sp
برای نکاتی پیرامون نحوهٔ راه‌اندازی سرور HTTP جهت استفاده با ccache، \c
.URL "https://ccache.dev/howto/http\-storage.html" "راهنمای راه‌اندازی ذخیره‌سازی HTTP"
را ببینید.
.sp .5v
.RE
.sp
مثال‌ها:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRhttp://localhost\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRhttp://someusername:p4ssw0rd@example.com/cache/\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRhttp://localhost:8080 @layout=bazel\fP
.RE
.sp
ویژگی‌های اختیاری:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB@bearer\-token\fP: توکن حامل (Bearer token) مورد استفاده برای احراز هویت درخواست‌های HTTP.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB@keep\-alive\fP: اگر برابر با \fBtrue\fP باشد، اتصال HTTP به سرور ذخیره‌سازی را باز نگه می‌دارد تا از اتصال‌های مجدد جلوگیری شود. مقدار پیش‌فرض \fBtrue\fP است.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB@layout\fP: نحوهٔ نگاشت نام‌های کلید به بخش مسیر URL. مقادیر موجود:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBbazel\fP: ذخیره مقادیر در قالبی سازگار با پروتکل حافظهٔ نهان HTTP برنامه Bazel. به طور دقیق‌تر، مدخل‌ها به صورت ۶۴ رقم هگزادسیمال در زیر بخش \f(CR/ac/\fP حافظهٔ نهان ذخیره می‌شوند.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B نکته
.ps -1
.br
.sp
برای این که این قابلیت کار کند ممکن است لازم باشد اعتبارسنجی مقادیر action cache را در سرور غیرفعال کنید، زیرا مدخل‌های ccache مقادیر معتبر فرادادهٔ نتیجهٔ کنش (action result) نیستند.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBflat\fP: الحاق مستقیم کلید به بخش مسیر URL (در صورت نیاز با یک اسلش در ابتدا).
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBsubdirs\fP: الحاق دو نویسهٔ نخست کلید به URL (در صورت نیاز با یک اسلش در ابتدا)، و به دنبال آن یک اسلش و باقی‌ماندهٔ کلید. این کار مدخل‌ها را به ۲۵۶ دسته تقسیم می‌کند.
.RE
.sp
مقدار پیش‌فرض \fBsubdirs\fP است.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB@header\fP: افزودن جفت key=value به هدرهای HTTP درخواست. به عنوان مثال: \f(CR@header=Content\-Type=application/octet\-stream\fP مقدار "Content\-Type: application/octet\-stream" را به سرآیندهای HTTP درخواست اضافه می‌کند.
.RE.SS "پشت‌بند ذخیره‌سازی Redis"
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B هشدار
.ps -1
.br
.sp
پشتیبانی داخلی از پروتکل Redis منسوخ شده است و در نسخهٔ بعدی غیر رفع‌باگ (non\-bug\-fix) ccache حذف خواهد شد. در عوض از یک دستیار ذخیره‌سازی دوردست (remote storage helper) استفاده کنید.
.sp .5v
.RE
.sp
قالب‌های URL:
.sp
\f(CRredis://[[USERNAME:]PASSWORD@]HOST[:PORT][/DBNUMBER]\fP
.br
\f(CRredis+unix:SOCKET_PATH[?db=DBNUMBER]\fP
.br
\f(CRredis+unix://[[USERNAME:]PASSWORD@localhost]SOCKET_PATH[?db=DBNUMBER]\fP
.sp
این پشت‌بند داده‌ها را در یک کارساز \c
.URL "https://redis.io" "Redis" ""
(یا سازگار با Redis)
ذخیره می‌کند. پیاده‌سازی‌هایی هم برای ذخیره‌سازی مبتنی بر حافظه و هم مبتنی بر دیسک وجود دارد.
مقدار پیش‌فرض \fBPORT\fP برابر \fB6379\fP و مقدار پیش‌فرض \fBDBNUMBER\fP برابر \fB0\fP است.
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B نکته
.ps -1
.br
.sp
برنامهٔ ccache هیچ‌گونه پاک‌سازی در فضای ذخیره‌سازی Redis انجام نخواهد داد، اما می‌توانید
.URL "https://redis.io/topics/lru\-cache" "تخلیهٔ حافظه بر اساس LRU را پیکربندی کنید" "."
.sp .5v
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B راهنمایی
.ps -1
.br
.sp
برای نکاتی دربارهٔ برپاسازی کارساز Redis جهت استفاده به همراه ccache، به \c
.URL "https://ccache.dev/howto/redis\-storage.html" "نحوهٔ برپاسازی ذخیره‌سازی Redis" " "
مراجعه کنید.
.sp .5v
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B راهنمایی
.ps -1
.br
.sp
می‌توانید با استفاده از ویژگی \f(CRshards\fP که در بخش \fIREMOTE STORAGE BACKENDS\fP شرح داده شده است، خوشه‌ای (کلاستری) از کارسازهای Redis را برپا کنید.
.sp .5v
.RE
.sp
مثال‌ها:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRredis://localhost\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRredis://p4ssw0rd@cache.example.com:6379/0\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRredis+unix:/run/redis.sock\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRredis+unix:///run/redis.sock\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CRredis+unix://p4ssw0rd@localhost/run/redis.sock?db=0\fP
.RE.SH "مدیریت حجم کَش (CACHE SIZE MANAGEMENT)"
.sp
به‌طور پیش‌فرض، ccache محدودیتی ۵ گیگابایتی (5 GB) برای مجموع اندازه فایل‌ها در کَش دارد و هیچ محدودیتی برای تعداد فایل‌ها در نظر نمی‌گیرد. شما می‌توانید با استفاده از گزینه‌های خط فرمان \f(CR\-M\fP/\f(CR\-\-max\-size\fP و \f(CR\-F\fP/\f(CR\-\-max\-files\fP محدودیت‌های متفاوتی را تنظیم کنید. برای مشاهده اندازه کَش و محدودیت‌های پیکربندی‌شده فعلی (علاوه بر آمارهای گوناگون دیگر) از گزینه \f(CR\-s\fP/\f(CR\-\-show\-stats\fP استفاده کنید.
.sp
پاک‌سازی می‌تواند به دو روش مختلف آغاز شود: خودکار و دستی.
.SS "پاک‌سازی خودکار (Automatic cleanup)"
.sp
پس از ذخیره یک نتیجه کامپایل جدید در کَش محلی، اگر مقدار \fBmax_size\fP یا \fBmax_files\fP فراتر رفته باشد، ccache یک پاک‌سازی خودکار را آغاز می‌کند. این پاک‌سازی، مدخل‌های کَش را بر اساس زمان تغییر (mtime) فایل‌های درون کَش و با ترتیبی تقریبی بر اساس LRU (کمتر اخیراً استفاده‌شده) حذف می‌کند. به همین دلیل، ccache زمان تغییر (mtime) فایل‌های کَش خوانده‌شده در هنگام اصابت به کَش (cache hit) را به‌روزرسانی می‌کند تا آن‌ها را به عنوان مواردی که اخیراً استفاده شده‌اند علامت‌گذاری کند.
.sp
به دلایل کارایی، هنگام آغاز پاک‌سازی خودکار تنها مدخل‌های موجود در زیرمجموعه‌ای از کَش بررسی می‌شوند؛ بنابراین قدیمی‌ترین مدخل‌ها لزوماً همیشه ابتدا حذف نمی‌شوند، اما رفتار کلی برنامه در طول زمان به الگوریتم LRU بسیار نزدیک است.
.SS "پاک‌سازی دستی (Manual cleanup)"
.sp
برای وادار کردن به پاک‌سازی کل کَش، دستور \f(CRccache \-\-cleanup\fP را اجرا کنید. این کار اطلاعات اندازه کَش را دوباره محاسبه کرده و تضمین می‌کند که اندازه کَش از \fBmax_size\fP و \fBmax_files\fP فراتر نرود.
.sp
توجه داشته باشید که همان‌طور که در بخش \fIپاک‌سازی خودکار\fP در بالا ذکر شد، هیچ تضمینی وجود ندارد که فقط قدیمی‌ترین مدخل‌ها بیرون انداخته شوند. برای پاک‌سازی و حذف بر اساس سن، از دستور \f(CRccache \-\-evict\-older\-than AGE\fP استفاده کنید.
.SH "فشرده‌سازی کَش (CACHE COMPRESSION)"
.sp
به‌طور پیش‌فرض، ccache تمام داده‌های کَش‌شده را با استفاده از الگوریتم
.URL "http://zstd.net" "Zstandard" ""
(zstd) در سطح فشرده‌سازی ۱ فشرده می‌کند. این الگوریتم به‌اندازه‌ای سریع است که فرایند فشرده‌سازی به‌ندرت بر کارایی تأثیر می‌گذارد. ممکن است تنها زمانی مایل به غیرفعال‌سازی فشرده‌سازی باشید که کَش شما روی یک فایل‌سیستم از پیش فشرده‌شده ذخیره شده باشد، جایی که فشرده‌سازی ccache تکراری و زائد خواهد بود.
.sp
برای جزئیات پیکربندی، \fBcompression\fP و \fBcompression_level\fP را ببینید.
.sp
برای نمایش اطلاعات فشرده‌سازی از \f(CRccache \-\-show\-compression\fP استفاده کنید. نمونه خروجی:
.sp
.if n .RS 4
.nf
.fam C
Total data:\&           14.8 GB (16.0 GB disk blocks)
Compressed data:\&      11.3 GB (30.6% of original size)
  Original size:\&      36.9 GB
  Compression ratio: 3.267 x\&  (69.4% space savings)
Incompressible data:\&   3.5 GB
.fam
.fi
.if n .RE
.sp
نکات:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBDisk blocks\fP: اندازه واقعی کَش با احتساب اندازه بلوک‌های فایل‌سیستم. این مقدار باید با "Cache size" در خروجی \f(CRccache \-\-show\-stats\fP مطابقت داشته باشد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBCompressed data\fP: فایل‌های نتایج و مانیفست ذخیره‌شده در کَش.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBIncompressible data\fP: فایل‌های ذخیره‌شده بدون فشرده‌سازی (به‌دلیل تنظیمات \fBfile_clone\fP یا \fBhard_link\fP) یا فایل‌های موروثی از نسخه‌های قدیمی‌تر ccache.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBCompression ratio\fP: تحت تأثیر \fBcompression_level\fP قرار دارد.
.RE
.sp
می‌توانید با استفاده از \f(CRccache \-\-recompress\fP داده‌های کَش‌شده را با سطوح فشرده‌سازی متفاوت مجدداً فشرده کنید. تنها فایل‌هایی که سطح فشرده‌سازی متفاوتی نسبت به مقدار هدف دارند مجدداً فشرده خواهند شد.
.SH "آمار کَش (CACHE STATISTICS)"
.sp
دستور \f(CRccache \-\-show\-stats\fP خلاصه‌ای از آمارها شامل اندازه کَش، پاک‌سازی‌ها (تعداد پاک‌سازی‌های انجام‌شده، چه به‌صورت ضمنی به دلیل رسیدن به حد نصاب اندازه کَش و چه به دلیل فراخوانی‌های صریح \f(CRccache \-c\fP)، نرخ اصابت (hit rate) کلی، نرخ اصابت برای حالت‌های مستقیم/پیش‌پردازش‌شده (direct/preprocessed)، و نرخ اصابت برای فضای ذخیره‌سازی محلی و از راه دور را نمایش می‌دهد.
.sp
شمارنده‌های آماری در طول فرایند ساخت توسط خود ccache استفاده نمی‌شوند. این بدان معناست که می‌توانید بدون تأثیر گذاشتن بر فرایند ساخت، هر زمان که بخواهید با استفاده از \f(CRccache \-\-zero\-stats\fP آن‌ها را بازنشانی کنید. به عنوان مثال، می‌توانید پیش از یک ساخت آن‌ها را بازنشانی کنید تا \f(CRccache \-\-show\-stats\fP تنها نتایج حاصل از همان ساخت خاص را خلاصه کند. همچنین می‌توانید پیش از شروع ساخت، \fBstats_log\fP را تنظیم کرده و سپس \f(CRccache \-\-show\-log\-stats\fP را اجرا کنید تا آمارهای مربوط به آن ساخت خاص را مشاهده نمایید. این روش به شمارنده‌های آماری اجازه می‌دهد تا به ردیابی کل طول عمر کَش ادامه دهند و همزمان اطلاعات تفصیلی مربوط به هر ساخت را نیز در اختیارتان بگذارند. یکی دیگر از مزایای \fBstats_log\fP این است که آمارها را بدون تداخل ناشی از سایر ساخت‌های همزمانی که به همان کَش دسترسی دارند جمع‌آوری می‌کند.
.sp
این خلاصه همچنین شامل شمارنده‌هایی با عنوان \(lqErrors\(rq و \(lqUncacheable\(rq است که حاصل‌جمع شمارنده‌های جزئی‌تر هستند. برای مشاهده آن شمارنده‌های تفصیلی، از پرچم \f(CR\-v\fP/\f(CR\-\-verbose\fP استفاده کنید. حالت پرگو (verbose) می‌تواند شمارنده‌های زیر را نشان دهد:
.TS
allbox tab(:);
ltB ltB.
T{
.sp
\fBشمارنده (Counter)\fP
T}:T{
.sp
\fBتوضیحات (Description)\fP
T}
.T&
lt lt.
T{
.sp
Autoconf compile/link
T}:T{
.sp
کامپایل یا پیوند غیرقابل کَش‌شدن توسط یک آزمون Autoconf.
T}
T{
.sp
Bad compiler arguments
T}:T{
.sp
آرگومان نامعتبر یا بدقواره کامپایلر، مانند نبود مقدار برای گزینه‌ای از کامپایلر که به آرگومان نیاز دارد، یا ناتوانی در خواندن فایلی که توسط آرگومان گزینه کامپایلر مشخص شده است.
T}
T{
.sp
Called for linking
T}:T{
.sp
کامپایلر برای پیوند دادن (linking) فراخوانی شده بود، نه کامپایل. ابزار ccache تنها از کامپایل یک تک‌فایل پشتیبانی می‌کند؛ یعنی فراخوانی کامپایلر با گزینه \f(CR\-c\fP برای تولید یک فایل شیء (object file) از یک فایل منبع واحد.
T}
T{
.sp
Called for preprocessing
T}:T{
.sp
کامپایلر برای پیش‌پردازش فراخوانی شده بود، نه کامپایل.
T}
T{
.sp
Ccache disabled
T}:T{
.sp
ابزار ccache توسط رشته \f(CRccache:disable\fP در فایل کد منبع غیرفعال شده بود.
T}
T{
.sp
Could not use modules
T}:T{
.sp
پیش‌شرط‌های استفاده از ماژول‌های ++C برآورده نشدند.
T}
T{
.sp
Could not use precompiled header
T}:T{
.sp
پیش‌شرط‌های استفاده از سرآیندهای پیش‌کامپایل‌شده برآورده نشدند.
T}
T{
.sp
Could not read or parse input file
T}:T{
.sp
یک فایل ورودی قابل خواندن یا تجزیه نبود (برای جزئیات گزارش اشکال‌زدایی را ببینید).
T}
T{
.sp
Could not write to output file
T}:T{
.sp
امکان نوشتن در مسیر خروجی تعیین‌شده با \f(CR\-o\fP وجود نداشت.
T}
T{
.sp
Compilation failed
T}:T{
.sp
فرایند کامپایل با شکست مواجه شد. هیچ نتیجه‌ای در کَش ذخیره نشد.
T}
T{
.sp
Compiler check failed
T}:T{
.sp
برنامه بررسی کامپایلر که توسط \fBcompiler_check\fP (\fBCCACHE_COMPILERCHECK\fP) مشخص شده بود شکست خورد.
T}
T{
.sp
Compiler output file missing
T}:T{
.sp
یکی از فایل‌هایی که انتظار می‌رفت توسط کامپایلر تولید شود پس از کامپایل یافت نشد.
T}
T{
.sp
Compiler produced empty output
T}:T{
.sp
فایل خروجی کامپایلر (معمولاً یک فایل شیء) پس از کامپایل خالی بود.
T}
T{
.sp
Could not find the compiler
T}:T{
.sp
کامپایلری که باید اجرا شود پیدا نشد.
T}
T{
.sp
Error hashing extra file
T}:T{
.sp
شکست در خواندن فایلی که توسط \fBextra_files_to_hash\fP (\fBCCACHE_EXTRAFILES\fP) مشخص شده بود.
T}
T{
.sp
Forced recache
T}:T{
.sp
از \fBCCACHE_RECACHE\fP برای بازنویسی یک نتیجه موجود استفاده شد.
T}
T{
.sp
Input file modified during compilation
T}:T{
.sp
یک فایل ورودی در حین کامپایل تغییر یافت.
T}
T{
.sp
Internal error
T}:T{
.sp
خطای غیرمنتظره داخلی، مثلاً به دلیل بروز مشکل در خواندن/نوشتن کَش.
T}
T{
.sp
Missing cache file
T}:T{
.sp
یک فایل به‌طور غیرمنتظره‌ای در کَش وجود نداشت. این مورد تنها در موقعیت‌های نادری رخ می‌دهد، مثلاً هنگامی که یک نمونه از ccache در شرف دریافت فایلی از کَش است در حالی که نمونه دیگری آن فایل را در حین پاک‌سازی کَش حذف کرده است.
T}
T{
.sp
Multiple source files
T}:T{
.sp
کامپایلر برای کامپایل همزمان چند فایل منبع در یک نوبت فراخوانی شده بود. این کار توسط ccache پشتیبانی نمی‌شود.
T}
T{
.sp
No input file
T}:T{
.sp
هیچ فایل ورودی‌ای به کامپایلر مشخص نشده بود.
T}
T{
.sp
Output to stdout
T}:T{
.sp
به کامپایلر دستور داده شده بود که با استفاده از \f(CR\-o \-\fP خروجی خود را در خروجی استاندارد بنویسد. این کار توسط ccache پشتیبانی نمی‌شود.
T}
T{
.sp
Preprocessing failed
T}:T{
.sp
پیش‌پردازش کد منبع با استفاده از گزینه \f(CR\-E\fP کامپایلر با شکست مواجه شد.
T}
T{
.sp
Unsupported code directive
T}:T{
.sp
کدی مانند دستور اسمبلی \f(CR.incbin\fP یافت شد. این مورد توسط ccache پشتیبانی نمی‌شود.
T}
T{
.sp
Unsupported compiler option
T}:T{
.sp
یک گزینه کامپایلر که توسط ccache پشتیبانی نمی‌شود یافت شد.
T}
T{
.sp
Unsupported environment variable
T}:T{
.sp
یک متغیر محیطی که توسط ccache پشتیبانی نمی‌شود تنظیم شده بود.
T}
T{
.sp
Unsupported source encoding
T}:T{
.sp
فایل منبع (یا یک سرآیند واردشده) دارای کدبندی پشتیبانی‌نشده است. ccache در حال حاضر برای MSVC در صورتی که \f(CRmsvc_utf8\fP مقدار true داشته باشد، به کد منبع با کدبندی UTF\-8 نیاز دارد.
T}
T{
.sp
Unsupported source language
T}:T{
.sp
یک زبان منبع، مثلاً مشخص‌شده با \f(CR\-x\fP، توسط ccache پشتیبانی نمی‌شود.
T}
.TE
.sp.SH "نحوه کارکرد CCACHE (HOW CCACHE WORKS)"
.sp
ابزار ccache تشخیص می‌دهد چه زمانی کد مشابهی را کامپایل می‌کنید و از خروجی‌های از پیش ذخیره‌شده دوباره استفاده می‌کند. این کار با ایجاد یک هش یکتا (\(lqهش ورودی\(rq یا \(lqinput hash\(rq) از اطلاعات گوناگونی که بر کامپایل اثرگذارند انجام می‌شود. هنگامی که دوباره با همان هش مواجه شود، ccache می‌تواند تمام خروجی‌های درست کامپایلر را از حافظه موقت (cache) بازیابی و ارائه کند.
.sp
برای هش‌کردن، ccache از \c
.URL "https://blake3.io" "BLAKE3" ","
یک الگوریتم هش رمزنگارانه سریع، استفاده می‌کند. برای تضمین یکپارچگی داده‌ها، داده‌های کَش‌شده با مجموع مقابله‌ای
.URL "https://xxhash.com" "XXH3" ""
محافظت می‌شوند تا خرابی داده‌ها تشخیص داده شود.
.sp
ابزار ccache دو راهبرد برای جمع‌آوری اطلاعاتی که جهت ایجاد کلیدهای جستجوی کَش استفاده می‌شوند دارد:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBحالت پیش‌پردازنده (Preprocessor mode)\fP: ابزار ccache پیش‌پردازنده را روی کد منبع اجرا کرده و نتیجه را هش می‌کند.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBحالت مستقیم (Direct mode)\fP: ابزار ccache کد منبع و فایل‌های include را مستقیماً هش می‌کند.
.RE
.sp
حالت مستقیم عموماً سریع‌تر است زیرا از بار اضافی اجرای پیش‌پردازنده جلوگیری می‌کند.
.sp
هنگامی که حالت مستقیم نتیجه‌ای در کَش پیدا نکند (cache miss)، ccache به حالت پیش‌پردازنده بازمی‌گردد؛ مگر اینکه \fBdepend mode\fP فعال باشد. در depend mode، حتی در صورت عدم یافتن در کَش، ccache هرگز پیش‌پردازنده را اجرا نمی‌کند. برای جزئیات بیشتر، \fIThe depend mode\fP را ببینید.
.SS "اطلاعات هش‌شده مشترک (Common hashed information)"
.sp
اطلاعات زیر همیشه در هش گنجانده می‌شوند:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
پسوندی که کامپایلر برای فایلی با خروجی پیش‌پردازنده استفاده می‌کند (به طور معمول \f(CR.i\fP برای کد C و \f(CR.ii\fP برای کد C++)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اندازه و زمان آخرین تغییر کامپایلر (یا سایر اطلاعات مختص کامپایلر که توسط \fBcompiler_check\fP مشخص شده است)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
نام کامپایلر
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
دایرکتوری جاری (در صورت فعال بودن \fBhash_dir\fP)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
محتوای فایل‌های مشخص‌شده توسط \fBextra_files_to_hash\fP (در صورت وجود)
.RE
.SS "حالت پیش‌پردازنده (The preprocessor mode)"
.sp
در حالت پیش‌پردازنده، هش از اطلاعات مشترک و موارد زیر تشکیل می‌شود:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
خروجی پیش‌پردازنده حاصل از اجرای کامپایلر با \f(CR\-E\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
گزینه‌های خط فرمان به‌جز مواردی که بر فایل‌های include اثر می‌گذارند (\f(CR\-I\fP، \f(CR\-include\fP، \f(CR\-D\fP و غیره؛ با این فرضیه که اگر این گزینه‌های خط فرمان کوچک‌ترین اثری داشته باشند، خروجی پیش‌پردازنده را تغییر خواهند داد)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
هرگونه خروجی خطای استاندارد (standard error) تولیدشده توسط پیش‌پردازنده
.RE
.sp
بر اساس این هش، نتیجه کامپایل ذخیره‌شده را می‌توان مستقیماً در کَش جستجو کرد..SS "حالت مستقیم (The direct mode)"
.sp
در حالت مستقیم، هش از اطلاعات مشترک و موارد زیر تشکیل می‌شود:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
فایل منبع ورودی
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
گزینه‌های کامپایلر
.RE
.sp
بر اساس این هش، ساختار داده‌ای به نام \(lqmanifest\(rq در کَش جستجو می‌شود. این مانیفست شامل موارد زیر است:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
ارجاع‌ها به نتایج کامپایل کَش‌شده (فایل هدف، فایل وابستگی و غیره) که توسط کامپایل‌های قبلی منطبق با هش ایجاد شده‌اند
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
مسیرهای فایل‌های include که در زمان ذخیرهٔ نتایج کامپایل در کَش خوانده شده بودند
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
مجموع‌های هش فایل‌های include در زمانی که نتایج کامپایل در کَش ذخیره شدند
.RE
.sp
سپس محتویات فعلی فایل‌های include هش شده و با اطلاعات موجود در مانیفست مقایسه می‌شوند. در صورت وجود تطابق، ccache نتیجهٔ کامپایل را می‌داند. در صورت عدم تطابق، ccache به اجرای پیش‌پردازنده بازمی‌گردد. خروجی پیش‌پردازنده برای یافتن فایل‌های include خوانده‌شده پردازش می‌شود. سپس مسیرها و مجموع‌های هش آن فایل‌های include به همراه اطلاعات مربوط به نتیجهٔ کامپایل تولیدشده در مانیفست ذخیره می‌شوند.
.sp
نکته‌ای در مورد حالت مستقیم وجود دارد: فایل‌های سرآیندی که توسط کامپایلر استفاده شده‌اند ثبت می‌شوند، اما فایل‌های سرآیندی که استفاده \fBنشده‌اند\fP، اما در صورت وجود داشتن استفاده می‌شدند، ثبت نمی‌شوند. برای کاهش این مشکل، ccache وجود دایرکتوری‌های مشخص‌شده با \f(CR\-I\fP و موارد مشابه را در زمان کامپایل ثبت می‌کند که اکثر موارد را مدیریت می‌کند. با این حال، هنگامی که ccache بررسی می‌کند آیا نتیجه‌ای می‌تواند از کَش برداشته شود یا خیر، در حال حاضر نمی‌تواند با دقت ۱۰۰٪ بررسی کند که آیا وجود یک فایل سرآیند جدید باید نتیجه را باطل کند یا خیر. در عمل، استفاده از حالت مستقیم در اکثریت قاطع موارد ایمن است.
.sp
در صورت برقراری هر یک از موارد زیر، حالت مستقیم غیرفعال خواهد شد:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
مقدار \fBdirect_mode\fP نادرست (false) باشد
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
زمان تغییر یکی از فایل‌های include بیش از حد جدید باشد (برای جلوگیری از شرایط رقابت ضروری است)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
گزینه‌ای از کامپایلر استفاده شود که توسط حالت مستقیم پشتیبانی نمی‌شود، برای مثال:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
یک گزینهٔ کامپایلر \f(CR\-Wp,*\fP غیر از \f(CR\-Wp,\-MD,<path>\fP، \f(CR\-Wp,\-MMD,<path>\fP،
\f(CR\-Wp,\-D<macro[=defn]>\fP یا \f(CR\-Wp,\-U<macro>\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اکثر موارد استفاده از \f(CR\-Xpreprocessor\fP
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
رشتهٔ \f(CR__TIME__\fP در کد منبع وجود داشته باشد
.RE.SS "حالت وابستگی (The depend mode)"
.sp
اگر حالت وابستگی فعال باشد، ccache به‌هیچ‌وجه از پیش‌پردازنده استفاده نخواهد کرد. هَش استفاده‌شده برای شناسایی نتایج در حافظه نهان (کَش) بر پایه هش حالت مستقیم توضیح داده‌شده در بالا، به‌علاوه اطلاعات مربوط به فایل‌های include خواهد بود که از فهرست وابستگی ایجادشده توسط MSVC با \f(CR/showIncludes\fP، یا فایل وابستگی تولیدشده توسط سایر کامپایلرها با \f(CR\-MD\fP یا \f(CR\-MMD\fP خوانده می‌شود.
.sp
مزایا:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
بار اضافی (overhead) در ccache هنگام نیافتن کَش (cache miss) بسیار کمتر خواهد بود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اجرا نکردن پیش‌پردازنده می‌تواند زمانی که کامپایل به‌صورت از راه دور انجام می‌شود، برای نمونه هنگام استفاده از distcc یا موارد مشابه، بسیار سودمند باشد؛ در این حالت ccache فراخوانی‌های بالقوه پرهزینه پیش‌پردازنده را روی ماشین محلی انجام نخواهد داد.
.RE
.sp
معایب:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
نرخ اصابت به کَش (cache hit rate) احتمالاً کمتر خواهد بود، زیرا هرگونه تغییر در گزینه‌های کامپایلر یا کد منبع باعث متفاوت شدن هش می‌شود. این حالت را با پیکربندی پیش‌فرض مقایسه کنید که در آن ccache به حالت پیش‌پردازنده بازمی‌گردد؛ حالتی که در برابر برخی از انواع تغییرات در گزینه‌های کامپایلر و کد منبع انعطاف‌پذیر است.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اگر از \f(CR\-MD\fP استفاده شود، مدخل‌های مانیفست شامل فایل‌های سرایند سیستم نیز خواهند بود و بنابراین همان‌طور که استفاده از \f(CR\-MD\fP ابزار make را کُند می‌کند، سرعت یافتن کَش را نیز کمی کاهش می‌دهد. این موضوع در مورد MSVC همراه با \f(CR/showIncludes\fP نیز صادق است.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اگر از \f(CR\-MMD\fP استفاده شود، مدخل‌های مانیفست شامل فایل‌های سرایند سیستم نخواهند بود؛ این بدان معناست که ccache تغییرات در آن‌ها را نادیده خواهد گرفت.
.RE
.sp
در صورت برقراری هر یک از شرایط زیر، حالت وابستگی غیرفعال خواهد شد:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
گزینه \fBdepend_mode\fP برابر با false باشد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
کامپایلر وابستگی‌ها را با استفاده از \f(CR\-MD\fP یا \f(CR\-MMD\fP تولید نکند (برای MSVC، اگر توسط کاربر مشخص نشده باشد، \f(CR/showIncludes\fP به‌طور خودکار افزوده می‌شود).
.RE
.SH "مدیریت فایل‌های منبع تازه ایجادشده (HANDLING OF NEWLY CREATED SOURCE FILES)"
.sp
اگر زمان آخرین تغییر (mtime) یا زمان تغییر وضعیت (ctime) فایل منبع یا یکی از فایل‌های include برابر با (یا جدیدتر از) زمان فراخوانی ccache باشد، ccache عملکرد کش کردن را به‌طور کامل غیرفعال می‌کند. این کار به عنوان یک اقدام ایمنی برای جلوگیری از شرایط رقابتی (race condition، پایین‌تر را ببینید) انجام می‌شود. در عمل، این موضوع تنها هنگام استفاده از سیستم‌های فایلی با دقت تفکیک زمانی (timestamp granularity) بسیار پایین مشکل‌ساز است. می‌توانید \fBsloppiness\fP را روی \fBinclude_file_ctime,include_file_mtime\fP تنظیم کنید تا از این اقدام ایمنی صرف‌نظر شود.
.sp
برای اطلاع، شرایط رقابتی ذکرشده در بالا شامل مراحل زیر است:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 1." 4.2
.\}
یک فایل کد منبع توسط ccache خوانده شده و به هش ورودی اضافه می‌شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 2." 4.2
.\}
فایل کد منبع تغییر داده می‌شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 3." 4.2
.\}
کامپایلر اجرا شده و کد منبعِ تغییریافته را می‌خواند.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 4." 4.2
.\}
برنامه ccache خروجی کامپایلر را در کَش مرتبط با یک کلید نادرست (بر پایه کد منبعِ تغییرنیافته) ذخیره می‌کند.
.RE.SH "اشکال‌زدایی حافظه پنهان (CACHE DEBUGGING)"
.sp
برای پی بردن به اینکه ccache دقیقاً چه اطلاعاتی را هش می‌کند، می‌توانید حالت اشکال‌زدایی را از طریق گزینه پیکربندی \fBdebug\fP یا با تنظیم \f(CRCCACHE_DEBUG\fP در محیط فعال کنید. این کار هنگامی که در حال بررسی علت عدم اصابت کَش (cache hit) هستید می‌تواند مفید باشد. توجه داشته باشید که کارایی کمی کاهش خواهد یافت.
.sp
هنگامی که حالت اشکال‌زدایی فعال باشد، ccache تا پنج فایل اضافی در کنار فایل شیء (object file) ایجاد می‌کند:
.TS
allbox tab(:);
ltB ltB ltB.
T{
.sp
\fBنام فایل\fP
T}:T{
.sp
\fBسطح اشکال‌زدایی\fP
T}:T{
.sp
\fBتوضیحات\fP
T}
.T&
lt lt lt.
T{
.sp
\f(CR<objectfile>.<timestamp>.ccache\-input\-c\fP
T}:T{
.sp
2
T}:T{
.sp
ورودی باینری هش‌شده توسط هر دو حالت مستقیم (direct mode) و حالت پیش‌پردازنده (preprocessor mode).
T}
T{
.sp
\f(CR<objectfile>.<timestamp>.ccache\-input\-d\fP
T}:T{
.sp
2
T}:T{
.sp
ورودی باینری که تنها توسط حالت مستقیم هش شده است.
T}
T{
.sp
\f(CR<objectfile>.<timestamp>.ccache\-input\-p\fP
T}:T{
.sp
2
T}:T{
.sp
ورودی باینری که تنها توسط حالت پیش‌پردازنده هش شده است.
T}
T{
.sp
\f(CR<objectfile>.<timestamp>.ccache\-input\-text\fP
T}:T{
.sp
2
T}:T{
.sp
نسخه متنی ترکیبی، خوانا برای انسان و قابل مقایسه (diffable) از سه فایل فوق.
T}
T{
.sp
\f(CR<objectfile>.<timestamp>.ccache\-log\fP
T}:T{
.sp
1
T}:T{
.sp
لاگ مربوط به این فایل شیء.
T}
.TE
.sp
.sp
قالب برچسب زمانی به صورت
\f(CR<year><month><day>_<hour><minute><second>_<microsecond>\fP است.
.sp
اگر تنها به فایل لاگ نیاز دارید، گزینه \fBdebug_level\fP (متغیر محیطی \f(CRCCACHE_DEBUGLEVEL\fP) را روی 1 تنظیم کنید.
.sp
در صورتی که \fBdebug_dir\fP (متغیر محیطی \f(CRCCACHE_DEBUGDIR\fP) تنظیم شده باشد، فایل‌های فوق به جای قرارگیری در کنار فایل شیء، با مسیرهای مطلق و کامل در آن دایرکتوری نوشته خواهند شد.
.sp
در حالت مستقیم، ccache از هش ۱۶۰ بیتی BLAKE3 روی داده‌های \(lqccache\-input\-c\(rq + \(lqccache\-input\-d\(rq (که در آن \fB+\fP به معنای الحاق است) استفاده می‌کند، در حالی که در حالت پیش‌پردازنده از داده‌های \(lqccache\-input\-c\(rq + \(lqccache\-input\-p\(rq استفاده می‌شود.
.sp
فایل \(lqccache\-input\-text\(rq یک نسخه متنی ترکیبی از سه فایل ورودی باینری است. این فایل سه بخش دارد (\(lqCOMMON\(rq، \(lqDIRECT MODE\(rq و \(lqPREPROCESSOR MODE\(rq) که به نوبه خود شامل حاشیه‌نویسی‌هایی هستند که مشخص می‌کنند چه نوع داده‌ای در ادامه می‌آید.
.sp
برای اشکال‌زدایی اینکه چرا برای یک فایل شیء با اصابت کَش مورد انتظار مواجه نمی‌شوید، می‌توانید مراحل زیر را دنبال کنید:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 1." 4.2
.\}
گزینه \f(CRdebug\fP (\f(CRCCACHE_DEBUG\fP) را فعال کنید.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 2." 4.2
.\}
پروژه را بسازید (Build).
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 3." 4.2
.\}
پاک‌سازی کرده و مجدداً بسازید (Clean and build).
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 4." 4.2
.\}
فایل‌های \f(CR<objectfile>.<timestamp>.ccache\-input\-text\fP را برای دو فرآیند ساخت مقایسه کنید. این کار به همراه فایل‌های \f(CR<objectfile>.<timestamp>.ccache\-log\fP سرنخ‌هایی در مورد آنچه رخ می‌دهد به شما ارائه خواهد داد.
.RE.SH "کامپایل در دایرکتوری‌های مختلف (COMPILING IN DIFFERENT DIRECTORIES)"
.sp
هنگام کامپایل یک کد منبع یکسان در دایرکتوری‌های مختلف، اگر مسیرهای مطلق بخشی از هش ورودی شوند، ccache اغلب نمی‌تواند نتایج ذخیره‌شده در حافظه موقت را به اشتراک بگذارد. این مسیرها در موارد زیر ظاهر می‌شوند:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
کد منبع پیش‌پردازش‌شده (هنگام استفاده از \f(CR\-g\fP برای اطلاعات اشکال‌زدایی یا مسیرهای مطلق در گزینه‌های \f(CR\-I\fP)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
آرگومان‌های خط فرمان (مسیرهای مطلق به فایل‌های منبع یا دایرکتوری‌های include)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
بسط ماکروها (ماکروهای \f(CR__FILE__\fP و هشدارهای پیش‌پردازنده)
.RE
.sp
برای فعال کردن اشتراک‌گذاری حافظه موقت در دایرکتوری‌های ساخت مختلف برای ساخت‌های اشکال‌زدایی (با استفاده از \f(CR\-g\fP)، مسیرهای اشکال‌زدایی را نرمال‌سازی کنید؛ برای مثال با گزینه GCC به شکل
\f(CR\-fdebug\-prefix\-map=$PWD=.\fP (نگاشت دایرکتوری جاری به نسبی) یا
\f(CR\-fdebug\-compilation\-dir=.\fP (تنظیم دایرکتوری کامپایل). یا به عنوان جایگزین،
\fBhash_dir\fP را روی \f(CRfalse\fP تنظیم کنید (که هش کردن دایرکتوری را غیرفعال می‌کند).
.sp
برای ساخت‌هایی با مسیرهای مطلق، \fBbase_dir\fP را روی یک دایرکتوری والد مشترک تنظیم کنید. Ccache پیش از هش کردن، مسیرهای مطلق زیر این دایرکتوری را به مسیرهای نسبی تبدیل خواهد کرد.
.sp
برای مثال، اگر پروژه‌ها در \f(CR/home/user/projects\fP قرار دارند، \fBbase_dir\fP را روی
\f(CR/home/user/projects\fP یا صرفاً \f(CR/home/user\fP تنظیم کنید.
.SH "هدرهای از پیش کامپایل‌شده (PRECOMPILED HEADERS)"
.sp
برنامه ccache پشتیبانی محدودی از هدرهای از پیش کامپایل‌شده (PCH) در GCC و Clang دارد.
.sp
پیکربندی لازم:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 1." 4.2
.\}
مقدار \fBsloppiness\fP را روی \f(CRpch_defines,time_macros\fP تنظیم کنید
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
این کار لازم است زیرا ccache هنگام استفاده از PCH نمی‌تواند استفاده از ماکروهای زمان یا تغییرات \f(CR#define\fP
را تشخیص دهد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
افزودن \f(CRinclude_file_mtime,include_file_ctime\fP را برای فایل‌های تازه ایجادشده در نظر بگیرید (بخش \fIHANDLING OF NEWLY CREATED SOURCE FILES\fP را ببینید).
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 2." 4.2
.\}
یکی از این موارد:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBGCC/Clang\fP: استفاده از \f(CR\-include header\fP (در کد منبع از \f(CR#include\fP استفاده نکنید؛ نام فایل باید برای یافتن هدر کافی باشد).
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBفقط Clang\fP: استفاده از \f(CR\-include\-pch\fP با فایل PCH تولیدشده.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fBفقط GCC\fP: افزودن \f(CR\-fpch\-preprocess\fP هنگام کامپایل.
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 3." 4.2
.\}
برای Clang، گزینه \f(CR\-fno\-pch\-timestamp\fP را جهت غیرفعال کردن بررسی برچسب‌های زمانی اضافه کنید.
.RE
.sp
عیب‌یابی:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
بدون پیکربندی مناسب، ccache به استفاده از هدر غیر پیش‌کامپایل‌شده (در صورت وجود) بازمی‌گردد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اگر راهکار جایگزینی وجود نداشته باشد، عبارت \(lqPreprocessing failed\(rq را در آمارها خواهید دید.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
فایل‌هایی که به جای محافظ‌های شمول از \f(CR#pragma once\fP استفاده می‌کنند ممکن است باعث ایجاد مشکل شوند.
.RE.SH "ماژول‌های C++ (C++ MODULES)"
.sp
در حال حاضر Ccache از ماژول‌های استاندارد C++20 پشتیبانی نمی‌کند.
.sp
با این حال، پشتیبانی محدودی از \(lqClang modules\(rq (گزینهٔ \f(CR\-fmodules\fP) با این شرایط وجود دارد:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
مقدار \fBsloppiness\fP را روی \f(CRmodules\fP تنظیم کنید.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
هر دو حالت \fBdirect mode\fP و \fBdepend
mode\fP را فعال کنید.
.RE
.sp
نحوه کارکرد آن به این صورت است:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
ابزار Ccache فایل‌های \f(CRmodule.modulemap\fP را هش می‌کند اما کَش ماژول باینری Clang را نادیده می‌گیرد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
این روش کار می‌کند زیرا فایل‌های یکسان \f(CRmodule.modulemap\fP باید نتایج کَش‌شدهٔ سازگاری تولید کنند.
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B نکته
.ps -1
.br
.sp
حالت پیش‌پردازنده (preprocessor mode) اطلاعات کافی را برای پشتیبانی ماژول در \fBdepend mode\fP فراهم نمی‌کند. هنگام استفاده از حالت پیش‌پردازنده، Clang اطلاعات کافی جهت امکان هش کردن فایل‌های \f(CRmodule.modulemap\fP را ارائه نمی‌دهد.
.sp .5v
.RE
.SH "اشتراک‌گذاری کَش محلی (SHARING A LOCAL CACHE)"
.sp
گروهی از توسعه‌دهندگان می‌توانند با به اشتراک‌گذاری یک دایرکتوری کَش محلی، نرخ برخورد کَش (cache hit rate) را افزایش دهند. برای به اشتراک‌گذاری یک کَش محلی بدون عوارض جانبی ناخواسته، باید شرایط زیر برقرار باشد:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
از یک دایرکتوری کَش یکسان استفاده کنید.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اطمینان حاصل کنید که گزینهٔ پیکربندی \fBhard_link\fP روی
false تنظیم شده باشد (که حالت پیش‌فرض است).
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اطمینان حاصل کنید که تمام کاربران در یک گروه یکسان عضویت دارند.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
گزینهٔ پیکربندی \fBumask\fP را روی \fB002\fP تنظیم کنید. این امر تضمین
می‌کند که فایل‌های کَش‌شده برای تمام افراد حاضر در گروه قابل دسترس باشند.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اطمینان حاصل کنید که تمام کاربران در تمام پوشهٔ کَش مجوز نوشتن دارند
(و این‌که شما به تمام کاربران این کَش مشترک اعتماد دارید).
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اطمینان حاصل کنید که بیت setgid روی تمام دایرکتوری‌های درون کَش تنظیم شده است. این
به سیستم‌فایل اعلام می‌کند که مالکیت گروهی را برای دایرکتوری‌های جدید به ارث ببرد. دستور
زیر ممکن است برای این منظور مفید باشد:
.sp
.if n .RS 4
.nf
.fam C
find $CCACHE_DIR \-type d | xargs chmod g+s
.fam
.fi
.if n .RE
.RE
.sp
دلیل اجتناب از حالت پیوند سخت (hard link mode) این است که پیوندهای سخت عوارض جانبی
ناخواسته‌ای ایجاد می‌کنند؛ زیرا تمام پیوندها به یک فایل کَش‌شده در برچسب زمانی تغییر
(timestamp) آن فایل مشترک هستند. این امر موجب می‌شود در سیستم‌های ساخت مبتنی بر
برچسب زمانی، هر زمان که کاربر دیگری به یک فایل موجود پیوند دهد، وابستگی‌های کاذب
فعال شوند. معمولاً کاربران متوجه خواهند شد که کتابخانه‌ها و فایل‌های باینری آن‌ها بدون
دلیل مشخصی مجدداً پیوند (relink) داده می‌شوند.
.sp
همچنین ممکن است بخواهید مطمئن شوید که یک دایرکتوری پایه (base directory) به‌درستی تنظیم
شده باشد، همان‌طور که در بخش‌های قبلی توضیح داده شد..SH "اشتراک‌گذاری کَش روی NFS (SHARING A CACHE ON NFS)"
.sp
امکان قرار دادن دایرکتوری کَش روی یک سیستم فایل NFS (یا سیستم‌های فایل مشابه)
وجود دارد، اما به یاد داشته باشید که:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
قرار داشتن کَش روی NFS ممکن است سرعت کامپایل را کاهش دهد. حتماً چند آزمایش
محک‌زنی (benchmarking) انجام دهید تا ببینید آیا ارزشش را دارد یا خیر.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
ابزار ccache به‌طور کامل و دقیق روی NFS آزمایش نشده است.
.RE
.sp
یک ترفند این است که \fBtemporary_dir\fP را روی دایرکتوری در میزبان محلی
تنظیم کنید تا از ترافیک NFS برای فایل‌های موقت جلوگیری شود.
.sp
توصیه می‌شود هنگام استفاده از کَش مشترک، از نسخه یکسان سیستم‌عامل استفاده شود.
اگر نسخه‌های سیستم‌عامل متفاوت باشند، احتمالاً فایل‌های include سیستم تفاوت
خواهند داشت و نرخ اصابت کَش (cache hit) میان سیستم‌ها بسیار کم یا صفر خواهد بود.
یک راه برای بهبود نرخ اصابت کَش در این وضعیت، تنظیم \fBsloppiness\fP روی
\fBsystem_headers\fP به منظور نادیده گرفتن سرآیندهای سیستم است.
.sp
یک جایگزین برای قرار دادن دایرکتوری اصلی کَش روی NFS، راه‌اندازی کَش فایل
ذخیره‌سازی از راه دور (remote storage file cache) است.
.SH "استفاده از CCACHE با سایر پوشش‌های کامپایلر (USING CCACHE WITH OTHER COMPILER WRAPPERS)"
.sp
روش توصیه‌شده برای ترکیب ccache با سایر پوشش‌های کامپایلر (مانند \(lqdistcc\(rq)
این است که اجازه دهید ccache پوشش کامپایلر را اجرا کند. این کار با تعریف
\fBprefix_command\fP انجام می‌شود، برای نمونه با تنظیم متغیر محیطی
\f(CRCCACHE_PREFIX\fP به نام پوشش (مانند \f(CRdistcc\fP). در این صورت ccache
هنگام اجرای کامپایلر، دستور مشخص‌شده را پیشوند خط فرمان قرار می‌دهد. برای تعیین
چندین دستور پیشوند، \fBprefix_command\fP را به فهرستی از دستورها که با فاصله
از هم جدا شده‌اند تنظیم کنید.
.sp
مگر اینکه \fBcompiler_check\fP را روی دستور مناسبی تنظیم کرده باشید (توضیحات
مربوط به این گزینه پیکربندی را ببینید)، توصیه نمی‌شود از قالب
\f(CRccache anotherwrapper compiler args\fP به عنوان دستور کامپایل استفاده
کنید. همچنین توصیه نمی‌شود از تکنیک ماسک‌گذاری (masquerading) برای پوشش کامپایلر
دیگر استفاده شود. دلیل این است که به‌طور پیش‌فرض، ccache در هر دو حالت به جای
کامپایلر واقعی، mtime و اندازه پوشش دیگر را هش می‌کند، که این یعنی:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
ارتقاهای کامپایلر به درستی شناسایی نخواهند شد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
نتایج کَش‌شده میان کامپایل‌های با و بدون پوشش دیگر به اشتراک گذاشته نخواهند شد.
.RE
.sp
نکته جزئی دیگر این است که اگر از \fBprefix_command\fP استفاده شود، ccache
هنگام اجرای پیش‌پردازنده (preprocessor)، پوشش دیگر را فراخوانی نخواهد کرد که این
امر کارایی را افزایش می‌دهد. اگر می‌خواهید هنگام پیش‌پردازش نیز پوشش دیگر
فراخوانی شود (معمولاً با افزودن \f(CR\-E\fP)، می‌توانید از
\fBprefix_command_cpp\fP استفاده کنید.
.SH "هشدارها (CAVEATS)"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
حالت مستقیم (direct mode) در برخی سناریوهای نادر در شناسایی فایل‌های سرآیند جدید
ناموفق است. بخش \fIThe direct mode\fP در بالا را ببینید.
.RE
.SH "عیب‌یابی (TROUBLESHOOTING)"
.SS "عمومی (General)"
.sp
برای درک اقداماتی که ccache انجام می‌دهد، می‌توانید لاگ‌گیری اشکال‌زدایی را با
تنظیم \fBdebug\fP روی \f(CRtrue\fP یا استفاده از متغیر محیطی
\f(CRCCACHE_DEBUG=1\fP فعال کنید. برای جزئیات بخش \fICACHE DEBUGGING\fP را ببینید.
.sp
همچنین می‌توانید از \f(CRccache \-s\fP برای مشاهده نرخ‌های اصابت کَش، دلایل عدم
اصابت (miss reasons) و سایر معیارهای کارایی استفاده کنید.
.SS "کارایی (Performance)"
.sp
ابزار ccache به‌گونه‌ای طراحی شده است که با حداقل پیکربندی به خوبی کار کند،
اما می‌توانید کارایی را بیش از این بهینه‌سازی کنید:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
دایرکتوری کَش را روی حافظه ذخیره‌سازی سریع قرار دهید (SSD ترجیح داده می‌شود).
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
از کافی بودن حافظه RAM اطمینان حاصل کنید تا فایل‌های کَش‌شده در کَش سیستم‌فایل باقی بمانند.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
استفاده از حافظه ذخیره‌سازی از راه دور را برای اشتراک کَش مد نظر قرار دهید.
.RE
.sp
برای نظارت بر اثربخشی کَش، خروجی \f(CRccache \-s\fP را قبل و بعد از ساخت‌ها
مقایسه کنید تا مشکلات را شناسایی نمایید.
.sp
اگر مقدار \(lqpreprocessed cache hits\(rq به جای \(lqdirect cache hits\(rq افزایش
یابد، ccache در حال بازگشت به حالت کندتر پیش‌پردازنده است. دلایل این موضوع عبارتند از:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
تغییرات کد منبع که تأثیری بر خروجی پیش‌پردازنده ندارند
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
تغییرات در گزینه‌های مربوط به include (مانند \f(CR\-I\fP، \f(CR\-include\fP، \f(CR\-D\fP) که کد
پیش‌پردازش‌شده نهایی را تغییر نمی‌دهند
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
استفاده از گزینه‌های پشتیبانی‌نشده پیش‌پردازنده مانند \f(CR\-Xpreprocessor\fP یا \f(CR\-Wp,*\fP
(به‌جز \f(CR\-Wp,\-MD,<path>\fP، \f(CR\-Wp,\-MMD,<path>\fP، \f(CR\-Wp,\-D<define>\fP)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
اولین کامپایل پس از تغییر دادن \fBbase_dir\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
فایل‌های include با برچسب‌های زمانی جدیدتر از زمان آغاز به کار ccache (بخش
\fIHANDLING OF NEWLY CREATED SOURCE FILES\fP را ببینید)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
کد حاوی \f(CR__TIME__\fP، \f(CR__DATE__\fP یا \f(CR__TIMESTAMP__\fP که موجب تحمیل
حالت پیش‌پردازنده می‌شود (اگر از این ماکروها عملاً استفاده نمی‌شود یا نیازی به مقادیر
جاری ندارید، \fBsloppiness\fP را روی \f(CRtime_macros\fP تنظیم کنید)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
تغییر مسیر فایل ورودی (بر بسط ماکروی \f(CR__FILE__\fP اثر می‌گذارد)
.RE
.sp
اگر کدهای یکسان منجر به اصابت کَش نمی‌شوند، برخی از دلایل احتمالی عبارتند از:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
ماکروهای زمان/تاریخ یا کدهای تولیدشده با برچسب‌های زمانی/شمارنده‌های ساخت
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
پاک‌سازی کَش به دلیل محدودیت‌های اندازه
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
تفاوت‌های محیطی که بر روند کامپایل اثر می‌گذارند
.RE
.sp
شمارنده‌های خطای متداول:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\(lqMultiple source files\(rq: کامپایلر با چندین فایل منبع به‌طور هم‌زمان فراخوانی
شده است (توسط ccache پشتیبانی نمی‌شود).
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\(lqUnsupported compiler option\(rq: لاگ‌گیری اشکال‌زدایی را فعال کنید تا ببینید کدام
گزینه رد شده است.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\(lqPreprocessing failed\(rq: می‌تواند نشان‌دهنده مشکلات سرآیند از پیش کامپایل‌شده باشد
(بخش \fIPRECOMPILED HEADERS\fP را ببینید).
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\(lqCould not use precompiled header\(rq: برای پیش‌نیازهای راه‌اندازی به بخش
\fIPRECOMPILED HEADERS\fP مراجعه کنید.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\(lqCould not use modules\(rq: برای نیازمندی‌های پیکربندی بخش \fIC++ MODULES\fP را
ببینید و بررسی کنید که کدام گزینه کامپایلر رد شده است.
.RE.SS "فایل‌های شیء خراب"
.sp
باید توجه داشت که ccache در برابر مشکلات عمومی ذخیره‌سازی آسیب‌پذیر است. اگر یک
فایل شیء معیوب به هر دلیلی وارد کَش شود، مسلماً معیوب باقی خواهد ماند.
برخی از دلایل احتمالی برای ایجاد فایل‌های شیء نادرست عبارتند از: سخت‌افزار معیوب (دیسک
درایو، کنترل‌کنندهٔ دیسک، حافظه و غیره)، درایورها یا سیستم‌های فایل دارای باگ، یک
\fBprefix_command\fP نامناسب یا لفاف کامپایلر (compiler wrapper). در صورت
بروز این مشکل، ساده‌ترین راه برای رفع آن به این ترتیب است:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 1." 4.2
.\}
پروژه را طوری کامپایل کنید که فایل شیء معیوب در درخت ساخت (build tree) ایجاد شود.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 2." 4.2
.\}
فایل شیء معیوب را از درخت ساخت حذف کنید.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.  sp -1
.  IP " 3." 4.2
.\}
با مقداردهی و فعال بودن \f(CRCCACHE_RECACHE\fP مجدداً عملیات ساخت را انجام دهید.
.RE
.sp
یک راهکار جایگزین این است که در صورت عدم تمایل به نگهداری سایر نتایج کَش‌شده، کل کَش
را با دستور \f(CRccache \-C\fP پاک کنید.
.sp
تاکنون هیچ مشکلی مبنی بر تولید بازتولیدپذیر فایل‌های شیء خراب توسط ccache گزارش
نشده است. این بدان معنا نیست که چنین اتفاقی هرگز رخ نمی‌دهد، بنابراین اگر با موردی
تکرارپذیر مواجه شدید، لطفاً آن را گزارش دهید.
.SH "اطلاعات بیشتر (MORE INFORMATION)"
.sp
قدردانی‌ها، اطلاعات فهرست پستی، دستورالعمل‌های گزارش باگ، کد منبع و موارد دیگر
را می‌توانید در وب‌سایت ccache بیابید: \c
.URL "https://ccache.dev" "" "."
.SH "نویسندگان (AUTHORS)"
.sp
برنامهٔ ccache در ابتدا توسط Andrew Tridgell نوشته شد و در حال حاضر توسط Joel Rosdahl
توسعه یافته و نگهداری می‌شود. برای مشاهدهٔ فهرست مشارکت‌کنندگان به AUTHORS.txt یا AUTHORS.html و
.URL "https://ccache.dev/credits.html" "" ""
مراجعه کنید.