.\" Automatically generated by Pandoc 3.7.0.2
.\"
.TH "BEAR" "1" "September 5, 2026" "Bear User Manuals"
.SH "نام (NAME)"
bear \- تولید پایگاه‌داده کامپایل برای ابزارهای مبتنی بر Clang
.SH "خلاصه دستور (SYNOPSIS)"
\f[B]bear\f[R] [\f[I]OPTIONS\f[R]] \-\- \f[I]BUILD_COMMAND\f[R]\&...
.PP
\f[B]bear intercept\f[R] [\f[I]OPTIONS\f[R]] \-\-output \f[I]FILE\f[R]
\-\- \f[I]BUILD_COMMAND\f[R]\&...
.PP
\f[B]bear semantic\f[R] [\f[I]OPTIONS\f[R]]
.PP
\f[B]bear parse\-sh\f[R] [\f[I]OPTIONS\f[R]]
.SH "توضیحات (DESCRIPTION)"
ابزار Bear یک پایگاه‌داده کامپایل JSON تولید می‌کند
(\f[CR]compile_commands.json\f[R]).
ابزارهای مبتنی بر Clang مانند clangd و clang\-tidy این فایل را می‌خوانند تا دریابند هر فایل مبدا از پروژه چگونه کامپایل می‌شود: با کدام کامپایلر، چه فلگ‌هایی و از چه شاخه‌ای.
سامانه‌های ساخت این موضوع را می‌دانند، اما بیشتر آن‌ها آن را صادر نمی‌کنند؛ ابزار Bear آن را از خود فرایند ساخت بازیابی می‌کند.
.PP
ابزار Bear در دو مرحله کار می‌کند.
نخست، دستوراتی را که یک ساخت اجرا می‌کند ضبط کرده و آن‌ها را به صورت جریانی از رویدادهای اجرا می‌نویسد.
این ضبط یا یک اجرای واقعی ساخت را نظاره می‌کند یا متن یک اجرای آزمایشی (dry run) را تجزیه می‌نماید.
سپس تحلیل معنایی، فراخوانی‌های کامپایلر را در میان آن رویدادها شناسایی کرده، خطوط فرمان آن‌ها را تجزیه می‌کند و پایگاه‌داده کامپایل را می‌نویسد.
.SS "حالت‌ها (Modes)"
.TP
\f[B]حالت ترکیبی (Combined mode)\f[R] (پیش‌فرض)
دستور \f[CR]bear \-\- <build command>\f[R] ساخت را اجرا می‌کند، ضبط و تحلیل را در یک مرحله انجام می‌دهد و پایگاه‌داده را می‌نویسد.
این شیوه پیشنهادی استفاده از Bear است: این حالت دستوراتی را که ساخت واقعاً اجرا می‌کند نظاره می‌کند، بنابراین نتیجه دقیق است.
هرگاه بتوانید ساخت را اجرا کنید، از آن استفاده نمایید.
.TP
\f[B]حالت رهگیری (Intercept mode)\f[R]
دستور \f[CR]bear intercept\f[R] ساخت را اجرا می‌کند اما تنها به ضبط می‌پردازد و جریان خام رویدادها را در یک فایل می‌نویسد.
زمانی مفید است که فرایند ساخت پرهزینه باشد و بخواهید آن را یک‌بار اجرا کنید و رویدادها را چندین بار پردازش نمایید، مثلاً برای آزمایش پیکربندی‌های خروجی متفاوت.
.TP
\f[B]حالت معنایی (Semantic mode)\f[R]
دستور \f[CR]bear semantic\f[R] هیچ ساختی را اجرا نمی‌کند: یک فیلتر است که جریان رویداد را (از \f[CR]bear intercept\f[R] یا هر تولیدکننده دیگری با قالب رویداد مستندشده) می‌خواند و پایگاه‌داده کامپایل را می‌نویسد.
آن را با حالت intercept ترکیب کنید تا پایگاه‌داده را بدون ساخت مجدد دوباره تولید نمایید.
.TP
\f[B]حالت تجزیه شل (Parse\-sh mode)\f[R]
دستور \f[CR]bear parse\-sh\f[R] پایگاه‌داده کامپایل را از متن دستورات شل، بدون اجرای هیچ دستوری، تولید می‌کند.
ورودی معمول خروجی آزمایشی یک سامانه ساخت (\f[CR]make \-n\f[R]) یا لاگ ذخیره‌شده ساخت است:
این یک تجزیه‌گر متنی است و ذاتاً وفاداری کمتری نسبت به رهگیری دارد؛ زمانی سراغ آن بروید که امکان اجرای ساخت وجود ندارد، مثلاً برای بازیابی پایگاه‌داده از لاگ CI.
محدودیت‌های آن را در بخش دستورات (COMMANDS) ببینید.
.SS "روش‌های رهگیری (Interception methods)"
خود رهگیری دارای دو روش است که در فایل پیکربندی قابل انتخاب هستند.
\f[B]پیش‌بارگذاری (Preload)\f[R] (پیش‌فرض در لینوکس و BSDها) یک کتابخانه کوچک را به هر فرایندی که ساخت آغاز می‌کند تزریق کرده و فراخوانی‌های \f[CR]exec()\f[R] آن را نظاره می‌کند.
\f[B]پوشش‌دهنده (Wrapper)\f[R] (پیش‌فرض در macOS و ویندوز) کامپایلرهای شناخته‌شده را با یک باینری اجرایی پوشش‌دهنده گزارش‌گر جایگزین می‌کند.
روش Preload برای ساخت شفاف است اما نمی‌تواند باینری‌های اجرایی پیوندیافته ایستا (statically linked) را نظاره کند، و در ویندوز و در macOS هنگامی که حفاظت یکپارچگی سامانه (SIP) فعال است در دسترس نیست؛ اجبار آن در این شرایط یک خطای زمان راه‌اندازی است که نام حالت wrapper را ذکر می‌کند، نه یک جایگزین خاموش.
حالت Wrapper در تمام پلتفرم‌ها کار می‌کند، اما ساخت باید پوشش‌دهنده را شناسایی کند: مرحله پیکربندی («configure») که کامپایلرها را کشف می‌کند باید خود تحت Bear اجرا شود (عیب‌یابی را ببینید).
.SS "گزینه‌ها (OPTIONS)"
.TP
\f[B]\-c, \-\-config\f[R] \f[I]FILE\f[R]
مسیر فایل پیکربندی.
روش رهگیری، شناسایی کامپایلر، فیلتر کردن مبدا، مدیریت موارد تکراری و قالب‌بندی خروجی را کنترل می‌کند (بخش پیکربندی را ببینید).
در صورتی که پیش از یک زیردستور داده شود، به آن زیردستور نیز اعمال می‌شود.
.TP
\f[B]\-o, \-\-output\f[R] \f[I]FILE\f[R]
مسیر پایگاه‌داده کامپایل جهت نوشتن (پیش‌فرض: \f[CR]compile_commands.json\f[R]).
مقدار \f[CR]\-\f[R] در اینجا پذیرفته نمی‌شود، زیرا در حالت ترکیبی خروجی استاندارد متعلق به ساخت است.
برای ارسال جریانی پایگاه‌داده، از \f[CR]bear semantic \-\-output \-\f[R] استفاده کنید (بخش دستورات را ببینید).
.TP
\f[B]\-a, \-\-append\f[R]
الحاق به یک فایل خروجی موجود به جای بازنویسی کامل آن.
ورودی‌های جدید پیش از ورودی‌های موجود قرار می‌گیرند، به طوری که تازه‌ترین فراخوانی یک فایل بازسازی‌شده در فیلتر موارد تکراری باقی مانده و جایگزین ورودی کهنه می‌شود (بخش \f[CR]duplicates\f[R] زیر پیکربندی را ببینید).
.TP
\f[B]\-\-overwrite\f[R]
جایگزینی فایل خروجی فقط با ورودی‌های این اجرا.
این رفتاری است که Bear در صورت مشخص نشدن هیچ پرچمی انجام می‌دهد؛ این پرچم وجود دارد تا یک اسکریپت بتواند رفتاری را که به آن وابسته است صراحتاً نام ببرد نه اینکه به پیش‌فرض تکیه کند.
ارائه همزمان آن با \f[CR]\-\-append\f[R] خطاست.
در نگارش‌های آینده الحاق به عنوان پیش‌فرض خواهد بود، و اسکریپتی که امروزه \f[CR]\-\-overwrite\f[R] را ارسال می‌کند، رفتار فعلی خود را حفظ خواهد کرد.
.TP
\f[B]\-h, \-\-help\f[R]
چاپ راهنما.
.TP
\f[B]\-V, \-\-version\f[R]
چاپ نسخه.
.SH "دستورات (COMMANDS)"
.SS bear intercept
ساخت را اجرا کرده و رویدادهای اجرا را در یک فایل ضبط می‌کند، بدون آنکه آن‌ها را تحلیل کند.
.PP
\f[B]bear intercept\f[R] [\f[I]OPTIONS\f[R]] \-\-output \f[I]FILE\f[R]
\-\- \f[I]BUILD_COMMAND\f[R]\&...
.TP
\f[B]\-o, \-\-output\f[R] \f[I]FILE\f[R]
مسیر فایل رویداد جهت نوشتن.
الزامی است، و \f[CR]\-\f[R] پذیرفته نمی‌شود: ساخت مالک خروجی استاندارد است و هیچ نام فایل رویداد پیش‌فرضی وجود ندارد.
.SS bear semantic
جریان رویداد را می‌خواند و پایگاه‌داده کامپایل را می‌نویسد.
هیچ ساختی را اجرا نمی‌کند، بنابراین به عنوان یک فیلتر ساده عمل می‌کند: پیام‌های تشخیصی به خطای استاندارد می‌روند و هر دو سر می‌توانند جریان‌های استاندارد باشند.
.PP
\f[B]bear semantic\f[R] [\f[I]OPTIONS\f[R]]
.TP
\f[B]\-i, \-\-input\f[R] \f[I]FILE\f[R]
مسیر فایل رویداد برای خواندن (پیش‌فرض: \f[CR]\-\f[R]، ورودی استاندارد).
هر تولیدکننده جریان رویداد منطبق می‌تواند خروجی خود را به آن لوله‌کشی (pipe) کند.
هنگامی که ورودی استاندارد یک ترمینال باشد یا جریان خالی باشد، یک اعلان در خطای استاندارد چاپ می‌شود.
.TP
\f[B]\-o, \-\-output\f[R] \f[I]FILE\f[R]
مسیر پایگاه‌داده کامپایل برای نوشتن (پیش‌فرض: \f[CR]compile_commands.json\f[R]).
برای نوشتن در خروجی استاندارد \f[CR]\-\f[R] را ارسال کنید؛ آن نوشتن نه اتمیک است و نه قابل الحاق، بنابراین \f[CR]\-\-output \-\f[R] همراه با \f[CR]\-\-append\f[R] رد می‌شود.
.TP
\f[B]\-a, \-\-append\f[R]
همانند حالت ترکیبی: ورودی‌های جدید را پیش از ورودی‌های موجود در فایل خروجی قرار می‌دهد.
.TP
\f[B]\-\-overwrite\f[R]
همانند حالت ترکیبی: مشخص کردن صریح پیش‌فرض فعلی.
همراه با \f[CR]\-\-append\f[R] پذیرفته نمی‌شود.
.SS bear parse\-sh
پایگاه‌داده کامپایل را از متن دستورات شل، بدون اجرای هیچ برنامه‌ای، تولید می‌کند.
ورودی معمول خروجی آزمایشی سامانه ساخت مانند \f[CR]make \-n\f[R] یا یک لاگ ساخت ذخیره‌شده است:
.IP
.EX
make \-n | bear parse\-sh
.EE
.PP
\f[B]bear parse\-sh\f[R] [\f[I]OPTIONS\f[R]]
.TP
\f[B]\-i, \-\-input\f[R] \f[I]FILE\f[R]
مسیر متن شل برای تجزیه (پیش‌فرض: \f[CR]\-\f[R]، ورودی استاندارد).
.TP
\f[B]\-o, \-\-output\f[R] \f[I]FILE\f[R]
مسیر پایگاه‌داده کامپایل جهت نوشتن (پیش‌فرض: \f[CR]compile_commands.json\f[R]).
ارسال \f[CR]\-\f[R] برای نوشتن در خروجی استاندارد؛ این نوشتن نه اتمیک است و نه قابل الحاق، بنابراین \f[CR]\-\-output \-\f[R] همراه با \f[CR]\-\-append\f[R] رد می‌شود.
.TP
\f[B]\-a, \-\-append\f[R]
همانند حالت ترکیبی: قرار دادن ورودی‌های جدید پیش از موارد موجود در فایل خروجی.
.TP
\f[B]\-\-overwrite\f[R]
همانند حالت ترکیبی: نام بردن صریح پیش‌فرض فعلی.
همراه با \f[CR]\-\-append\f[R] پذیرفته نمی‌شود.
.TP
\f[B]\-C, \-\-directory\f[R] \f[I]DIR\f[R]
شاخه کاری اولیه برای دستورات تجزیه‌شده.
از آن برای ورودی ضبط‌شده در جایی دیگر (یک لاگ CI، یک اجرای آزمایشی از نسخه‌ای دیگر) استفاده کنید.
یک مسیر مطلق بدهید؛ نیازی نیست شاخه روی این رایانه وجود داشته باشد.
.PP
دستورات شناسایی‌شده در متن از همان مرحله تحلیل معنایی و خروجی یک ساخت رهگیری‌شده عبور می‌کنند، بنابراین پیکربندی دقیقاً مشابه حالت ترکیبی اعمال می‌شود.
دستورات تجزیه‌شده‌ای که فراخوانی کامپایلر نیستند (\f[CR]ar\f[R]، \f[CR]mv\f[R]، \f[CR]mkdir\f[R]) هیچ ورودی تولید نمی‌کنند.
.PP
این ابزار زیرمجموعه مستندشده‌ای از نحو شل POSIX را می‌فهمد: شکستن کلمات و نقل‌قول‌ها؛ جداکننده‌های \f[CR];\f[R]، \f[CR]&&\f[R]، \f[CR]||\f[R]، \f[CR]&\f[R] و \f[CR]|\f[R]؛ کامنت‌ها؛ تغییرمسیرها؛ \f[CR]cd\f[R]؛ گروه‌های آکولادی (\f[CR]{ ...; }\f[R] که تغییر \f[CR]cd\f[R] آن‌ها پس از آکولاد بسته ادامه دارد)؛ و نشانگرهای \f[CR]Entering directory\f[R] / \f[CR]Leaving directory\f[R] دستور make، که شاخه کاری را در یک ساخت بازگشتی ردیابی می‌کنند.
زیر-makeها این نشانگرها را به طور پیش‌فرض چاپ می‌کنند؛ دستور \f[CR]make \-nw\f[R] را اجرا کنید تا make سطح بالا نیز آن‌ها را چاپ کند، تا خود لاگ ریشه ساخت را مشخص نماید.
خطی که از هر چیزی خارج از این زیرمجموعه استفاده کند نادیده گرفته شده و در خطای استاندارد همراه با شماره خط و دلیل گزارش می‌شود.
این شامل زیرشل‌ها، جایگزینی فرمان، گسترش پارامتر، تطبیق الگو (glob) در موقعیت فایل اجرایی، here-documents، نقل‌قول‌های بسته نشده و کلمات کلیدی شل مانند \f[CR]if\f[R] یا \f[CR]for\f[R] است.
اجرا تا زمانی که حداقل یک خط به عنوان دستور تجزیه شود موفق خواهد بود.
.PP
رهگیری همچنان پیش‌فرض با وفاداری بالاتر باقی می‌ماند: این روش فراخوانی‌های \f[CR]exec()\f[R] را که ساخت واقعاً انجام می‌دهد نظاره می‌کند، در حالی که \f[CR]bear parse\-sh\f[R] رویدادهای تقریبی را از متنی که سامانه ساخت برای چاپ برگزیده بازسازی می‌کند.
یک اجرای آزمایشی می‌تواند دستورات را حذف کند (make بازگشتی همیشه \f[CR]\-n\f[R] را منتشر نمی‌کند، و دستورات پشت مبداهایی که هنوز تولید نشده‌اند هرگز چاپ نمی‌شوند)؛ محیط و \f[CR]PATH\f[R] استفاده‌شده برای حل نام فایل‌های اجرایی همان‌های زمان تجزیه هستند نه ساخت واقعی؛ و فقط متن شل POSIX پشتیبانی می‌شود.
هر زمان ساخت واقعاً قابل اجرا باشد، \f[CR]bear \-\- <build command>\f[R] را ترجیح دهید.
.PP
فایل‌های مبدا ذکرشده در دستورات تجزیه‌شده نیازی به وجود ندارند: ورودی‌ها تنها از روی متن بازسازی می‌شوند.
تنها استثنا قالب مسیر \f[CR]canonical\f[R] است که پیوندهای نمادین روی دیسک را حل می‌کند؛ در صورت غیاب مبداها، در عوض \f[CR]absolute\f[R] را پیکربندی کنید (بخش \f[CR]format.paths\f[R] زیر پیکربندی را ببینید).
.SH "خروجی (OUTPUT)"
ابزار Bear یک پایگاه‌داده کامپایل JSON مطابق با مشخصات Clang JSON Compilation Database می‌نویسد: یک آرایه JSON از اشیاء ورودی با فیلدهای زیر:
.TP
\f[B]directory\f[R]
شاخه کاری کامپایل.
.TP
\f[B]file\f[R]
فایل مبدا واحد ترجمه اصلی.
.TP
\f[B]arguments\f[R]
دستور کامپایل به صورت آرایه‌ای از رشته‌ها.
این حالت پیش‌فرض است؛ Bear آن را به \f[CR]command\f[R] ترجیح می‌دهد زیرا از مشکلات فرار شل (shell\-escaping) جلوگیری می‌کند.
.TP
\f[B]command\f[R]
دستور کامپایل به عنوان یک رشته تک فرار داده‌شده (زمانی نوشته می‌شود که \f[CR]format.entries.use_array_format\f[R] برابر \f[CR]false\f[R] باشد).
.TP
\f[B]output\f[R]
فایل تولیدشده توسط کامپایل (اختیاری).
.PP
به طور پیش‌فرض Bear مسیرها را تغییر نمی‌دهد: هر ورودی آن‌ها را همان‌طور که در فراخوانی رهگیری‌شده ظاهر شده بودند ثبت می‌کند، بنابراین \f[CR]file\f[R] و \f[CR]output\f[R] اغلب نسبت به \f[CR]directory\f[R] نسبی هستند.
از \f[CR]format.paths\f[R] در پیکربندی برای نرمال‌سازی آن‌ها استفاده کنید.
.PP
دو کامپایلر شکلی از ورودی تولید می‌کنند که دانستن آن ارزشمند است:
.IP \(bu 2
\f[B]swiftc\f[R]: فراخوانی کل پودمان با ذکر چندین مبدا \f[CR].swift\f[R]، یک ورودی به ازای هر مبدا تولید می‌کند که هر کدام آرگومان‌های کامل فراخوانی را به همراه دارند (تمام مبداهای پودمان، نه فقط مال خودش).
این مطابق شکلی است که CMake منتشر می‌کند و SourceKit\-LSP مصرف می‌نماید.
داده‌های تکراری آرگومان مورد انتظار است، نه یک اشکال.
کارهای داخلی \f[CR]swift\-frontend\f[R] که \f[CR]swiftc\f[R] ایجاد می‌کند به طور خودکار فیلتر می‌شوند.
.IP \(bu 2
\f[B]valac\f[R]: یک ورودی به ازای هر فراخوانی \f[CR]valac\f[R] (کامپایلر valac تمام مبداهای \f[CR].vala\f[R]/\f[CR].gs\f[R] یک هدف را با هم به عنوان یک واحد کامپایل می‌کند)؛ فیلد \f[CR]file\f[R] ورودی همان اولین مبدا است و تمام مبداها در دستور نگه داشته می‌شوند.
از آنجا که valac به C ترجمه می‌کند و نتیجه را کامپایل می‌نماید، پایگاه‌داده همچنین شامل ورودی‌هایی برای فایل‌های C تولیدشده است (برای پیامدهای clangd بخش عیب‌یابی را ببینید).
.SH "پیکربندی (CONFIGURATION)"
ابزار Bear یک فایل پیکربندی YAML را می‌خواند که از طریق جستجو (بخش فایل‌ها را ببینید) پیدا شده یا با \f[CR]\-\-config\f[R] مشخص می‌شود.
بدون آن، پیش‌فرض‌های داخلی اعمال می‌شوند.
فایلی که نوشته می‌شود باید \f[CR]schema\f[R] را مشخص کند؛ هر بخشی زیر آن اختیاری است.
مثال زیر تمامی بخش‌ها را نشان می‌دهد:
.IP
.EX
schema\f[B]:\f[R] \(dq4.2\(dq
intercept\f[B]:\f[R]
  mode\f[B]:\f[R] wrapper\f[I]              # پیش‌فرض: preload روی لینوکس و BSDها\f[R]
compilers\f[B]:\f[R]
  \f[B]\-\f[R] path\f[B]:\f[R] /usr/bin/cc
    as\f[B]:\f[R] gcc
  \f[B]\-\f[R] path\f[B]:\f[R] /usr/local/bin/gcc
    ignore\f[B]:\f[R] true
sources\f[B]:\f[R]
  directories\f[B]:\f[R]
    \f[B]\-\f[R] path\f[B]:\f[R] /project/tests
      action\f[B]:\f[R] exclude
  files\f[B]:\f[R]
    \f[B]\-\f[R] pattern\f[B]:\f[R] \(dqmoc_*.cpp\(dq
      action\f[B]:\f[R] exclude
    \f[B]\-\f[R] pattern\f[B]:\f[R] \(dq*.pb.cc\(dq
      action\f[B]:\f[R] exclude
duplicates\f[B]:\f[R]
  match_on\f[B]:\f[R]\f[I]                  # پیش‌فرض: directory, file\f[R]
    \f[B]\-\f[R] file
    \f[B]\-\f[R] arguments
format\f[B]:\f[R]
  paths\f[B]:\f[R]
    directory\f[B]:\f[R] canonical\f[I]     # پیش‌فرض: as\-is\f[R]
    file\f[B]:\f[R] canonical\f[I]          # پیش‌فرض: as\-is\f[R]
  entries\f[B]:\f[R]
    use_array_format\f[B]:\f[R] true
    include_output_field\f[B]:\f[R] true
  arguments\f[B]:\f[R]
    from_response_files\f[B]:\f[R] false
    from_environment\f[B]:\f[R] true
headers\f[B]:\f[R]
  enabled\f[B]:\f[R] true\f[I]               # پیش‌فرض: false\f[R]
  strategy\f[B]:\f[R] siblings
.EE
.PP
هر مقدار بالا جنبه توضیحی دارد؛ مقادیر غیرپیش‌فرض به صورت درون‌خطی حاشیه‌نویسی شده‌اند.
هر بخش در زیر پیش‌فرض‌های واقعی خود را بیان می‌کند.
.SS intercept
روش رهگیری را کنترل می‌کند (برای مقایسه به بخش توضیحات مراجعه کنید):
.IP \(bu 2
\f[B]mode\f[R]: مقدار \f[CR]preload\f[R] (پیش‌فرض در لینوکس و BSDها) یا \f[CR]wrapper\f[R] (پیش‌فرض در macOS و ویندوز؛ در همه جا کار می‌کند).
.SS compilers
راهنمایی‌هایی برای شناسایی کامپایلر.
ابزار Bear درایورهای سازگار با GCC و Clang (شامل نام‌های پیشونددار کامپایل متقاطع)، درایورهای رایج کامپایلرهای تجاری و اسمبلرهای مستقل، \f[CR]swiftc\f[R] و \f[CR]valac\f[R]، راه‌اندازهای کامپایلر و پوشش‌دهنده‌های کامپایلر MPI را می‌شناسد.
دستور \f[CR]bear semantic \-\-print\-compilers\f[R] را برای فهرست کامل نام‌های کامپایلر شناخته‌شده اجرا کنید.
.PP
چند رفتار شناسایی ارزش دانستن دارد:
راه‌اندازهای کامپایلر (\f[CR]ccache\f[R]، \f[CR]distcc\f[R]، \f[CR]sccache\f[R]، \f[CR]icecc\f[R]) از دستور ثبت‌شده حذف می‌شوند: مثلاً \f[CR]ccache gcc \-c main.c\f[R] یک ورودی برای \f[CR]gcc \-c main.c\f[R] ایجاد می‌کند.
پوشش‌دهنده‌های کامپایلر MPI همان‌طور که فراخوانی شده‌اند ثبت می‌شوند و به کامپایلری که پوشش می‌دهند گسترش نمی‌یابند.
واحدهای رابط پودمان C++20 (مانند \f[CR].cppm\f[R]، \f[CR].ixx\f[R] و مشابه آن) به عنوان مبدا شناخته می‌شوند، در حالی که مصنوعات پیش‌کامپایل‌شده \f[CR].pcm\f[R] هرگز به عنوان \f[CR]file\f[R] ظاهر نمی‌شوند.
.PP
در حالت wrapper، این بخش همچنین تصمیم می‌گیرد چه مواردی پوشش داده شوند.
اگر ورودی دیگری جز موارد \f[CR]ignore\f[R] وجود نداشته باشد، Bear هنگام راه‌اندازی متغیر PATH را پویش کرده و هر کامپایلری را که می‌شناسد پوشش می‌دهد.
به محض اینکه یک ورودی نادیده گرفته نشود، Bear دقیقاً مسیرهای فهرست‌شده را پوشش می‌دهد و از پویش صرف‌نظر می‌کند.
کامپایلرهای مشخص‌شده در متغیرهای محیطی کامپایلر (\f[CR]CC\f[R]، \f[CR]CXX\f[R] و مشابه آن) در هر دو حالت پوشش داده می‌شوند.
حالت Preload تحت تأثیر قرار نمی‌گیرد: این روش هر برنامه اجراشده را صرف‌نظر از این بخش رهگیری می‌کند.
.PP
زمانی از این بخش استفاده کنید که یک کامپایلر در مسیری مشخص شناخته نشده یا نادرست شناخته شده باشد:
.IP \(bu 2
\f[B]path\f[R]: مسیر فایل اجرایی کامپایلر. الزامی.
.IP \(bu 2
\f[B]as\f[R]: راهنمای نوع کامپایلر برای تحلیل معنایی.
اختیاری؛ در صورت حذف، Bear خانواده کامپایلر را از روی نام فایل اجرایی حدس می‌زند و در صورت عدم تطابق به \f[CR]gcc\f[R] بازمی‌گردد.
.IP \(bu 2
\f[B]ignore\f[R]: حذف فراخوانی‌های این فایل اجرایی از پایگاه‌داده. اختیاری، پیش‌فرض \f[CR]false\f[R].
.PP
نام‌های عمومی \f[CR]cc\f[R]، \f[CR]c++\f[R] و پوشش‌دهنده HPE Cray PrgEnv با نام \f[CR]CC\f[R] با بررسی خروجی \f[CR]\-\-version\f[R] فایل اجرایی طبقه‌بندی می‌شوند.
زمانی که این کاوش نتواند فایل اجرایی را دسته‌بندی کند، آن را بازنویسی نمایید:
.IP
.EX
compilers\f[B]:\f[R]
  \f[B]\-\f[R] path\f[B]:\f[R] /usr/bin/cc
    as\f[B]:\f[R] clang
.EE
.SS sources
ورودی‌ها را بر اساس مکان فایل مبدا و نام فایل فیلتر می‌کند.
.IP \(bu 2
\f[B]directories\f[R]: فهرستی از قوانین مبتنی بر شاخه، هر کدام با یک \f[B]path\f[R] و یک \f[B]action\f[R] (\f[CR]include\f[R] یا \f[CR]exclude\f[R]).
.IP \(bu 2
\f[B]files\f[R]: فهرستی از قوانین تطبیق الگو (glob) برای نام فایل، هر کدام با یک \f[B]pattern\f[R] و یک \f[B]action\f[R] (\f[CR]include\f[R] یا \f[CR]exclude\f[R]).
.PP
قوانین هر فهرست به ترتیب ارزیابی می‌شوند، آخرین قانون منطبق اولویت دارد، و ورودی‌ای که با هیچ قانونی مطابقت نداشته باشد شامل می‌شود؛ یک فهرست خالی همه چیز را شامل می‌کند.
این دو فهرست با هم ترکیب می‌شوند: یک ورودی تنها زمانی صادر می‌شود که هر دو آن را بپذیرند.
یک الگوی فایل بدون جداکننده مسیر، با نام پایه فایل مبدا مطابقت دارد؛ الگوی حاوی جداکننده با مسیر کامل مبدا مطابقت دارد.
الگوی نامعتبر در هنگام اعتبارسنجی رد می‌شود.
کاربرد معمول برای الگوهای فایل، حذف مبداهای تولیدشده ماشینی است (خروجی \f[CR]moc\f[R] کیوت، کدهای ساختگی protobuf).
.SS duplicates
تشخیص موارد تکراری را کنترل می‌کند.
.IP \(bu 2
\f[B]match_on\f[R]: فهرستی از فیلدهای ورودی برای مقایسه (\f[CR]file\f[R]، \f[CR]arguments\f[R]، \f[CR]directory\f[R]، \f[CR]command\f[R]، \f[CR]output\f[R]).
دو ورودی زمانی تکراری هستند که تمام فیلدهای پیکربندی‌شده مطابقت داشته باشند؛ اولین رخداد نگه داشته می‌شود.
پیش‌فرض \f[CR]directory\f[R] و \f[CR]file\f[R] است، بنابراین یک ورودی به ازای هر فایل مبدا در هر شاخه نگه داشته می‌شود؛ وقتی ساخت یک فایل یکسان را با پرچم‌های متفاوت کامپایل می‌کند، \f[CR]arguments\f[R] را اضافه کنید تا یک ورودی به ازای هر پیکربندی حفظ شود.
ترکیب با \f[CR]\-\-append\f[R] بدین معناست که جدیدترین فراخوانی فایل بازسازی‌شده جایگزین ورودی قدیمی آن می‌شود.
.SS format
قالب‌بندی خروجی را کنترل می‌کند.
.IP \(bu 2
\f[B]paths.directory\f[R], \f[B]paths.file\f[R]: نحوه قالب‌بندی مسیرها: \f[CR]as\-is\f[R] (پیش‌فرض، بدون تغییر)، \f[CR]canonical\f[R] (حل پیوندهای نمادین؛ نیازمند وجود مسیر)، \f[CR]relative\f[R] (نسبت به فیلد \f[CR]directory\f[R])، یا \f[CR]absolute\f[R].
.IP \(bu 2
\f[B]entries.use_array_format\f[R]: استفاده از آرایه \f[CR]arguments\f[R] (پیش‌فرض) به جای رشته \f[CR]command\f[R].
برای مصرف‌کنندگانی که فقط فیلد \f[CR]command\f[R] را می‌خوانند، روی \f[CR]false\f[R] تنظیم شود.
.IP \(bu 2
\f[B]entries.include_output_field\f[R]: شامل کردن فیلد \f[CR]output\f[R] در ورودی‌ها.
.IP \(bu 2
\f[B]arguments.from_response_files\f[R]: جایگزینی ارجاعات فایل پاسخ \f[CR]\(atfile\f[R] با محتویات نشانه‌گذاری‌شده فایل.
به طور پیش‌فرض غیرفعال است.
.IP \(bu 2
\f[B]arguments.from_environment\f[R]: گنجاندن متغیرهای محیطی کامپایلر که به عنوان پرچم‌های ضمنی عمل می‌کنند در آرگومان‌ها.
مسیرهای جستجوی سرآیند در GCC/Clang (مانند \f[CR]CPATH\f[R]، \f[CR]C_INCLUDE_PATH\f[R]) تبدیل به پرچم‌های include می‌شوند، و متغیرهای \f[CR]CL\f[R] / \f[CR]_CL_\f[R] در MSVC به گزینه‌های ابتدا / انتها تبدیل می‌گردند.
به طور پیش‌فرض فعال است.
.SS headers
ویرایشگرها و ابزارهای بررسی کد (لینترها) اغلب به پرچم‌های کامپایل برای فایل‌های سرآیند نیاز دارند، نه تنها برای واحدهای ترجمه‌ای که کامپایل شده‌اند.
در صورت فعال بودن، Bear با شبیه‌سازی آرگومان‌های یک واحد ترجمه کامپایل‌شده C/C++/Objective\-C، جایگزینی مسیر مبدا با مسیر سرآیند و حذف پرچم خروجی، یک ورودی برای سرآیند می‌سازد.
به طور پیش‌فرض خاموش است.
.IP \(bu 2
\f[B]enabled\f[R]: روشن یا خاموش کردن تولید ساختگی ورودی سرآیند. پیش‌فرض \f[CR]false\f[R].
.IP \(bu 2
\f[B]strategy\f[R]: نحوه کشف سرآیندها و اینکه کدام واحد ترجمه پرچم‌ها را اهدا کند:
.RS 2
.IP \(bu 2
\f[CR]siblings\f[R] (پیش‌فرض): سرآیندها یک ورودی شبیه‌سازی‌شده از یک مبدا کامپایل‌شده در همان شاخه دریافت می‌کنند.
بدون پیش‌نیاز، اما پرچم‌ها تقریبی هستند، و سرآیندها در شاخه‌های بدون مبدا کامپایل‌شده چیزی دریافت نمی‌کنند.
.IP \(bu 2
\f[CR]dependency\-files\f[R]: فایل‌های وابستگی \f[CR].d\f[R] به سبک make را که ساخت قبلاً منتشر کرده می‌خواند و برای هر پیش‌نیاز سرآیند ورودی می‌سازد.
دقیق است، اما نیازمند وجود فایل‌های وابستگی روی دیسک است.
.RE
.PP
مجموعه پسوندهای سرآیند ثابت است.
ورودی‌های سنتز‌شده مانند هر ورودی دیگر از تشخیص موارد تکراری عبور می‌کنند.
.SH "وضعیت خروج (EXIT STATUS)"
در حالت‌های combined و intercept، ابزار Bear با کد خروج دستور ساخت خارج می‌شود: ۰ در صورت موفقیت ساخت، و همان کد غیرصفر در صورت شکست.
.PP
در حالت semantic، در صورت موفقیت ۰ و در صورت شکست تحلیل مقداری غیرصفر برمی‌گرداند.
.PP
در حالت parse\-sh، چنانچه ورودی قابل تجزیه باشد ۰ برمی‌گرداند - حتی اگر پایگاه‌داده خالی باشد - و همچنین روی ورودی خالی (با اعلان در خطای استاندارد).
اگر تمام خطوط ورودی غیرخالی رد شوند، مقداری غیرصفر برمی‌گرداند تا اجرایی که چیزی نفهمیده موفق قلمداد نشود.
.PP
اگر خود Bear با یک خطای داخلی مواجه شود، صرف‌نظر از وضعیت دستور ساخت با مقداری غیرصفر خارج می‌شود.
.SH "متغیرهای محیطی (ENVIRONMENT)"
.TP
\f[B]RUST_LOG\f[R]
قالب تشخیصی و میزان پرگویی را در خطای استاندارد انتخاب می‌کند.
در صورت عدم تنظیم، Bear از سبک یونیکس \f[CR]bear: message\f[R] استفاده کرده و فقط هشدارها و خطاها را نشان می‌دهد.
هنگامی که روی یک سطح تنظیم شود (\f[CR]error\f[R]، \f[CR]warn\f[R]، \f[CR]info\f[R] یا \f[CR]debug\f[R])، Bear به یک قالب توسعه‌دهنده تغییر وضعیت می‌دهد که هر خط را با برچسب زمان، سطح، فرایند و مکان مبدا مشخص می‌کند.
خروجی دیباگ برای عیب‌یابی ضروری است.
.SH "فایل‌ها (FILES)"
فایل پیکربندی \f[CR]bear.yml\f[R] به ترتیب در مکان‌های زیر جستجو می‌شود؛ اولین فایل یافت‌شده بارگیری خواهد شد:
.TP
\f[B]\f[CB]./bear.yml\f[B]\f[R]
شاخه کاری فعلی.
.TP
\f[B]\f[CB]$XDG_CONFIG_HOME/bear.yml\f[B]\f[R], \f[B]\f[CB]$XDG_CONFIG_HOME/Bear/bear.yml\f[B]\f[R] (Unix)
هنگامی که \f[CR]$XDG_CONFIG_HOME\f[R] تنظیم شده باشد.
.TP
\f[B]\f[CB]$HOME/.config/bear.yml\f[B]\f[R], \f[B]\f[CB]$HOME/.config/Bear/bear.yml\f[B]\f[R] (Unix)
هنگامی که \f[CR]$XDG_CONFIG_HOME\f[R] تنظیم نشده باشد.
.TP
\f[B]\f[CB]%LOCALAPPDATA%\(rsbear.yml\f[B]\f[R], \f[B]\f[CB]%LOCALAPPDATA%\(rsBear\(rsbear.yml\f[B]\f[R] (Windows)
هنگامی که \f[CR]%LOCALAPPDATA%\f[R] تنظیم شده باشد.
.TP
\f[B]\f[CB]%APPDATA%\(rsbear.yml\f[B]\f[R], \f[B]\f[CB]%APPDATA%\(rsBear\(rsbear.yml\f[B]\f[R] (Windows)
هنگامی که \f[CR]%APPDATA%\f[R] تنظیم شده باشد.
.SH "مثال‌ها (EXAMPLES)"
تولید پایگاه‌داده برای یک پروژه Make:
.IP
.EX
bear \-\- make
.EE
.PP
برای یک پروژه CMake در حالت preload، فقط ساخت نیازمند Bear است:
.IP
.EX
cmake \-B build
bear \-\- cmake \-\-build build
.EE
.PP
در حالت wrapper، مرحله پیکربندی نیز باید تحت Bear اجرا شود تا پوشش‌دهنده را به عنوان کامپایلر کشف کند؛ خروجی آن اجرا را نادیده بگیرید:
.IP
.EX
bear \-\- cmake \-B build
bear \-\- cmake \-\-build build
.EE
.PP
یک‌بار ضبط کنید، بارها تحلیل نمایید. این به شما امکان می‌دهد پیکربندی‌های خروجی را بدون ساخت مجدد امتحان کنید:
.IP
.EX
bear intercept \-\-output events.json \-\- make
bear semantic \-\-input events.json
bear \-\-config strict.yml semantic \-\-input events.json \-\-output strict.json
.EE
.PP
بازیابی پایگاه‌داده از یک اجرای آزمایشی، بدون انجام ساخت:
.IP
.EX
make \-n | bear parse\-sh
.EE
.PP
برای ساخت بازگشتی Make، گزینه \f[CR]\-w\f[R] را اضافه کنید:
.IP
.EX
make \-nw | bear parse\-sh
.EE
.PP
به‌روزرسانی پایگاه‌داده پس از بازسازی بخشی از پروژه:
.IP
.EX
bear \-\-append \-\- make \-C src/module
.EE
.PP
حذف مبداهای تولیدشده (خروجی moc کیوت، کدهای protobuf) با یک \f[CR]bear.yml\f[R]:
.IP
.EX
sources\f[B]:\f[R]
  files\f[B]:\f[R]
    \f[B]\-\f[R] pattern\f[B]:\f[R] \(dqmoc_*.cpp\(dq
      action\f[B]:\f[R] exclude
    \f[B]\-\f[R] pattern\f[B]:\f[R] \(dq*.pb.cc\(dq
      action\f[B]:\f[R] exclude
    \f[B]\-\f[R] pattern\f[B]:\f[R] \(dq*.pb.h\(dq
      action\f[B]:\f[R] exclude
.EE
.PP
تولید ورودی برای سرآیندها در طرح‌بندی مجزای \f[CR]include/\f[R] + \f[CR]src/\f[R]، زمانی که ساخت فایل‌های وابستگی \f[CR].d\f[R] را منتشر می‌کند:
.IP
.EX
headers\f[B]:\f[R]
  enabled\f[B]:\f[R] true
  strategy\f[B]:\f[R] dependency\-files
.EE
.SH "عیب‌یابی (TROUBLESHOOTING)"
.SS "گزارش‌گیری اشکال‌زدایی (Debug logging)"
پیش از گزارش هرگونه مشکل، Bear را با گزارش‌گیری دیباگ فعال اجرا کنید و خروجی را در گزارش بگنجانید:
.IP
.EX
RUST_LOG=debug bear \-\- <build command>
.EE
.SS "خروجی خالی (Empty output)"
شایع‌ترین علت این است که ساخت هیچ کامپایلری را اجرا نکرده است: یک ساخت افزایشی که همه چیز آن به‌روز است چیزی اجرا نمی‌کند.
ابزار Bear فقط دستورات اجراشده را رهگیری می‌کند؛ فایل‌های ساخت را نمی‌خواند.
یک ساخت تمیز (clean build) انجام دهید.
.PP
در حالت wrapper، مرحله پیکربندی که کامپایلرها را شناسایی می‌کند مسیر واقعی کامپایلر را پیش از جایگزینی پوشش‌دهنده ثبت می‌نماید. مرحله پیکربندی را نیز تحت Bear اجرا کنید.
.SS "متغیرهای کامپایلر همراه با پرچم‌ها (Compiler variables with flags)"
در حالت wrapper، ابزار Bear قرارداد GNU Make مبنی بر متغیر کامپایلر حاوی یک یا دو پرچم انتهایی (\f[CR]CC=\(dqgcc \-std=c11\(dq make\f[R]) را می‌پذیرد: مقدار را بر اساس فاصله‌ها می‌شکند، اولین بخش را به عنوان کامپایلر حل می‌کند و متغیر را بازنویسی می‌نماید تا ساخت همچنان پرچم‌ها را ببیند.
برای هر چیزی فراتر از توکن‌های ساده، از \f[CR]CFLAGS\f[R] / \f[CR]CXXFLAGS\f[R] / \f[CR]LDFLAGS\f[R] استفاده کنید.
.SS "خطاهای پیش‌بارگذاری در کامپایل متقاطع (Preload errors in cross\-compilation)"
خطایی مانند
\f[CR]version \(aqGLIBC_2.33\(aq not found (required by .../libexec.so)\f[R]
بدین معناست که کتابخانه پیش‌بارگذاری Bear در برابر glibc جدیدتری نسبت به کامپایلرهای SDK ساخته شده است. از ساخت Bear پیوندخورده با glibc هم‌تراز یا قدیمی‌تر از SDK استفاده کنید.
.SS "کارگزارهای زبان در پروژه‌های Vala (Language servers on Vala projects)"
ابزار vala\-language\-server فیلد \f[CR]command\f[R] را می‌خواند و آرایه \f[CR]arguments\f[R] را نادیده می‌گیرد؛ پایگاه‌داده را با \f[CR]format.entries.use_array_format: false\f[R] بسازید.
در یک پروژه مختلط C/Vala، ابزار clangd همچنین ورودی‌های \f[CR]valac\f[R] را نمایه کرده و هشدارهای آرگومان ناشناخته صادر می‌کند؛ آن را با یک فایل \f[CR].clangd\f[R] خاموش کنید:
.IP
.EX
If\f[B]:\f[R]
  PathMatch\f[B]:\f[R] .*\(rs.vala
Diagnostics\f[B]:\f[R]
  Suppress\f[B]:\f[R] \(aq*\(aq
.EE
.SS "دریافت کمک (Getting help)"
برای مشکلات شناخته‌شده به سایت مستندات مراجعه کرده و مسائل موجود را پیش از ثبت گزارش جدید جستجو کنید.
همیشه خروجی \f[CR]RUST_LOG=debug\f[R] را ضمیمه نمایید.
.SH "همچنین ببینید (SEE ALSO)"
\f[B]clangd\f[R](1), \f[B]clang\-tidy\f[R](1), \f[B]make\f[R](1)
.PP
سایت مستندات، با صفحات راهنما برای سامانه‌های ساخت، پلتفرم‌ها و زنجیره‌های ابزار: \c
.UR https://rizsotto.github.io/Bear/
.UE \c
.PP
مشخصات پایگاه‌داده کامپایل Clang JSON: \c
.UR https://clang.llvm.org/docs/JSONCompilationDatabase.html
.UE \c
.PP
صفحه اصلی پروژه و پیگیری مشکلات: \c
.UR https://github.com/rizsotto/Bear
.UE \c
.SH "حق نشر (COPYRIGHT)"
Copyright (C) 2012\-2026 by László Nagy \c
.UR https://github.com/rizsotto/Bear
.UE \c
.SH "نویسندگان (AUTHORS)"
László Nagy.