نام (NAME)

dpkg-gensymbols - تولید فایل‌های نماد (اطلاعات وابستگی کتابخانه اشتراکی)

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

dpkg-gensymbols [گزینه...]

توضیحات (DESCRIPTION)

dpkg-gensymbols درخت ساخت موقت (به‌طور پیش‌فرض debian/tmp) را برای یافتن کتابخانه‌ها پویش می‌کند و یک فایل symbols شامل توصیف آن‌ها تولید می‌نماید. این فایل، در صورتی که خالی نباشد، سپس در زیرپوشه DEBIAN از درخت ساخت نصب می‌شود تا در نهایت در فراداده‌های بسته گنجانده شود.

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

debian/package.symbols.arch
debian/symbols.arch
debian/package.symbols
debian/symbols

هدف اصلی این فایل‌ها، ارائه حداقل نسخه مرتبط با هر نماد ارائه‌شده توسط کتابخانه‌ها است. معمولاً این نسخه با نخستین نسخه بسته که نماد را ارائه کرده است مطابقت دارد، اما اگر ABI نماد بدون شکستن سازگاری عقبرو گسترش یابد، می‌تواند به‌صورت دستی توسط نگه‌دارنده افزایش داده شود. مسئولیت به‌روز و دقیق نگه داشتن این فایل‌ها با نگه‌دارنده است، اما dpkg-gensymbols به این کار کمک می‌کند.

هنگامی که فایل‌های نماد تولیدشده با فایلی که توسط نگه‌دارنده ارائه شده متفاوت باشد، dpkg-gensymbols تفاوت (diff) بین دو نسخه را چاپ خواهد کرد. علاوه بر این اگر تفاوت بیش از حد قابل توجه باشد، حتی با شکست مواجه خواهد شد (می‌توانید میزان تفاوتی را که تحمل می‌کنید شخصی‌سازی کنید، گزینه -c را ببینید).

این برنامه در dpkg نسخه 1.14.8 معرفی شد.

نگهداری فایل‌های نماد (MAINTAINING SYMBOLS FILES)

فرمت تبادل پایه فایل نمادها در deb-symbols(5) توصیف شده است که توسط فایل‌های نماد موجود در بسته‌های دودویی استفاده می‌شود. این فایل‌ها از فایل‌های الگوی نماد با قالبی بر پایه قالب اولیه، که در deb-src-symbols(5) توصیف شده و در بسته‌های منبع گنجانده شده‌اند، تولید می‌شوند.

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

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

در بیشتر موارد، تفاوت مستقیماً روی فایل debian/package.symbols اعمال می‌شود. با این حال، معمولاً تغییرات بیشتری مورد نیاز است: برای مثال توصیه می‌شود نسخه بازنگری دبیان (Debian revision) از نسخه حداقلی حذف شود تا بسته‌های پورت‌شده به عقب (backports) با شماره نسخه پایین‌تر اما همان نسخه بالادستی، همچنان وابستگی‌های تولیدشده را برآورده کنند. اگر بازنگری دبیان را نتوان حذف کرد چون نماد واقعاً توسط تغییر خاص دبیان اضافه شده است، باید پسوند ‘~’ به نسخه اضافه شود.

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

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

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

مدیریت مناسب کتابخانه (Good library management)

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

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

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

گزینه‌ها (OPTIONS)

-Ppackage-build-dir: پویش package-build-dir به جای debian/tmp.
-ppackage: تعیین نام بسته. اگر بیش از یک بسته دودویی در debian/control فهرست شده باشد (یا اگر فایل debian/control وجود نداشته باشد) الزامی است.
-vversion: تعیین نسخه بسته. پیش‌فرض آن نسخه‌ای است که از debian/changelog استخراج می‌شود. اگر خارج از درخت بسته منبع فراخوانی شود الزامی است.
-elibrary-file: تنها تحلیل کتابخانه‌هایی که صریحاً فهرست شده‌اند، به جای یافتن تمام کتابخانه‌های عمومی. می‌توانید از الگوهای پوسته مورد استفاده برای بسط مسیر در library-file استفاده کنید (برای جزئیات به صفحه راهنمای File::Glob مراجعه کنید) تا چندین کتابخانه را با یک آرگومان تطبیق دهید (در غیر این صورت به چندین -e نیاز دارید).
-ldirectory: افزودن directory به ابتدای فهرست پوشه‌های جستجو برای کتابخانه‌های اشتراکی خصوصی (از dpkg 1.19.1 به بعد). این گزینه می‌تواند چندین بار استفاده شود.
توجه: از این گزینه به جای تنظیم LD_LIBRARY_PATH استفاده کنید، زیرا آن متغیر محیطی برای کنترل پیونددهنده زمان اجرا استفاده می‌شود و استفاده نادرست از آن برای تنظیم مسیرهای کتابخانه اشتراکی در زمان ساخت، برای مثال هنگام کامپایل متقاطع می‌تواند مشکل‌ساز باشد.
-Ifilename: استفاده از filename به عنوان فایل مرجع برای تولید فایل نمادهایی که در خود بسته ادغام می‌شود.
-O[filename]: چاپ فایل نمادهای تولیدشده در خروجی استاندارد یا در filename در صورت مشخص شدن، به جای debian/tmp/DEBIAN/symbols (یا package-build-dir/DEBIAN/symbols اگر -P استفاده شده باشد). اگر filename از قبل وجود داشته باشد، محتویات آن به عنوان مبنایی برای فایل نمادهای تولیدشده استفاده می‌شود. می‌توانید از این ویژگی برای به‌روزرسانی فایل نمادها استفاده کنید تا با نسخه بالادستی جدیدتر کتابخانه شما مطابقت داشته باشد.
-t: نوشتن فایل نمادها در حالت الگو به جای قالبی که با deb-symbols(5) سازگار است. تفاوت اصلی این است که در حالت الگو، نام‌ها و برچسب‌های نماد به شکل اصلی خود نوشته می‌شوند، بر خلاف نام نمادهای پس‌پردازش‌شده با برچسب‌های حذف‌شده در حالت سازگاری. علاوه بر این، ممکن است هنگام نوشتن یک فایل استاندارد deb-symbols(5) برخی نمادها حذف شوند (بر اساس قواعد پردازش برچسب) در حالی که همه نمادها همیشه در الگوی فایل نماد نوشته می‌شوند.
-c[0-4]: تعیین بررسی‌هایی که هنگام مقایسه فایل نمادهای تولیدشده با فایل الگوی استفاده‌شده به عنوان نقطه شروع انجام می‌شود. به‌طور پیش‌فرض این سطح 1 است. افزایش سطوح بررسی‌های بیشتری انجام می‌دهد و شامل تمام بررسی‌های سطوح پایین‌تر نیز می‌شود.

سطح 0: هرگز با شکست مواجه نمی‌شود.
سطح 1: اگر برخی نمادها ناپدید شده باشند با شکست مواجه می‌شود.
سطح 2: اگر برخی نمادهای جدید معرفی شده باشند با شکست مواجه می‌شود.
سطح 3: اگر برخی کتابخانه‌ها ناپدید شده باشند با شکست مواجه می‌شود.
سطح 4: اگر برخی کتابخانه‌های جدید معرفی شده باشند با شکست مواجه می‌شود.

این مقدار می‌تواند توسط متغیر محیطی DPKG_GENSYMBOLS_CHECK_LEVEL بازنویسی شود.

-q: سکوت پیشه کردن و هرگز تفاوتی بین فایل نمادهای تولیدشده و فایل الگوی مورد استفاده به عنوان نقطه شروع تولید نکردن و عدم نمایش هرگونه هشدار در مورد کتابخانه‌ها یا نمادهای جدید/گمشده. این گزینه فقط خروجی اطلاعاتی را غیرفعال می‌کند اما خود بررسی‌ها را غیرفعال نمی‌کند (گزینه -c را ببینید).
-aarch: فرض کردن arch به عنوان معماری میزبان هنگام پردازش فایل‌های نماد. از این گزینه برای تولید یک فایل نماد یا تفاوت برای هر معماری استفاده کنید، به شرطی که فایل‌های دودویی آن از قبل در دسترس باشند.
-d: فعال کردن حالت اشکال‌زدایی. پیام‌های متعددی برای توضیح آنچه dpkg-gensymbols انجام می‌دهد نمایش داده می‌شود.
-V: فعال کردن حالت پرگویی (verbose). فایل نمادهای تولیدشده شامل نمادهای منسوخ به صورت یادداشت است. علاوه بر این در حالت الگو، نمادهای الگو با یادداشت‌هایی دنبال می‌شوند که نمادهای واقعی منطبق با الگو را فهرست می‌کنند.
-?, --help: نمایش پیام راهنما و خروج.
--version: نمایش نسخه و خروج.

محیط (ENVIRONMENT)

DEB_HOST_ARCH: تعیین معماری میزبان در صورتی که گزینه --arch مشخص نشده باشد.
DPKG_GENSYMBOLS_CHECK_LEVEL: سطح بررسی دستور را بازنویسی می‌کند، حتی اگر آرگومان خط فرمان -c داده شده باشد (توجه داشته باشید که این با سنت معمول تقدم داشتن آرگومان‌های خط فرمان بر متغیرهای محیطی مغایرت دارد).
DPKG_COLORS: حالت رنگی را تنظیم می‌کند (از dpkg 1.18.5 به بعد). مقادیر پذیرفته‌شده در حال حاضر عبارتند از: auto (پیش‌فرض)، always و never.
DPKG_NLS: در صورت تنظیم، برای تصمیم‌گیری در مورد فعال‌سازی پشتیبانی از زبان مادری (Native Language Support)، که به عنوان پشتیبانی بین‌المللی‌سازی (یا i18n) نیز شناخته می‌شود، استفاده خواهد شد (از dpkg 1.19.0 به بعد). مقادیر پذیرفته‌شده عبارتند از: 0 و 1 (پیش‌فرض).

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

https://people.redhat.com/drepper/symbol-versioning, https://people.redhat.com/drepper/goodpractice.pdf, https://people.redhat.com/drepper/dsohowto.pdf, deb-src-symbol(5), deb-symbols(5), dpkg-shlibdeps(1).