نام (NAME)

bear - تولید پایگاه‌داده کامپایل برای ابزارهای مبتنی بر Clang

خلاصه دستور (SYNOPSIS)

bear [OPTIONS] -- BUILD_COMMAND...

bear intercept [OPTIONS] --output FILE -- BUILD_COMMAND...

bear semantic [OPTIONS]

bear parse-sh [OPTIONS]

توضیحات (DESCRIPTION)

ابزار Bear یک پایگاه‌داده کامپایل JSON تولید می‌کند (compile_commands.json). ابزارهای مبتنی بر Clang مانند clangd و clang-tidy این فایل را می‌خوانند تا دریابند هر فایل مبدا از پروژه چگونه کامپایل می‌شود: با کدام کامپایلر، چه فلگ‌هایی و از چه شاخه‌ای. سامانه‌های ساخت این موضوع را می‌دانند، اما بیشتر آن‌ها آن را صادر نمی‌کنند؛ ابزار Bear آن را از خود فرایند ساخت بازیابی می‌کند.

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

حالت‌ها (Modes)

حالت ترکیبی (Combined mode) (پیش‌فرض): دستور bear -- <build command> ساخت را اجرا می‌کند، ضبط و تحلیل را در یک مرحله انجام می‌دهد و پایگاه‌داده را می‌نویسد. این شیوه پیشنهادی استفاده از Bear است: این حالت دستوراتی را که ساخت واقعاً اجرا می‌کند نظاره می‌کند، بنابراین نتیجه دقیق است. هرگاه بتوانید ساخت را اجرا کنید، از آن استفاده نمایید.
حالت رهگیری (Intercept mode): دستور bear intercept ساخت را اجرا می‌کند اما تنها به ضبط می‌پردازد و جریان خام رویدادها را در یک فایل می‌نویسد. زمانی مفید است که فرایند ساخت پرهزینه باشد و بخواهید آن را یک‌بار اجرا کنید و رویدادها را چندین بار پردازش نمایید، مثلاً برای آزمایش پیکربندی‌های خروجی متفاوت.
حالت معنایی (Semantic mode): دستور bear semantic هیچ ساختی را اجرا نمی‌کند: یک فیلتر است که جریان رویداد را (از bear intercept یا هر تولیدکننده دیگری با قالب رویداد مستندشده) می‌خواند و پایگاه‌داده کامپایل را می‌نویسد. آن را با حالت intercept ترکیب کنید تا پایگاه‌داده را بدون ساخت مجدد دوباره تولید نمایید.
حالت تجزیه شل (Parse-sh mode): دستور bear parse-sh پایگاه‌داده کامپایل را از متن دستورات شل، بدون اجرای هیچ دستوری، تولید می‌کند. ورودی معمول خروجی آزمایشی یک سامانه ساخت (make -n) یا لاگ ذخیره‌شده ساخت است: این یک تجزیه‌گر متنی است و ذاتاً وفاداری کمتری نسبت به رهگیری دارد؛ زمانی سراغ آن بروید که امکان اجرای ساخت وجود ندارد، مثلاً برای بازیابی پایگاه‌داده از لاگ CI. محدودیت‌های آن را در بخش دستورات (COMMANDS) ببینید.

روش‌های رهگیری (Interception methods)

خود رهگیری دارای دو روش است که در فایل پیکربندی قابل انتخاب هستند. پیش‌بارگذاری (Preload) (پیش‌فرض در لینوکس و BSDها) یک کتابخانه کوچک را به هر فرایندی که ساخت آغاز می‌کند تزریق کرده و فراخوانی‌های exec() آن را نظاره می‌کند. پوشش‌دهنده (Wrapper) (پیش‌فرض در macOS و ویندوز) کامپایلرهای شناخته‌شده را با یک باینری اجرایی پوشش‌دهنده گزارش‌گر جایگزین می‌کند. روش Preload برای ساخت شفاف است اما نمی‌تواند باینری‌های اجرایی پیوندیافته ایستا (statically linked) را نظاره کند، و در ویندوز و در macOS هنگامی که حفاظت یکپارچگی سامانه (SIP) فعال است در دسترس نیست؛ اجبار آن در این شرایط یک خطای زمان راه‌اندازی است که نام حالت wrapper را ذکر می‌کند، نه یک جایگزین خاموش. حالت Wrapper در تمام پلتفرم‌ها کار می‌کند، اما ساخت باید پوشش‌دهنده را شناسایی کند: مرحله پیکربندی («configure») که کامپایلرها را کشف می‌کند باید خود تحت Bear اجرا شود (عیب‌یابی را ببینید).

گزینه‌ها (OPTIONS)

-c, --config FILE: مسیر فایل پیکربندی. روش رهگیری، شناسایی کامپایلر، فیلتر کردن مبدا، مدیریت موارد تکراری و قالب‌بندی خروجی را کنترل می‌کند (بخش پیکربندی را ببینید). در صورتی که پیش از یک زیردستور داده شود، به آن زیردستور نیز اعمال می‌شود.
-o, --output FILE: مسیر پایگاه‌داده کامپایل جهت نوشتن (پیش‌فرض: compile_commands.json). مقدار - در اینجا پذیرفته نمی‌شود، زیرا در حالت ترکیبی خروجی استاندارد متعلق به ساخت است. برای ارسال جریانی پایگاه‌داده، از bear semantic --output - استفاده کنید (بخش دستورات را ببینید).
-a, --append: الحاق به یک فایل خروجی موجود به جای بازنویسی کامل آن. ورودی‌های جدید پیش از ورودی‌های موجود قرار می‌گیرند، به طوری که تازه‌ترین فراخوانی یک فایل بازسازی‌شده در فیلتر موارد تکراری باقی مانده و جایگزین ورودی کهنه می‌شود (بخش duplicates زیر پیکربندی را ببینید).
--overwrite: جایگزینی فایل خروجی فقط با ورودی‌های این اجرا. این رفتاری است که Bear در صورت مشخص نشدن هیچ پرچمی انجام می‌دهد؛ این پرچم وجود دارد تا یک اسکریپت بتواند رفتاری را که به آن وابسته است صراحتاً نام ببرد نه اینکه به پیش‌فرض تکیه کند. ارائه همزمان آن با --append خطاست. در نگارش‌های آینده الحاق به عنوان پیش‌فرض خواهد بود، و اسکریپتی که امروزه --overwrite را ارسال می‌کند، رفتار فعلی خود را حفظ خواهد کرد.
-h, --help: چاپ راهنما.
-V, --version: چاپ نسخه.

دستورات (COMMANDS)

bear intercept

ساخت را اجرا کرده و رویدادهای اجرا را در یک فایل ضبط می‌کند، بدون آنکه آن‌ها را تحلیل کند.

bear intercept [OPTIONS] --output FILE -- BUILD_COMMAND...

-o, --output FILE: مسیر فایل رویداد جهت نوشتن. الزامی است، و - پذیرفته نمی‌شود: ساخت مالک خروجی استاندارد است و هیچ نام فایل رویداد پیش‌فرضی وجود ندارد.

bear semantic

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

bear semantic [OPTIONS]

-i, --input FILE: مسیر فایل رویداد برای خواندن (پیش‌فرض: -، ورودی استاندارد). هر تولیدکننده جریان رویداد منطبق می‌تواند خروجی خود را به آن لوله‌کشی (pipe) کند. هنگامی که ورودی استاندارد یک ترمینال باشد یا جریان خالی باشد، یک اعلان در خطای استاندارد چاپ می‌شود.
-o, --output FILE: مسیر پایگاه‌داده کامپایل برای نوشتن (پیش‌فرض: compile_commands.json). برای نوشتن در خروجی استاندارد - را ارسال کنید؛ آن نوشتن نه اتمیک است و نه قابل الحاق، بنابراین --output - همراه با --append رد می‌شود.
-a, --append: همانند حالت ترکیبی: ورودی‌های جدید را پیش از ورودی‌های موجود در فایل خروجی قرار می‌دهد.
--overwrite: همانند حالت ترکیبی: مشخص کردن صریح پیش‌فرض فعلی. همراه با --append پذیرفته نمی‌شود.

bear parse-sh

پایگاه‌داده کامپایل را از متن دستورات شل، بدون اجرای هیچ برنامه‌ای، تولید می‌کند. ورودی معمول خروجی آزمایشی سامانه ساخت مانند make -n یا یک لاگ ساخت ذخیره‌شده است:

make -n | bear parse-sh

bear parse-sh [OPTIONS]

-i, --input FILE: مسیر متن شل برای تجزیه (پیش‌فرض: -، ورودی استاندارد).
-o, --output FILE: مسیر پایگاه‌داده کامپایل جهت نوشتن (پیش‌فرض: compile_commands.json). ارسال - برای نوشتن در خروجی استاندارد؛ این نوشتن نه اتمیک است و نه قابل الحاق، بنابراین --output - همراه با --append رد می‌شود.
-a, --append: همانند حالت ترکیبی: قرار دادن ورودی‌های جدید پیش از موارد موجود در فایل خروجی.
--overwrite: همانند حالت ترکیبی: نام بردن صریح پیش‌فرض فعلی. همراه با --append پذیرفته نمی‌شود.
-C, --directory DIR: شاخه کاری اولیه برای دستورات تجزیه‌شده. از آن برای ورودی ضبط‌شده در جایی دیگر (یک لاگ CI، یک اجرای آزمایشی از نسخه‌ای دیگر) استفاده کنید. یک مسیر مطلق بدهید؛ نیازی نیست شاخه روی این رایانه وجود داشته باشد.

دستورات شناسایی‌شده در متن از همان مرحله تحلیل معنایی و خروجی یک ساخت رهگیری‌شده عبور می‌کنند، بنابراین پیکربندی دقیقاً مشابه حالت ترکیبی اعمال می‌شود. دستورات تجزیه‌شده‌ای که فراخوانی کامپایلر نیستند (ar، mv، mkdir) هیچ ورودی تولید نمی‌کنند.

این ابزار زیرمجموعه مستندشده‌ای از نحو شل POSIX را می‌فهمد: شکستن کلمات و نقل‌قول‌ها؛ جداکننده‌های ;، &&، ||، & و |؛ کامنت‌ها؛ تغییرمسیرها؛ cd؛ گروه‌های آکولادی ({ ...; } که تغییر cd آن‌ها پس از آکولاد بسته ادامه دارد)؛ و نشانگرهای Entering directory / Leaving directory دستور make، که شاخه کاری را در یک ساخت بازگشتی ردیابی می‌کنند. زیر-makeها این نشانگرها را به طور پیش‌فرض چاپ می‌کنند؛ دستور make -nw را اجرا کنید تا make سطح بالا نیز آن‌ها را چاپ کند، تا خود لاگ ریشه ساخت را مشخص نماید. خطی که از هر چیزی خارج از این زیرمجموعه استفاده کند نادیده گرفته شده و در خطای استاندارد همراه با شماره خط و دلیل گزارش می‌شود. این شامل زیرشل‌ها، جایگزینی فرمان، گسترش پارامتر، تطبیق الگو (glob) در موقعیت فایل اجرایی، here-documents، نقل‌قول‌های بسته نشده و کلمات کلیدی شل مانند if یا for است. اجرا تا زمانی که حداقل یک خط به عنوان دستور تجزیه شود موفق خواهد بود.

رهگیری همچنان پیش‌فرض با وفاداری بالاتر باقی می‌ماند: این روش فراخوانی‌های exec() را که ساخت واقعاً انجام می‌دهد نظاره می‌کند، در حالی که bear parse-sh رویدادهای تقریبی را از متنی که سامانه ساخت برای چاپ برگزیده بازسازی می‌کند. یک اجرای آزمایشی می‌تواند دستورات را حذف کند (make بازگشتی همیشه -n را منتشر نمی‌کند، و دستورات پشت مبداهایی که هنوز تولید نشده‌اند هرگز چاپ نمی‌شوند)؛ محیط و PATH استفاده‌شده برای حل نام فایل‌های اجرایی همان‌های زمان تجزیه هستند نه ساخت واقعی؛ و فقط متن شل POSIX پشتیبانی می‌شود. هر زمان ساخت واقعاً قابل اجرا باشد، bear -- <build command> را ترجیح دهید.

فایل‌های مبدا ذکرشده در دستورات تجزیه‌شده نیازی به وجود ندارند: ورودی‌ها تنها از روی متن بازسازی می‌شوند. تنها استثنا قالب مسیر canonical است که پیوندهای نمادین روی دیسک را حل می‌کند؛ در صورت غیاب مبداها، در عوض absolute را پیکربندی کنید (بخش format.paths زیر پیکربندی را ببینید).

خروجی (OUTPUT)

ابزار Bear یک پایگاه‌داده کامپایل JSON مطابق با مشخصات Clang JSON Compilation Database می‌نویسد: یک آرایه JSON از اشیاء ورودی با فیلدهای زیر:

directory: شاخه کاری کامپایل.
file: فایل مبدا واحد ترجمه اصلی.
arguments: دستور کامپایل به صورت آرایه‌ای از رشته‌ها. این حالت پیش‌فرض است؛ Bear آن را به command ترجیح می‌دهد زیرا از مشکلات فرار شل (shell-escaping) جلوگیری می‌کند.
command: دستور کامپایل به عنوان یک رشته تک فرار داده‌شده (زمانی نوشته می‌شود که format.entries.use_array_format برابر false باشد).
output: فایل تولیدشده توسط کامپایل (اختیاری).

به طور پیش‌فرض Bear مسیرها را تغییر نمی‌دهد: هر ورودی آن‌ها را همان‌طور که در فراخوانی رهگیری‌شده ظاهر شده بودند ثبت می‌کند، بنابراین file و output اغلب نسبت به directory نسبی هستند. از format.paths در پیکربندی برای نرمال‌سازی آن‌ها استفاده کنید.

دو کامپایلر شکلی از ورودی تولید می‌کنند که دانستن آن ارزشمند است:

swiftc: فراخوانی کل پودمان با ذکر چندین مبدا .swift، یک ورودی به ازای هر مبدا تولید می‌کند که هر کدام آرگومان‌های کامل فراخوانی را به همراه دارند (تمام مبداهای پودمان، نه فقط مال خودش). این مطابق شکلی است که CMake منتشر می‌کند و SourceKit-LSP مصرف می‌نماید. داده‌های تکراری آرگومان مورد انتظار است، نه یک اشکال. کارهای داخلی swift-frontend که swiftc ایجاد می‌کند به طور خودکار فیلتر می‌شوند.
valac: یک ورودی به ازای هر فراخوانی valac (کامپایلر valac تمام مبداهای .vala/.gs یک هدف را با هم به عنوان یک واحد کامپایل می‌کند)؛ فیلد file ورودی همان اولین مبدا است و تمام مبداها در دستور نگه داشته می‌شوند. از آنجا که valac به C ترجمه می‌کند و نتیجه را کامپایل می‌نماید، پایگاه‌داده همچنین شامل ورودی‌هایی برای فایل‌های C تولیدشده است (برای پیامدهای clangd بخش عیب‌یابی را ببینید).

پیکربندی (CONFIGURATION)

ابزار Bear یک فایل پیکربندی YAML را می‌خواند که از طریق جستجو (بخش فایل‌ها را ببینید) پیدا شده یا با --config مشخص می‌شود. بدون آن، پیش‌فرض‌های داخلی اعمال می‌شوند. فایلی که نوشته می‌شود باید schema را مشخص کند؛ هر بخشی زیر آن اختیاری است. مثال زیر تمامی بخش‌ها را نشان می‌دهد:

schema: "4.2"
intercept:
  mode: wrapper              # پیش‌فرض: preload روی لینوکس و BSDها
compilers:
  - path: /usr/bin/cc
    as: gcc
  - path: /usr/local/bin/gcc
    ignore: true
sources:
  directories:
    - path: /project/tests
      action: exclude
  files:
    - pattern: "moc_*.cpp"
      action: exclude
    - pattern: "*.pb.cc"
      action: exclude
duplicates:
  match_on:                  # پیش‌فرض: directory, file
    - file
    - arguments
format:
  paths:
    directory: canonical     # پیش‌فرض: as-is
    file: canonical          # پیش‌فرض: as-is
  entries:
    use_array_format: true
    include_output_field: true
  arguments:
    from_response_files: false
    from_environment: true
headers:
  enabled: true               # پیش‌فرض: false
  strategy: siblings

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

intercept

روش رهگیری را کنترل می‌کند (برای مقایسه به بخش توضیحات مراجعه کنید):

•: mode: مقدار preload (پیش‌فرض در لینوکس و BSDها) یا wrapper (پیش‌فرض در macOS و ویندوز؛ در همه جا کار می‌کند).

compilers

راهنمایی‌هایی برای شناسایی کامپایلر. ابزار Bear درایورهای سازگار با GCC و Clang (شامل نام‌های پیشونددار کامپایل متقاطع)، درایورهای رایج کامپایلرهای تجاری و اسمبلرهای مستقل، swiftc و valac، راه‌اندازهای کامپایلر و پوشش‌دهنده‌های کامپایلر MPI را می‌شناسد. دستور bear semantic --print-compilers را برای فهرست کامل نام‌های کامپایلر شناخته‌شده اجرا کنید.

چند رفتار شناسایی ارزش دانستن دارد: راه‌اندازهای کامپایلر (ccache، distcc، sccache، icecc) از دستور ثبت‌شده حذف می‌شوند: مثلاً ccache gcc -c main.c یک ورودی برای gcc -c main.c ایجاد می‌کند. پوشش‌دهنده‌های کامپایلر MPI همان‌طور که فراخوانی شده‌اند ثبت می‌شوند و به کامپایلری که پوشش می‌دهند گسترش نمی‌یابند. واحدهای رابط پودمان C++20 (مانند .cppm، .ixx و مشابه آن) به عنوان مبدا شناخته می‌شوند، در حالی که مصنوعات پیش‌کامپایل‌شده .pcm هرگز به عنوان file ظاهر نمی‌شوند.

در حالت wrapper، این بخش همچنین تصمیم می‌گیرد چه مواردی پوشش داده شوند. اگر ورودی دیگری جز موارد ignore وجود نداشته باشد، Bear هنگام راه‌اندازی متغیر PATH را پویش کرده و هر کامپایلری را که می‌شناسد پوشش می‌دهد. به محض اینکه یک ورودی نادیده گرفته نشود، Bear دقیقاً مسیرهای فهرست‌شده را پوشش می‌دهد و از پویش صرف‌نظر می‌کند. کامپایلرهای مشخص‌شده در متغیرهای محیطی کامپایلر (CC، CXX و مشابه آن) در هر دو حالت پوشش داده می‌شوند. حالت Preload تحت تأثیر قرار نمی‌گیرد: این روش هر برنامه اجراشده را صرف‌نظر از این بخش رهگیری می‌کند.

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

path: مسیر فایل اجرایی کامپایلر. الزامی.
as: راهنمای نوع کامپایلر برای تحلیل معنایی. اختیاری؛ در صورت حذف، Bear خانواده کامپایلر را از روی نام فایل اجرایی حدس می‌زند و در صورت عدم تطابق به gcc بازمی‌گردد.
ignore: حذف فراخوانی‌های این فایل اجرایی از پایگاه‌داده. اختیاری، پیش‌فرض false.

نام‌های عمومی cc، c++ و پوشش‌دهنده HPE Cray PrgEnv با نام CC با بررسی خروجی --version فایل اجرایی طبقه‌بندی می‌شوند. زمانی که این کاوش نتواند فایل اجرایی را دسته‌بندی کند، آن را بازنویسی نمایید:

compilers:
  - path: /usr/bin/cc
    as: clang

sources

ورودی‌ها را بر اساس مکان فایل مبدا و نام فایل فیلتر می‌کند.

directories: فهرستی از قوانین مبتنی بر شاخه، هر کدام با یک path و یک action (include یا exclude).
files: فهرستی از قوانین تطبیق الگو (glob) برای نام فایل، هر کدام با یک pattern و یک action (include یا exclude).

قوانین هر فهرست به ترتیب ارزیابی می‌شوند، آخرین قانون منطبق اولویت دارد، و ورودی‌ای که با هیچ قانونی مطابقت نداشته باشد شامل می‌شود؛ یک فهرست خالی همه چیز را شامل می‌کند. این دو فهرست با هم ترکیب می‌شوند: یک ورودی تنها زمانی صادر می‌شود که هر دو آن را بپذیرند. یک الگوی فایل بدون جداکننده مسیر، با نام پایه فایل مبدا مطابقت دارد؛ الگوی حاوی جداکننده با مسیر کامل مبدا مطابقت دارد. الگوی نامعتبر در هنگام اعتبارسنجی رد می‌شود. کاربرد معمول برای الگوهای فایل، حذف مبداهای تولیدشده ماشینی است (خروجی moc کیوت، کدهای ساختگی protobuf).

duplicates

تشخیص موارد تکراری را کنترل می‌کند.

•: match_on: فهرستی از فیلدهای ورودی برای مقایسه (file، arguments، directory، command، output). دو ورودی زمانی تکراری هستند که تمام فیلدهای پیکربندی‌شده مطابقت داشته باشند؛ اولین رخداد نگه داشته می‌شود. پیش‌فرض directory و file است، بنابراین یک ورودی به ازای هر فایل مبدا در هر شاخه نگه داشته می‌شود؛ وقتی ساخت یک فایل یکسان را با پرچم‌های متفاوت کامپایل می‌کند، arguments را اضافه کنید تا یک ورودی به ازای هر پیکربندی حفظ شود. ترکیب با --append بدین معناست که جدیدترین فراخوانی فایل بازسازی‌شده جایگزین ورودی قدیمی آن می‌شود.

format

قالب‌بندی خروجی را کنترل می‌کند.

paths.directory, paths.file: نحوه قالب‌بندی مسیرها: as-is (پیش‌فرض، بدون تغییر)، canonical (حل پیوندهای نمادین؛ نیازمند وجود مسیر)، relative (نسبت به فیلد directory)، یا absolute.
entries.use_array_format: استفاده از آرایه arguments (پیش‌فرض) به جای رشته command. برای مصرف‌کنندگانی که فقط فیلد command را می‌خوانند، روی false تنظیم شود.
entries.include_output_field: شامل کردن فیلد output در ورودی‌ها.
arguments.from_response_files: جایگزینی ارجاعات فایل پاسخ @file با محتویات نشانه‌گذاری‌شده فایل. به طور پیش‌فرض غیرفعال است.
arguments.from_environment: گنجاندن متغیرهای محیطی کامپایلر که به عنوان پرچم‌های ضمنی عمل می‌کنند در آرگومان‌ها. مسیرهای جستجوی سرآیند در GCC/Clang (مانند CPATH، C_INCLUDE_PATH) تبدیل به پرچم‌های include می‌شوند، و متغیرهای CL / _CL_ در MSVC به گزینه‌های ابتدا / انتها تبدیل می‌گردند. به طور پیش‌فرض فعال است.

headers

ویرایشگرها و ابزارهای بررسی کد (لینترها) اغلب به پرچم‌های کامپایل برای فایل‌های سرآیند نیاز دارند، نه تنها برای واحدهای ترجمه‌ای که کامپایل شده‌اند. در صورت فعال بودن، Bear با شبیه‌سازی آرگومان‌های یک واحد ترجمه کامپایل‌شده C/C++/Objective-C، جایگزینی مسیر مبدا با مسیر سرآیند و حذف پرچم خروجی، یک ورودی برای سرآیند می‌سازد. به طور پیش‌فرض خاموش است.

enabled: روشن یا خاموش کردن تولید ساختگی ورودی سرآیند. پیش‌فرض false.
strategy: نحوه کشف سرآیندها و اینکه کدام واحد ترجمه پرچم‌ها را اهدا کند:

siblings (پیش‌فرض): سرآیندها یک ورودی شبیه‌سازی‌شده از یک مبدا کامپایل‌شده در همان شاخه دریافت می‌کنند. بدون پیش‌نیاز، اما پرچم‌ها تقریبی هستند، و سرآیندها در شاخه‌های بدون مبدا کامپایل‌شده چیزی دریافت نمی‌کنند.
dependency-files: فایل‌های وابستگی .d به سبک make را که ساخت قبلاً منتشر کرده می‌خواند و برای هر پیش‌نیاز سرآیند ورودی می‌سازد. دقیق است، اما نیازمند وجود فایل‌های وابستگی روی دیسک است.

مجموعه پسوندهای سرآیند ثابت است. ورودی‌های سنتز‌شده مانند هر ورودی دیگر از تشخیص موارد تکراری عبور می‌کنند.

وضعیت خروج (EXIT STATUS)

در حالت‌های combined و intercept، ابزار Bear با کد خروج دستور ساخت خارج می‌شود: ۰ در صورت موفقیت ساخت، و همان کد غیرصفر در صورت شکست.

در حالت semantic، در صورت موفقیت ۰ و در صورت شکست تحلیل مقداری غیرصفر برمی‌گرداند.

در حالت parse-sh، چنانچه ورودی قابل تجزیه باشد ۰ برمی‌گرداند - حتی اگر پایگاه‌داده خالی باشد - و همچنین روی ورودی خالی (با اعلان در خطای استاندارد). اگر تمام خطوط ورودی غیرخالی رد شوند، مقداری غیرصفر برمی‌گرداند تا اجرایی که چیزی نفهمیده موفق قلمداد نشود.

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

متغیرهای محیطی (ENVIRONMENT)

RUST_LOG: قالب تشخیصی و میزان پرگویی را در خطای استاندارد انتخاب می‌کند. در صورت عدم تنظیم، Bear از سبک یونیکس bear: message استفاده کرده و فقط هشدارها و خطاها را نشان می‌دهد. هنگامی که روی یک سطح تنظیم شود (error، warn، info یا debug)، Bear به یک قالب توسعه‌دهنده تغییر وضعیت می‌دهد که هر خط را با برچسب زمان، سطح، فرایند و مکان مبدا مشخص می‌کند. خروجی دیباگ برای عیب‌یابی ضروری است.

فایل‌ها (FILES)

فایل پیکربندی bear.yml به ترتیب در مکان‌های زیر جستجو می‌شود؛ اولین فایل یافت‌شده بارگیری خواهد شد:

./bear.yml: شاخه کاری فعلی.
$XDG_CONFIG_HOME/bear.yml, $XDG_CONFIG_HOME/Bear/bear.yml (Unix): هنگامی که $XDG_CONFIG_HOME تنظیم شده باشد.
$HOME/.config/bear.yml, $HOME/.config/Bear/bear.yml (Unix): هنگامی که $XDG_CONFIG_HOME تنظیم نشده باشد.
%LOCALAPPDATA%\bear.yml, %LOCALAPPDATA%\Bear\bear.yml (Windows): هنگامی که %LOCALAPPDATA% تنظیم شده باشد.
%APPDATA%\bear.yml, %APPDATA%\Bear\bear.yml (Windows): هنگامی که %APPDATA% تنظیم شده باشد.

مثال‌ها (EXAMPLES)

تولید پایگاه‌داده برای یک پروژه Make:

bear -- make

برای یک پروژه CMake در حالت preload، فقط ساخت نیازمند Bear است:

cmake -B build
bear -- cmake --build build

در حالت wrapper، مرحله پیکربندی نیز باید تحت Bear اجرا شود تا پوشش‌دهنده را به عنوان کامپایلر کشف کند؛ خروجی آن اجرا را نادیده بگیرید:

bear -- cmake -B build
bear -- cmake --build build

یک‌بار ضبط کنید، بارها تحلیل نمایید. این به شما امکان می‌دهد پیکربندی‌های خروجی را بدون ساخت مجدد امتحان کنید:

bear intercept --output events.json -- make
bear semantic --input events.json
bear --config strict.yml semantic --input events.json --output strict.json

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

make -n | bear parse-sh

برای ساخت بازگشتی Make، گزینه -w را اضافه کنید:

make -nw | bear parse-sh

به‌روزرسانی پایگاه‌داده پس از بازسازی بخشی از پروژه:

bear --append -- make -C src/module

حذف مبداهای تولیدشده (خروجی moc کیوت، کدهای protobuf) با یک bear.yml:

sources:
  files:
    - pattern: "moc_*.cpp"
      action: exclude
    - pattern: "*.pb.cc"
      action: exclude
    - pattern: "*.pb.h"
      action: exclude

تولید ورودی برای سرآیندها در طرح‌بندی مجزای include/ + src/، زمانی که ساخت فایل‌های وابستگی .d را منتشر می‌کند:

headers:
  enabled: true
  strategy: dependency-files

عیب‌یابی (TROUBLESHOOTING)

گزارش‌گیری اشکال‌زدایی (Debug logging)

پیش از گزارش هرگونه مشکل، Bear را با گزارش‌گیری دیباگ فعال اجرا کنید و خروجی را در گزارش بگنجانید:

RUST_LOG=debug bear -- <build command>

خروجی خالی (Empty output)

شایع‌ترین علت این است که ساخت هیچ کامپایلری را اجرا نکرده است: یک ساخت افزایشی که همه چیز آن به‌روز است چیزی اجرا نمی‌کند. ابزار Bear فقط دستورات اجراشده را رهگیری می‌کند؛ فایل‌های ساخت را نمی‌خواند. یک ساخت تمیز (clean build) انجام دهید.

در حالت wrapper، مرحله پیکربندی که کامپایلرها را شناسایی می‌کند مسیر واقعی کامپایلر را پیش از جایگزینی پوشش‌دهنده ثبت می‌نماید. مرحله پیکربندی را نیز تحت Bear اجرا کنید.

متغیرهای کامپایلر همراه با پرچم‌ها (Compiler variables with flags)

در حالت wrapper، ابزار Bear قرارداد GNU Make مبنی بر متغیر کامپایلر حاوی یک یا دو پرچم انتهایی (CC="gcc -std=c11" make) را می‌پذیرد: مقدار را بر اساس فاصله‌ها می‌شکند، اولین بخش را به عنوان کامپایلر حل می‌کند و متغیر را بازنویسی می‌نماید تا ساخت همچنان پرچم‌ها را ببیند. برای هر چیزی فراتر از توکن‌های ساده، از CFLAGS / CXXFLAGS / LDFLAGS استفاده کنید.

خطاهای پیش‌بارگذاری در کامپایل متقاطع (Preload errors in cross-compilation)

خطایی مانند version 'GLIBC_2.33' not found (required by .../libexec.so) بدین معناست که کتابخانه پیش‌بارگذاری Bear در برابر glibc جدیدتری نسبت به کامپایلرهای SDK ساخته شده است. از ساخت Bear پیوندخورده با glibc هم‌تراز یا قدیمی‌تر از SDK استفاده کنید.

کارگزارهای زبان در پروژه‌های Vala (Language servers on Vala projects)

ابزار vala-language-server فیلد command را می‌خواند و آرایه arguments را نادیده می‌گیرد؛ پایگاه‌داده را با format.entries.use_array_format: false بسازید. در یک پروژه مختلط C/Vala، ابزار clangd همچنین ورودی‌های valac را نمایه کرده و هشدارهای آرگومان ناشناخته صادر می‌کند؛ آن را با یک فایل .clangd خاموش کنید:

If:
  PathMatch: .*\.vala
Diagnostics:
  Suppress: '*'

دریافت کمک (Getting help)

برای مشکلات شناخته‌شده به سایت مستندات مراجعه کرده و مسائل موجود را پیش از ثبت گزارش جدید جستجو کنید. همیشه خروجی RUST_LOG=debug را ضمیمه نمایید.

همچنین ببینید (SEE ALSO)

clangd(1), clang-tidy(1), make(1)

سایت مستندات، با صفحات راهنما برای سامانه‌های ساخت، پلتفرم‌ها و زنجیره‌های ابزار: https://rizsotto.github.io/Bear/

مشخصات پایگاه‌داده کامپایل Clang JSON: https://clang.llvm.org/docs/JSONCompilationDatabase.html

صفحه اصلی پروژه و پیگیری مشکلات: https://github.com/rizsotto/Bear

حق نشر (COPYRIGHT)

نویسندگان (AUTHORS)

László Nagy.