توضیحات (Comments)

توضیحات در پرونده‌های الگوی نماد پشتیبانی می‌شوند. هر خطی که نخستین نویسه آن ‘#’ باشد یک توضیح است، مگر اینکه با ‘#include’ آغاز شود (بخش «استفاده از includeها» را ببینید). خطوطی که با ‘#MISSING:’ آغاز می‌شوند توضیحات ویژه‌ای هستند که نمادهای ناپدیدشده را مستند می‌کنند.

استفاده از جایگزینی‌های فرامتغیر (Using metavariable substitutions)

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

برخلاف فرامتغیر #MINVER#، فرامتغیرهای زیر هرگز در یک پرونده نمادها درون یک بسته باینری ظاهر نخواهند شد.

استفاده از فرامتغیر #PACKAGE#

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

استفاده از فرامتغیر #CURVER# (Using the #CURVER# metavariable)

در برخی موارد، یک نماد با ABI ناپایدار به یک وابستگی دقیق به نسخه بسته فعلی نیاز خواهد داشت. برای جلوگیری از کدگذاری سخت نسخه فعلی در پرونده نمادها، می‌توانید از فرامتغیر #CURVER# استفاده کنید. این متغیر با یک قید نسخه وابستگی به صورت “(= binary-version)” جایگزین خواهد شد، جایی که معمولاً در ترکیب با #PACKAGE# استفاده می‌شود.

پشتیبانی‌شده از dpkg 1.23.4.

استفاده از برچسب‌های نماد (Using symbol tags)

برچسب‌گذاری نماد برای علامت‌گذاری نمادهایی که به نحوی خاص هستند مفید است. هر نماد می‌تواند تعداد دلخواهی برچسب مرتبط داشته باشد. در حالی که همه برچسب‌ها تجزیه و ذخیره می‌شوند، تنها برخی از آن‌ها توسط dpkg-gensymbols درک شده و پردازش ویژه‌ای را برای نمادها فعال می‌کنند. برای ارجاع به این برچسب‌ها، زیربخش «برچسب‌های استاندارد نماد» را ببینید.

مشخصات برچسب دقیقاً پیش از نام نماد می‌آید (هیچ فاصله خالی مجاز نیست). این مشخصات همیشه با یک قلاب بازشونده ( آغاز می‌شود، با یک قلاب بسته‌شونده ) پایان می‌یابد و باید حداقل شامل یک برچسب باشد. برچسب‌های چندگانه با نویسه | از یکدیگر جدا می‌شوند. هر برچسب می‌تواند به صورت اختیاری دارای یک مقدار باشد که با نویسه = از نام برچسب جدا می‌شود. نام‌ها و مقادیر برچسب می‌توانند رشته‌های دلخواه باشند، به جز اینکه نمی‌توانند شامل نویسه‌های ویژه ) | = باشند. نام‌های نماد پس از مشخصات برچسب می‌توانند به صورت اختیاری با نویسه‌های ' یا " درون نقل‌قول قرار گیرند تا وجود فاصله‌های خالی در آن‌ها مجاز باشد. با این حال، اگر هیچ برچسبی برای نماد مشخص نشده باشد، نقل‌قول‌ها به عنوان بخشی از نام نماد در نظر گرفته می‌شوند که تا اولین فاصله ادامه می‌یابد.

(tag1=i am marked|tag name with space)"tagged quoted symbol"@Base 1.0
(optional)tagged_unquoted_symbol@Base 1.0 1
untagged_symbol@Base 1.0

نخستین نماد در این مثال tagged quoted symbol نام دارد و دارای دو برچسب است: tag1 با مقدار i am marked و tag name with space که مقداری ندارد. نماد دوم به نام tagged_unquoted_symbol تنها با برچسب optional برچسب‌گذاری شده است. نماد آخر نمونه‌ای از یک نماد معمولی بدون برچسب است.

از آنجا که برچسب‌های نماد توسعه‌ای از قالب deb-symbols(5) هستند، آن‌ها تنها می‌توانند بخشی از پرونده‌های نماد مورد استفاده در بسته‌های مبدا باشند (این پرونده‌ها سپس باید به عنوان الگوهایی در نظر گرفته شوند که برای ساخت پرونده‌های نماد تعبیه‌شده در بسته‌های باینری به کار می‌روند). هنگامی که dpkg-gensymbols بدون گزینه -t فراخوانی شود، پرونده‌های نمادهایی سازگار با قالب deb-symbols(5) خروجی می‌دهد: این ابزار نمادها را طبق نیازمندی‌های برچسب‌های استاندارد آن‌ها به‌طور کامل پردازش کرده و تمام برچسب‌ها را از خروجی حذف می‌کند. برعکس، در حالت الگو (-t) تمام نمادها و برچسب‌های آن‌ها (هم برچسب‌های استاندارد و هم ناشناخته) در خروجی حفظ شده و به همان شکل اصلی که بارگذاری شده بودند نوشته می‌شوند.

برچسب‌های استاندارد نماد (Standard symbol tags)

optional

نمادی که به عنوان اختیاری (optional) علامت‌گذاری شده است می‌تواند در هر زمانی از کتابخانه ناپدید شود و این هرگز باعث شکست dpkg-gensymbols نخواهد شد. با این حال، نمادهای اختیاری ناپدیدشده به‌طور مداوم در diff هر بازبینی جدید بسته به صورت MISSING ظاهر می‌شوند. این رفتار به عنوان یادآوری برای نگهدارنده بسته عمل می‌کند که چنین نمادی باید از پرونده نماد حذف شود یا دوباره به کتابخانه اضافه گردد. هنگامی که نماد اختیاری، که پیش‌تر به صورت MISSING اعلام شده بود، ناگهان در بازبینی بعدی دوباره ظاهر شود، با حفظ حداقل نسخه خود به وضعیت «موجود» (existing) بازگردانده می‌شود.

این برچسب برای نمادهایی که خصوصی هستند و ناپدید شدن آن‌ها باعث شکستن ABI نمی‌شود مفید است. برای نمونه، بیشتر نمونه‌سازی‌های الگوی C++ در این دسته‌بندی قرار می‌گیرند. مانند هر برچسب دیگری، این برچسب نیز ممکن است دارای یک مقدار دلخواه باشد: می‌توان از آن برای نشان دادن علت اختیاری بودن نماد استفاده کرد.

arch=architecture-list

arch-bits=architecture-bits

arch-endian=architecture-endianness

این برچسب‌ها امکان محدود کردن مجموعه معماری‌هایی را فراهم می‌کنند که نماد انتظار می‌رود در آن‌ها وجود داشته باشد. برچسب‌های arch-bits و arch-endian از dpkg 1.18.0 پشتیبانی می‌شوند. هنگامی که فهرست نمادها با نمادهای کشف‌شده در کتابخانه به‌روزرسانی می‌شود، با همه نمادهای وابسته به معماری که به معماری میزبان فعلی مربوط نیستند طوری رفتار می‌شود که گویی وجود ندارند. اگر نمادی وابسته به معماری که با معماری میزبان فعلی مطابقت دارد در کتابخانه وجود نداشته باشد، رویه‌های معمول برای نمادهای ناموجود اعمال شده و ممکن است باعث شکست dpkg-gensymbols شود. از سوی دیگر، اگر نماد وابسته به معماری در حالی یافت شود که قرار نبوده وجود داشته باشد (زیرا معماری میزبان فعلی در برچسب فهرست نشده یا با اندیان بودن و تعداد بیت‌ها مطابقت ندارد)، آن نماد خنثی نسبت به معماری در نظر گرفته می‌شود (یعنی برچسب‌های arch، arch-bits و arch-endian حذف می‌شوند و نماد به دلیل این تغییر در diff ظاهر خواهد شد)، اما به عنوان نمادی جدید در نظر گرفته نمی‌شود.

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

قالب architecture-list همان قالبی است که در فیلد Build-Depends در debian/control استفاده می‌شود (به جز کروشه‌های احاطه‌کننده []). برای نمونه، نخستین نماد از فهرست زیر تنها در معماری‌های arm64، any-amd64 و riscv64 در نظر گرفته خواهد شد، دومی تنها در معماری‌های linux و سومی در هر جایی به جز armel.

(arch=arm64 any-amd64 riscv64)arch_specific_symbol@Base 1.0
(arch=linux-any)linux_specific_symbol@Base 1.0
(arch=!armel)symbol_armel_does_not_have@Base 1.0

شناسه architecture-bits یا 32 یا 64 است.

(arch-bits=32)32bit_specific_symbol@Base 1.0
(arch-bits=64)64bit_specific_symbol@Base 1.0

شناسه architecture-endianness یا little یا big است.

(arch-endian=little)little_endian_specific_symbol@Base 1.0
(arch-endian=big)big_endian_specific_symbol@Base 1.0

می‌توان چندین محدودیت را زنجیره‌وار ترکیب کرد.

(arch-bits=32|arch-endian=little)32bit_le_symbol@Base 1.0

allow-internal

دستور dpkg-gensymbols دارای فهرستی از نمادهای داخلی است که نباید در پرونده‌های نمادها ظاهر شوند زیرا معمولاً فقط عوارض جانبی جزئیات پیاده‌سازی زنجیره ابزار هستند (از dpkg 1.20.1). اگر بنا به دلایلی واقعاً می‌خواهید یکی از آن نمادها در پرونده نمادها گنجانده شود، باید نماد را با برچسب allow-internal علامت‌گذاری کنید. این کار می‌تواند برای برخی از کتابخانه‌های سطح پایین زنجیره ابزار مانند “libgcc” ضروری باشد.

c++

نشان‌دهنده الگوی نماد c++ است. زیربخش «استفاده از الگوهای نماد» در ادامه را ببینید.

symver

نشان‌دهنده الگوی نماد symver (نسخه نماد) است. زیربخش «استفاده از الگوهای نماد» در ادامه را ببینید.

regex

نشان‌دهنده الگوی نماد regex است. زیربخش «استفاده از الگوهای نماد» در ادامه را ببینید.

استفاده از الگوهای نماد (Using symbol patterns)

برخلاف مشخصات استاندارد یک نماد، یک الگو می‌تواند چندین نماد واقعی از کتابخانه را پوشش دهد. ابزار dpkg-gensymbols تلاش خواهد کرد تا هر الگو را با هر نماد واقعی که همتای نماد مشخصی در پرونده نمادها برای آن تعریف نشده است مطابقت دهد. هر زمان که نخستین الگوی منطبق پیدا شود، تمام برچسب‌ها و ویژگی‌های آن به عنوان مشخصات پایه نماد استفاده خواهند شد. اگر هیچ‌یک از الگوها مطابقت نداشته باشد، نماد به عنوان نمادی جدید در نظر گرفته خواهد شد.

یک الگو اگر با هیچ نمادی در کتابخانه مطابقت نداشته باشد مفقود (lost) تلقی می‌شود. به طور پیش‌فرض این امر باعث شکست dpkg-gensymbols تحت سطح -c1 یا بالاتر خواهد شد. با این حال، اگر این شکست نامطلوب باشد، می‌توان الگو را با برچسب optional علامت‌گذاری کرد. در این صورت اگر الگو با چیزی مطابقت نداشته باشد، تنها به صورت MISSING در diff ظاهر خواهد شد. علاوه بر این، مانند هر نمادی، الگو را می‌توان با برچسب arch به معماری‌های خاصی محدود کرد. لطفاً برای اطلاعات بیشتر به زیربخش «برچسب‌های استاندارد نماد» در بالا مراجعه کنید.

الگوها توسعه‌ای از قالب deb-symbols(5) هستند، بنابراین تنها در الگوهای پرونده نماد معتبر هستند. نحو مشخصات الگو با مشخصات یک نماد معین هیچ تفاوتی ندارد. با این حال، بخش نام نماد در این مشخصات به عنوان یک عبارت برای مطابقت با name@version نماد واقعی عمل می‌کند. به منظور تمایز بین انواع مختلف الگو، یک الگو معمولاً با یک برچسب ویژه مشخص می‌شود.

در حال حاضر، dpkg-gensymbols از سه نوع الگوی پایه پشتیبانی می‌کند:

c++

این الگو با برچسب c++ مشخص می‌شود. این الگو تنها با نمادهای C++ بر اساس نام ناآمیخته (demangled) آن‌ها (همان‌طور که توسط ابزار c++filt(1) تولید می‌شود) مطابقت می‌یابد. این الگو برای تطبیق نمادهایی که نام‌های درهم‌ریخته (mangled) آن‌ها ممکن است در معماری‌های مختلف متفاوت باشد در حالی که نام‌های ناآمیخته آن‌ها یکسان می‌ماند بسیار کاربردی است. یک گروه از چنین نمادهایی، thunkهای غیرمجازی (non-virtual thunks) هستند که آفست‌های وابسته به معماری در نام‌های درهم‌ریخته آن‌ها تعبیه شده است. یک نمونه متداول از این حالت، یک تخریب‌کننده مجازی (virtual destructor) است که تحت وراثت لوزی (diamond inheritance) به یک نماد thunk غیرمجازی نیاز دارد. برای نمونه، حتی اگر _ZThn8_N3NSB6ClassDD1Ev@Base در معماری‌های ۳۲ بیتی احتمالاً در معماری‌های ۶۴ بیتی به صورت _ZThn16_N3NSB6ClassDD1Ev@Base باشد، می‌توان آن را با یک الگوی منفرد c++ مطابقت داد:

libdummy.so.1 libdummy1 #MINVER#
 [...]
 (c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
 [...]

نام ناآمیخته فوق را می‌توان با اجرای دستور زیر به دست آورد:

$ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt

لطفاً توجه داشته باشید در حالی که نام درهم‌ریخته (mangled) بنا به تعریف در کتابخانه منحصر‌به‌فرد است، این امر لزوماً در مورد نام‌های ناآمیخته (demangled) صدق نمی‌کند. چند نماد واقعی متمایز ممکن است نام ناآمیخته یکسانی داشته باشند. برای نمونه، این حالت در مورد نمادهای thunk غیرمجازی در پیکربندی‌های وراثت پیچیده، یا با بیشتر سازنده‌ها و مخرب‌ها رخ می‌دهد (زیرا g++ معمولاً دو نماد واقعی برای آن‌ها تولید می‌کند). با این حال، از آنجا که این برخوردها در سطح ABI رخ می‌دهند، نباید کیفیت پرونده نماد را کاهش دهند.

symver

این الگو با برچسب symver مشخص می‌شود. کتابخانه‌هایی که به خوبی نگهداری می‌شوند دارای نمادهای نسخه‌دار هستند که در آن‌ها هر نسخه با نسخه بالادستی که نماد در آن اضافه شده مطابقت دارد. اگر چنین باشد، می‌توانید از یک الگوی symver برای تطبیق هر نماد مرتبط با نسخه مشخص استفاده کنید. برای نمونه:

libc.so.6 libc6 #MINVER#
 (symver)GLIBC_2.0 2.0
 [...]
 (symver)GLIBC_2.7 2.7
 access@GLIBC_2.0 2.2

تمام نمادهای مرتبط با نسخه‌های GLIBC_2.0 و GLIBC_2.7 به ترتیب به حداقل نسخه 2.0 و 2.7 منجر خواهند شد، به استثنای نماد access@GLIBC_2.0. نماد اخیر علی‌رغم قرار داشتن در دامنه الگوی "(symver)GLIBC_2.0" به حداقل وابستگی به نسخه 2.2 از libc6 منجر خواهد شد، زیرا نمادهای خاص بر الگوها اولویت دارند.

لطفاً توجه داشته باشید در حالی که الگوهای نویسه عام به سبک قدیمی (که با "*@version" در فیلد نام نماد مشخص می‌شوند) هنوز پشتیبانی می‌شوند، با نحو سبک جدید "(symver|optional)version" منسوخ شده‌اند. برای نمونه، اگر رفتار مشابهی مورد نیاز باشد، "*@GLIBC_2.0 2.0" باید به صورت "(symver|optional)GLIBC_2.0 2.0" نوشته شود.

regex

الگوهای عبارت باقاعده با برچسب regex مشخص می‌شوند. آن‌ها با عبارت باقاعده پرل مشخص‌شده در فیلد نام نماد مطابقت می‌یابند. یک عبارت باقاعده همان‌طور که هست مطابقت داده می‌شود، بنابراین فراموش نکنید که آن را با نویسه ^ شروع کنید، در غیر این صورت ممکن است با هر بخشی از رشته name@version نماد واقعی مطابقت یابد. برای نمونه:

libdummy.so.1 libdummy1 #MINVER#
 (regex)"^mystack_.*@Base$" 1.0
 (regex|optional)"private" 1.0

نمادهایی مانند "mystack_new@Base"، "mystack_push@Base"، "mystack_pop@Base" و غیره با الگوی اول مطابقت خواهند داشت در حالی که "ng_mystack_new@Base" مطابقت نخواهد داشت. الگوی دوم با همه نمادهایی که رشته "private" را در نام خود دارند مطابقت خواهد داشت و نمادهای منطبق برچسب optional را از الگو به ارث می‌برند.

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

(c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
(regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0

با نمادهای "_ZN3NSA6ClassA7Private11privmethod1Ei@Base" و "_ZN3NSA6ClassA7Private11privmethod2Ei@Base" مطابقت خواهند داشت. هنگام تطبیق با الگوی اول، نماد خام ابتدا به عنوان نماد C++ ناآمیخته (demangle) می‌شود، سپس نام ناآمیخته با عبارت باقاعده مطابقت داده می‌شود. از سوی دیگر، هنگام تطبیق با الگوی دوم، عبارت باقاعده ابتدا با نام نماد خام مطابقت داده می‌شود، سپس با تلاش برای ناآمیختن آن بررسی می‌شود که آیا نماد C++ است یا خیر. شکست هر یک از الگوهای پایه منجر به شکست کل الگو خواهد شد. بنابراین، برای نمونه، "__N3NSA6ClassA7Private11privmethod\dEi@Base" با هیچ‌یک از الگوها مطابقت نخواهد داشت زیرا یک نماد معتبر C++ نیست.

به طور کلی، همه الگوها به دو گروه تقسیم می‌شوند: نام‌های مستعار (aliasهای پایه‌ای c++ و symver) و الگوهای عمومی (regex، تمام ترکیب‌های چندین الگوی پایه). تطبیق الگوهای مبتنی بر نام مستعار پایه سریع است (O(1)) در حالی که الگوهای عمومی برای هر نماد O(N) (که N تعداد الگوهای عمومی است) هستند. بنابراین، توصیه می‌شود بیش از حد از الگوهای عمومی استفاده نکنید.

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

استفاده از includeها (Using includes)

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

• می‌توانید بخش مشترک را در یک پرونده خارجی فاکتور بگیرید و آن پرونده را در پرونده package.symbols.arch خود با استفاده از یک دستور include به شکل زیر وارد کنید:

  #include "I<packages>.symbols.common"

• دستور include همچنین می‌تواند مانند هر نمادی برچسب‌گذاری شود:

  (tag|...|tagN)#include "file-to-include"

  در نتیجه، تمام نمادهای واردشده از file-to-include به طور پیش‌فرض با tag ... tagN برچسب‌گذاری‌شده در نظر گرفته می‌شوند. می‌توانید از این ویژگی برای ایجاد یک پرونده package.symbols مشترک که پرونده‌های نمادهای مختص معماری را وارد می‌کند استفاده کنید:

   common_symbol1@Base 1.0
  (arch-bits=64)#include "package.symbols.64-bit"
  (arch-bits=32)#include "package.symbols.32-bit"
   common_symbol2@Base 1.0

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

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

#include "libsomething1.symbols.common"
 arch_specific_symbol@Base 1.0