.\" SPDX-License-Identifier: MIT .\" .Dd August 1, 2026 .Dt RGBLINK 1 .Os .Sh "نام (NAME)" .Nm rgblink .Nd پیونددهنده Game Boy .Sh "خلاصه دستور (SYNOPSIS)" .Nm .Op Fl dhMtVvwx .Op Fl B Ar param .Op Fl \-color Ar when .Op Fl l Ar linker_script .Op Fl m Ar map_file .Op Fl n Ar sym_file .Op Fl O Ar overlay_file .Op Fl o Ar out_file .Op Fl p Ar pad_value .Op Fl S Ar spec .Op Fl W Ar warning .Ar .Sh "توضیحات (DESCRIPTION)" برنامه .Nm فایل‌های شیء RGB را، که معمولاً توسط .Xr rgbasm 1 ایجاد می‌شوند، به یک تک‌فایل ROM مربوط به Game Boy پیوند می‌دهد. قالب فایل شیء در .Xr rgbds 5 مستند شده است. .Pp بخش‌های ROM0 در ۱۶ کیبی‌بایت نخست ROM خروجی قرار می‌گیرند، و بخش‌های ROMX در هر .Dq بانک ۱۶ کیبی‌بایتی به جز اولین بانک جای داده می‌شوند. اگر ROM شما تنها ۳۲ کیبی‌بایت باشد، می‌توانید از گزینه .Fl t برای تغییر این رفتار استفاده کنید. .Pp به همین ترتیب، بخش‌های WRAM0 در ۴ کیبی‌بایت نخست WRAM .Pq Dq بانک ۰ قرار می‌گیرند، و بخش‌های WRAMX در هر بانکی از ۴ کیبی‌بایت پایانی قرار داده می‌شوند. اگر ROM شما از WRAM بانک‌بندی‌شده استفاده نمی‌کند، می‌توانید از گزینه .Fl w برای تغییر این رفتار استفاده کنید. .Pp همچنین اگر ROM شما برای یک Game Boy تک‌رنگ طراحی شده است، می‌توانید با استفاده از گزینه .Fl d اطمینان حاصل کنید که از هیچ بخش ناسازگاری استفاده نمی‌کنید؛ این گزینه مستلزم .Fl w است و علاوه بر آن، استفاده از VRAM بانک‌بندی‌شده را نیز ممنوع می‌کند. .Sh "آرگومان‌ها (ARGUMENTS)" .Nm گزینه‌های کوتاه و طولانی معمول مانند .Fl V و .Fl \-version را می‌پذیرد. گزینه‌های بعدی در خط فرمان، گزینه‌های تعیین‌شده در قبل را بازنویسی می‌کنند، مگر در مواردی که گزینه‌های تکراری یک خطا تلقی شوند. گزینه‌ها را می‌توان تا زمانی که سردرگمی ایجاد نکنند، مخفف کرد: .Fl \-verb همان .Fl \-verbose است، اما .Fl \-ver نامعتبر است زیرا می‌تواند نشان‌دهنده .Fl \-version نیز باشد. .Pp مگر در مواردی که خلاف آن ذکر شده باشد، ارسال .Ql - (یک خط تیره تکی) به‌عنوان نام فایل باعث می‌شود که .Nm از ورودی استاندارد (برای فایل‌های ورودی) یا خروجی استاندارد (برای فایل‌های خروجی) استفاده کند. برای لغو این رفتار و باز کردن فایلی در دایرکتوری جاری که نام واقعی آن .Ql - است، به جای آن .Ql ./- را ارسال کنید. استفاده از ورودی یا خروجی استاندارد برای بیش از یک فایل در یک دستور منفرد ممکن است نتایج غیرمنتظره‌ای به همراه داشته باشد. .Pp .Nm اعداد ده‌دهی، شانزده‌شانزدهی، هشت‌هشتی و دودویی را برای آرگومان‌های عددی گزینه‌ها می‌پذیرد. اعداد ده‌دهی طبق معمول نوشته می‌شوند؛ اعداد شانزده‌شانزدهی باید پیشوندی از .Ql $ یا .Ql 0x داشته باشند؛ اعداد هشت‌هشتی باید پیشوندی از .Ql & یا .Ql 0o داشته باشند؛ و اعداد دودویی باید پیشوندی از .Ql % یا .Ql 0b داشته باشند. (پیشوندهای .Ql $ و .Ql & احتمالاً برای جلوگیری از تفسیر توسط پوسته به گریزدهی یا قرار گرفتن در نقل‌قول نیاز دارند.) صفرهای ابتدایی (پس از پیشوند مبنا، در صورت وجود) پذیرفته می‌شوند و حروف به بزرگی و کوچکی حساس نیستند. برای نمونه، همه موارد زیر معادل یکدیگرند: .Ql 42 , .Ql 042 , .Ql 0x2A , .Ql 0X2A , .Ql 0x2a , .Ql &52 , .Ql 0o52 , .Ql 0O052 , .Ql 0b00101010 , .Ql 0B101010 . .Pp گزینه‌های زیر پذیرفته می‌شوند: .Bl -tag -width Ds .It Fl B Ar param , Fl \-backtrace Ar param چگونگی چاپ ردگیری‌های مکانی را هنگام بروز هشدارها یا خطاها پیکربندی می‌کند. این پرچم را می‌توان چندین بار با پارامترهای گوناگون مشخص کرد که به شکل معناداری با یکدیگر ترکیب می‌شوند. اگر .Ar param یک عدد مثبت باشد، حداکثر عمق ردگیری را مشخص می‌کند و ردگیری‌های عمیق‌تر را خلاصه می‌سازد. سایر مقادیر معتبر برای پارامتر عبارتند از: .Bl -tag -width Ds .It Cm 0 حداکثر عمق ردگیری را محدود نکن؛ این مقدار پیش‌فرض است. .It Cm all چاپ اجباری همه مکان‌ها، حتی مکان‌های «بی‌صدا» (برای جزئیات به .Dq Excluding locations from backtraces در .Xr rgbasm 5 مراجعه کنید). .It Cm no-all مکان‌های «بی‌صدا شده» را در ردگیری‌ها چاپ نکن؛ این مقدار پیش‌فرض است. .It Cm collapse چاپ تمام مکان‌ها در یک خط. .It Cm no-collapse چاپ یک مکان در هر خط؛ این مقدار پیش‌فرض است. .El .It Fl \-color Ar when مشخص می‌کند چه زمانی پیام‌های هشدار و خطا با رنگ برجسته شوند: .Ql always , .Ql never , یا .Ql auto . مقدار .Ql auto بر اساس متغیرهای محیطی .Ql Lk https://no-color.org NO_COLOR یا .Ql Lk https://force-color.org FORCE_COLOR یا اینکه آیا خروجی به یک TTY است، استفاده از رنگ‌ها را تعیین می‌کند. .It Fl d , Fl \-dmg فعال کردن حالت DMG. استفاده از بخش‌هایی را که در یک DMG وجود ندارند، مانند بانک ۱ VRAM، ممنوع می‌کند. این گزینه به طور خودکار .Fl w را فعال می‌کند. .It Fl h , Fl \-help چاپ متن راهنمای برنامه و خروج. (متن راهنما به مقدار متغیر محیطی .Dv COLUMNS در صورتی که مقداری غیرصفر داشته باشد پیچیده می‌شود؛ و در غیر این صورت، چنانچه خروجی به یک TTY باشد، متناسب با پهنای پنجره کنسول تراز می‌شود.) .It Fl l Ar linker_script , Fl \-linkerscript Ar linker_script یک فایل اسکریپت پیونددهنده را مشخص می‌کند که به پیونددهنده نحوه قرارگیری بخش‌ها در ROM را اعلام می‌نماید. ویژگی‌های تخصیص‌یافته در اسکریپت پیونددهنده باید با ویژگی‌های تخصیص‌یافته در کد همخوانی داشته باشند. برای اطلاعات بیشتر درباره قالب اسکریپت پیونددهنده به .Xr rgblink 5 مراجعه کنید. .It Fl M , Fl \-no-sym-in-map در صورت مشخص شدن، فایل نگاشت شامل فهرست نمادها نخواهد بود و تنها بخش‌ها را فهرست می‌کند. .It Fl m Ar map_file , Fl \-map Ar map_file یک فایل نگاشت در نام فایل داده‌شده می‌نویسد که چگونگی تخصیص بخش‌ها و نمادها را فهرست می‌کند. .It Fl n Ar sym_file , Fl \-sym Ar sym_file یک فایل نماد در نام فایل داده‌شده می‌نویسد که تمام برچسب‌های مرئی و ثوابت عددی صادرشده را فهرست می‌کند. برچسب‌ها بانک و آدرس خود را خروجی می‌دهند، و ثوابت عددی مقدار خود را طبق .Lk https://rgbds.gbdev.io/sym این مشخصات خروجی می‌دهند. چندین برنامه خارجی می‌توانند از این اطلاعات استفاده کنند، برای نمونه جهت کمک به اشکال‌زدایی ROMها. .It Fl O Ar overlay_file , Fl \-overlay Ar overlay_file در صورت تعیین شدن، بخش‌ها «بر روی» تصویر ROM در .Ar overlay_file هم‌پوشانی می‌شوند: فضای خالی بین بخش‌ها با بایت‌های مربوطه از .Ar overlay_file پر خواهد شد. این قابلیت برای وصله زدن یک ROM موجود مفید است. توجه داشته باشید که تمام بخش‌ها باید ثابت (بانک .Sy و آدرس اجباری) باشند! .It Fl o Ar out_file , Fl \-output Ar out_file تصویر ROM را در فایل داده‌شده می‌نویسد. .It Fl p Ar pad_value , Fl \-pad Ar pad_value هنگام درج لایه‌گذاری بین بخش‌ها، با این مقدار لایه‌گذاری می‌کند. مقدار پیش‌فرض 0 است. .It Fl S Ar spec , Fl \-scramble Ar spec الگوریتم متفاوتی را تحت عنوان .Dq درهم‌ریزی برای جای‌گذاری بخش‌ها فعال می‌کند. برای توضیح و شرح .Ar spec به بخش .Sx الگوریتم درهم‌ریزی در ادامه مراجعه کنید. .It Fl t , Fl \-tiny اندازه بخش ROM0 را از ۱۶ کیبی‌بایت به کل ۳۲ کیبی‌بایت اختصاص‌یافته به ROM گسترش می‌دهد. بخش‌های ROMX که به بانکی غیر از ۱ مقید شده‌اند تبدیل به خطا می‌شوند، و سایر بخش‌های ROMX به عنوان ROM0 در نظر گرفته می‌شوند. برای ROMهایی که در ۳۲ کیبی‌بایت جا می‌شوند مفید است. .It Fl V , Fl \-version نسخه برنامه را چاپ کرده و خارج شو. .It Fl v , Fl \-verbose حالت پرگو. سطح پرگویی با هر بار مشخص کردن این پرچم یک واحد افزایش می‌یابد و هر سطح شامل سطح پیشین نیز می‌شود: .Bl -enum -compact .It چاپ پیکربندی .Nm پیش از انجام اقدامات. .It چاپ یک اعلان پیش از اقدامات مهم. .It چاپ برخی از نتایج میانی اقدامات. .It چاپ برخی اطلاعات اشکال‌زدایی داخلی. .It چاپ اطلاعات دقیق داخلی. .El سطح پرگویی از ۶ فراتر نمی‌رود. .Pp توجه داشته باشید که خروجی پرگو تنها برای خوانده شدن توسط انسان طراحی شده است و ممکن است بدون اطلاع قبلی بین نسخه‌های RGBDS تغییر کند؛ تکیه بر آن‌ها در اسکریپت‌ها توصیه نمی‌شود. .It Fl W Ar warning , Fl \-warning Ar warning تنظیم پرچم هشدار .Ar warning . اگر .Ar warning یک پرچم هشدار ناشناخته باشد، پیام هشداری چاپ خواهد شد. برای مشاهده فهرست هشدارها به بخش .Sx خطاها (DIAGNOSTICS) مراجعه کنید. .It Fl w , Fl \-wramx اندازه بخش WRAM0 را از ۴ کیبی‌بایت به کل ۸ کیبی‌بایت اختصاص‌یافته به WRAM گسترش می‌دهد. بخش‌های WRAMX که به بانکی غیر از ۱ مقید شده‌اند تبدیل به خطا می‌شوند، و سایر بخش‌های WRAMX به عنوان WRAM0 در نظر گرفته می‌شوند. .It Fl x , Fl \-nopad لایه‌گذاری انتهای فایل نهایی را غیرفعال می‌کند. این گزینه به طور خودکار .Fl t را فعال می‌کند. می‌توانید از این گزینه برای ایجاد فایل‌های باینری که ROM نیستند استفاده کنید. هنگام ساخت ROM، توجه داشته باشید که عدم استفاده از این گزینه جایگزینی برای گزینه .Fl p برنامه .Xr rgbfix 1 نیست! .It @ Ns Ar at_file گزینه‌ها و آرگومان‌های بیشتری را از یک فایل می‌خواند، گویی محتویات آن در خط فرمان ارائه شده است. آرگومان‌ها با فاصله خالی یا خط جدید جدا می‌شوند. خطوطی که با علامت هش .Pq Ql # شروع می‌شوند دیدگاه محسوب شده و نادیده گرفته می‌شوند. .Pp هیچ پردازش پوسته‌ای مانند بسط نویسه‌های عام یا بسط متغیرها انجام نمی‌شود. هیچ پشتیبانی برای گریزدهی یا نقل‌قول کردن فاصله‌های خالی برای گنجاندن در آرگومان‌ها وجود ندارد. گزینه استاندارد .Ql -- برای توقف پردازش گزینه‌ها، پردازش at-file را نیز غیرفعال می‌کند. توجه داشته باشید که با اینکه .Ql -- می‌تواند .Em درون یک at-file استفاده شود، تنها پردازش گزینه را درون آن at-file غیرفعال می‌کند و پردازش در دامنه والد ادامه می‌یابد. .El .Ss الگوریتم درهم‌ریزی الگوریتم پیش‌فرض جای‌گذاری بخش‌ها تلاش می‌کند بخش‌ها را در کمترین تعداد بانک ممکن جای دهد. (مشخص شده است که جای‌گذاری بخش‌ها یک مسئله NP-کامل موسوم به «بسته‌بندی سطل‌ها» است، بنابراین .Nm تلاشی برای یافتن راه‌حل بهینه نمی‌کند، بلکه از یک روش اکتشافی «اولین برازش» برای یافتن پاسخی مناسب در مدت زمانی معقول استفاده می‌نماید.) هیچ تضمینی در مورد محل قرارگیری بخش‌ها توسط این الگوریتم، فارغ از محدودیت‌های بانک، آدرس و ترازسازی که به طور دستی برای بخش‌ها تعیین شده‌اند، وجود ندارد. .Pp .Dq درهم‌ریزی در عوض، بخش‌ها را درون یک استخر داده‌شده از بانک‌ها جای می‌دهد و تلاش می‌کند تعداد بخش‌هایی را که یک بانک مشترک دارند به حداقل برساند. این قابلیت برای شناسایی فرضیات نادرست در مورد بانک‌ها مفید است، مانند انتظار اینکه دو بخش مختلف در یک بانک قرار گیرند (این امر تضمین نمی‌شود مگر اینکه برای هر دوی آن‌ها به طور دستی شماره بانک یکسانی تعیین شده باشد). همچنان هیچ تضمینی در مورد مکان قرارگیری بخش‌ها توسط این الگوریتم، به جز اندازه استخر بانک‌ها و هرگونه محدودیت‌های دستی تعیین‌شده برای بخش‌ها، وجود ندارد. .Pp یک مشخصه درهم‌ریزی فهرستی جداشده با کاما از مشخصه‌های ناحیه است. یک کامای انتهایی، و همچنین فاصله خالی میان تمامی مشخصه‌ها و مؤلفه‌های آن‌ها مجاز است. هر مشخصه ناحیه به شکل زیر است: .D1 Ar region Ns Op = Ns Ar size .Ar region نوع بخش را مشخص می‌کند، و .Ar size تعداد بانک‌های موجود در استخر را برای آن نوع بخش تعیین می‌نماید. .Ar region باید یکی از مقادیر زیر باشد (غیرحساس به بزرگی و کوچکی حروف)، در حالی که .Ar size باید یک عدد صحیح مثبت ده‌دهی بین ۱ و حداکثر مقدار مربوطه باشد. برخی نواحی اجازه حذف اندازه را می‌دهند، که در این صورت مقدار پیش‌فرض آن برابر با بیشینه مقدار آن خواهد بود. .Bl -column "نام ناحیه" "بیشینه اندازه" "اندازه اختیاری" نام ناحیه Ta بیشینه اندازه Ta اندازه اختیاری .Cm romx Ta 65535 Ta \&خیر .Cm sram Ta 255 Ta \&خیر .Cm wramx Ta 7 Ta بله .El .Pp یک .Ar size برابر با ۰ درهم‌ریزی را برای آن ناحیه غیرفعال می‌کند. .Pp برای نمونه، .Ql romx=64,wramx,sram=4 بخش‌های .Ic ROMX را میان بانک‌های ROM از ۱ تا ۶۴، بخش‌های .Ic WRAMX را میان بانک‌های RAM از ۱ تا ۷، و بخش‌های .Ic SRAM را میان بانک‌های SRAM از ۰ تا ۳ درهم می‌ریزد. .Pp مشخصه‌های ناحیه که بعدتر می‌آیند موارد پیشین را باطل و بازنویسی می‌کنند؛ برای مثال، .Ql romx=42, Romx=0 درهم‌ریزی را برای .Cm romx غیرفعال می‌کند. .Pp درهم‌ریزی .Cm wramx در صورت ارسال .Fl w (از جمله اگر توسط .Fl d اعمال شده باشد) در سکوت نادیده گرفته می‌شود، زیرا بخش‌های .Ic WRAMX به‌عنوان .Ic WRAM0 در نظر گرفته خواهند شد. .Sh "خطاها (DIAGNOSTICS)" هشدارها پیام‌های تشخیصی هستند که رفتارهای احتمالاً اشتباهی را نشان می‌دهند که لزوماً روند پیوند زدن را مختل نمی‌کنند. گزینه‌های زیر نحوه پردازش هشدارها را تغییر می‌دهند. .Bl -tag -width Ds .It Fl Werror تبدیل همه هشدارها به خطا. می‌توان این گزینه را با .Fl Wno-error نقیض کرد تا از تبدیل تمام هشدارها به خطا جلوگیری شود. .It Fl Werror= تبدیل هشدار یا فرا-هشدار مشخص‌شده به خطا. نام یک هشدار پیوست می‌شود .Pq مثال: Fl Werror=obsolete ، و این هشدار به طور ضمنی فعال شده و به یک خطا تبدیل می‌شود. می‌توان این را با .Fl Wno-error= نقیض کرد تا از تبدیل یک هشدار مشخص به خطا جلوگیری شود، حتی اگر .Fl Werror فعال باشد. .El .Pp هشدارهای زیر فرا-هشدار .Pq Dq meta هستند، که مجموعه‌ای از هشدارهای دیگر را فعال می‌کنند. اگر یک هشدار مشخص هم از طریق یک پرچم فرا و هم یک پرچم خاص تغییر وضعیت دهد، پرچم خاص‌تر اولویت دارد. موقعیت در خط فرمان به عنوان معیار تعیین‌کننده نهایی عمل می‌کند و آخرین مورد اثرگذار خواهد بود. .Bl -tag -width Ds .It Fl Wall این گزینه هشدارهایی را فعال می‌کند که احتمالاً نشان‌دهنده یک خطا یا رفتار نامطلوب هستند و می‌توانند به‌راحتی برطرف شوند. .It Fl Weverything دقیقاً تک‌تک هشدارها را فعال می‌کند. .El .Pp هشدارهای زیر پرچم‌های واقعی هشدار هستند؛ همراه با هر شرح، پرچم هشدار مربوطه نیز آورده شده است. توجه داشته باشید که هر یک از این پرچم‌ها دارای یک نقیض نیز هستند (برای مثال، .Fl Wobsolete هشداری را فعال می‌کند که .Fl Wno-obsolete آن را غیرفعال می‌سازد؛ و .Fl Wall هر هشداری را که .Fl Wno-all غیرفعال می‌کند، فعال می‌سازد). در اینجا فقط پرچم‌های غیرپیش‌فرض فهرست شده‌اند. با صرف‌نظر از پیشوند .Dq no- Ns ، مدخل‌ها بر اساس حروف الفبا فهرست شده‌اند. .Bl -tag -width Ds .It Fl Wno-assert هنگامی که ادعاهای نوع .Ic WARN شکست می‌خورند، هشدار بده. (برای .Ic ASSERT به .Dq Aborting the assembly process در .Xr rgbasm 5 مراجعه کنید). .It Fl Wdiv هنگام تقسیم کوچک‌ترین عدد صحیح منفی (-2**31) بر -1 هشدار بده، که به دلیل سرریز عدد صحیح خودِ آن عدد حاصل می‌شود. این هشدار توسط .Fl Wall فعال می‌شود. .It Fl Wno-large-constant هنگام مواجهه با ثابتی که بزرگ‌تر از آن است که در یک عدد صحیح ۳۲ بیتی علامت‌دار بگنجد، هشدار بده. .It Fl Wno-obsolete هنگام مواجهه با ویژگی‌های منسوخ‌شده هشدار بده، که منسوخ شده‌اند و ممکن است در آینده حذف شوند. .It Fl Wshift هنگام شیفت دادن یک مقدار منفی به راست هشدار بده. به جای آن از تقسیم بر 2**N استفاده کنید. این هشدار توسط .Fl Wall فعال می‌شود. .It Fl Wshift-amount هنگامی که عملوندِ شیفت منفی یا بزرگ‌تر از ۳۲ باشد، هشدار بده. این هشدار توسط .Fl Wall فعال می‌شود. .It Fl Wtruncation= هنگامی که یک کوتاه کردن ضمنی (برای مثال، .Ic db به یک مقدار ۸ بیتی) باعث از دست رفتن برخی بیت‌ها شود، هشدار بده. .Fl Wtruncation=0 یا .Fl Wno-truncation این هشدار را غیرفعال می‌کند. .Fl Wtruncation=1 یا صرفاً .Fl Wtruncation زمانی هشدار می‌دهد که یک مقدار N بیتی، برابر یا بزرگ‌تر از 2**N یا کوچک‌تر از -2**N باشد. .Fl Wtruncation=2 علاوه بر این زمانی هشدار می‌دهد که یک مقدار N بیتی کمتر از -2**(N-1) باشد، که در کدگذاری مکمل دو نمی‌گنجد. .El .Sh "مثال‌ها (EXAMPLES)" تنها چیزی که برای یک ROM پایه‌ای نیاز دارید یک فایل شیء است که می‌توان آن را به شکل زیر به یک تصویر ROM تبدیل کرد: .Pp .Dl $ rgblink -o bar.gb foo.o .Pp فایل حاصل .Ar bar.gb دارای مجموع‌های مقابله‌ای صحیح نخواهد بود (مگر اینکه آن‌ها را در سورس اسمبلی قرار داده باشید). شما باید از .Xr rgbfix 1 برای اصلاح این موارد استفاده کنید تا برنامه واقعاً در یک Game Boy اجرا شود: .Pp .Dl $ rgbfix -v bar.gb .Pp در اینجا یک مثال کامل‌تر آورده شده است: .Pp .Dl $ rgblink -o bin/game.gb -n bin/game.sym -p 0xFF obj/title.o obj/engine.o .Sh "گزارش باگ‌ها (BUGS)" لطفاً باگ‌ها یا اشتباهات موجود در این مستندات را در .Lk https://github.com/gbdev/rgbds/issues GitHub گزارش دهید. .Sh "همچنین ببینید (SEE ALSO)" .Xr rgbasm 1 , .Xr rgblink 5 , .Xr rgbfix 1 , .Xr rgbgfx 1 , .Xr gbz80 7 , .Xr rgbds 5 , .Xr rgbds 7 .Sh "تاریخچه (HISTORY)" .Nm در ابتدا توسط .An Carsten S\(/orensen به‌عنوان بخشی از بسته ASMotor نوشته شد و بعداً توسط .An Justin Lloyd در RGBDS مجدداً بسته‌بندی گردید. این پروژه اکنون توسط تعدادی از مشارکت‌کنندگان در .Lk https://github.com/gbdev/rgbds نگه‌داری می‌شود.