CCACHE(1)   CCACHE(1)

ccache - یک حافظهٔ نهان سریع برای کامپایلرهای C/C++

ccache [ccache options]
ccache [KEY=VALUE ...] compiler [compiler options]
compiler [compiler options]

شکل نخست، گزینه‌های شرح داده‌شده در بخش گزینه‌های خط فرمان در ادامه را می‌پذیرد. شکل دوم کامپایلر را فراخوانی می‌کند که به صورت اختیاری می‌تواند از گزینه‌های پیکربندی به عنوان آرگومان‌های KEY=VALUE استفاده کند. در شکل سوم، ccache مطابق آنچه در بخش حالت‌های اجرا شرح داده شده است، در نقش کامپایلر ظاهر می‌شود.

ابزار Ccache یک حافظهٔ نهان (cache) برای کامپایلر است که با ذخیره کردن نتایج کامپایل‌های پیشین و استفادهٔ مجدد از آن‌ها در زمان اجرای دوبارهٔ همان کامپایل، سرعت کامپایل مجدد را به‌طور چشمگیری افزایش می‌دهد.

ابزار Ccache به گونه‌ای طراحی شده است که دقیقاً همان خروجی کامپایلر را در یک کامپایل عادی تولید کند. تنها تفاوتی که باید احساس کنید، زمان ساخت (build) سریع‌تر است. هرگونه استثنای شناخته‌شده برای این رفتار در بخش CAVEATS مستند شده است. اگر با موردی مواجه شدید که ccache خروجی متفاوتی نسبت به آنچه انتظار می‌رفت تولید کرد، لطفاً آن را گزارش دهید.

دو راه برای استفاده از ccache جهت ذخیره‌سازی کامپایل‌ها در حافظهٔ نهان وجود دارد:

1.روش پیشوند (Prefix method): عبارت ccache را پیش از دستور کامپایل خود اضافه کنید. این ساده‌ترین رویکرد برای زمانی است که می‌خواهید ccache را آزمایش کرده یا از آن برای پروژه‌های خاصی استفاده کنید. مثال: 
ccache gcc -c example.c
2.روش تغییر چهره (Masquerade method): با ایجاد یک پیوند نمادین (symbolic link) به ccache با نام کامپایلر، کاری کنید که ccache در نقش کامپایلر ظاهر شود. این روش زمانی کاربرد دارد که می‌خواهید از ccache برای تمامی کامپایل‌ها استفاده کنید. برای تنظیم ccache جهت جا زدن خود به جای gcc و g++: 
cp ccache /usr/local/bin/
ln -s ccache /usr/local/bin/gcc
ln -s ccache /usr/local/bin/g++

در سیستم‌هایی که از پیوندهای نمادین پشتیبانی نمی‌کنند، می‌توانید به جای آن ccache را کپی کنید:

cp ccache /usr/local/bin/gcc
cp ccache /usr/local/bin/g++

این روش تا زمانی کار می‌کند که دایرکتوری حاوی پیوندهای نمادین یا نسخه‌های کپی‌شدهٔ ccache، پیش از دایرکتوری کامپایلر واقعی (به‌طور معمول /usr/bin) در متغیر محیطی PATH شما قرار گرفته باشد.


هشدار (Warning)

روش تغییر چهره به‌خوبی کار می‌کند، اما ممکن است با ابزارهای دیگری که از همین تکنیک استفاده می‌کنند تداخل داشته باشد. برای اطلاعات بیشتر بخش USING CCACHE WITH OTHER COMPILER WRAPPERS را ببینید.

این گزینه‌های خط فرمان تنها زمانی اعمال می‌شوند که ccache را مستقیماً به‌صورت “ccache” فراخوانی کنید. هنگامی که ccache در نقش یک کامپایلر عمل می‌کند (همان‌طور که در بخش پیشین توضیح داده شد)، باید از گزینه‌های معمولی کامپایلر استفاده کرده و به مستندات کامپایلر خود مراجعه کنید.

-c, --cleanup

پاک‌سازی حافظهٔ پنهان (cache) با حذف فایل‌های اخیراً استفاده‌نشده تا زمانی که از محدودیت‌های مشخص‌شده برای تعداد فایل‌ها و اندازهٔ حافظهٔ پنهان فراتر نرود. این کار همچنین تعداد کل فایل‌ها و اندازهٔ کلی حافظهٔ پنهان را مجدداً محاسبه می‌کند. به طور معمول، نیازی به شروع دستی پاک‌سازی نیست، چرا که ccache در زمان اجرا حافظهٔ پنهان را کمتر از محدودیت‌های تعیین‌شده نگه می‌دارد و آمارها را با هر کامپایل به‌روز می‌کند. پاک‌سازی اجباری بیشتر زمانی مفید است که محتویات حافظهٔ پنهان را به‌صورت دستی تغییر داده باشید یا احساس کنید که آمارهای اندازهٔ حافظهٔ پنهان ممکن است نادرست باشند.

-C, --clear

پاک کردن تمام حافظهٔ پنهان، با حذف کلیهٔ فایل‌های ذخیره‌شده، در حالی که فایل پیکربندی حفظ می‌شود.

--config-path PATH

اعمال گزینه‌های خط فرمان روی فایل پیکربندی PATH به‌جای مسیر پیش‌فرض. استفاده از این گزینه اثری یکسان با مقداردهی (بازنویسی) موقت متغیر محیطی CCACHE_CONFIGPATH دارد.

-d, --dir PATH

اعمال گزینه‌های خط فرمان روی دایرکتوری حافظهٔ پنهان PATH به‌جای مسیر پیش‌فرض. برای مثال، جهت نمایش آمار یک دایرکتوری حافظهٔ پنهان در /shared/ccache می‌توانید دستور ccache -d /shared/ccache -s را اجرا کنید. استفاده از این گزینه اثری یکسان با مقداردهی موقت متغیر محیطی CCACHE_DIR دارد.

--dry-run

هیچ عملیات نوشتنی انجام نده.

--evict-namespace NAMESPACE

فایل‌های ایجادشده در namespace داده‌شده را از حافظهٔ پنهان حذف کن.

--evict-older-than AGE

حذف فایل‌هایی از حافظهٔ پنهان که قدیمی‌تر از AGE استفاده شده‌اند. AGE باید یک عدد صحیح بدون علامت همراه با پسوند d (روز) یا s (ثانیه) باشد. در صورت ترکیب با --evict-namespace، تنها فایل‌های درون آن namespace حذف می‌شوند.

-h, --help

چاپ خلاصه‌ای از گزینه‌های خط فرمان.

-F NUM, --max-files NUM

تنظیم حداکثر تعداد فایل‌های مجاز در حافظهٔ پنهان روی NUM. مقدار 0 را برای بدون محدودیت به کار ببرید. این مقدار در یک فایل پیکربندی درون دایرکتوری حافظهٔ پنهان ذخیره می‌شود و برای تمامی کامپایل‌های بعدی اعمال خواهد شد.

-M SIZE, --max-size SIZE

تنظیم حداکثر اندازهٔ فایل‌های ذخیره‌شده در حافظهٔ پنهان. SIZE باید یک عدد همراه با یک پسوند اختیاری باشد: kB، MB، GB، TB (ده‌دهی)، KiB، MiB، GiB یا TiB (دودویی). پسوند پیش‌فرض GiB است. برای بدون محدودیت از 0 استفاده کنید. این مقدار در یک فایل پیکربندی در دایرکتوری حافظهٔ پنهان ذخیره می‌شود و برای تمامی کامپایل‌های بعدی اعمال می‌گردد.

-X LEVEL, --recompress LEVEL

فشرده‌سازی مجدد حافظهٔ پنهان به سطح LEVEL با استفاده از الگوریتم Zstandard. سطح می‌تواند یک عدد صحیح باشد (با همان مفاهیم گزینهٔ پیکربندی compression_level) یا مقدار ویژهٔ uncompressed برای بدون فشرده‌سازی. برای اطلاعات بیشتر، بخش CACHE COMPRESSION را ببینید. این عملیات می‌تواند زمان زیادی ببرد، چرا که تمام فایل‌های حافظهٔ پنهان باید پیمایش شوند. تنها فایل‌هایی که در حال حاضر با سطحی متفاوت از LEVEL فشرده شده‌اند مجدداً فشرده خواهند شد.

-o KEY=VALUE, --set-config KEY=VALUE

تنظیم گزینهٔ پیکربندی KEY به VALUE در فایل پیکربندی. برای اطلاعات بیشتر، بخش CONFIGURATION را ببینید.

-x, --show-compression

چاپ آمار فشرده‌سازی حافظهٔ پنهان. برای اطلاعات بیشتر، بخش CACHE COMPRESSION را ببینید. این عملیات می‌تواند زمان زیادی ببرد، زیرا تمام فایل‌های حافظهٔ پنهان باید پیمایش شوند.

-p, --show-config

چاپ گزینه‌های پیکربندی فعلی و خاستگاه آن‌ها (متغیر محیطی، فایل پیکربندی، یا پیش‌فرض زمان کامپایل) در قالبی خوانا برای انسان.

--show-log-stats

چاپ شمارنده‌های آماری از لاگ آمار در قالبی خوانا برای انسان. بخش stats_log را ببینید. برای جزئیات بیشتر، یک یا دو بار از -v/--verbose استفاده کنید.

-s, --show-stats

چاپ خلاصه‌ای از پیکربندی و شمارنده‌های آماری در قالبی خوانا برای انسان. برای جزئیات بیشتر، یک یا دو بار از -v/--verbose استفاده کنید. برای اطلاعات بیشتر بخش Cache statistics را ببینید.

--stop-storage-helpers

برنامه‌های کمکی ذخیره‌سازی معمولاً پس از مدتی عدم فعالیت کلاینت متوقف می‌شوند، اما این گزینه می‌تواند برای متوقف کردن فوری تمام برنامه‌های کمکی در حال اجرا استفاده شود.

--threads THREADS

استفاده از حداکثر THREADS ریسه برای عملیات چندریسمانی. پیش‌فرض، استفاده از یک ریسه به ازای هر پردازنده (CPU) است.

-v, --verbose

افزایش پرگویی (جزئیات پیام‌ها). این گزینه را می‌توان چندین بار مشخص کرد.

-V, --version

چاپ اطلاعات نسخه و کپی‌رایت.

-z, --zero-stats

صفر کردن آمارهای حافظهٔ پنهان (بدون تغییر گزینه‌های پیکربندی).

--trim-dir PATH

فایل‌هایی را که اخیراً استفاده نشده‌اند از دایرکتوری PATH حذف می‌کند تا زمانی که اندازهٔ آن حداکثر به مقدار مشخص‌شده توسط --trim-max-size برسد.

هشدار

از این گزینه برای هرس کردن کَش محلی استفاده نکنید. برای هرس کردن دایرکتوری کَش محلی به یک اندازهٔ مشخص، از CCACHE_MAXSIZE=SIZE ccache -c استفاده کنید.

--trim-max-size SIZE

حداکثر اندازه را برای --trim-dir تعیین می‌کند. SIZE باید یک عدد به همراه یک پسوند اختیاری باشد: kB، MB، GB، TB (ده‌دهی)، KiB، MiB، GiB یا TiB (دودویی). پسوند پیش‌فرض GiB است. از 0 برای حالت بدون محدودیت استفاده کنید.

--trim-method METHOD

روش هرس کردن دایرکتوری با --trim-dir را تعیین می‌کند. مقادیر ممکن عبارتند از:

atime

روش LRU (کمتر استفاده‌شده در این اواخر) با استفاده از برچسب زمان دسترسی به فایل. این مقدار پیش‌فرض است.

mtime

روش LRU (کمتر استفاده‌شده در این اواخر) با استفاده از برچسب زمان تغییر فایل.

--trim-recompress LEVEL

هنگام استفاده از --trim-dir، فشرده‌سازی مجدد را با استفاده از الگوریتم Zstandard تا سطح LEVEL انجام می‌دهد. این سطح می‌تواند یک عدد صحیح با همان مفاهیم گزینهٔ پیکربندی compression_level، یا مقدار ویژهٔ uncompressed برای بدون فشرده‌سازی باشد. برای اطلاعات بیشتر CACHE COMPRESSION را ببینید. این عملیات بالقوه ممکن است زمان زیادی ببرد، زیرا تمام فایل‌های موجود در کَش باید بررسی شوند. تنها فایل‌هایی که در حال حاضر با سطحی متفاوت از LEVEL فشرده شده‌اند، مجدداً فشرده‌سازی خواهند شد.

--checksum-file PATH

چک‌سام (128 بیتی XXH3) فایل موجود در PATH را چاپ می‌کند (- برای ورودی استاندارد).

--extract-result PATH

داده‌های ذخیره‌شده در فایل نتیجه در PATH را استخراج می‌کند (- برای ورودی استاندارد). داده‌ها در فایل‌های ccache-result.* درون دایرکتوری کاری جاری نوشته خواهند شد. این گزینه تنها هنگام اشکال‌زدایی ccache و رفتارهای آن مفید است.

--format FORMAT

قالب خروجی را برای --print-log-stats و --print-stats تعیین می‌کند. مقادیر ممکن عبارتند از:

tab

جداسازی با تب (Tab-separated). این مقدار پیش‌فرض است.

json

قالب‌بندی‌شده به صورت JSON.

-k KEY, --get-config KEY

مقدار گزینهٔ پیکربندی KEY را چاپ می‌کند. برای اطلاعات بیشتر CONFIGURATION را ببینید.

--hash-file PATH

هش (160 بیتی BLAKE3) فایل در PATH را چاپ می‌کند (- برای ورودی استاندارد). این گزینه تنها هنگام اشکال‌زدایی ccache و رفتارهای آن کاربرد دارد.

--inspect PATH

محتوای یک فایل نتیجه یا مانیفست در PATH را (- برای ورودی استاندارد) در قالبی انسان‌خوان در خروجی استاندارد چاپ می‌کند. با این حال، محتوای فایلِ تعبیه‌شده در یک فایل نتیجه چاپ نخواهد شد؛ برای استخراج محتوای فایل از --extract-result استفاده کنید. این گزینه تنها هنگام اشکال‌زدایی ccache و رفتار آن مفید است.

--print-log-stats

شمارنده‌های آماری را از گزارش لاگ آمار (stats log) در قالبی قابل پردازش توسط ماشین (جداسازی با تب یا JSON) چاپ می‌کند. stats_log و --format را ببینید.

--print-stats

شناسه‌های شمارندهٔ آمار و مقادیر متناظر آن‌ها را در قالبی قابل پردازش توسط ماشین (جداسازی با تب یا JSON) چاپ می‌کند. --format را ببینید.

--print-version

نسخه را چاپ می‌کند و کار دیگری انجام نمی‌دهد.

هنگامی که ccache به عنوان یک کامپایلر اجرا می‌شود، معمولاً همان گزینه‌های خط فرمانی را دریافت می‌کند که کامپایلرِ مورد استفادهٔ شما می‌گیرد. تنها استثنا در این مورد، گزینهٔ --ccache-skip است. از این گزینه می‌توان برای واداشتن ccache به پرهیز از تفسیر گزینهٔ بعدی به هر نحو و ارسال مستقیم و دست‌نخوردهٔ آن به کامپایلر استفاده کرد.


نکته

گزینهٔ --ccache-skip در حال حاضر تنها به ccache می‌گوید که گزینهٔ بعدی
را به عنوان یک گزینهٔ ویژهٔ کامپایلر تفسیر نکند — این گزینه همچنان در هش حالت مستقیم (direct mode hash) گنجانده خواهد شد.

دلیل اهمیت این موضوع این است که ccache باید خط فرمان را تجزیه کرده و مشخص کند چه چیزی نام فایل ورودی و چه چیزی گزینهٔ کامپایلر است، زیرا برای تعیین نام فایل شیء (object file) حاصل (از میان موارد دیگر) به نام فایل ورودی نیاز دارد. روش اکتشافی که ccache هنگام تجزیهٔ خط فرمان استفاده می‌کند این است که با هر آرگومانی که به عنوان یک فایل وجود داشته باشد، به عنوان نام فایل ورودی برخورد می‌شود. با استفاده از --ccache-skip می‌توانید اجبار کنید که با یک گزینه به عنوان نام فایل ورودی برخورد نشود و در عوض به عنوان یک گزینهٔ خط فرمان به کامپایلر فرستاده شود.

مورد دیگری که --ccache-skip می‌تواند مفید باشد زمانی است که ccache یک گزینه را به طور ویژه تفسیر می‌کند در حالی که نباید چنین کند، چرا که آن گزینه برای کامپایلر شما معنایی متفاوت از آنچه ccache می‌پندارد دارد.

همچنین نگاه کنید به ignore_options.

می‌توانید رفتار ccache را با استفاده از فایل‌های پیکربندی و متغیرهای محیطی سفارشی‌سازی کنید. گزینه‌های پیکربندی به ترتیب اولویت زیر پردازش می‌شوند (بالاترین اولویت در ابتدا):

1.تنظیمات خط فرمان در قالب KEY=VALUE. مثال: 
ccache debug=true compiler_check="%compiler% --version" gcc -c example.c
2.متغیرهای محیطی که با CCACHE_ آغاز می‌شوند.
3.فایل پیکربندی ویژهٔ دایرکتوری.
4.فایل پیکربندی اختصاصی حافظهٔ پنهان (cache).
5.فایل پیکربندی سراسری سیستم <sysconfdir>/ccache.conf (معمولاً /etc/ccache.conf یا /usr/local/etc/ccache.conf).
6.پیش‌فرض‌های زمان کامپایل.

استثنا: اگر متغیر محیطی CCACHE_CONFIGPATH تنظیم شده باشد، مشخص‌کنندهٔ تنها فایل پیکربندی‌ای خواهد بود که خوانده می‌شود (متغیرهای محیطی و تنظیمات خط فرمان همچنان اعمال خواهند شد)..SS "فایل پیکربندی اختصاصی حافظهٔ نهان (Cache-specific configuration file)"

مکان فایل پیکربندی اختصاصی حافظهٔ نهان در سیستم‌های غیرویندوزی به این صورت تعیین می‌شود:

1.اگر CCACHE_CONFIGPATH تنظیم شده باشد، از آن مسیر استفاده می‌شود.
2.در غیر این صورت، اگر متغیر محیطی CCACHE_DIR تنظیم شده باشد، از $CCACHE_DIR/ccache.conf استفاده می‌شود.
3.در غیر این صورت، اگر cache_dir در فایل پیکربندی سیستم تنظیم شده باشد، از <cache_dir>/ccache.conf استفاده می‌شود.
4.در غیر این صورت، اگر دایرکتوری قدیمی $HOME/.ccache وجود داشته باشد، از $HOME/.ccache/ccache.conf استفاده می‌شود.
5.در غیر این صورت، اگر XDG_CONFIG_HOME تنظیم شده باشد، از $XDG_CONFIG_HOME/ccache/ccache.conf استفاده می‌شود.
6.در غیر این صورت، از $HOME/Library/Preferences/ccache/ccache.conf (در macOS) یا $HOME/.config/ccache/ccache.conf (در سایر سیستم‌ها) استفاده می‌شود.

در ویندوز، روش مورد استفاده برای یافتن فایل پیکربندی بدین صورت است:

1.اگر CCACHE_CONFIGPATH تنظیم شده باشد، از آن مسیر استفاده می‌شود.
2.در غیر این صورت، اگر متغیر محیطی CCACHE_DIR تنظیم شده باشد، از %CCACHE_DIR%/ccache.conf استفاده می‌شود.
3.در غیر این صورت، اگر cache_dir در فایل پیکربندی سیستم تنظیم شده باشد، از <cache_dir>\ccache.conf استفاده می‌شود. پیکربندی سراسری سیستم در ویندوز به‌طور پیش‌فرض %ALLUSERSPROFILE%\ccache\ccache.conf است. متغیر محیطی ALLUSERSPROFILE معمولاً C:\ProgramData می‌باشد.
4.در غیر این صورت، اگر دایرکتوری قدیمی %USERPROFILE%\.ccache وجود داشته باشد، از %USERPROFILE%\.ccache\ccache.conf استفاده می‌شود.
5.در غیر این صورت، چنانچه وجود داشته باشد، از %LOCALAPPDATA%\ccache\ccache.conf استفاده می‌شود.
6.در غیر این صورت، از %APPDATA%\ccache\ccache.conf استفاده می‌شود.

همچنین برای چگونگی تعیین مکان دایرکتوری حافظهٔ نهان، گزینهٔ پیکربندی cache_dir را ببینید..SS "فایل پیکربندی ویژه دایرکتوری"

دستور Ccache برای یافتن فایل ccache.conf (جدا از فایل پیکربندی ویژه کش که در بالا شرح داده شد) در دایرکتوری کاری فعلی یا هر دایرکتوری والد جستجو می‌کند. مالک فایل پیداشده باید کاربر مؤثر باشد و فایل نباید برای همه قابل نوشتن باشد؛ در غیر این صورت ccache با یک خطا متوقف خواهد شد. جستجو با رسیدن به موارد زیر متوقف می‌شود:

•دایرکتوری فهرست‌شده در یک «دایرکتوری سقف» (به‌طور پیش‌فرض دایرکتوری خانگی کاربر)
•دایرکتوری دارای یک «نشانگر سقف» (به‌طور پیش‌فرض .git)
•دایرکتوری متعلق به کاربری دیگر
•مرز یک سیستم‌فایل (نقطه پیوند)

به‌طور پیش‌فرض، این فایل نمی‌تواند «گزینه‌های ناامن» را تنظیم کند، یعنی گزینه‌هایی که بر تعیین اینکه چه دستورهایی اجرا شوند، چه فایل‌هایی (به‌جز ورودی‌های کش) نوشته شوند و از کدام فضای ذخیره‌سازی راه‌دور استفاده شود اثر می‌گذارند. می‌توان با افزودن یک ورودی به safe_dirs، گزینه‌های ناامن را مجاز کرد.

تمام مقادیر پیکربندی از بسط متغیرهای محیطی پشتیبانی می‌کنند. ساختار آن شبیه به ساختار پوسته POSIX است: $VAR یا ${VAR}. هر دو نگارش به مقدار متغیر محیطی VAR بسط می‌یابند.

دو علامت دلار متوالی ($$) به یک علامت دلار تکی ($) بسط می‌یابند.

فایل‌های پیکربندی در قالب سادهٔ “key = value” هستند، یک گزینه در هر خط. خطوطی که با علامت هش (#) آغاز می‌شوند، توضیح هستند. خطوط خالی و همچنین فاصله‌های خالی پیرامون کلیدها و مقادیر نادیده گرفته می‌شوند. مثال:

# Set maximum cache size to 10 GB:
max_size = 10GB

مقادیر می‌توانند با استفاده از ادامه بر پایهٔ تورفتگی، چند خط را در بر بگیرند. خطوطی که با نویسهٔ فاصله (فاصله یا تب) آغاز می‌شوند به‌عنوان خطوط ادامه در نظر گرفته شده و با یک فاصلهٔ تکی به مقدار قبلی متصل می‌شوند. توضیحات و خطوط خالی درون یک مقدار چندخطی نادیده گرفته می‌شوند. برای مثال:

ignore_options =
  -Wall
  -Wextra
  # This is a comment within the value
  -pedantic
# This ends the multi-line value
compiler = gcc

این معادل است با:

ignore_options = -Wall -Wextra -pedantic
compiler = gcc

مقادیر چندخطی به‌ویژه برای گزینه‌هایی که چندین مورد را می‌پذیرند مفید هستند.

برخی از گزینه‌های پیکربندی مقادیر بولی (یعنی مقادیر درستی) هستند. در یک فایل پیکربندی، چنین مقادیری باید روی رشتهٔ true یا false تنظیم شوند. برای متغیرهای محیطی متناظر، معناشناسی کمی متفاوت است:

•یک متغیر محیطی مقداردهی‌شده به معنای “true” است (حتی اگر روی رشتهٔ خالی تنظیم شده باشد).
•مقادیر منفی زیر (بدون حساسیت به بزرگی و کوچکی حروف) به‌جای سردرگم کردن کاربر، خطا در نظر گرفته می‌شوند: 0، false، disable و no.
•یک متغیر محیطی مقداردهی‌نشده به معنای “false” است.

هر متغیر محیطی بولی همچنین دارای یک شکل نفی‌شده است که با CCACHE_NO آغاز می‌شود. برای نمونه، CCACHE_COMPRESS می‌تواند برای اجبار فشرده‌سازی تنظیم شود و CCACHE_NOCOMPRESS می‌تواند برای اجبار عدم فشرده‌سازی تنظیم گردد..SS "فهرست‌های مسیر (Path lists)"

گزینه‌هایی که فهرستی از مسیرها را تعریف می‌کنند، ورودی‌هایشان با ; در Windows و : در سایر سیستم‌ها از یکدیگر جدا می‌شوند.

در زیر فهرستی از گزینه‌های پیکربندی موجود آورده شده است. نام متغیر محیطی متناظر در پرانتز پس از کلید هر گزینهٔ پیکربندی مشخص شده است.

absolute_paths_in_stderr (CCACHE_ABSSTDERR)

این گزینه مشخص می‌کند که آیا ccache باید مسیرهای نسبی را در خروجی متنی کامپایلر (خطای استاندارد و خروجی استاندارد) به مسیرهای مطلق بازنویسی کند یا خیر. این قابلیت زمانی می‌تواند مفید باشد که از base_dir به همراه یک سیستم ساخت (مانند CMake با مولد "Unix Makefiles") استفاده کنید که کامپایلر را در دایرکتوری کاری متفاوتی اجرا می‌کند، امری که باعث نادرست شدن مسیرهای نسبی در خطاها یا هشدارهای کامپایلر می‌شود. مقدار پیش‌فرض false است.

base_dir (CCACHE_BASEDIR)

این گزینه فهرستی از مسیرهای مطلق را تعیین می‌کند. در صورت تنظیم، ccache مسیرهای مطلق را قبل از ارسال به کامپایلر (یا گنجاندن در هش ورودی) به مسیرهای نسبی تبدیل می‌کند، اما تنها برای مسیرهایی که با یکی از دایرکتوری‌های پایهٔ مشخص‌شده آغاز می‌شوند. در اینجا منظور از «نسبی»، «نسبت به دایرکتوری کاری فعلی» است.

این قابلیت اشتراک‌گذاری کَش را بین کامپایل‌ها در دایرکتوری‌های مختلف امکان‌پذیر می‌سازد، حتی اگر پروژه از مسیرهای مطلق استفاده کند. برای جزئیات بیشتر به بخش COMPILING IN DIFFERENT DIRECTORIES_ مراجعه کنید. در صورت خالی بودن (حالت پیش‌فرض)، هیچ بازنویسی مسیری رخ نمی‌دهد.

از به‌کارگیری / به عنوان دایرکتوری پایه خودداری کنید، چرا که این کار مسیرهای سرایند سیستمی را نیز بازنویسی می‌کند که معمولاً نتیجه‌ای معکوس دارد.

سناریوی نمونه: Alice در /home/alice/project1/build کار می‌کند و فرایند کامپایل را به این صورت انجام می‌دهد:

ccache gcc -I/usr/include/example -I/home/alice/project2/include -c /home/alice/project1/src/example.c

در اینجا آنچه ccache واقعاً برای تنظیمات مختلف base_dir اجرا خواهد کرد آورده شده است:

# 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

اگر Bob همان پروژه‌ها را در /home/bob/stuff ذخیره کند و هر دو کاربر base_dir را روی /home یا /home/$USER تنظیم نمایند، به دلیل یکسان بودن خطوط فرمان بازنویسی‌شده، از اصابت‌های کَش (cache hits) مشترک بهره‌مند خواهند شد:

# 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

بدون base_dir، به دلیل تفاوت در مسیرهای مطلق، عدم اصابت کَش (cache miss) رخ خواهد داد. با تنظیم base_dir روی /، به دلیل تفاوت در مسیر نسبی به /usr/include/example عدم اصابت کَش پیش می‌آید. با تنظیم base_dir روی /home/bob/stuff/project1 نیز عدم اصابت رخ می‌دهد زیرا مسیر به project2 یک مسیر مطلق متفاوت خواهد بود.


هشدار

بازنویسی مسیرهای مطلق به نسبی تا حدی یک راهکار شکننده (brittle hack) است.
این روش در بسیاری از موارد به خوبی کار می‌کند، اما ممکن است شرایطی پیش بیاید که کار مختل شود. یک مشکل شناخته‌شده این است که مسیرهای مطلق در فایل‌های وابستگی بازتولید نمی‌شوند، که این امر می‌تواند تشخیص وابستگی را در ابزارهایی مانند Make و Ninja به هم بریزد. در صورت امکان، از همان ابتدا به جای استفاده از base_dir از مسیرهای نسبی استفاده کنید.

cache_dir (CCACHE_DIR)

این گزینه مشخص می‌کند که ccache خروجی‌های کَش‌شدهٔ کامپایلر را در کجا نگهداری کند.

در سیستم‌های غیر Windows، در صورت وجود چنین دایرکتوری‌ای مقدار پیش‌فرض $HOME/.ccache است؛ در غیر این صورت اگر XDG_CACHE_HOME تنظیم شده باشد $XDG_CACHE_HOME/ccache، وگرنه $HOME/Library/Caches/ccache (در macOS) یا $HOME/.cache/ccache (در سایر سیستم‌ها) خواهد بود.

در Windows، پیش‌فرض %USERPROFILE%\.ccache است اگر چنین دایرکتوری‌ای وجود داشته باشد، در غیر این صورت %LOCALAPPDATA%\ccache خواهد بود.


هشدار

نسخه‌های پیشین ccache به طور پیش‌فرض در Windows کَش را در %APPDATA%\ccache
ذخیره می‌کردند. این امر می‌تواند منجر به انتقال فایل‌های حجیم کَش از طریق شبکه در محیط‌های دامنه‌ای (domain) و مشکلات مشابه شود. لطفاً این دایرکتوری را برای دایرکتوری‌های کَش بررسی کرده و آن‌ها یا کل دایرکتوری را حذف کنید، یا آن‌ها را به دایرکتوری %LOCALAPPDATA%\ccache منتقل نمایید.

همچنین بخش Cache-specific configuration file را ببینید.

ceiling_dirs (CCACHE_CEILING_DIRS)

این گزینه دایرکتوری‌های مطلقی را مشخص می‌کند که ccache در آن‌ها جستجو برای یافتن فایل پیکربندی ویژهٔ دایرکتوری را متوقف خواهد کرد. اگر دسترسی به فایل‌ها در دایرکتوری‌های والد بسیار کُند است (مثلاً در سیستم‌های فایل شبکه‌ای)، ممکن است بخواهید این گزینه را تنظیم کنید. حالت پیش‌فرض، توقف جستجو هنگام رسیدن به دایرکتوری خانگی (home) کاربر است.

ceiling_markers (CCACHE_CEILING_MARKERS)

این گزینه یک یا چند نام فایل یا دایرکتوری را مشخص می‌کند (با ; در Windows و : در سایر سیستم‌ها جدا می‌شوند). هنگام جستجو برای فایل پیکربندی ویژهٔ دایرکتوری، ccache با رسیدن به دایرکتوری‌ای که حاوی هر یک از نام‌های مشخص‌شده باشد، جستجو در دایرکتوری‌های والد را متوقف خواهد کرد. مقدار پیش‌فرض .git است.

compiler (CCACHE_COMPILER or (منسوخ‌شده) CCACHE_CC)

این گزینه می‌تواند برای اجبار نام کامپایلرِ مورد استفاده به کار رود. اگر روی یک رشتهٔ خالی (که حالت پیش‌فرض است) تنظیم شود، ccache آن را از خط فرمان استخراج می‌کند.

compiler_check (CCACHE_COMPILERCHECK)

به‌طور پیش‌فرض، ccache زمان تغییر (“mtime”) و اندازهٔ کامپایلر را در هش می‌گنجاند تا اطمینان حاصل شود که نتایج بازیابی‌شده از کَش دقیق هستند. در صورت استفاده از افزونه‌های کامپایلر، این افزونه‌ها نیز به هش اضافه خواهند شد. این گزینه می‌تواند برای انتخاب یک راهبرد دیگر به کار رود. مقادیر ممکن عبارتند از:

content

هش کردن محتوای باینری کامپایلر. این کار سرعت ccache را در مقایسه با mtime بسیار اندک کاهش می‌دهد، اما باعث سازگاری بهتر با ارتقای کامپایلر در طول فرایند خودراه‌اندازی (bootstrapping) ساخت می‌شود.

mtime

هش کردن mtime و اندازهٔ کامپایلر، که سریع است. این حالت پیش‌فرض است.

none

هیچ چیزی هش نمی‌شود. این حالت ممکن است برای شرایطی مناسب باشد که می‌توانید با اطمینان خاطر از نتایج کَش‌شده استفاده کنید، حتی اگر mtime یا اندازهٔ کامپایلر تغییر کرده باشد (مثلاً اگر کامپایلر به عنوان بخشی از سیستم ساخت شما ساخته می‌شود و سورس کامپایلر تغییر نکرده است، یا اگر کامپایلر تنها تغییراتی داشته که بر تولید کد تأثیر نمی‌گذارند). تنها در صورتی باید از none استفاده کنید که دقیقاً بدانید چه کاری انجام می‌دهید.

string:value

مقدار value هش می‌شود. این می‌تواند برای نمونه یک شماره بازنگری (revision) کامپایلر یا رشتهٔ دیگری باشد که سیستم ساخت برای شناسایی کامپایلر تولید می‌کند.

a command string

خروجی استاندارد و خروجی خطای استاندارد دستور مشخص‌شده را هش می‌کند. رشته با استفاده از فاصله‌های خالی (whitespace) برای یافتن دستور و آرگومان‌های اجرایی تفکیک می‌شود. هیچ تفسیر دیگری روی رشتهٔ دستور انجام نخواهد شد، به جز اینکه عبارت ویژهٔ %compiler% با مسیر کامپایلر جایگزین می‌شود. می‌توان چندین دستور را با استفاده از ; به عنوان جداکننده تعیین کرد. مثال‌ها: 
%compiler% -v
%compiler% -dumpmachine; %compiler% -dumpversion

باید اطمینان حاصل کنید که دستور مشخص‌شده تا حد امکان سریع باشد زیرا برای هر بار فراخوانی ccache یک بار اجرا خواهد شد.

شناسایی کامپایلر با استفاده از یک دستور در صورتی مفید است که بخواهید از عدم اصابت‌های کَش در شرایطی که کامپایلر بازسازی شده اما تغییر نکرده است، جلوگیری نمایید.

حالت دیگر زمانی است که کامپایلر (از دید ccache) در واقع کامپایلر واقعی نبوده بلکه یک پوشش‌دهندهٔ دیگر کامپایلر (compiler wrapper) است — در این صورت، روش پیش‌فرض mtime مقدار mtime و اندازهٔ پوشش‌دهندهٔ دیگر را هش می‌کند، بدین معنا که ccache قادر به تشخیص ارتقای کامپایلر نخواهد بود. بنابراین استفاده از یک دستور مناسب برای شناسایی کامپایلر امن‌تر است، اما کُندتر نیز خواهد بود؛ از این رو باید در صورت امکان، ادامهٔ استفاده از روش mtime در ترکیب با گزینهٔ prefix_command را مد نظر قرار دهید. بخش USING CCACHE WITH OTHER COMPILER WRAPPERS را ببینید.

compiler_type (CCACHE_COMPILERTYPE)

سی‌کَش معمولاً نوع کامپایلر را بر اساس نام کامپایلر حدس می‌زند. گزینهٔ compiler_type به شما امکان می‌دهد نوع کامپایلر را اجبار کنید. این در حالتی مفید است که کامپایلر نام غیر استانداردی دارد اما در واقع یکی از انواع شناخته‌شدهٔ کامپایلر است. مقادیر ممکن عبارتند از:

auto

یکی از انواع زیر را بر اساس نام کامپایلر (با دنبال کردن پیوندهای نمادین) حدس می‌زند. این مقدار پیش‌فرض است.

clang

کامپایلر مبتنی بر Clang.

clang-cl

کامپایلر clang-cl.

gcc

کامپایلر مبتنی بر GCC.

icl

کامپایلر Intel در Windows.

icx

کامپایلر مبتنی بر LLVM شرکت Intel.

icx-cl

کامپایلر سازگار با MSVC مبتنی بر LLVM شرکت Intel.

msvc

کامپایلر Microsoft Visual C++ (MSVC).

nvcc

کامپایلر NVCC (CUDA).

qcc

کامپایلر QCC (QNX).

other

هر کامپایلری غیر از انواع شناخته‌شده.

compression (CCACHE_COMPRESS یا CCACHE_NOCOMPRESS، بخش Boolean values در بالا را ببینید)

اگر true باشد، ccache داده‌هایی را که در کَش قرار می‌دهد فشرده‌سازی می‌کند. با این حال، این گزینه تأثیری بر نحوهٔ بازیابی فایل‌ها از کَش ندارد؛ نتایج فشرده‌شده و فشرده‌نشده بدون در نظر گرفتن این گزینه همچنان قابل استفاده خواهند بود. مقدار پیش‌فرض true است.

فشرده‌سازی با استفاده از الگوریتم Zstandard انجام می‌شود. این الگوریتم به اندازهٔ کافی سریع است و دلیل چندانی برای غیرفعال کردن فشرده‌سازی جهت دستیابی به عملکرد بیشتر وجود ندارد. یک استثنا زمانی است که کَش روی یک سیستم فایل فشرده‌شده قرار دارد، که در این حالت مسلماً فشرده‌سازی انجام‌شده توسط ccache تکراری و زائد است.

در صورت فعال بودن شبیه‌سازی فایل (گزینهٔ file_clone) یا پیوند سخت (گزینهٔ hard_link)، فشرده‌سازی غیرفعال خواهد شد.

compression_level (CCACHE_COMPRESSLEVEL)

این گزینه سطحی را تعیین می‌کند که ccache در آن فایل‌های شیء را با استفاده از الگوریتم فشرده‌سازی بی‌درنگ Zstandard فشرده می‌کند. این گزینه تنها در صورتی تأثیر دارد که compression فعال باشد (که به طور پیش‌فرض فعال است). الگوریتم Zstandard برای خروج از حالت فشرده (decompression) فوق‌العاده سریع و برای فشرده‌سازی در سطوح پایین بسیار سریع است. مقدار پیش‌فرض 0 است.

معناشناسی compression_level:

> 0

یک مقدار مثبت متناظر با سطوح فشرده‌سازی عادی Zstandard است. سطوح پایین‌تر (مانند 1) به معنای فشرده‌سازی سریع‌تر اما ضریب فشرده‌سازی ضعیف‌تر است. سطوح بالاتر (مانند 19) به معنای فشرده‌سازی کُندتر اما ضریب فشرده‌سازی بهتر است. حداکثر مقدار ممکن به نسخهٔ libzstd بستگی دارد، اما حداقل تا سطح 19 برای همهٔ نسخه‌ها در دسترس است. سرعت خروج از فشرده‌سازی اساساً برای تمام سطوح یکسان است. به عنوان یک قاعدهٔ تجربی، از سطح 5 یا پایین‌تر استفاده کنید زیرا سطوح بالاتر ممکن است فرایند کامپایل را به طرز محسوسی کُند کنند. با این حال سطوح بالاتر هنگام فشرده‌سازی مجدد کَش با گزینهٔ خط فرمان -X/--recompress مفید هستند.

< 0

یک مقدار منفی با سطوح فشرده‌سازی «فوق سریع» (ultra-fast) در Zstandard مطابقت دارد که حتی از سطح 1 سریع‌تر هستند اما نسبت فشرده‌سازی پایین‌تری دارند. برای نمونه، سطح -3 متناظر با --fast=3 برای ابزار خط فرمان zstd است. در عمل، کاربرد چندانی برای سطوح پایین‌تر از حدود -5 وجود ندارد.

0 (پیش‌فرض)

مقدار 0 بدین معناست که ccache یک سطح مناسب را انتخاب خواهد کرد که در حال حاضر 1 است.

برای اطلاعات بیشتر مستندات Zstandard https://facebook.github.io/zstd را ببینید.

debug (CCACHE_DEBUG یا CCACHE_NODEBUG، بخش Boolean values در بالا را ببینید)

اگر true باشد، حالت اشکال‌زدایی (debug) فعال می‌شود. حالت اشکال‌زدایی فایل‌های اشکال‌زدایی مجزایی به ازای هر شیء (per-object) ایجاد می‌کند که هنگام اشکال‌زدایی از عدم اصابت‌های غیرمنتظره در کَش مفید هستند. با این حال توجه داشته باشید که کارایی ccache اندکی کاهش می‌یابد. برای اطلاعات بیشتر بخش CACHE DEBUGGING را ببینید. پیش‌فرض false است.

debug_dir (CCACHE_DEBUGDIR)

مشخص می‌کند که در صورت فعال بودن حالت اشکال‌زدایی، فایل‌های اشکال‌زدایی به ازای هر شیء در کجا نوشته شوند. در صورت تنظیم روی رشتهٔ خالی، فایل‌ها در کنار فایل شیء نوشته خواهند شد. در صورت تنظیم روی یک دایرکتوری، فایل‌های اشکال‌زدایی با مسیرهای کامل و مطلق در آن دایرکتوری نوشته می‌شوند و در صورت نیاز آن دایرکتوری ایجاد می‌گردد. پیش‌فرض رشتهٔ خالی است.

به عنوان مثال، اگر debug_dir روی /example تنظیم شده باشد، دایرکتوری کاری فعلی /home/user باشد و فایل شیء build/output.o باشد، گزارش اشکال‌زدایی در /example/home/user/build/output.o.ccache-log نوشته خواهد شد. همچنین بخش CACHE DEBUGGING را ببینید.

debug_level (CCACHE_DEBUGLEVEL)

میزان اطلاعاتی را که هنگام فعال بودن حالت اشکال‌زدایی نوشته می‌شود تعیین می‌کند. برای اطلاعات بیشتر بخش CACHE DEBUGGING را ببینید. پیش‌فرض 2 است.

depend_mode (CCACHE_DEPEND یا CCACHE_NODEPEND، بخش Boolean values در بالا را ببینید)

اگر true باشد، از حالت وابستگی (depend mode) استفاده خواهد شد. پیش‌فرض false است. بخش The depend mode را ببینید.

direct_mode (CCACHE_DIRECT یا CCACHE_NODIRECT، بخش Boolean values در بالا را ببینید)

اگر true باشد، از حالت مستقیم (direct mode) استفاده خواهد شد. پیش‌فرض true است. بخش The direct mode را ببینید.

disable (CCACHE_DISABLE یا CCACHE_NODISABLE، بخش Boolean values در بالا را ببینید)

هنگامی که true باشد، ccache صرفاً کامپایلر واقعی را فراخوانی می‌کند و کَش را کاملاً دور می‌زند. پیش‌فرض false است.

همچنین می‌توان با افزودن رشتهٔ ccache:disable در یک کامنت درون 4096 بایت نخست فایل سورس کد، ccache را برای یک فایل سورس کد مشخص غیرفعال کرد.

extra_files_to_hash (CCACHE_EXTRAFILES)

این گزینه فهرستی از مسیرهای فایل‌هایی است که ccache در مجموع هشِ (hash sum) شناساگر ساخت می‌گنجاند.

file_clone (CCACHE_FILECLONE یا CCACHE_NOFILECLONE، بخش Boolean values در بالا را ببینید)

اگر true باشد، ccache تلاش می‌کند از شبیه‌سازی فایل (معروف به «رونوشت هنگام نوشتن»، «CoW» یا «reflinks») برای ذخیره و واکشی نتایج کَش‌شدهٔ کامپایلر استفاده کند. file_clone بر hard_link اولویت دارد. مقدار پیش‌فرض false است.

فایل‌های ذخیره‌شده از طریق شبیه‌سازی را نمی‌توان فشرده کرد، بنابراین در صورت فعال بودن این گزینه احتمالاً اندازهٔ کَش به میزان چشمگیری بزرگ‌تر خواهد بود. با این حال، بسته به مورد کاربرد، عملکرد ممکن است بهبود یابد.

برخلاف گزینهٔ hard_link، استفاده از file_clone کاملاً امن است، اما همهٔ سیستم‌های فایل از این ویژگی پشتیبانی نمی‌کنند. برای چنین سیستم‌های فایلی، ccache به کپی کردن معمولی (یا پیوندهای سخت در صورت فعال بودن hard_link) بازمی‌گردد.

hard_link (CCACHE_HARDLINK یا CCACHE_NOHARDLINK، بخش Boolean values در بالا را ببینید)

اگر true باشد، ccache تلاش خواهد کرد تا از پیوندهای سخت برای ذخیره و واکشی فایل‌های شیء کَش‌شده استفاده کند. پیش‌فرض false است.

فایل‌های ذخیره‌شده از طریق پیوندهای سخت را نمی‌توان فشرده کرد، بنابراین در صورت فعال بودن این گزینه به احتمال قوی اندازهٔ کَش به طرز چشمگیری بزرگ‌تر خواهد بود. با این حال، بسته به مورد کاربرد، کارایی ممکن است بهبود پیدا کند.


هشدار

این گزینه را فعال نکنید مگر اینکه از این نکات آگاه باشید:

•اگر فایل حاصل ویرایش شود، فایل موجود در کَش نیز به دلیل محتوای اشتراکی ویرایش خواهد شد، که این امر باعث خرابی ورودی کَش می‌گردد. از نسخهٔ 4.0، ccache به عنوان یک تدبیر ایمنی، فایل‌های شیء ذخیره‌شده و واکشی‌شده را فقط‌خواندنی می‌کند. علاوه بر این، یک بررسی جامعیت ساده برای فایل‌های شیء کَش‌شده با تأیید صحت اندازهٔ آن‌ها انجام می‌پذیرد. این بدان معناست که اشتباهاتی نظیر strip file.o یا echo >file.o حتی در صورت قابل‌نوشتن بودن فایل شیء شناسایی خواهند شد، اما تغییری که اندازهٔ فایل را دگرگون نسازد تشخیص داده نخواهد شد.
•برنامه‌هایی که انتظار ندارند فایل‌های حاصل از دو کامپایل یکسان به صورت پیوندهای سخت به یکدیگر باشند، ممکن است دچار خطا شوند.
•برنامه‌هایی که به زمان‌های تغییر اتکا دارند (مانند make)، اگر چندین کاربر (یا یک کاربر با چند درخت ساخت مختلف) از یک دایرکتوری کَش مشترک استفاده کنند، ممکن است به اشتباه بیفتند. دلیل این امر این است که فایل‌های شیء دارای اینودهای (i-nodes) مشترک و در نتیجه برچسب زمانی تغییر یکسانی هستند. اگر file.o در درخت ساخت A (با پیوند سخت از کَش) وجود داشته باشد و سپس file.o در درخت ساخت B توسط ccache با پیوند سخت از کَش ایجاد گردد، برچسب زمانی تغییر برای file.o در درخت ساخت A نیز به‌روزرسانی خواهد شد. این امر می‌تواند موجب اجرای مجدد مرحلهٔ پیونددهی (relinking) در درخت ساخت A شود، حتی اگر در واقع چیزی تغییر نکرده باشد.

hash_dir (CCACHE_HASHDIR یا CCACHE_NOHASHDIR، بخش Boolean values در بالا را ببینید)

اگر true باشد (که پیش‌فرض است)، ccache هنگام تولید اطلاعات اشکال‌زدایی (گزینهٔ کامپایلر -g با مشتقات آن)، دایرکتوری کاری فعلی (CWD) را در هشی که برای تفکیک دو کامپایل استفاده می‌شود می‌گنجاند. استثنا: اگر گزینه‌های کامپایلر -fdebug-prefix-map یا -fdebug-compilation-dir به درستی به کار برده شوند، CWD در هش گنجانده نخواهد شد. همچنین به بحث در بخش COMPILING IN DIFFERENT DIRECTORIES مراجعه کنید.

دلیل گنجاندن CWD در هش به طور پیش‌فرض، جلوگیری از بروز مشکل در ذخیره‌سازی دایرکتوری کاری فعلی در اطلاعات اشکال‌زدایی یک فایل شیء است، که می‌تواند باعث شود ccache فایل شیء کَش‌شده‌ای را بازگرداند که دایرکتوری کاری در اطلاعات اشکال‌زدایی آن به اشتباه تنظیم شده است.

اگر برایتان مهم نیست که CWD در اطلاعات اشکال‌زدایی ممکن است نادرست باشد، می‌توانید این گزینه را غیرفعال کنید تا هنگام کامپایل یک سورس کد یکسان در دایرکتوری‌های متفاوت، اصابت‌های کَش دریافت نمایید.

ignore_headers_in_manifest (CCACHE_IGNOREHEADERS)

این گزینه فهرستی از مسیرها به فایل‌ها (یا دایرکتوری‌های حاوی سرایندها) است که ccache آن‌ها را در فهرست مانیفستِ تشکیل‌دهندهٔ حالت مستقیم نمی‌گنجاند. توجه داشته باشید که اگر این سرایندها واقعاً تغییر کنند، این امر می‌تواند منجر به اصابت‌های کهنه در کَش شود.

ignore_options (CCACHE_IGNOREOPTIONS)

این گزینه فهرستی با جداکنندهٔ فاصله از گزینه‌های کامپایلر است که ccache آن‌ها را نادیده می‌گیرد. ورودی‌های این فهرست به صورت اختیاری می‌توانند با یک ستاره (*) خاتمه یابند تا با هر پسوندی از گزینه مطابقت داشته باشند. به عنوان مثال، -fmessage-length=* هم با -fmessage-length=20 و هم با -fmessage-length=70 مطابقت خواهد داشت. گزینهٔ کامپایلر منطبق‌شده نه به طور خاص تفسیر می‌شود و نه بخشی از هش ورودی خواهد بود. نادیده گرفتن یک گزینهٔ کامپایلر از هش زمانی مفید است که می‌دانید آن گزینه بر نتیجه تأثیری ندارد (و ccache این را نمی‌داند)، یا زمانی که تأثیر می‌گذارد اما برای شما اهمیتی ندارد. همچنین بخش Extra options را ببینید.

inode_cache (CCACHE_INODECACHE یا CCACHE_NOINODECACHE، بخش Boolean values در بالا را ببینید)

اگر true باشد، ccache هش‌های فایل سورس را بر اساس دستگاه، اینود و برچسب‌های زمانی کَش می‌کند. این امر زمان صرف‌شده برای هش کردن فایل‌های ضمیمه‌شده (include) را کاهش می‌دهد چرا که نتیجه می‌تواند بین کامپایل‌ها مجدداً مورد استفاده قرار گیرد. پیش‌فرض true است. این ویژگی نیازمند آن است که temporary_dir روی یک سیستم فایل محلی با نوع پشتیبانی‌شده قرار داشته باشد.

نکته

پشتیبانی از ویژگی کَش اینود در Windows آزمایشی است. در Windows مقدار پیش‌فرض false است.

keep_comments_cpp (CCACHE_COMMENTS یا CCACHE_NOCOMMENTS، بخش Boolean values در بالا را ببینید)

اگر true باشد، ccache پیش از هش کردن خروجی پیش‌پردازنده، کامنت‌ها را دور نمی‌ریزد. پیش‌فرض false است. این گزینه می‌تواند برای بررسی مستندات با -Wdocumentation استفاده شود.

libexec_dirs (CCACHE_LIBEXEC_DIRS)

در صورت تنظیم، ccache برنامه‌های کمکی را به جای مسیر پیش‌فرض در این دایرکتوری‌ها جستجو خواهد کرد.

log_file (CCACHE_LOGFILE)

اگر روی یک مسیر فایل تنظیم شود، ccache اطلاعات مربوط به کارهایی را که انجام می‌دهد در فایل مشخص‌شده می‌نویسد. این امر برای ردیابی و بررسی مشکلات مفید است.

اگر روی syslog تنظیم شود، ccache به جای فایل، گزارش‌ها را با استفاده از syslog() ثبت می‌کند. اگر از rsyslogd استفاده می‌کنید، می‌توانید موردی مانند این را به /etc/rsyslog.conf یا فایلی درون /etc/rsyslog.d اضافه کنید:

# log ccache to file
:programname, isequal, "ccache"         /var/log/ccache
# remove from syslog
& ~

max_files (CCACHE_MAXFILES)

این گزینه حداکثر تعداد فایل‌ها را برای نگهداری در کَش مشخص می‌کند. از 0 برای بدون محدودیت بودن استفاده کنید (که حالت پیش‌فرض است). همچنین بخش CACHE SIZE MANAGEMENT را ببینید.

max_size (CCACHE_MAXSIZE)

این گزینه حداکثر اندازهٔ کَش را مشخص می‌کند. برای عدم اعمال محدودیت، 0 را به کار ببرید. مقدار پیش‌فرض 5GiB است. پسوندهای در دسترس: kB، MB، GB، TB (ده‌دهی) و KiB، MiB، GiB، TiB (دودویی). پسوند پیش‌فرض GiB است. همچنین بخش CACHE SIZE MANAGEMENT را ببینید.

msvc_dep_prefix (CCACHE_MSVC_DEP_PREFIX)

این گزینه پیشوند خروجی فایل‌های ضمیمه‌شده را برای کامپایلر MSVC مشخص می‌کند. پیشوند پیش‌فرض “Note: including file:” است. اگر از کامپایلر بومی‌سازی‌شده استفاده می‌کنید، این مقدار باید بر همان اساس تنظیم شود.

msvc_utf8 (CCACHE_MSVC_UTF8)

این گزینه هنگام اجرای پیش‌پردازنده، /utf-8 را به خط فرمان msvc می‌افزاید تا اطمینان حاصل شود که نام فایل‌ها برای نویسه‌های غیر ascii مخدوش نمی‌شوند. این کار به طور ضمنی /validate-charset را فعال کرده و با سورس کد همانند utf-8 رفتار می‌کند که ممکن است در صورت وجود نویسه‌هایی در بازهٔ [128, 255] در کامنت‌های کد شما بر اساس جدول کد سیستم Windows (که توالی نامعتبر utf-8 ایجاد می‌کند)، خطاهای کامپایل ایجاد کند. پیش‌فرض true است.

namespace (CCACHE_NAMESPACE)

در صورت تنظیم، رشتهٔ فضای نام برای هر فرایند کامپایل به داده‌های هش‌شده افزوده خواهد شد. این کار ورودی‌های کَش مرتبط را از نظر منطقی از ورودی‌های کَش با سایر فضاهای نام تفکیک می‌کند، اما آن‌ها همچنان از یک فضای ذخیره‌سازی مشترک استفاده خواهند کرد. ورودی‌های کَش را می‌توان همچنین به طور گزینشی با گزینهٔ خط فرمان --evict-namespace، احتمالاً در ترکیب با --evict-older-than، از کَش محلی پاک‌سازی کرد.

به عنوان مثال، اگر از یک کَش محلی یکسان برای چندین پروژهٔ مجزا استفاده می‌کنید، می‌توانید برای هر کدام یک رشتهٔ فضای نام منحصر‌به‌فرد اختصاص دهید. این امر به شما امکان می‌دهد در صورت متوقف کردن کار بر روی یک پروژهٔ خاص، ورودی‌های کَش متعلق به آن را حذف کنید.

path (CCACHE_PATH)

در صورت تنظیم، ccache هنگام جستجو برای کامپایلر واقعی، دایرکتوری‌های موجود در این فهرست را بررسی خواهد کرد. در صورت عدم تنظیم، ccache اولین فایل اجرایی مطابق با نام کامپایلر را در PATH عادی جستجو می‌کند که یک پیوند نمادین به خود ccache نباشد.

pch_external_checksum (CCACHE_PCH_EXTSUM یا CCACHE_NOPCH_EXTSUM، بخش Boolean values در بالا را ببینید)

هنگامی که این گزینه تنظیم شده باشد و ccache یک فایل سرایند از پیش‌کامپایل‌شده را بیابد، به دنبال فایلی با پسوند افزودهٔ “.sum” می‌گردد (مثلاً “pre.h.gch.sum”)، و در صورت یافتن، به جای خود سرایند از پیش‌کامپایل‌شده، این فایل را هش می‌کند تا افت کارایی ناشی از هش کردن فایل‌های بسیار بزرگ برطرف گردد.

prefix_command (CCACHE_PREFIX)

این گزینه فهرستی از پیشوندها (جداشده با فاصله) را به خط فرمانی که ccache هنگام فراخوانی کامپایلر به کار می‌گیرد اضافه می‌کند. همچنین بخش USING CCACHE WITH OTHER COMPILER WRAPPERS را ببینید.

prefix_command_cpp (CCACHE_PREFIX_CPP)

این گزینه فهرستی از پیشوندها (جداشده با فاصله) را به خط فرمانی که ccache هنگام فراخوانی پیش‌پردازنده به کار می‌گیرد اضافه می‌کند.

read_only (CCACHE_READONLY یا CCACHE_NOREADONLY، بخش Boolean values در بالا را ببینید)

اگر true باشد، ccache تلاش می‌کند از نتایج کَش‌شدهٔ موجود استفاده کند، اما نتایج جدیدی را به هیچ پیشانهٔ (backend) کَشی اضافه نخواهد کرد. با این وجود شمارنده‌های آمار همچنان به‌روزرسانی خواهند شد، مگر اینکه گزینهٔ stats روی false تنظیم شده باشد.

اگر به این دلیل از این گزینه استفاده می‌کنید که دایرکتوری ccache شما فقط‌خواندنی است، باید temporary_dir را تنظیم نمایید چرا که در غیر این صورت ccache در ایجاد فایل‌های موقت با شکست مواجه خواهد شد. همچنین ممکن است مایل باشید stats را روی false بگذارید تا ccache حتی برای به‌روزرسانی فایل‌های آمار تلاشی نکند.

read_only_direct (CCACHE_READONLY_DIRECT یا CCACHE_NOREADONLY_DIRECT، بخش Boolean values در بالا را ببینید)

دقیقاً مانند read_only است با این تفاوت که ccache تنها تلاش می‌کند تا نتایج را با استفاده از حالت مستقیم از کَش بازیابی کند، نه حالت پیش‌پردازنده. مستندات مربوط به read_only را در رابطه با به‌کارگیری یک دایرکتوری فقط‌خواندنی ccache مشاهده فرمایید.

recache (CCACHE_RECACHE یا CCACHE_NORECACHE، بخش Boolean values در بالا را ببینید)

اگر true باشد، ccache از هیچ نتیجهٔ ذخیره‌شدهٔ قبلی استفاده نخواهد کرد. نتایج جدید همچنان کَش خواهند شد، و احتمالاً بر روی هر نتیجهٔ از پیش موجودی بازنویسی می‌شوند.

remote_only (CCACHE_REMOTE_ONLY یا CCACHE_NOREMOTE_ONLY، بخش Boolean values در بالا را ببینید)

اگر true باشد، ccache تنها از فضای ذخیره‌سازی دوردست (remote) استفاده خواهد کرد. مقدار پیش‌فرض false است. توجه داشته باشید که شمارنده‌های آمار کَش همچنان در دایرکتوری کَش محلی نگهداری خواهند شد مگر اینکه stats برابر با false باشد. همچنین بخش Storage interaction را ببینید.

remote_storage (CCACHE_REMOTE_STORAGE)

این گزینه یک یا چند پیشانهٔ ذخیره‌سازی (جداشده با فاصلهٔ خالی) را برای پرس‌وجو پس از بررسی کَش محلی مشخص می‌کند (مگر اینکه remote_only روی true باشد). برای اطلاع از نحو و پیشانه‌های موجود به REMOTE STORAGE BACKENDS مراجعه نمایید.

مثال‌ها:

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

نکته

در نسخه‌های پیشین ccache، این گزینه secondary_storage (CCACHE_SECONDARY_STORAGE)
نامیده می‌شد که هنوز هم می‌تواند به عنوان یک نام مستعار به کار رود.

reshare (CCACHE_RESHARE یا CCACHE_NORESHARE، بخش Boolean values در بالا را ببینید)

اگر true باشد، ccache حتی برای اصابت‌های کَش محلی نیز نتایج را در فضای ذخیره‌سازی دوردست می‌نویسد. مقدار پیش‌فرض false است.

response_file_format (CCACHE_RESPONSE_FILE_FORMAT)

سی‌کَش معمولاً قالب فایل پاسخ (response file) را بر اساس نوع کامپایلر حدس می‌زند. گزینهٔ response_file_format به شما اجازه می‌دهد رفتار نقل‌قول (quoting) فایل پاسخ را اجبار کنید. این در حالتی کاربرد دارد که کامپایلر از هر دو روش نقل‌قول POSIX و Windows پشتیبانی نماید. مقادیر ممکن عبارتند از:

auto

یکی از قالب‌های زیر را بر اساس نوع کامپایلر حدس می‌زند. این مقدار پیش‌فرض است.

posix

رفتار نقل‌قول POSIX.

windows

رفتار نقل‌قول Windows.

safe_dirs (CCACHE_SAFE_DIRS)

فهرستی از دایرکتوری‌های مورد اعتماد که فایل‌های پیکربندی ویژهٔ دایرکتوری در آن‌ها مجاز به تعیین «گزینه‌های ناامن» هستند (بخش Directory-specific configuration file را ببینید). پیش‌فرض خالی است.

مقادیر مجاز فهرست: * با هر دایرکتوری مطابقت دارد. یک مسیر مطلق که با /* خاتمه یابد با تمام زیردایرکتوری‌های (در هر عمقی) زیر آن مسیر منطبق است. یک مسیر مطلق که به /* ختم نشود تنها با همان دایرکتوری مطابقت دارد.

sloppiness (CCACHE_SLOPPINESS)

به‌طور پیش‌فرض، ccache تلاش می‌کند تا حد ممکن کمترین اصابت‌های نادرست در کَش (false cache hits) رخ دهد. با این حال، در برخی شرایط ممکن است شما از مواردی مطلع باشید که ccache نمی‌تواند آن‌ها را بدیهی فرض کند. این گزینه امکان می‌دهد تا به ccache اعلام کنید برخی از بررسی‌ها را آسان‌تر بگیرد تا نرخ اصابت افزایش یابد. مقادیر در دسترس (جداشده با فاصله یا ویرگول):

clang_index_store

مورد کاربرد: پروژه‌های Xcode با مسیرهای متغیر index store.
اثر: گزینه‌های -index-store-path و -index-unit-output-path را هنگام هش کردن نادیده می‌گیرد.
بده‌بستان: نمایه (Index) در صورت اصابت کَش به درستی به‌روزرسانی نخواهد شد.

file_stat_matches

مورد کاربرد: هنگامی که بررسی محتوای فایل بیش از حد کُند است.
اثر: از برچسب‌های زمانی فایل به جای محتوا برای اعتبارسنجی کَش استفاده می‌کند.
بده‌بستان: ممکن است تغییرات محتوا با برچسب‌های زمانی یکسان نادیده گرفته شوند.

file_stat_matches_ctime

مورد کاربرد: هنگامی که برچسب‌های زمانی فایل به صورت دستی کنترل می‌شوند.
اثر: در صورت فعال بودن file_stat_matches، زمان تغییر وضعیت (ctime) را نادیده می‌گیرد.
بده‌بستان: ممکن است برخی از تغییرات سیستم فایل از دست بروند.

gcno_cwd

مورد کاربرد: ساخت‌های پوشش کد (code coverage) در دایرکتوری‌های مختلف.
اثر: دایرکتوری فعلی را هنگام ایجاد فایل‌های .gcno نادیده می‌گیرد (-ftest-coverage). همچنین در صورت استفاده از -fprofile-abs-path، هش کردن دایرکتوری کاری فعلی را غیرفعال می‌سازد.
بده‌بستان: اطلاعات دایرکتوری در فایل‌های پوشش کد ممکن است نادرست باشد.

نکته

روی --coverage بی‌تأثیر است (زیرا متضمن -fprofile-arcs است).

incbin

مورد کاربرد: پروژه‌هایی که از دستورات اسمبلی .incbin استفاده می‌کنند.
اثر: امکان کَش کردن فایل‌های حاوی دستورات .incbin را فراهم می‌کند.
بده‌بستان: تغییرات در فایل‌های باینری ضمیمه‌شده شناسایی نخواهد شد.

include_file_ctime

مورد کاربرد: سیستم‌های ساختی که برچسب‌های زمانی فایل را به طور مکرر تغییر می‌دهند.
اثر: هنگام بررسی تغییرات اخیر، زمان تغییر وضعیت فایل را نادیده می‌گیرد.
بده‌بستان: ممکن است تغییرات اخیر در فایل‌های سورس نادیده گرفته شوند.

include_file_mtime

مورد کاربرد: سیستم‌های ساختی که برچسب‌های زمانی فایل را به طور مداوم تغییر می‌دهند.
اثر: هنگام بررسی تغییرات اخیر، زمان ویرایش فایل را نادیده می‌گیرد.
بده‌بستان: ممکن است ویرایش‌های اخیر در فایل‌های سورس نادیده گرفته شوند.

ivfsoverlay

مورد کاربرد: پروژه‌های Xcode که کدهای Objective-C و Swift را ترکیب می‌کنند.
اثر: گزینهٔ سیستم فایل مجازی -ivfsoverlay را نادیده می‌گیرد.
بده‌بستان: ممکن است تغییرات مربوط به VFS شناسایی نشوند.

locale

مورد کاربرد: ساخت در محیط‌هایی با تنظیمات متغیر محلی‌سازی (locale).
اثر: متغیرهای محیطی locale را نادیده می‌گیرد (LANG، LC_ALL، LC_CTYPE، LC_MESSAGES).
بده‌بستان: پیام‌های هشدار کامپایلر ممکن است بین ساخت‌های کَش‌شده و تازه تفاوت داشته باشند.

modules

مورد کاربرد: ساخت‌های Clang با استفاده از -fmodules.
اثر: هنگام استفاده از ماژول‌های C++ امکان کَش کردن را فراهم می‌آورد.
بده‌بستان: ممکن است تغییرات در وضعیت درونی ماژول تشخیص داده نشود.

برای جزئیات بیشتر بخش C++ MODULES را ببینید.

pch_defines

مورد کاربرد: پروژه‌های دارای سرایندهای از پیش‌کامپایل‌شده.
اثر: بررسی دستورات #define در سرایندهای از پیش‌کامپایل‌شده را آسان‌تر می‌گیرد.
بده‌بستان: ممکن است برخی از تغییرات در تعاریف ماکرو شناسایی نشوند.

برای جزئیات بیشتر بخش PRECOMPILED HEADERS را ببینید.

random_seed

مورد کاربرد: ساخت‌هایی با مقادیر متغیر -frandom-seed.
اثر: مقادیر تصادفی seed را در هش کامپایل نادیده می‌گیرد.
بده‌بستان: ساخت‌ها ممکن است کاملاً بازتولیدپذیر نباشند.

system_headers

مورد کاربرد: سیستم‌هایی با سرایندهای سیستمی که به طور مکرر تغییر می‌کنند.
اثر: در حالت مستقیم تنها سرایندهای غیر سیستمی را ردیابی می‌کند.
بده‌بستان: تغییرات سرایندهای سیستمی را که بر کامپایل اثر می‌گذارند تشخیص نمی‌دهد.
محدودیت‌ها: تنها برای کامپایلرهای مشابه GCC پشتیبانی می‌شود (نه MSVC). سرایندهای سیستمی همچنان در حالت پیش‌پردازنده بررسی می‌شوند.

همچنین گزینهٔ ignore_headers_in_manifest را ببینید.

time_macros

مورد کاربرد: کدهایی که از ماکروهای زمان استفاده می‌کنند اما مقادیر آن‌ها اهمیتی ندارد.
اثر: ماکروهای __DATE__، __TIME__ و __TIMESTAMP__ را در سورس کد نادیده می‌گیرد.
بده‌بستان: مقادیر زمانی در خروجی متعلق به کامپایل کَش‌شده خواهند بود.

stats (CCACHE_STATS یا CCACHE_NOSTATS، بخش Boolean values در بالا را ببینید)

اگر true باشد، ccache در هر کامپایل شمارنده‌های آمار را به‌روزرسانی می‌کند. پیش‌فرض true است. اگر false باشد، پاک‌سازی خودکار نیز غیرفعال خواهد شد.

stats_log (CCACHE_STATSLOG)

اگر روی یک مسیر فایل تنظیم شود، ccache به‌روزرسانی‌های شمارندهٔ آمار را در فایل مشخص‌شده ثبت می‌کند. این امر برای به دست آوردن آمار برای ساخت‌های مجزا کاربرد دارد. برای مشاهدهٔ خلاصه‌ای از گزارش آمار فعلی، از دستور ccache --show-log-stats استفاده کنید.

نکته

سطرهایی در گزارش آمار که با علامت هش (#) آغاز می‌شوند، کامنت هستند.

temporary_dir (CCACHE_TEMPDIR)

این گزینه مشخص می‌کند که ccache فایل‌های موقت را در کجا قرار دهد. پیش‌فرض $XDG_RUNTIME_DIR/ccache-tmp (معمولاً /run/user/<UID>/ccache-tmp) است در صورتی که XDG_RUNTIME_DIR تنظیم شده و دایرکتوری موجود باشد؛ در غیر این صورت <cache_dir>/tmp خواهد بود.

نکته

در نسخه‌های پیشین ccache، مقدار CCACHE_TEMPDIR باید روی همان سیستم فایلِ مسیر
CCACHE_DIR قرار می‌داشت، اما این محدودیت برطرف شده است.

umask (CCACHE_UMASK)

این گزینه (یک عدد صحیح در مبنای هشت) مقدار umask را برای فایل‌ها و دایرکتوری‌های درون دایرکتوری کَش مشخص می‌کند. این گزینه عمدتاً زمانی مفید است که بخواهید کَش خود را با سایر کاربران به اشتراک بگذارید.

برای غیرفعال‌کردن کامل ccache برای همهٔ فراخوانی‌ها، disable = true (CCACHE_DISABLE=1) را تنظیم کنید. همچنین می‌توانید با افزودن رشتهٔ ccache:disable در یک توضیح (کامنت) در ۴۰۹۶ بایت نخست فایل، ccache را برای یک فایل کد منبع خاص غیرفعال کنید. در حالت اخیر، شمارندهٔ آماری Ccache disabled افزایش خواهد یافت.

گزینهٔ remote_storage به شما امکان می‌دهد ccache را برای استفاده از یک یا چند پشت‌بانهٔ ذخیره‌سازی دوردست پیکربندی کنید. به‌طور پیش‌فرض، دایرکتوری محلی حافظهٔ پنهان واقع در cache_dir در ابتدا و ذخیره‌سازی دوردست در اولویت بعدی پرس‌وجو می‌شوند، اما می‌توان remote_only را روی true تنظیم کرد تا ذخیره‌سازی محلی غیرفعال شود. توجه داشته باشید که شمارنده‌های آماری حافظهٔ پنهان همچنان در دایرکتوری محلی حافظهٔ پنهان نگه‌داری خواهند شد — پشت‌بانه‌های ذخیره‌سازی دوردست تنها نتایج کامپایل و مانیفست‌ها را ذخیره می‌کنند.

ccache می‌تواند یک فرایند محلی کمکی ذخیره‌سازیِ طولانی‌زیست (که جداگانه نصب می‌شود) برای مدیریت ارتباط با ذخیره‌سازی دوردست ایجاد کند. کمکی‌های ذخیره‌سازی برای بهره‌وری اتصالات دوردست را باز نگه می‌دارند و پس از مدتی عدم فعالیت خاتمه می‌یابند. برای فهرستی از کمکی‌های شناخته‌شده، Storage helpers https://ccache.dev/storage-helpers.html را ببینید.

برنامهٔ کمکی ذخیره‌سازی ccache-storage-<scheme> نام دارد، که در آن <scheme> بخش طرح‌وارهٔ یک URL است، مانند https. این برنامه می‌تواند در این مکان‌ها قرار گیرد (به ترتیب اولویت):

1.در مکانی که با ویژگی helper مشخص شده است (پایین را ببینید).
2.در یک دایرکتوری libexec.
3.در کنار فایل اجرایی ccache.
4.در $PATH.

اگر برنامه پیدا نشود، ccache در صورت دردسترس بودن به یکی از پشت‌بانه‌های توکار (builtin) بازمی‌گردد؛ در غیر این صورت ccache با یک خطا خارج می‌شود.

یک پشت‌بانهٔ ذخیره‌سازی دوردست با یک URL مشخص می‌شود و می‌تواند به دنبال آن فهرستی از ویژگی‌ها (key=value) و صفت‌های سفارشی (@key=value) که با نویسه‌های فاصله‌ساز (whitespace) از هم جدا شده‌اند قرار گیرد. نبود =value کوتاه‌نوشتی برای تنظیم مقدار روی true است. در صورتی که مقادیر شامل نویسه‌های %، | یا نویسه‌های فاصله‌ساز باشند، باید به‌صورت percent-encoded https://en.wikipedia.org/wiki/Percent-encoding باشند. برای سازگاری با نسخه‌های قدیمی‌تر ccache، با نویسه‌های | مانند فاصله رفتار می‌شود.

•data-timeout: مهلت زمانی انتقال داده برای ارسال/دریافت. هر زمان که داده‌ای دریافت شود یا امکان ارسال داشته باشد، بازنشانی می‌شود. پیش‌فرض: 10s.
•helper: بازتعریف این‌که کدام کمکی ذخیره‌سازی اجرا شود (یک نام فایل یا یک مسیر کامل). این گزینه عمدتاً هنگام توسعه یا آزمایش کمکی‌های جدید کاربرد دارد.
•idle-timeout: مهلت زمانی انتظار فرایند کمکی پیش از خروج پس از عدم فعالیت کلاینت (0s: برای همیشه فعال بماند). پیش‌فرض: 10m.
•read-only: در صورت true بودن، تنها از این پشت‌بانه می‌خواند و در آن نمی‌نویسد. پیش‌فرض false است.
•request-timeout: مهلت زمانی برای کل درخواست. پیش‌فرض: 1m.
•shards: فهرستی از نام‌ها که با کاما از هم جدا شده‌اند برای قطعه‌بندی (sharding / افراز) مدخل‌های حافظهٔ پنهان با استفاده از Rendezvous hashing https://en.wikipedia.org/wiki/Rendezvous_hashing، که معمولاً برای توزیع حافظهٔ پنهان بر روی یک خوشه از سرورها به کار می‌رود. در صورت تنظیم، URL ذخیره‌سازی باید شامل یک ستاره (*) باشد، که با یکی از نام‌های shard برای ساخت یک URL واقعی جایگزین خواهد شد. یک نام shard می‌تواند به‌صورت اختیاری یک وزن الحاق‌شده داخل پرانتز داشته باشد تا مشخص کند چه مقدار از فضای کلید باید به آن shard اختصاص یابد. یک shard با وزن w شامل w/S از حافظهٔ پنهان خواهد بود، که در آن S مجموع وزن‌های همهٔ shardها است. برای نمونه می‌توان یک وزن را طوری تنظیم کرد که نشان‌دهندهٔ حافظهٔ دردسترس برای یک حافظهٔ پنهان در حافظه روی یک سرور خاص باشد. وزن پیش‌فرض 1 است.

مثال‌ها:

•http://cache-*.example.com shards=a(3),b(1),c(1.5) مقدار ۵۵٪ (۳/۵٫۵) از حافظهٔ پنهان را روی http://cache-a.example.com، مقدار ۱۸٪ (۱/۵٫۵) را روی http://cache-b.example.com و مقدار ۲۷٪ (۱٫۵/۵٫۵) را روی http://cache-c.example.com قرار خواهد داد.
•http://example.com/* shards=alpha,beta مقدار ۵۰٪ از حافظهٔ پنهان را روی http://example.com/alpha و ۵۰٪ را روی http://example.com/beta قرار خواهد داد.

مهلت‌های زمانی را می‌توان با پسوند ms (میلی‌ثانیه)، s (ثانیه)، m (دقیقه)، h (ساعت) یا d (روز) مشخص کرد..SS "ویژگی‌های سفارشی (Custom attributes)"

ویژگی‌های سفارشی در قالب @key=value مختص پیاده‌سازی هر storage helper هستند. برای آگاهی از ویژگی‌های دردسترس به مستندات backend مراجعه کنید. مثال‌ها:

•file:///example/directory @umask=002 @update-mtime=true
•https://example.com/path @bearer-token=deadbeef

جدول زیر تعامل میان فضای ذخیره‌سازی محلی و دوردست را هنگام یافت‌شدن (hit) و یافت‌نشدن (miss) در حافظهٔ نهان در صورتی که remote_only برابر false باشد (که پیش‌فرض است) شرح می‌دهد:

فضای ذخیره‌سازی محلی فضای ذخیره‌سازی دوردست آنچه رخ می‌دهد
یافت‌نشدن (miss) یافت‌نشدن (miss) کامپایل، نوشتن در محلی، نوشتن در دوردست[1]
یافت‌نشدن (miss) یافت‌شدن (hit) خواندن از دوردست، نوشتن در محلی
یافت‌شدن (hit) - خواندن از محلی، بدون نوشتن در دوردست[2]

[1] مگر این‌که فضای ذخیره‌سازی دوردست دارای ویژگی read-only=true باشد.
[2] مگر این‌که فضای ذخیره‌سازی محلی طوری تنظیم شده باشد که موارد یافت‌شده در حافظهٔ نهان را با گزینهٔ reshare به اشتراک بگذارد.

اگر remote_only برابر true باشد:

فضای ذخیره‌سازی محلی فضای ذخیره‌سازی دوردست آنچه رخ می‌دهد
- یافت‌نشدن (miss) کامپایل، نوشتن در دوردست، بدون نوشتن در محلی
- یافت‌شدن (hit) خواندن از دوردست، بدون نوشتن در محلی

قالب URL: file:DIRECTORY یا file://[HOST]DIRECTORY

این پشت‌بند داده‌ها را به صورت فایل‌های مجزا در یک ساختار دایرکتوری زیر DIRECTORY ذخیره می‌کند، مشابه (اما نه یکسان) با ذخیره‌سازی کَش محلی. یک کاربرد رایج برای این پشت‌بند، اشتراک‌گذاری کَش در یک دایرکتوری NFS است. DIRECTORY باید با یک اسلش آغاز شود. HOST می‌تواند رشته‌ای خالی یا localhost باشد. در Windows، همچنین HOST می‌تواند نام سروری باشد که یک پوشهٔ اشتراکی را میزبانی می‌کند.


مهم

ccache هیچ‌گونه پاک‌سازی در فضای ذخیره‌سازی انجام نخواهد داد — این کار باید
از روش‌های دیگر انجام شود، به عنوان مثال با اجرای دوره‌ای ccache --trim-dir.

مثال‌ها:

•file:/shared/nfs/directory
•file:///shared/nfs/directory @umask=002 @update-mtime=true
•file:///Z:/example/windows/folder
•file://example.com/shared/ccache%20folder

ویژگی‌های اختیاری:

•@layout: نحوهٔ ذخیره فایل‌ها در دایرکتوری کَش. مقادیر موجود:
•flat: ذخیرهٔ همهٔ فایل‌ها مستقیماً زیر دایرکتوری کَش.
•local: خواندن فایل‌ها با استفاده از چیدمان دایرکتوری پویای کَش محلی. این چیدمان برای یک رونوشت یک‌طرفه یا سوار کردن (mount) فقط‌خواندنی یک دایرکتوری کَش محلی در نظر گرفته شده است و پشت‌بند ذخیره‌سازی فایل را فقط‌خواندنی می‌کند. این دایرکتوری باید شامل ورودی‌های خودکفا باشد (file_clone یا hard_link پشتیبانی نمی‌شوند).
•subdirs: ذخیرهٔ فایل‌ها در 256 زیردایرکتوری از دایرکتوری کَش.

پیش‌فرض subdirs است.

•@umask: این ویژگی (یک عدد صحیح در مبنای هشت) مقدار umask مورد استفاده برای فایل‌ها و دایرکتوری‌ها را در دایرکتوری کَش بازنویسی می‌کند.
•@update-mtime: اگر true باشد، زمان ویرایش (mtime) ورودی‌های کَش خوانده‌شده را به‌روزرسانی می‌کند. مقدار پیش‌فرض false است.

قالب URL: crsh:IPC_ENDPOINT

این بک‌اند به یک فرایند دستیار ذخیره‌سازی ccache‏ (CRSH) که در حال حاضر در حال اجرا است و روی IPC_ENDPOINT (مسیر سوکت یونیکس یا پایپ نام‌گذاری‌شدهٔ ویندوز) گوش می‌دهد، متصل می‌شود. کاربرد این بخش عمدتاً هنگام توسعه یا اشکال‌زدایی یک دستیار ذخیره‌سازی، یا در برپاسازی‌های خاصی است که برنامهٔ دستیار به صورت خارجی اجرا و مدیریت می‌شود.

مثال‌ها:

•crsh:/path/to/your.sock (سوکت یونیکس)
•crsh:name-of-your-pipe (پایپ نام‌گذاری‌شدهٔ ویندوز)


هشدار

پشتیبانی توکار از پروتکل HTTP منسوخ شده است و در نسخهٔ بعدی ccache (که صرفاً رفع باگ نباشد) حذف خواهد شد. به جای آن از یک دستیار ذخیره‌سازی راه دور استفاده کنید.

قالب URL: http://HOST[:PORT][/PATH]

این بک‌اند داده‌ها را در یک سرور سازگار با HTTP ذخیره می‌کند. متدهای HTTP مورد نیاز شامل GET، PUT و DELETE هستند.


مهم

برنامه ccache هیچ‌گونه پاک‌سازی‌ای روی فضای ذخیره‌سازی انجام نخواهد داد — این کار باید به روش‌های دیگر انجام شود، به عنوان مثال با اجرای دوره‌ای ccache --trim-dir.


نکته

پروتکل HTTPS پشتیبانی نمی‌شود.


توصیه

برای نکاتی پیرامون نحوهٔ راه‌اندازی سرور HTTP جهت استفاده با ccache،
راهنمای راه‌اندازی ذخیره‌سازی HTTP https://ccache.dev/howto/http-storage.html را ببینید.

مثال‌ها:

•http://localhost
•http://someusername:p4ssw0rd@example.com/cache/
•http://localhost:8080 @layout=bazel

ویژگی‌های اختیاری:

•@bearer-token: توکن حامل (Bearer token) مورد استفاده برای احراز هویت درخواست‌های HTTP.
•@keep-alive: اگر برابر با true باشد، اتصال HTTP به سرور ذخیره‌سازی را باز نگه می‌دارد تا از اتصال‌های مجدد جلوگیری شود. مقدار پیش‌فرض true است.
•@layout: نحوهٔ نگاشت نام‌های کلید به بخش مسیر URL. مقادیر موجود:
•bazel: ذخیره مقادیر در قالبی سازگار با پروتکل حافظهٔ نهان HTTP برنامه Bazel. به طور دقیق‌تر، مدخل‌ها به صورت ۶۴ رقم هگزادسیمال در زیر بخش /ac/ حافظهٔ نهان ذخیره می‌شوند.

نکته

برای این که این قابلیت کار کند ممکن است لازم باشد اعتبارسنجی مقادیر action cache را در سرور غیرفعال کنید، زیرا مدخل‌های ccache مقادیر معتبر فرادادهٔ نتیجهٔ کنش (action result) نیستند.

•flat: الحاق مستقیم کلید به بخش مسیر URL (در صورت نیاز با یک اسلش در ابتدا).
•subdirs: الحاق دو نویسهٔ نخست کلید به URL (در صورت نیاز با یک اسلش در ابتدا)، و به دنبال آن یک اسلش و باقی‌ماندهٔ کلید. این کار مدخل‌ها را به ۲۵۶ دسته تقسیم می‌کند.

مقدار پیش‌فرض subdirs است.

•@header: افزودن جفت key=value به هدرهای HTTP درخواست. به عنوان مثال: @header=Content-Type=application/octet-stream مقدار "Content-Type: application/octet-stream" را به سرآیندهای HTTP درخواست اضافه می‌کند.

هشدار

پشتیبانی داخلی از پروتکل Redis منسوخ شده است و در نسخهٔ بعدی غیر رفع‌باگ (non-bug-fix) ccache حذف خواهد شد. در عوض از یک دستیار ذخیره‌سازی دوردست (remote storage helper) استفاده کنید.

قالب‌های URL:

redis://[[USERNAME:]PASSWORD@]HOST[:PORT][/DBNUMBER]
redis+unix:SOCKET_PATH[?db=DBNUMBER]
redis+unix://[[USERNAME:]PASSWORD@localhost]SOCKET_PATH[?db=DBNUMBER]

این پشت‌بند داده‌ها را در یک کارساز Redis https://redis.io (یا سازگار با Redis) ذخیره می‌کند. پیاده‌سازی‌هایی هم برای ذخیره‌سازی مبتنی بر حافظه و هم مبتنی بر دیسک وجود دارد. مقدار پیش‌فرض PORT برابر 6379 و مقدار پیش‌فرض DBNUMBER برابر 0 است.


نکته

برنامهٔ ccache هیچ‌گونه پاک‌سازی در فضای ذخیره‌سازی Redis انجام نخواهد داد، اما می‌توانید
تخلیهٔ حافظه بر اساس LRU را پیکربندی کنید https://redis.io/topics/lru-cache.


راهنمایی

برای نکاتی دربارهٔ برپاسازی کارساز Redis جهت استفاده به همراه ccache، به
نحوهٔ برپاسازی ذخیره‌سازی Redis https://ccache.dev/howto/redis-storage.html مراجعه کنید.


راهنمایی

می‌توانید با استفاده از ویژگی shards که در بخش REMOTE STORAGE BACKENDS شرح داده شده است، خوشه‌ای (کلاستری) از کارسازهای Redis را برپا کنید.

مثال‌ها:

•redis://localhost
•redis://p4ssw0rd@cache.example.com:6379/0
•redis+unix:/run/redis.sock
•redis+unix:///run/redis.sock
•redis+unix://p4ssw0rd@localhost/run/redis.sock?db=0

به‌طور پیش‌فرض، ccache محدودیتی ۵ گیگابایتی (5 GB) برای مجموع اندازه فایل‌ها در کَش دارد و هیچ محدودیتی برای تعداد فایل‌ها در نظر نمی‌گیرد. شما می‌توانید با استفاده از گزینه‌های خط فرمان -M/--max-size و -F/--max-files محدودیت‌های متفاوتی را تنظیم کنید. برای مشاهده اندازه کَش و محدودیت‌های پیکربندی‌شده فعلی (علاوه بر آمارهای گوناگون دیگر) از گزینه -s/--show-stats استفاده کنید.

پاک‌سازی می‌تواند به دو روش مختلف آغاز شود: خودکار و دستی.

پس از ذخیره یک نتیجه کامپایل جدید در کَش محلی، اگر مقدار max_size یا max_files فراتر رفته باشد، ccache یک پاک‌سازی خودکار را آغاز می‌کند. این پاک‌سازی، مدخل‌های کَش را بر اساس زمان تغییر (mtime) فایل‌های درون کَش و با ترتیبی تقریبی بر اساس LRU (کمتر اخیراً استفاده‌شده) حذف می‌کند. به همین دلیل، ccache زمان تغییر (mtime) فایل‌های کَش خوانده‌شده در هنگام اصابت به کَش (cache hit) را به‌روزرسانی می‌کند تا آن‌ها را به عنوان مواردی که اخیراً استفاده شده‌اند علامت‌گذاری کند.

به دلایل کارایی، هنگام آغاز پاک‌سازی خودکار تنها مدخل‌های موجود در زیرمجموعه‌ای از کَش بررسی می‌شوند؛ بنابراین قدیمی‌ترین مدخل‌ها لزوماً همیشه ابتدا حذف نمی‌شوند، اما رفتار کلی برنامه در طول زمان به الگوریتم LRU بسیار نزدیک است.

برای وادار کردن به پاک‌سازی کل کَش، دستور ccache --cleanup را اجرا کنید. این کار اطلاعات اندازه کَش را دوباره محاسبه کرده و تضمین می‌کند که اندازه کَش از max_size و max_files فراتر نرود.

توجه داشته باشید که همان‌طور که در بخش پاک‌سازی خودکار در بالا ذکر شد، هیچ تضمینی وجود ندارد که فقط قدیمی‌ترین مدخل‌ها بیرون انداخته شوند. برای پاک‌سازی و حذف بر اساس سن، از دستور ccache --evict-older-than AGE استفاده کنید.

به‌طور پیش‌فرض، ccache تمام داده‌های کَش‌شده را با استفاده از الگوریتم Zstandard http://zstd.net (zstd) در سطح فشرده‌سازی ۱ فشرده می‌کند. این الگوریتم به‌اندازه‌ای سریع است که فرایند فشرده‌سازی به‌ندرت بر کارایی تأثیر می‌گذارد. ممکن است تنها زمانی مایل به غیرفعال‌سازی فشرده‌سازی باشید که کَش شما روی یک فایل‌سیستم از پیش فشرده‌شده ذخیره شده باشد، جایی که فشرده‌سازی ccache تکراری و زائد خواهد بود.

برای جزئیات پیکربندی، compression و compression_level را ببینید.

برای نمایش اطلاعات فشرده‌سازی از ccache --show-compression استفاده کنید. نمونه خروجی:

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

نکات:

•Disk blocks: اندازه واقعی کَش با احتساب اندازه بلوک‌های فایل‌سیستم. این مقدار باید با "Cache size" در خروجی ccache --show-stats مطابقت داشته باشد.
•Compressed data: فایل‌های نتایج و مانیفست ذخیره‌شده در کَش.
•Incompressible data: فایل‌های ذخیره‌شده بدون فشرده‌سازی (به‌دلیل تنظیمات file_clone یا hard_link) یا فایل‌های موروثی از نسخه‌های قدیمی‌تر ccache.
•Compression ratio: تحت تأثیر compression_level قرار دارد.

می‌توانید با استفاده از ccache --recompress داده‌های کَش‌شده را با سطوح فشرده‌سازی متفاوت مجدداً فشرده کنید. تنها فایل‌هایی که سطح فشرده‌سازی متفاوتی نسبت به مقدار هدف دارند مجدداً فشرده خواهند شد.

دستور ccache --show-stats خلاصه‌ای از آمارها شامل اندازه کَش، پاک‌سازی‌ها (تعداد پاک‌سازی‌های انجام‌شده، چه به‌صورت ضمنی به دلیل رسیدن به حد نصاب اندازه کَش و چه به دلیل فراخوانی‌های صریح ccache -c)، نرخ اصابت (hit rate) کلی، نرخ اصابت برای حالت‌های مستقیم/پیش‌پردازش‌شده (direct/preprocessed)، و نرخ اصابت برای فضای ذخیره‌سازی محلی و از راه دور را نمایش می‌دهد.

شمارنده‌های آماری در طول فرایند ساخت توسط خود ccache استفاده نمی‌شوند. این بدان معناست که می‌توانید بدون تأثیر گذاشتن بر فرایند ساخت، هر زمان که بخواهید با استفاده از ccache --zero-stats آن‌ها را بازنشانی کنید. به عنوان مثال، می‌توانید پیش از یک ساخت آن‌ها را بازنشانی کنید تا ccache --show-stats تنها نتایج حاصل از همان ساخت خاص را خلاصه کند. همچنین می‌توانید پیش از شروع ساخت، stats_log را تنظیم کرده و سپس ccache --show-log-stats را اجرا کنید تا آمارهای مربوط به آن ساخت خاص را مشاهده نمایید. این روش به شمارنده‌های آماری اجازه می‌دهد تا به ردیابی کل طول عمر کَش ادامه دهند و همزمان اطلاعات تفصیلی مربوط به هر ساخت را نیز در اختیارتان بگذارند. یکی دیگر از مزایای stats_log این است که آمارها را بدون تداخل ناشی از سایر ساخت‌های همزمانی که به همان کَش دسترسی دارند جمع‌آوری می‌کند.

این خلاصه همچنین شامل شمارنده‌هایی با عنوان “Errors” و “Uncacheable” است که حاصل‌جمع شمارنده‌های جزئی‌تر هستند. برای مشاهده آن شمارنده‌های تفصیلی، از پرچم -v/--verbose استفاده کنید. حالت پرگو (verbose) می‌تواند شمارنده‌های زیر را نشان دهد:

شمارنده (Counter) توضیحات (Description)
Autoconf compile/link کامپایل یا پیوند غیرقابل کَش‌شدن توسط یک آزمون Autoconf.
Bad compiler arguments آرگومان نامعتبر یا بدقواره کامپایلر، مانند نبود مقدار برای گزینه‌ای از کامپایلر که به آرگومان نیاز دارد، یا ناتوانی در خواندن فایلی که توسط آرگومان گزینه کامپایلر مشخص شده است.
Called for linking کامپایلر برای پیوند دادن (linking) فراخوانی شده بود، نه کامپایل. ابزار ccache تنها از کامپایل یک تک‌فایل پشتیبانی می‌کند؛ یعنی فراخوانی کامپایلر با گزینه -c برای تولید یک فایل شیء (object file) از یک فایل منبع واحد.
Called for preprocessing کامپایلر برای پیش‌پردازش فراخوانی شده بود، نه کامپایل.
Ccache disabled ابزار ccache توسط رشته ccache:disable در فایل کد منبع غیرفعال شده بود.
Could not use modules پیش‌شرط‌های استفاده از ماژول‌های ++C برآورده نشدند.
Could not use precompiled header پیش‌شرط‌های استفاده از سرآیندهای پیش‌کامپایل‌شده برآورده نشدند.
Could not read or parse input file یک فایل ورودی قابل خواندن یا تجزیه نبود (برای جزئیات گزارش اشکال‌زدایی را ببینید).
Could not write to output file امکان نوشتن در مسیر خروجی تعیین‌شده با -o وجود نداشت.
Compilation failed فرایند کامپایل با شکست مواجه شد. هیچ نتیجه‌ای در کَش ذخیره نشد.
Compiler check failed برنامه بررسی کامپایلر که توسط compiler_check (CCACHE_COMPILERCHECK) مشخص شده بود شکست خورد.
Compiler output file missing یکی از فایل‌هایی که انتظار می‌رفت توسط کامپایلر تولید شود پس از کامپایل یافت نشد.
Compiler produced empty output فایل خروجی کامپایلر (معمولاً یک فایل شیء) پس از کامپایل خالی بود.
Could not find the compiler کامپایلری که باید اجرا شود پیدا نشد.
Error hashing extra file شکست در خواندن فایلی که توسط extra_files_to_hash (CCACHE_EXTRAFILES) مشخص شده بود.
Forced recache از CCACHE_RECACHE برای بازنویسی یک نتیجه موجود استفاده شد.
Input file modified during compilation یک فایل ورودی در حین کامپایل تغییر یافت.
Internal error خطای غیرمنتظره داخلی، مثلاً به دلیل بروز مشکل در خواندن/نوشتن کَش.
Missing cache file یک فایل به‌طور غیرمنتظره‌ای در کَش وجود نداشت. این مورد تنها در موقعیت‌های نادری رخ می‌دهد، مثلاً هنگامی که یک نمونه از ccache در شرف دریافت فایلی از کَش است در حالی که نمونه دیگری آن فایل را در حین پاک‌سازی کَش حذف کرده است.
Multiple source files کامپایلر برای کامپایل همزمان چند فایل منبع در یک نوبت فراخوانی شده بود. این کار توسط ccache پشتیبانی نمی‌شود.
No input file هیچ فایل ورودی‌ای به کامپایلر مشخص نشده بود.
Output to stdout به کامپایلر دستور داده شده بود که با استفاده از -o - خروجی خود را در خروجی استاندارد بنویسد. این کار توسط ccache پشتیبانی نمی‌شود.
Preprocessing failed پیش‌پردازش کد منبع با استفاده از گزینه -E کامپایلر با شکست مواجه شد.
Unsupported code directive کدی مانند دستور اسمبلی .incbin یافت شد. این مورد توسط ccache پشتیبانی نمی‌شود.
Unsupported compiler option یک گزینه کامپایلر که توسط ccache پشتیبانی نمی‌شود یافت شد.
Unsupported environment variable یک متغیر محیطی که توسط ccache پشتیبانی نمی‌شود تنظیم شده بود.
Unsupported source encoding فایل منبع (یا یک سرآیند واردشده) دارای کدبندی پشتیبانی‌نشده است. ccache در حال حاضر برای MSVC در صورتی که msvc_utf8 مقدار true داشته باشد، به کد منبع با کدبندی UTF-8 نیاز دارد.
Unsupported source language یک زبان منبع، مثلاً مشخص‌شده با -x، توسط ccache پشتیبانی نمی‌شود.

ابزار ccache تشخیص می‌دهد چه زمانی کد مشابهی را کامپایل می‌کنید و از خروجی‌های از پیش ذخیره‌شده دوباره استفاده می‌کند. این کار با ایجاد یک هش یکتا (“هش ورودی” یا “input hash”) از اطلاعات گوناگونی که بر کامپایل اثرگذارند انجام می‌شود. هنگامی که دوباره با همان هش مواجه شود، ccache می‌تواند تمام خروجی‌های درست کامپایلر را از حافظه موقت (cache) بازیابی و ارائه کند.

برای هش‌کردن، ccache از BLAKE3 https://blake3.io, یک الگوریتم هش رمزنگارانه سریع، استفاده می‌کند. برای تضمین یکپارچگی داده‌ها، داده‌های کَش‌شده با مجموع مقابله‌ای XXH3 https://xxhash.com محافظت می‌شوند تا خرابی داده‌ها تشخیص داده شود.

ابزار ccache دو راهبرد برای جمع‌آوری اطلاعاتی که جهت ایجاد کلیدهای جستجوی کَش استفاده می‌شوند دارد:

•حالت پیش‌پردازنده (Preprocessor mode): ابزار ccache پیش‌پردازنده را روی کد منبع اجرا کرده و نتیجه را هش می‌کند.
•حالت مستقیم (Direct mode): ابزار ccache کد منبع و فایل‌های include را مستقیماً هش می‌کند.

حالت مستقیم عموماً سریع‌تر است زیرا از بار اضافی اجرای پیش‌پردازنده جلوگیری می‌کند.

هنگامی که حالت مستقیم نتیجه‌ای در کَش پیدا نکند (cache miss)، ccache به حالت پیش‌پردازنده بازمی‌گردد؛ مگر اینکه depend mode فعال باشد. در depend mode، حتی در صورت عدم یافتن در کَش، ccache هرگز پیش‌پردازنده را اجرا نمی‌کند. برای جزئیات بیشتر، The depend mode را ببینید.

اطلاعات زیر همیشه در هش گنجانده می‌شوند:

•پسوندی که کامپایلر برای فایلی با خروجی پیش‌پردازنده استفاده می‌کند (به طور معمول .i برای کد C و .ii برای کد C++)
•اندازه و زمان آخرین تغییر کامپایلر (یا سایر اطلاعات مختص کامپایلر که توسط compiler_check مشخص شده است)
•نام کامپایلر
•دایرکتوری جاری (در صورت فعال بودن hash_dir)
•محتوای فایل‌های مشخص‌شده توسط extra_files_to_hash (در صورت وجود)

در حالت پیش‌پردازنده، هش از اطلاعات مشترک و موارد زیر تشکیل می‌شود:

•خروجی پیش‌پردازنده حاصل از اجرای کامپایلر با -E
•گزینه‌های خط فرمان به‌جز مواردی که بر فایل‌های include اثر می‌گذارند (-I، -include، -D و غیره؛ با این فرضیه که اگر این گزینه‌های خط فرمان کوچک‌ترین اثری داشته باشند، خروجی پیش‌پردازنده را تغییر خواهند داد)
•هرگونه خروجی خطای استاندارد (standard error) تولیدشده توسط پیش‌پردازنده

بر اساس این هش، نتیجه کامپایل ذخیره‌شده را می‌توان مستقیماً در کَش جستجو کرد..SS "حالت مستقیم (The direct mode)"

در حالت مستقیم، هش از اطلاعات مشترک و موارد زیر تشکیل می‌شود:

•فایل منبع ورودی
•گزینه‌های کامپایلر

بر اساس این هش، ساختار داده‌ای به نام “manifest” در کَش جستجو می‌شود. این مانیفست شامل موارد زیر است:

•ارجاع‌ها به نتایج کامپایل کَش‌شده (فایل هدف، فایل وابستگی و غیره) که توسط کامپایل‌های قبلی منطبق با هش ایجاد شده‌اند
•مسیرهای فایل‌های include که در زمان ذخیرهٔ نتایج کامپایل در کَش خوانده شده بودند
•مجموع‌های هش فایل‌های include در زمانی که نتایج کامپایل در کَش ذخیره شدند

سپس محتویات فعلی فایل‌های include هش شده و با اطلاعات موجود در مانیفست مقایسه می‌شوند. در صورت وجود تطابق، ccache نتیجهٔ کامپایل را می‌داند. در صورت عدم تطابق، ccache به اجرای پیش‌پردازنده بازمی‌گردد. خروجی پیش‌پردازنده برای یافتن فایل‌های include خوانده‌شده پردازش می‌شود. سپس مسیرها و مجموع‌های هش آن فایل‌های include به همراه اطلاعات مربوط به نتیجهٔ کامپایل تولیدشده در مانیفست ذخیره می‌شوند.

نکته‌ای در مورد حالت مستقیم وجود دارد: فایل‌های سرآیندی که توسط کامپایلر استفاده شده‌اند ثبت می‌شوند، اما فایل‌های سرآیندی که استفاده نشده‌اند، اما در صورت وجود داشتن استفاده می‌شدند، ثبت نمی‌شوند. برای کاهش این مشکل، ccache وجود دایرکتوری‌های مشخص‌شده با -I و موارد مشابه را در زمان کامپایل ثبت می‌کند که اکثر موارد را مدیریت می‌کند. با این حال، هنگامی که ccache بررسی می‌کند آیا نتیجه‌ای می‌تواند از کَش برداشته شود یا خیر، در حال حاضر نمی‌تواند با دقت ۱۰۰٪ بررسی کند که آیا وجود یک فایل سرآیند جدید باید نتیجه را باطل کند یا خیر. در عمل، استفاده از حالت مستقیم در اکثریت قاطع موارد ایمن است.

در صورت برقراری هر یک از موارد زیر، حالت مستقیم غیرفعال خواهد شد:

•مقدار direct_mode نادرست (false) باشد
•زمان تغییر یکی از فایل‌های include بیش از حد جدید باشد (برای جلوگیری از شرایط رقابت ضروری است)
•گزینه‌ای از کامپایلر استفاده شود که توسط حالت مستقیم پشتیبانی نمی‌شود، برای مثال:
•یک گزینهٔ کامپایلر -Wp,* غیر از -Wp,-MD,<path>، -Wp,-MMD,<path>، -Wp,-D<macro[=defn]> یا -Wp,-U<macro>
•اکثر موارد استفاده از -Xpreprocessor
•رشتهٔ __TIME__ در کد منبع وجود داشته باشد

اگر حالت وابستگی فعال باشد، ccache به‌هیچ‌وجه از پیش‌پردازنده استفاده نخواهد کرد. هَش استفاده‌شده برای شناسایی نتایج در حافظه نهان (کَش) بر پایه هش حالت مستقیم توضیح داده‌شده در بالا، به‌علاوه اطلاعات مربوط به فایل‌های include خواهد بود که از فهرست وابستگی ایجادشده توسط MSVC با /showIncludes، یا فایل وابستگی تولیدشده توسط سایر کامپایلرها با -MD یا -MMD خوانده می‌شود.

مزایا:

•بار اضافی (overhead) در ccache هنگام نیافتن کَش (cache miss) بسیار کمتر خواهد بود.
•اجرا نکردن پیش‌پردازنده می‌تواند زمانی که کامپایل به‌صورت از راه دور انجام می‌شود، برای نمونه هنگام استفاده از distcc یا موارد مشابه، بسیار سودمند باشد؛ در این حالت ccache فراخوانی‌های بالقوه پرهزینه پیش‌پردازنده را روی ماشین محلی انجام نخواهد داد.

معایب:

•نرخ اصابت به کَش (cache hit rate) احتمالاً کمتر خواهد بود، زیرا هرگونه تغییر در گزینه‌های کامپایلر یا کد منبع باعث متفاوت شدن هش می‌شود. این حالت را با پیکربندی پیش‌فرض مقایسه کنید که در آن ccache به حالت پیش‌پردازنده بازمی‌گردد؛ حالتی که در برابر برخی از انواع تغییرات در گزینه‌های کامپایلر و کد منبع انعطاف‌پذیر است.
•اگر از -MD استفاده شود، مدخل‌های مانیفست شامل فایل‌های سرایند سیستم نیز خواهند بود و بنابراین همان‌طور که استفاده از -MD ابزار make را کُند می‌کند، سرعت یافتن کَش را نیز کمی کاهش می‌دهد. این موضوع در مورد MSVC همراه با /showIncludes نیز صادق است.
•اگر از -MMD استفاده شود، مدخل‌های مانیفست شامل فایل‌های سرایند سیستم نخواهند بود؛ این بدان معناست که ccache تغییرات در آن‌ها را نادیده خواهد گرفت.

در صورت برقراری هر یک از شرایط زیر، حالت وابستگی غیرفعال خواهد شد:

•گزینه depend_mode برابر با false باشد.
•کامپایلر وابستگی‌ها را با استفاده از -MD یا -MMD تولید نکند (برای MSVC، اگر توسط کاربر مشخص نشده باشد، /showIncludes به‌طور خودکار افزوده می‌شود).

اگر زمان آخرین تغییر (mtime) یا زمان تغییر وضعیت (ctime) فایل منبع یا یکی از فایل‌های include برابر با (یا جدیدتر از) زمان فراخوانی ccache باشد، ccache عملکرد کش کردن را به‌طور کامل غیرفعال می‌کند. این کار به عنوان یک اقدام ایمنی برای جلوگیری از شرایط رقابتی (race condition، پایین‌تر را ببینید) انجام می‌شود. در عمل، این موضوع تنها هنگام استفاده از سیستم‌های فایلی با دقت تفکیک زمانی (timestamp granularity) بسیار پایین مشکل‌ساز است. می‌توانید sloppiness را روی include_file_ctime,include_file_mtime تنظیم کنید تا از این اقدام ایمنی صرف‌نظر شود.

برای اطلاع، شرایط رقابتی ذکرشده در بالا شامل مراحل زیر است:

1.یک فایل کد منبع توسط ccache خوانده شده و به هش ورودی اضافه می‌شود.
2.فایل کد منبع تغییر داده می‌شود.
3.کامپایلر اجرا شده و کد منبعِ تغییریافته را می‌خواند.
4.برنامه ccache خروجی کامپایلر را در کَش مرتبط با یک کلید نادرست (بر پایه کد منبعِ تغییرنیافته) ذخیره می‌کند.

برای پی بردن به اینکه ccache دقیقاً چه اطلاعاتی را هش می‌کند، می‌توانید حالت اشکال‌زدایی را از طریق گزینه پیکربندی debug یا با تنظیم CCACHE_DEBUG در محیط فعال کنید. این کار هنگامی که در حال بررسی علت عدم اصابت کَش (cache hit) هستید می‌تواند مفید باشد. توجه داشته باشید که کارایی کمی کاهش خواهد یافت.

هنگامی که حالت اشکال‌زدایی فعال باشد، ccache تا پنج فایل اضافی در کنار فایل شیء (object file) ایجاد می‌کند:

نام فایل سطح اشکال‌زدایی توضیحات
<objectfile>.<timestamp>.ccache-input-c 2 ورودی باینری هش‌شده توسط هر دو حالت مستقیم (direct mode) و حالت پیش‌پردازنده (preprocessor mode).
<objectfile>.<timestamp>.ccache-input-d 2 ورودی باینری که تنها توسط حالت مستقیم هش شده است.
<objectfile>.<timestamp>.ccache-input-p 2 ورودی باینری که تنها توسط حالت پیش‌پردازنده هش شده است.
<objectfile>.<timestamp>.ccache-input-text 2 نسخه متنی ترکیبی، خوانا برای انسان و قابل مقایسه (diffable) از سه فایل فوق.
<objectfile>.<timestamp>.ccache-log 1 لاگ مربوط به این فایل شیء.

قالب برچسب زمانی به صورت <year><month><day>_<hour><minute><second>_<microsecond> است.

اگر تنها به فایل لاگ نیاز دارید، گزینه debug_level (متغیر محیطی CCACHE_DEBUGLEVEL) را روی 1 تنظیم کنید.

در صورتی که debug_dir (متغیر محیطی CCACHE_DEBUGDIR) تنظیم شده باشد، فایل‌های فوق به جای قرارگیری در کنار فایل شیء، با مسیرهای مطلق و کامل در آن دایرکتوری نوشته خواهند شد.

در حالت مستقیم، ccache از هش ۱۶۰ بیتی BLAKE3 روی داده‌های “ccache-input-c” + “ccache-input-d” (که در آن + به معنای الحاق است) استفاده می‌کند، در حالی که در حالت پیش‌پردازنده از داده‌های “ccache-input-c” + “ccache-input-p” استفاده می‌شود.

فایل “ccache-input-text” یک نسخه متنی ترکیبی از سه فایل ورودی باینری است. این فایل سه بخش دارد (“COMMON”، “DIRECT MODE” و “PREPROCESSOR MODE”) که به نوبه خود شامل حاشیه‌نویسی‌هایی هستند که مشخص می‌کنند چه نوع داده‌ای در ادامه می‌آید.

برای اشکال‌زدایی اینکه چرا برای یک فایل شیء با اصابت کَش مورد انتظار مواجه نمی‌شوید، می‌توانید مراحل زیر را دنبال کنید:

1.گزینه debug (CCACHE_DEBUG) را فعال کنید.
2.پروژه را بسازید (Build).
3.پاک‌سازی کرده و مجدداً بسازید (Clean and build).
4.فایل‌های <objectfile>.<timestamp>.ccache-input-text را برای دو فرآیند ساخت مقایسه کنید. این کار به همراه فایل‌های <objectfile>.<timestamp>.ccache-log سرنخ‌هایی در مورد آنچه رخ می‌دهد به شما ارائه خواهد داد.

هنگام کامپایل یک کد منبع یکسان در دایرکتوری‌های مختلف، اگر مسیرهای مطلق بخشی از هش ورودی شوند، ccache اغلب نمی‌تواند نتایج ذخیره‌شده در حافظه موقت را به اشتراک بگذارد. این مسیرها در موارد زیر ظاهر می‌شوند:

•کد منبع پیش‌پردازش‌شده (هنگام استفاده از -g برای اطلاعات اشکال‌زدایی یا مسیرهای مطلق در گزینه‌های -I)
•آرگومان‌های خط فرمان (مسیرهای مطلق به فایل‌های منبع یا دایرکتوری‌های include)
•بسط ماکروها (ماکروهای __FILE__ و هشدارهای پیش‌پردازنده)

برای فعال کردن اشتراک‌گذاری حافظه موقت در دایرکتوری‌های ساخت مختلف برای ساخت‌های اشکال‌زدایی (با استفاده از -g)، مسیرهای اشکال‌زدایی را نرمال‌سازی کنید؛ برای مثال با گزینه GCC به شکل -fdebug-prefix-map=$PWD=. (نگاشت دایرکتوری جاری به نسبی) یا -fdebug-compilation-dir=. (تنظیم دایرکتوری کامپایل). یا به عنوان جایگزین، hash_dir را روی false تنظیم کنید (که هش کردن دایرکتوری را غیرفعال می‌کند).

برای ساخت‌هایی با مسیرهای مطلق، base_dir را روی یک دایرکتوری والد مشترک تنظیم کنید. Ccache پیش از هش کردن، مسیرهای مطلق زیر این دایرکتوری را به مسیرهای نسبی تبدیل خواهد کرد.

برای مثال، اگر پروژه‌ها در /home/user/projects قرار دارند، base_dir را روی /home/user/projects یا صرفاً /home/user تنظیم کنید.

برنامه ccache پشتیبانی محدودی از هدرهای از پیش کامپایل‌شده (PCH) در GCC و Clang دارد.

پیکربندی لازم:

1.مقدار sloppiness را روی pch_defines,time_macros تنظیم کنید
•این کار لازم است زیرا ccache هنگام استفاده از PCH نمی‌تواند استفاده از ماکروهای زمان یا تغییرات #define را تشخیص دهد.
•افزودن include_file_mtime,include_file_ctime را برای فایل‌های تازه ایجادشده در نظر بگیرید (بخش HANDLING OF NEWLY CREATED SOURCE FILES را ببینید).
2.یکی از این موارد:
•GCC/Clang: استفاده از -include header (در کد منبع از #include استفاده نکنید؛ نام فایل باید برای یافتن هدر کافی باشد).
•فقط Clang: استفاده از -include-pch با فایل PCH تولیدشده.
•فقط GCC: افزودن -fpch-preprocess هنگام کامپایل.
3.برای Clang، گزینه -fno-pch-timestamp را جهت غیرفعال کردن بررسی برچسب‌های زمانی اضافه کنید.

عیب‌یابی:

•بدون پیکربندی مناسب، ccache به استفاده از هدر غیر پیش‌کامپایل‌شده (در صورت وجود) بازمی‌گردد.
•اگر راهکار جایگزینی وجود نداشته باشد، عبارت “Preprocessing failed” را در آمارها خواهید دید.
•فایل‌هایی که به جای محافظ‌های شمول از #pragma once استفاده می‌کنند ممکن است باعث ایجاد مشکل شوند.

در حال حاضر Ccache از ماژول‌های استاندارد C++20 پشتیبانی نمی‌کند.

با این حال، پشتیبانی محدودی از “Clang modules” (گزینهٔ -fmodules) با این شرایط وجود دارد:

•مقدار sloppiness را روی modules تنظیم کنید.
•هر دو حالت direct mode و depend mode را فعال کنید.

نحوه کارکرد آن به این صورت است:

•ابزار Ccache فایل‌های module.modulemap را هش می‌کند اما کَش ماژول باینری Clang را نادیده می‌گیرد.
•این روش کار می‌کند زیرا فایل‌های یکسان module.modulemap باید نتایج کَش‌شدهٔ سازگاری تولید کنند.

نکته

حالت پیش‌پردازنده (preprocessor mode) اطلاعات کافی را برای پشتیبانی ماژول در depend mode فراهم نمی‌کند. هنگام استفاده از حالت پیش‌پردازنده، Clang اطلاعات کافی جهت امکان هش کردن فایل‌های module.modulemap را ارائه نمی‌دهد.

گروهی از توسعه‌دهندگان می‌توانند با به اشتراک‌گذاری یک دایرکتوری کَش محلی، نرخ برخورد کَش (cache hit rate) را افزایش دهند. برای به اشتراک‌گذاری یک کَش محلی بدون عوارض جانبی ناخواسته، باید شرایط زیر برقرار باشد:

•از یک دایرکتوری کَش یکسان استفاده کنید.
•اطمینان حاصل کنید که گزینهٔ پیکربندی hard_link روی false تنظیم شده باشد (که حالت پیش‌فرض است).
•اطمینان حاصل کنید که تمام کاربران در یک گروه یکسان عضویت دارند.
•گزینهٔ پیکربندی umask را روی 002 تنظیم کنید. این امر تضمین می‌کند که فایل‌های کَش‌شده برای تمام افراد حاضر در گروه قابل دسترس باشند.
•اطمینان حاصل کنید که تمام کاربران در تمام پوشهٔ کَش مجوز نوشتن دارند (و این‌که شما به تمام کاربران این کَش مشترک اعتماد دارید).
•اطمینان حاصل کنید که بیت setgid روی تمام دایرکتوری‌های درون کَش تنظیم شده است. این به سیستم‌فایل اعلام می‌کند که مالکیت گروهی را برای دایرکتوری‌های جدید به ارث ببرد. دستور زیر ممکن است برای این منظور مفید باشد: 
find $CCACHE_DIR -type d | xargs chmod g+s

دلیل اجتناب از حالت پیوند سخت (hard link mode) این است که پیوندهای سخت عوارض جانبی ناخواسته‌ای ایجاد می‌کنند؛ زیرا تمام پیوندها به یک فایل کَش‌شده در برچسب زمانی تغییر (timestamp) آن فایل مشترک هستند. این امر موجب می‌شود در سیستم‌های ساخت مبتنی بر برچسب زمانی، هر زمان که کاربر دیگری به یک فایل موجود پیوند دهد، وابستگی‌های کاذب فعال شوند. معمولاً کاربران متوجه خواهند شد که کتابخانه‌ها و فایل‌های باینری آن‌ها بدون دلیل مشخصی مجدداً پیوند (relink) داده می‌شوند.

همچنین ممکن است بخواهید مطمئن شوید که یک دایرکتوری پایه (base directory) به‌درستی تنظیم شده باشد، همان‌طور که در بخش‌های قبلی توضیح داده شد..SH "اشتراک‌گذاری کَش روی NFS (SHARING A CACHE ON NFS)"

امکان قرار دادن دایرکتوری کَش روی یک سیستم فایل NFS (یا سیستم‌های فایل مشابه) وجود دارد، اما به یاد داشته باشید که:

•قرار داشتن کَش روی NFS ممکن است سرعت کامپایل را کاهش دهد. حتماً چند آزمایش محک‌زنی (benchmarking) انجام دهید تا ببینید آیا ارزشش را دارد یا خیر.
•ابزار ccache به‌طور کامل و دقیق روی NFS آزمایش نشده است.

یک ترفند این است که temporary_dir را روی دایرکتوری در میزبان محلی تنظیم کنید تا از ترافیک NFS برای فایل‌های موقت جلوگیری شود.

توصیه می‌شود هنگام استفاده از کَش مشترک، از نسخه یکسان سیستم‌عامل استفاده شود. اگر نسخه‌های سیستم‌عامل متفاوت باشند، احتمالاً فایل‌های include سیستم تفاوت خواهند داشت و نرخ اصابت کَش (cache hit) میان سیستم‌ها بسیار کم یا صفر خواهد بود. یک راه برای بهبود نرخ اصابت کَش در این وضعیت، تنظیم sloppiness روی system_headers به منظور نادیده گرفتن سرآیندهای سیستم است.

یک جایگزین برای قرار دادن دایرکتوری اصلی کَش روی NFS، راه‌اندازی کَش فایل ذخیره‌سازی از راه دور (remote storage file cache) است.

روش توصیه‌شده برای ترکیب ccache با سایر پوشش‌های کامپایلر (مانند “distcc”) این است که اجازه دهید ccache پوشش کامپایلر را اجرا کند. این کار با تعریف prefix_command انجام می‌شود، برای نمونه با تنظیم متغیر محیطی CCACHE_PREFIX به نام پوشش (مانند distcc). در این صورت ccache هنگام اجرای کامپایلر، دستور مشخص‌شده را پیشوند خط فرمان قرار می‌دهد. برای تعیین چندین دستور پیشوند، prefix_command را به فهرستی از دستورها که با فاصله از هم جدا شده‌اند تنظیم کنید.

مگر اینکه compiler_check را روی دستور مناسبی تنظیم کرده باشید (توضیحات مربوط به این گزینه پیکربندی را ببینید)، توصیه نمی‌شود از قالب ccache anotherwrapper compiler args به عنوان دستور کامپایل استفاده کنید. همچنین توصیه نمی‌شود از تکنیک ماسک‌گذاری (masquerading) برای پوشش کامپایلر دیگر استفاده شود. دلیل این است که به‌طور پیش‌فرض، ccache در هر دو حالت به جای کامپایلر واقعی، mtime و اندازه پوشش دیگر را هش می‌کند، که این یعنی:

•ارتقاهای کامپایلر به درستی شناسایی نخواهند شد.
•نتایج کَش‌شده میان کامپایل‌های با و بدون پوشش دیگر به اشتراک گذاشته نخواهند شد.

نکته جزئی دیگر این است که اگر از prefix_command استفاده شود، ccache هنگام اجرای پیش‌پردازنده (preprocessor)، پوشش دیگر را فراخوانی نخواهد کرد که این امر کارایی را افزایش می‌دهد. اگر می‌خواهید هنگام پیش‌پردازش نیز پوشش دیگر فراخوانی شود (معمولاً با افزودن -E)، می‌توانید از prefix_command_cpp استفاده کنید.

•حالت مستقیم (direct mode) در برخی سناریوهای نادر در شناسایی فایل‌های سرآیند جدید ناموفق است. بخش The direct mode در بالا را ببینید.

برای درک اقداماتی که ccache انجام می‌دهد، می‌توانید لاگ‌گیری اشکال‌زدایی را با تنظیم debug روی true یا استفاده از متغیر محیطی CCACHE_DEBUG=1 فعال کنید. برای جزئیات بخش CACHE DEBUGGING را ببینید.

همچنین می‌توانید از ccache -s برای مشاهده نرخ‌های اصابت کَش، دلایل عدم اصابت (miss reasons) و سایر معیارهای کارایی استفاده کنید.

ابزار ccache به‌گونه‌ای طراحی شده است که با حداقل پیکربندی به خوبی کار کند، اما می‌توانید کارایی را بیش از این بهینه‌سازی کنید:

•دایرکتوری کَش را روی حافظه ذخیره‌سازی سریع قرار دهید (SSD ترجیح داده می‌شود).
•از کافی بودن حافظه RAM اطمینان حاصل کنید تا فایل‌های کَش‌شده در کَش سیستم‌فایل باقی بمانند.
•استفاده از حافظه ذخیره‌سازی از راه دور را برای اشتراک کَش مد نظر قرار دهید.

برای نظارت بر اثربخشی کَش، خروجی ccache -s را قبل و بعد از ساخت‌ها مقایسه کنید تا مشکلات را شناسایی نمایید.

اگر مقدار “preprocessed cache hits” به جای “direct cache hits” افزایش یابد، ccache در حال بازگشت به حالت کندتر پیش‌پردازنده است. دلایل این موضوع عبارتند از:

•تغییرات کد منبع که تأثیری بر خروجی پیش‌پردازنده ندارند
•تغییرات در گزینه‌های مربوط به include (مانند -I، -include، -D) که کد پیش‌پردازش‌شده نهایی را تغییر نمی‌دهند
•استفاده از گزینه‌های پشتیبانی‌نشده پیش‌پردازنده مانند -Xpreprocessor یا -Wp,* (به‌جز -Wp,-MD,<path>، -Wp,-MMD,<path>، -Wp,-D<define>)
•اولین کامپایل پس از تغییر دادن base_dir
•فایل‌های include با برچسب‌های زمانی جدیدتر از زمان آغاز به کار ccache (بخش HANDLING OF NEWLY CREATED SOURCE FILES را ببینید)
•کد حاوی __TIME__، __DATE__ یا __TIMESTAMP__ که موجب تحمیل حالت پیش‌پردازنده می‌شود (اگر از این ماکروها عملاً استفاده نمی‌شود یا نیازی به مقادیر جاری ندارید، sloppiness را روی time_macros تنظیم کنید)
•تغییر مسیر فایل ورودی (بر بسط ماکروی __FILE__ اثر می‌گذارد)

اگر کدهای یکسان منجر به اصابت کَش نمی‌شوند، برخی از دلایل احتمالی عبارتند از:

•ماکروهای زمان/تاریخ یا کدهای تولیدشده با برچسب‌های زمانی/شمارنده‌های ساخت
•پاک‌سازی کَش به دلیل محدودیت‌های اندازه
•تفاوت‌های محیطی که بر روند کامپایل اثر می‌گذارند

شمارنده‌های خطای متداول:

•“Multiple source files”: کامپایلر با چندین فایل منبع به‌طور هم‌زمان فراخوانی شده است (توسط ccache پشتیبانی نمی‌شود).
•“Unsupported compiler option”: لاگ‌گیری اشکال‌زدایی را فعال کنید تا ببینید کدام گزینه رد شده است.
•“Preprocessing failed”: می‌تواند نشان‌دهنده مشکلات سرآیند از پیش کامپایل‌شده باشد (بخش PRECOMPILED HEADERS را ببینید).
•“Could not use precompiled header”: برای پیش‌نیازهای راه‌اندازی به بخش PRECOMPILED HEADERS مراجعه کنید.
•“Could not use modules”: برای نیازمندی‌های پیکربندی بخش C++ MODULES را ببینید و بررسی کنید که کدام گزینه کامپایلر رد شده است.

باید توجه داشت که ccache در برابر مشکلات عمومی ذخیره‌سازی آسیب‌پذیر است. اگر یک فایل شیء معیوب به هر دلیلی وارد کَش شود، مسلماً معیوب باقی خواهد ماند. برخی از دلایل احتمالی برای ایجاد فایل‌های شیء نادرست عبارتند از: سخت‌افزار معیوب (دیسک درایو، کنترل‌کنندهٔ دیسک، حافظه و غیره)، درایورها یا سیستم‌های فایل دارای باگ، یک prefix_command نامناسب یا لفاف کامپایلر (compiler wrapper). در صورت بروز این مشکل، ساده‌ترین راه برای رفع آن به این ترتیب است:

1.پروژه را طوری کامپایل کنید که فایل شیء معیوب در درخت ساخت (build tree) ایجاد شود.
2.فایل شیء معیوب را از درخت ساخت حذف کنید.
3.با مقداردهی و فعال بودن CCACHE_RECACHE مجدداً عملیات ساخت را انجام دهید.

یک راهکار جایگزین این است که در صورت عدم تمایل به نگهداری سایر نتایج کَش‌شده، کل کَش را با دستور ccache -C پاک کنید.

تاکنون هیچ مشکلی مبنی بر تولید بازتولیدپذیر فایل‌های شیء خراب توسط ccache گزارش نشده است. این بدان معنا نیست که چنین اتفاقی هرگز رخ نمی‌دهد، بنابراین اگر با موردی تکرارپذیر مواجه شدید، لطفاً آن را گزارش دهید.

قدردانی‌ها، اطلاعات فهرست پستی، دستورالعمل‌های گزارش باگ، کد منبع و موارد دیگر را می‌توانید در وب‌سایت ccache بیابید: https://ccache.dev.

برنامهٔ ccache در ابتدا توسط Andrew Tridgell نوشته شد و در حال حاضر توسط Joel Rosdahl توسعه یافته و نگهداری می‌شود. برای مشاهدهٔ فهرست مشارکت‌کنندگان به AUTHORS.txt یا AUTHORS.html و https://ccache.dev/credits.html مراجعه کنید.

2026-09-04 Ccache 4.14