ABIPKGDIFF(1) Libabigail ABIPKGDIFF(1)

abipkgdiff - مقایسه ABI فایل‌های دودویی ELF در بسته‌های نرم‌افزاری

ابزار abipkgdiff رابط‌های باینری کاربردی (Application Binary Interfaces یا ABI) فایل‌های دودویی ELF http://en.wikipedia.org/wiki/Executable_and_Linkable_Format موجود در دو مجموعه از بسته‌های نرم‌افزاری را با یکدیگر مقایسه می‌کند. قالب‌های بسته نرم‌افزاری که در حال حاضر پشتیبانی می‌شوند عبارتند از Deb https://en.wikipedia.org/wiki/Deb_%28file_format%29، RPM https://en.wikipedia.org/wiki/RPM_Package_Manager، آرشیوهای tar https://en.wikipedia.org/wiki/Tar_%28computing%29 (چه فشرده‌شده و چه فشرده‌نشده) و پوشه‌های معمولی حاوی فایل‌های دودویی.

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

برای دریافت یک گزارش جامع از تغییرات ABI که شامل تغییرات مربوط به زیرنوع‌های توابع و متغیرها نیز باشد، دو مجموعه بسته ورودی باید همراه با بسته‌های اطلاعات اشکال‌زدایی مربوط به خود باشند؛ این اطلاعات اشکال‌زدایی می‌تواند در قالب‌های DWARF http://www.dwarfstd.org، CTF https://raw.githubusercontent.com/wiki/oracle/binutils-gdb/files/ctf-spec.pdf یا BTF https://docs.kernel.org/bpf/btf.html باشد. با این حال لطفاً توجه داشته باشید که برخی بسته‌ها حاوی فایل‌های دودویی هستند که اطلاعات اشکال‌زدایی را مستقیماً درون بخشی از همان فایل دودویی تعبیه کرده‌اند. در این‌گونه موارد، طبیعتاً نیازی به بسته اطلاعات اشکال‌زدایی جداگانه نیست زیرا این ابزار اطلاعات اشکال‌زدایی را درون فایل‌های دودویی خواهد یافت.

به‌طور پیش‌فرض، abipkgdiff در صورت وجود از اطلاعات اشکال‌زدایی در قالب DWARF http://www.dwarfstd.org استفاده می‌کند؛ در غیر این صورت، رابط‌های فایل‌های دودویی را با استفاده از اطلاعات اشکال‌زدایی در قالب‌های CTF https://raw.githubusercontent.com/wiki/oracle/binutils-gdb/files/ctf-spec.pdf یا BTF https://docs.kernel.org/bpf/btf.html (در صورت وجود) مقایسه می‌نماید. در نهایت، اگر هیچ اطلاعات اشکال‌زدایی در این قالب‌ها یافت نشود، تنها نمادهای ELF http://en.wikipedia.org/wiki/Executable_and_Linkable_Format را در نظر گرفته و افزودن یا حذف آن‌ها را گزارش می‌دهد.

این ابزار از کتابخانه libabigail برای تحلیل فایل باینری و اطلاعات اشکال‌زدایی مرتبط با آن استفاده می‌کند. شیوه کلی عملکرد آن به شرح زیر است:

هنگامی که به ابزار دستور داده شود، یک فایل دودویی و اطلاعات اشکال‌زدایی مرتبط با آن خوانده و تحلیل می‌شوند. بدین منظور، libabigail به‌طور پیش‌فرض توصیف نوع‌های قابل‌دسترسی از طریق رابط‌هایی (توابع و متغیرها) را تحلیل می‌کند که خارج از واحد ترجمه (translation unit) خود قابل مشاهده هستند. پس از اتمام این تحلیل، یک پیکره رابط باینری کاربردی (Application Binary Interface Corpus) تنها با در نظر گرفتن زیرمجموعه‌ای از نوع‌های قابل‌دسترسی از رابط‌های مرتبط با نمادهای ELF http://en.wikipedia.org/wiki/Executable_and_Linkable_Format که توسط فایل دودویی تعریف و صادر شده‌اند، ساخته می‌شود. این پیکره نهایی ABI است که libabigail آن را به عنوان نماینده ABI فایل دودوییِ تحلیل‌شده در نظر می‌گیرد.

سپس Libabigail این قابلیت را دارد که بازنمایی‌های متنی از پیکره‌های ABI تولید کند، آن‌ها را با یکدیگر مقایسه نماید، تغییراتشان را تحلیل کرده و درباره آن‌ها گزارش ارائه دهد.

abipkgdiff [options] <package1> <package2>

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

شیوه فراخوانی جایگزین به این صورت است:

abipkgdiff [options] --set1 <pkg1-v1> <pkg2-v1> <pkg3-v1> \
                     --set2 <pkg1-v2> <pkg2-v2> <pkg3-v2>

که در آن ABI فایل‌های دودویی موجود در دومین مجموعه بسته‌ها در برابر فایل‌های باینری موجود در نخستین مجموعه بسته‌ها مقایسه می‌شوند.

دستور abipkgdiff دو فایل مشخصات سرکوب پیش‌فرض <#suppr-spec-label> را بارگذاری کرده، محتوای آن‌ها را ادغام می‌کند و از آن برای پالایش و حذف گزارش‌های تغییرات ABI که ممکن است برای کاربران مثبت کاذب تلقی شوند استفاده می‌نماید.

  • فایل مشخصات سرکوب پیش‌فرض سراسری سیستم

    این فایل از طریق متغیر محیطی اختیاری LIBABIGAIL_DEFAULT_SYSTEM_SUPPRESSION_FILE تعیین می‌شود. اگر این متغیر محیطی مقداردهی نشده باشد، abipkgdiff تلاش می‌کند فایل سرکوب $libdir/libabigail/libabigail-default.abignore را بارگذاری کند. در صورتی که این فایل موجود نباشد، هیچ فایل مشخصات سرکوب پیش‌فرض سیستمی بارگذاری نمی‌شود.

  • فایل مشخصات سرکوب پیش‌فرض کاربر

    این فایل از طریق متغیر محیطی اختیاری LIBABIGAIL_DEFAULT_USER_SUPPRESSION_FILE تعیین می‌شود. اگر این متغیر محیطی مقداردهی نشده باشد، abipkgdiff تلاش می‌کند فایل سرکوب $HOME/.abignore را بارگذاری کند. در صورتی که این فایل موجود نباشد، هیچ فایل مشخصات سرکوب پیش‌فرضی برای کاربر بارگذاری نمی‌شود.

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

کاربر همچنین می‌تواند از گزینه --suppressions (که در ادامه مستند شده است) برای ارائه یک فایل مشخصات سرکوب استفاده کند.

  • --allow-non-exported-interfaces

    هنگام بررسی اطلاعات اشکال‌زدایی همراه با یک فایل باینری، این ابزار توصیف نوع‌های قابل‌دسترسی از طریق رابط‌هایی (توابع و متغیرها) را تحلیل می‌کند که خارج از واحد ترجمه خود قابل مشاهده هستند. پس از انجام این تحلیل، یک پیکره ABI تنها با در نظر گرفتن زیرمجموعه‌ای از نوع‌های قابل‌دسترسی از رابط‌های مرتبط با نمادهای ELF http://en.wikipedia.org/wiki/Executable_and_Linkable_Format که توسط فایل دودویی تعریف و صادر شده‌اند ساخته می‌شود. این پیکره‌های نهایی ABI هستند که توسط این ابزار مقایسه می‌شوند.

    با این حال، مشکل این رویکرد آن است که تحلیل تمام رابط‌های قابل‌مشاهده از خارج از واحد ترجمه می‌تواند حجم بسیار زیادی از داده‌ها باشد، به‌ویژه زمانی که این فایل‌های باینری برنامه‌های کاربردی باشند (برخلاف کتابخانه‌های اشتراکی). یک نمونه از این برنامه‌ها هسته لینوکس https://kernel.org است. تحلیل چنین پیکره‌های عظیم ABI می‌تواند به شدت کُند باشد.

    اما در حضور یک فایل باینری با «اندازه متوسط»، می‌توان با استفاده از این گزینه به libabigail اجازه داد تا تمام رابط‌های قابل مشاهده در خارج از واحد ترجمه خود را تحلیل کند.

    توجه داشته باشید که این گزینه به‌طور پیش‌فرض فعال است، مگر آنکه با هسته لینوکس https://kernel.org سر و کار داشته باشیم.

  • --btf
این گزینه برای مقایسه بسته‌ها با استفاده از اطلاعات اشکال‌زدایی BTF https://docs.kernel.org/bpf/btf.html (در صورت وجود) به کار می‌رود.
•
--ctf
این گزینه برای مقایسه بسته‌ها با استفاده از اطلاعات اشکال‌زدایی CTF https://raw.githubusercontent.com/wiki/oracle/binutils-gdb/files/ctf-spec.pdf (در صورت وجود) به کار می‌رود.
  • --debug-info-pkg1 | --d1 <path>

    در مواردی که اطلاعات اشکال‌زدایی برای package1 در یک فایل جداگانه قرار دارد، به abipkgdiff اعلام می‌کند که بسته اطلاعات اشکال‌زدایی جداگانه را در کجا پیدا کند.

    توجه داشته باشید که اطلاعات اشکال‌زدایی برای package1 ممکن است در چندین بسته اطلاعات اشکال‌زدایی مختلف تقسیم شده باشد. در این حالت، می‌توان چندین نمونه از این گزینه را همراه با آن بسته‌های اطلاعات اشکال‌زدایی ارائه داد.

  • --debug-info-pkg2 | --d2 <path>

    در مواردی که اطلاعات اشکال‌زدایی برای package2 در یک فایل جداگانه قرار دارد، به abipkgdiff اعلام می‌کند که بسته اطلاعات اشکال‌زدایی جداگانه را در کجا پیدا کند.

    توجه داشته باشید که اطلاعات اشکال‌زدایی برای package2 ممکن است در چندین بسته اطلاعات اشکال‌زدایی مختلف تقسیم شده باشد. در این حالت، می‌توان چندین نمونه از این گزینه را همراه با آن بسته‌های اطلاعات اشکال‌زدایی ارائه داد.

  • --devel-pkg1 | --devel1 <path>

    محل یافتن بسته توسعه https://fedoraproject.org/wiki/Packaging:Guidelines?rd=Packaging/Guidelines#Devel_Packages مرتبط با اولین بسته مورد مقایسه را مشخص می‌کند. این بسته توسعه در مسیر path باید دست‌کم حاوی فایل‌های سرآیندی باشد که نوع‌های عمومی ارائه‌شده توسط کتابخانه‌ها (در اولین بسته مورد مقایسه) در آن‌ها تعریف شده است. هنگامی که این گزینه ارائه شود، این ابزار گزارش‌های مربوط به تغییرات ABI در نوع‌هایی را که در این فایل‌های سرآیند تعریف نشده‌اند فیلتر و حذف می‌کند.

  • --devel-pkg2 | --devel2 <path>

    محل یافتن بسته توسعه https://fedoraproject.org/wiki/Packaging:Guidelines?rd=Packaging/Guidelines#Devel_Packages مرتبط با دومین بسته مورد مقایسه را مشخص می‌کند. این بسته توسعه در مسیر path باید دست‌کم حاوی فایل‌های سرآیندی باشد که نوع‌های عمومی ارائه‌شده توسط کتابخانه‌ها (در دومین بسته مورد مقایسه) در آن‌ها تعریف شده است. هنگامی که این گزینه ارائه شود، این ابزار گزارش‌های مربوط به تغییرات ABI در نوع‌هایی را که در این فایل‌های سرآیند تعریف نشده‌اند فیلتر و حذف می‌کند.

  • --drop-private-types

    این گزینه برای استفاده به همراه گزینه‌های --devel-pkg1 و --devel-pkg2 در نظر گرفته شده است. با استفاده از این گزینه، نوع‌هایی که در فایل‌های سرآیند تعریف نشده‌اند به‌طور کامل از بازنمایی داخلی ایجادشده توسط Libabigail برای نمایش ABI حذف می‌شوند. بنابراین، نیازی به پالایش آن‌ها از گزارش نهایی تغییرات ABI نیست زیرا اصلاً در بازنمایی Libabigail وجود نخواهند داشت.

    اما بدون این گزینه، آن نوع‌های خصوصی در بازنمایی داخلی نگهداری شده و بعداً از گزارش پالایش و فیلتر می‌شوند.

    بنابراین این گزینه می‌تواند مصرف حافظه Libabigail را کاهش دهد. این گزینه عمدتاً برای بهینه‌سازی مصرف حافظه ابزار بر روی فایل‌های باینری با تعداد بسیار زیادی نوع تعریف‌شده و صادرشده عمومی در نظر گرفته شده است.

  • --dso-only

    تنها فایل‌های ELF را که کتابخانه‌های اشتراکی هستند مقایسه می‌کند. به عنوان مثال، فایل‌های اجرایی را مقایسه نمی‌کند.

  • --exported-interfaces-only

    به‌طور پیش‌فرض، هنگام بررسی اطلاعات اشکال‌زدایی همراه با یک فایل باینری، این ابزار توصیف نوع‌های قابل‌دسترسی از طریق رابط‌هایی (توابع و متغیرها) را تحلیل می‌کند که خارج از واحد ترجمه خود قابل مشاهده هستند. پس از اتمام این تحلیل، یک پیکره ABI تنها با در نظر گرفتن زیرمجموعه‌ای از نوع‌های قابل‌دسترسی از رابط‌های مرتبط با نمادهای ELF http://en.wikipedia.org/wiki/Executable_and_Linkable_Format که توسط فایل دودویی تعریف و صادر شده‌اند ساخته می‌شود. این پیکره‌های نهایی ABI هستند که توسط این ابزار مقایسه می‌شوند.

    با این حال، مشکل این رویکرد آن است که تحلیل تمام رابط‌های قابل‌مشاهده از خارج از واحد ترجمه می‌تواند حجم عظیمی از داده باشد، به‌ویژه زمانی که این فایل‌های باینری برنامه‌های کاربردی باشند (برخلاف کتابخانه‌های اشتراکی). یک نمونه از این برنامه‌ها هسته لینوکس https://kernel.org است. تحلیل چنین پیکره‌های عظیم ABI می‌تواند به شدت کُند باشد.

    برای حل این مشکل کارایی، این گزینه به libabigail امکان می‌دهد تنها نوع‌هایی را تحلیل کند که از رابط‌های مرتبط با نمادهای تعریف‌شده و صادرشده ELF http://en.wikipedia.org/wiki/Executable_and_Linkable_Format قابل دسترسی هستند.

    توجه داشته باشید که این گزینه هنگام تحلیل هسته لینوکس https://kernel.org به‌طور پیش‌فرض فعال است؛ در غیر این صورت، به‌طور پیش‌فرض خاموش می‌باشد.

  • --fail-no-dbg

    در صورتی که برنامه نتواند هیچ‌یک از اطلاعات اشکال‌زدایی ناشی از بسته‌های debug info ارائه‌شده در خط فرمان را بخواند، اجرای برنامه را با خطا متوقف کرده و یک کد خروج غیرصفر برمی‌گرداند. اگر هیچ بسته debug info در خط فرمان مشخص نشده باشد، این گزینه فعال نخواهد بود.

    توجه داشته باشید که کد خروج غیرصفرِ بازگردانده‌شده توسط برنامه در نتیجه این گزینه، مقدار ثابت ABIDIFF_ERROR است. برای آگاهی از مقدار عددی این ثابت، لطفاً به مستندات کد خروج <#abidiff-return-value-label> مراجعه فرمایید.

  • --full-impact|-f

    هنگام مقایسه دو بسته هسته لینوکس، این گزینه به abipkgdiff دستور می‌دهد تا اصطلاحاً گزارش تأثیر کامل (full impact report) را صادر کند که نوع گزارش پیش‌فرضی است که توسط ابزار abidiff تولید می‌شود:

$ abidiff libtest-v0.so libtest-v1.so
Functions changes summary: 0 Removed, 1 Changed, 0 Added function
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
1 function with some indirect sub-type change:
  [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
    parameter 1 of type 'C&' has sub-type changes:
      in referenced type 'struct C' at test-v1.cc:7:1:
        type size hasn't changed
        1 data member change:
         type of 'leaf* C::m0' changed:
           in pointed to type 'struct leaf' at test-v1.cc:1:1:
             type size changed from 32 to 64 bits
             1 data member insertion:
               'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
$
  • --harmless

    در گزارش تفاضلی، تنها تغییرات بی‌ضرر <#harmlesschangeconcept-label> را نمایش می‌دهد. به‌طور پیش‌فرض، تغییرات بی‌ضرر از گزارش تفاضلی فیلتر می‌شوند تا شلوغی خروجی به حداقل رسیده و بخت شناسایی مشکلات واقعی ABI بیشتر شود.

  • --help | -h

    نمایش راهنمای مختصر درباره دستور و خروج.

  • --ignore-soname

    اگر دو فایل باینری با SONAMEهای مختلف، نام یکسانی در بسته‌های قدیمی و جدید مورد مقایسه داشته باشند، این گزینه abipkgdiff را وادار می‌کند تا آن‌ها را صرف‌نظر از تغییر آشکار SONAME مقایسه کند. این امر امکان تحلیل تغییرات ABI را که ممکن است توسعه‌دهندگان را به تغییر SONAME واداشته باشد، فراهم می‌سازد.

  • --impacted-interfaces
هنگام نمایش تغییرات انتهایی (leaf changes)، این گزینه به abipkgdiff دستور می‌دهد تا فهرست رابط‌های متأثر را نمایش دهد. بنابراین، این گزینه باید همراه با گزینه --leaf-changes-only یا هنگام مقایسه دو بسته هسته لینوکس استفاده شود؛ در غیر این صورت، نادیده گرفته می‌شود.
  • --keep-tmp-files

    پوشه‌ها و فایل‌های موقتی را که در طول اجرای ابزار ایجاد می‌شوند پاک نمی‌کند.

  • --leaf-changes-only|-l تنها تغییرات برگ (انتهایی) را نمایش می‌دهد، بنابراین گزارش تحلیل تأثیر را نشان نمی‌دهد. این گزینه متضمن --redundant است.

    خروجی نوعی abipkgdiff و abidiff هنگام مقایسه دو فایل باینری که آن را گزارش تأثیر کامل می‌نامیم، به شکل زیر است:

$ abidiff libtest-v0.so libtest-v1.so
Functions changes summary: 0 Removed, 1 Changed, 0 Added function
Variables changes summary: 0 Removed, 0 Changed, 0 Added variable
1 function with some indirect sub-type change:
  [C]'function void fn(C&)' at test-v1.cc:13:1 has some indirect sub-type changes:
    parameter 1 of type 'C&' has sub-type changes:
      in referenced type 'struct C' at test-v1.cc:7:1:
        type size hasn't changed
        1 data member change:
         type of 'leaf* C::m0' changed:
           in pointed to type 'struct leaf' at test-v1.cc:1:1:
             type size changed from 32 to 64 bits
             1 data member insertion:
               'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
$

بنابراین در این مثال، گزارش اطلاعاتی درباره چگونگی دسترسی به تغییر درج عضو داده "struct leaf" از تابع "void fn(C&)" ارائه می‌دهد. به بیان دیگر، گزارش نه‌تنها تغییر عضو داده روی "struct leaf" را نشان می‌دهد، بلکه تأثیر آن تغییر بر روی تابع "void fn(C&)" را نیز مشخص می‌کند.

در اصطلاحات abidiff (و abipkgdiff)، تغییر روی "struct leaf" یک تغییر برگ یا انتهایی (leaf change) نامیده می‌شود. بنابراین گزینه‌های --leaf-changes-only --impacted-interfaces تنها همان تغییر برگ را نمایش می‌دهند، که به شکل زیر خواهد بود:

$ abidiff -l libtest-v0.so libtest-v1.so
'struct leaf' changed:
  type size changed from 32 to 64 bits
  1 data member insertion:
    'char leaf::m1', at offset 32 (in bits) at test-v1.cc:4:1
  one impacted interface:
    function void fn(C&)
$

توجه داشته باشید که گزارش چگونه با نمایش فهرستی از رابط‌های متأثر از تغییر برگ به پایان می‌رسد. این حاصل اثر گزینه تکمیلی --impacted-interfaces است.

حال اگر مایل به مشاهده آن فهرست از رابط‌های متأثر نیستید، می‌توانید به سادگی از به کار بردن گزینه --impacted-interface خودداری نمایید. در هر صورت، می‌توانید درباره این گزینه در بخش‌های دیگر مطالعه کنید.

لطفاً توجه داشته باشید که هنگام مقایسه دو بسته هسته لینوکس، این گزارش تغییرات برگ است که به‌طور پیش‌فرض صادر می‌شود. گزارش معمولی موسوم به گزارش تأثیر کامل را می‌توان با گزینه --full-impact که پیش‌تر در بالا توضیح داده شد صادر کرد.

  • --linux-kernel-abi-whitelist | -w <path-to-whitelist>

    هنگام مقایسه دو بسته RPM هسته لینوکس، این گزینه به فهرست سفید (لیست مجاز) نام‌های نمادهای ELF از توابع و متغیرهایی اشاره دارد که باید برای تغییرات ABI مقایسه شوند. این لیست مجاز «فهرست سفید ABI هسته لینوکس» نامیده می‌شود.

    هر تابع یا متغیر دیگری که نماد ELF آن در آن فهرست سفید موجود نباشد، توسط فرایند مقایسه ABI در نظر گرفته نخواهد شد.

    اگر این گزینه ارائه نشود -- یعنی اگر هیچ فهرست سفیدی ارائه نگردد -- آنگاه ABI تمامی توابع و متغیرهای سراسری که به صورت عمومی توسط فایل‌های باینری هسته لینوکس تعریف و صادر شده‌اند، مقایسه می‌شود.

    لطفاً توجه داشته باشید که اگر یک بسته فهرست سفید به عنوان پارامتر داده شود، این گزینه به درستی آن را پردازش می‌کند، درست مانند اینکه از گزینه --wp استفاده شده باشد.

  • --no-abignore

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

  • --no-added-binaries

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

    لطفاً توجه داشته باشید که وجود چنین فایل‌های باینری اضافه‌شده‌ای توسط این ابزار به عنوان تغییر ABI تلقی نمی‌شود؛ از این رو، هیچ تأثیری بر کد خروج ابزار ندارد و تنها جنبه اطلاع‌رسانی دارد. با این حال، فایل‌های باینری حذف‌شده به عنوان تغییر ABI در نظر گرفته می‌شوند.

  • --no-added-syms

    فهرست توابع، متغیرها یا هر نمادی را که اضافه شده است نمایش نمی‌دهد.

  • --no-assume-odr-for-cplusplus

    هنگام تحلیل یک فایل باینری منشعب از کد ++C با استفاده از اطلاعات اشکال‌زدایی DWARF http://www.dwarfstd.org، کتابخانه libabigail برای افزایش سرعت تحلیل، قاعده یک تعریف (One Definition Rule) https://en.wikipedia.org/wiki/One_Definition_Rule را مفروض می‌داند. در این حالت، هنگامی که چندین نوع دارای نام یکسانی در فایل باینری باشند، همگی برابر فرض می‌شوند.

    این گزینه این فرض را غیرفعال کرده و به libabigail دستور می‌دهد تا نوع‌ها را واقعاً مقایسه کند تا برابری آن‌ها را بسنجد.

  • --no-default-suppression

    فایل‌های مشخصات سرکوب پیش‌فرض را بارگذاری نمی‌کند.

  • --no-leverage-dwarf-factorization

    هنگام تحلیل یک فایل باینری که اطلاعات اشکال‌زدایی DWARF http://www.dwarfstd.org آن توسط ابزار DWZ https://sourceware.org/dwz پردازش شده است، انتظار می‌رود اطلاعات نوع قبلاً فاکتورگیری شده باشد. این زمینه توسط libabigail برای انجام برخی بهینه‌سازی‌های سرعت مورد استفاده قرار می‌گیرد.

    این گزینه این بهینه‌سازی‌ها را غیرفعال می‌کند.

  • --no-linkage-name

    در گزارش حاصل، نام‌های پیوند (linkage names) توابع یا متغیرهای اضافه‌شده، حذف‌شده یا تغییریافته را نمایش نمی‌دهد.

  • --no-parallel

    به‌طور پیش‌فرض، abipkgdiff از تمام پردازنده‌های در دسترس برای اجرای همزمان استفاده خواهد کرد. این گزینه به آن دستور می‌دهد که بسته‌ها را استخراج نکرده یا مقایسه‌ها را به صورت موازی اجرا ننماید.

  • --non-reachable-types|-t

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

    این گزینه ممکن است افت کارایی شدیدی در پی داشته باشد زیرا تعداد نوع‌های تحلیل‌شده می‌تواند بسیار بالا باشد. با این حال، اگر با گزینه‌های --devel-pkg{1,2} همراه شود، نوع‌های غیرقابل‌دسترسِ تحلیل‌شده تنها به مواردی محدود می‌شوند که در فایل‌های سرآیند عمومی موجود در بسته‌های توسعه مرجع تعریف شده‌اند، که امید می‌رود افت کارایی را در حدی قابل قبول نگه دارد.

    همچنین استفاده از این گزینه در کنار مشخصات سرکوب (با استفاده از گزینه --suppressions) ممکن است به کنترل تعداد نوع‌های تحلیل‌شده (و افت احتمالی کارایی) کمک نماید.

    توجه داشته باشید که بدون این گزینه، تنها نوع‌هایی که از طریق توابع و متغیرهای سراسری قابل دسترسی هستند تحلیل می‌شوند، بنابراین ابزار تغییرات را تنها روی این نوع‌های در دسترس شناسایی و گزارش می‌کند.

  • --no-show-locs
اطلاعات مربوط به اینکه در کجای دومین کتابخانه اشتراکی نوع مربوطه تغییر یافته است را نمایش نمی‌دهد.
•
--no-show-relative-offset-changes
بدون این گزینه، هنگامی که آفست یک عضو داده تغییر می‌کند، گزارش تغییرات نه‌تنها آفست قبلی و جدید را ذکر می‌کند، بلکه بیان می‌دارد که عضو داده به اندازه چند بیت تغییر یافته است. با این گزینه، این مورد اخیر نمایش داده نمی‌شود.
  • --no-unreferenced-symbols

    در گزارش حاصل، اطلاعات تغییر نمادهای توابع و متغیرهایی را که توسط هیچ اطلاعات اشکال‌زدایی ارجاع داده نشده‌اند نمایش نمی‌دهد. توجه داشته باشید که برای این نمادهای ارجاع‌داده‌نشده توسط اطلاعات اشکال‌زدایی، اطلاعات تغییرِ نمایش‌داده‌شده صرفاً شامل نمادهای اضافه‌شده یا حذف‌شده است.

  • --show-bits

    نمایش اندازه‌ها و آفست‌ها بر حسب بیت، نه بایت. این گزینه به‌طور پیش‌فرض فعال است.

  • --show-bytes

    نمایش اندازه‌ها و آفست‌ها بر حسب بایت، نه بیت. به‌طور پیش‌فرض اندازه‌ها و آفست‌ها بر حسب بیت نمایش داده می‌شوند.

  • --show-dec

    نمایش اندازه‌ها و آفست‌ها در مبنای ده‌دهی (decimal). این گزینه به‌طور پیش‌فرض فعال است.

  • --show-hex

    نمایش اندازه‌ها و آفست‌ها در مبنای شانزده‌شانزدهی (hexadecimal).

  • --show-identical-binaries
نام تمام فایل‌های باینری مقایسه‌شده را نمایش می‌دهد، از جمله فایل‌های باینری که ABI آن‌ها یکسان است. به‌طور پیش‌فرض، در صورتی که این گزینه ارائه نشود، تنها فایل‌های باینری دارای تغییرات ABI در خروجی ذکر می‌شوند.
  • --private-dso

    به‌طور پیش‌فرض، abipkgdiff اشیاء اشتراکی پویایی (DSO) را که مختص بسته RPM هستند مقایسه نمی‌کند. یک DSO اختصاصی، شیء اشتراکی است که SONAME آن در ویژگی «provides» بسته RPM اعلان نشده باشد.

    این گزینه به abipkgdiff دستور می‌دهد تا DSOهایی را که در ویژگی «provides» بسته RPM اعلان نشده‌اند نیز مقایسه کند.

    لطفاً توجه داشته باشید این موضوع که (به‌طور پیش‌فرض) abipkgdiff از DSOهای اختصاصی صرف‌نظر می‌کند، قابلیتی است که در حال حاضر تنها برای بسته‌های RPM موجود است. ما با کمال میل وصله‌هایی را که این ویژگی را برای سایر قالب‌های بسته بیفزایند می‌پذیریم.

  • --redundant
در گزارش‌های تفاضلی، تغییرات مازاد (تکراری) را نمایش می‌دهد. تغییر مازاد تغییری است که در بخش دیگری از یک گزارش مشخص نمایش داده شده باشد.
•
--self-check

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

$ abipkgdiff --self-check --d1 mesa-libGLU-debuginfo-9.0.1-3.fc33.x86_64.rpm  mesa-libGLU-9.0.1-3.fc33.x86_64.rpm
 ==== SELF CHECK SUCCEEDED for 'libGLU.so.1.3.1' ====
$
  • --set1 <package1-path> <package2-path> <package2-path> ...

    نخستین مجموعه از بسته‌هایی را مشخص می‌کند که فایل‌های باینری آن‌ها قرار است در برابر مجموعه دوم مقایسه شوند. توجه داشته باشید که دومین مجموعه بسته‌ها باید با استفاده از گزینه --set2 مشخص شود.

  • --set2 <package1-path> <package2-path> <package2-path> ...

    دومین مجموعه از بسته‌هایی را مشخص می‌کند که فایل‌های باینری آن‌ها قرار است در برابر مجموعه اول مقایسه شوند. توجه داشته باشید که نخستین مجموعه بسته‌ها باید با استفاده از گزینه --set1 مشخص شود.

  • --suppressions | --suppr <path-to-suppressions>

    از یک فایل مشخصات سرکوب <#suppr-spec-label> واقع در path-to-suppressions استفاده می‌کند. توجه داشته باشید که این گزینه می‌تواند چندین بار در خط فرمان تکرار شود. در این حالت، تمامی فایل‌های مشخصات سرکوب در نظر گرفته خواهند شد.

    لطفاً توجه داشته باشید که به‌طور پیش‌فرض، اگر این گزینه ارائه نشود، فایل‌های مشخصات سرکوب پیش‌فرض بارگذاری می‌شوند.

  • --version | -v

    نمایش نسخه برنامه و خروج.

  • --wp <path-to-whitelist-package>

    هنگام مقایسه دو بسته RPM هسته لینوکس، این گزینه به یک بسته RPM حاوی چندین فهرست سفید از نام‌های نمادهای ELF از توابع و متغیرهایی اشاره دارد که باید برای تغییرات ABI مقایسه شوند. این لیست‌های مجاز «فهرست‌های سفید ABI هسته لینوکس» نام دارند.

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

    آن فهرست سفید انتخاب‌شده ABI هسته لینوکس شامل فهرست نام‌های نمادهای ELF مربوط به توابع و متغیرهایی است که باید برای تغییرات ABI مقایسه شوند.

    هر تابع یا متغیر دیگری که نماد ELF آن در آن فهرست سفید وجود نداشته باشد، در فرایند مقایسه ABI در نظر گرفته نخواهد شد.

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

    اگر این گزینه ارائه نشود -- یعنی اگر هیچ فهرست سفیدی ارائه نگردد -- آنگاه ABI تمامی توابع و متغیرهای سراسری که به صورت عمومی توسط فایل‌های باینری هسته لینوکس تعریف و صادر شده‌اند، مقایسه می‌شود.

  • --verbose

    پیام‌های پیشرفت تفصیلی را صادر می‌کند.

  • --verbose-diff

    پیام‌های تفصیلی و زمان‌بندی‌شده درباره فرآیند مقایسه (diffing) صادر می‌کند. این گزینه متضمن گزینه --verbose است.

کد خروج دستور abipkgdiff در صورتی که ABI فایل‌های باینری مقایسه‌شده یکسان باشد برابر با 0 است، و در صورتی که با یکدیگر تفاوت داشته باشند یا ابزار با خطایی مواجه شود، غیرصفر خواهد بود.

در حالت دوم، مقدار کد خروج همانند ابزار abidiff است <#abidiff-return-value-label>.

Dodji Seketeli

2014-2025, Red Hat, Inc.

May 1, 2026