.\" SPDX-License-Identifier: MIT
.\"
.Dd August 1, 2026
.Dt RGBLINK 5
.Os
.Sh "نام (NAME)"
.Nm rgblink
.Nd قالب فایل اسکریپت پیونددهنده
.Sh "توضیحات (DESCRIPTION)"
اسکریپت پیونددهنده فایلی است که امکان تعیین ویژگی‌های بخش‌ها را در زمان پیوند و به شیوه‌ای متمرکز فراهم می‌کند.
در هر بار فراخوانی
.Nm
تنها یک اسکریپت پیونددهنده می‌تواند وجود داشته باشد، اما می‌توان آن را به چندین فایل تقسیم کرد
.Pq با استفاده از دستورالعمل Ic INCLUDE No .
.Ss نحو پایه
نحو اسکریپت پیونددهنده خط‌محور است.
هر خط می‌تواند شامل یک دستورالعمل یا نام بخش، یک توضیح، هر دو، یا هیچ‌کدام باشد.
فاصله‌های خالی (نویسه‌های فاصله و تب) برای جداسازی عناصر نحوی استفاده می‌شوند، اما در غیر این صورت نادیده گرفته می‌شوند.
.Pp
توضیحات با نویسهٔ نقطه‌ویرگول
.Ql \&;
آغاز می‌شوند و تا انتهای خط ادامه دارند.
آن‌ها به سادگی نادیده گرفته می‌شوند.
.Pp
کلیدواژه‌ها از حروف و ارقام تشکیل شده‌اند (اما نمی‌توانند با یک رقم آغاز شوند)؛ همهٔ آن‌ها به بزرگی و کوچکی حروف حساس نیستند.
.Pp
اعداد را می‌توان در قالب‌های مختلفی نوشت.
.Bl -column -offset indent "Hexadecimal" "Possible prefixes"
.It Sy نوع قالب Ta Sy پیشوندهای ممکن Ta Sy نویسه‌های پذیرفته‌شده
.It ده‌دهی (Decimal) Ta هیچ Ta 0123456789
.It شانزده‌شانزدهی (Hexadecimal) Ta Li $ , 0x , 0X Ta 0123456789ABCDEF
.It هشت‌هشتی (Octal) Ta Li & , 0o , 0O Ta 01234567
.It دودویی (Binary) Ta Li % , 0b , 0B Ta 01
.El
.Pp
خط زیر (Underscore) نیز در اعداد پذیرفته می‌شود، به جز در ابتدای عدد.
این قابلیت می‌تواند برای گروه‌بندی ارقام مفید باشد، مانند
.Ql 1_234
یا
.Ql $ff_80 .
.Pp
رشته‌ها با یک علامت نقل‌قول دوتایی (گیومه) آغاز می‌شوند و در نقل‌قول دوتایی بعدی (که فرار نیافته باشد) پایان می‌یابند.
رشته‌ها نباید شامل نویسه‌های لفظی خط جدید (newline) باشند.
بیشتر توالی‌های گریز نویسه‌ای مشابه
.Xr rgbasm 5
پشتیبانی می‌شوند، به ویژه
.Ql \e\e ,
.Ql \e" ,
.Ql \en ,
.Ql \er ,
.Ql \et ,
و
.Ql \e0 .
سایر توالی‌های گریز ممیز وارونه (backslash) در
.Xr rgbasm 5
فقط مربوط به کد اسمبلی هستند و در اسکریپت‌های پیونددهنده اعمال نمی‌شوند.
.Ss دستورالعمل‌ها
.Bl -tag -width Ds
.It شامل کردن فایل‌های دیگر
.Ql Ic INCLUDE Ar path
به گونه‌ای عمل می‌کند که گویی محتویات فایل واقع در
.Ar path
در محل دستورالعمل
.Ic INCLUDE
کپی و جای‌گذاری شده است.
.Ar path
باید یک رشته باشد.
.It تعیین بانک فعال
بانک فعال را می‌توان با تعیین نوع (ناحیه حافظه) و شمارهٔ آن تنظیم کرد.
انواع ممکن عبارتند از:
.Ic ROM0 , ROMX , VRAM , SRAM , WRAM0 , WRAMX , OAM ,
و
.Ic HRAM .
شماره بانک را می‌توان از انواعی که تنها شامل یک بانک هستند حذف کرد، که عبارتند از:
.Ic ROM0 ,
.Ic ROMX
اگر
.Fl t
به
.Xr rgblink 1
داده شده باشد،
.Ic VRAM
اگر
.Fl d
به
.Xr rgblink 1
داده شده باشد،
.Ic WRAM0 ,
.Ic WRAMX
اگر
.Fl w
به
.Xr rgblink 1
داده شده باشد،
.Ic OAM ,
و
.Ic HRAM .
.Pq Ic SRAM No تنها نوعی است که هرگز نمی‌توان شماره بانک آن را حذف کرد .
.Pp
پس از تعیین یک بانک،
.Dq آدرس فعلی
روی آخرین مقداری که برای آن بانک داشته تنظیم می‌شود.
اگر آن بانک تاکنون هرگز فعال نبوده باشد،
.Dq آدرس فعلی
به طور پیش‌فرض روی ابتدای بانک قرار می‌گیرد
.Pq مثلاً Ad $4000 No برای بخش‌های Ic ROMX No .
.Pp
به جای دادن شماره بانک، می‌توان از کلیدواژهٔ
.Ic FLOATING
استفاده کرد؛ این کار نوع بخش‌های بعدی را بدون مقید کردن آن‌ها به یک بانک خاص تنظیم می‌کند.
(اگر آن نوع تنها اجازه یک بانک را می‌دهد، مثلاً
.Ic ROM0 ,
آنگاه
.Ic FLOATING
معتبر است اما زائد بوده و هیچ اثری ندارد.)
از آنجا که هیچ بخش خاصی فعال نیست،
.Dq آدرس فعلی
شناور می‌شود (گویی توسط یک دستورالعمل
.Ql Ic FLOATING
انجام شده باشد)، و
.Ic ORG
مجاز نیست.
.It تغییر آدرس فعلی
برای استفاده از هر یک از این دستورالعمل‌ها، یک بانک باید فعال باشد.
.Pp
.Ql Ic ORG Ar addr
مقدار
.Dq آدرس فعلی
را روی
.Ar addr
تنظیم می‌کند.
این دستورالعمل نمی‌تواند برای به عقب بردن آدرس استفاده شود:
.Ar addr
باید بزرگ‌تر یا مساوی با
.Dq آدرس فعلی
باشد.
.Pp
.Ql Ic FLOATING
باعث می‌شود تمام بخش‌های بین آن و دستورالعمل
.Ic ORG
یا تعیین بانک بعدی، در آدرس‌هایی قرار گیرند که به طور خودکار توسط
.Nm
تعیین می‌شوند.
.Pq با این حال، با Ic ALIGN No در زیر سازگار است.
.Pp
.Ql Ic ALIGN Ar addr , Ar offset
مقدار
.Dq آدرس فعلی
را تا زمانی افزایش می‌دهد که با مرز مشخص‌شده تراز شود (یعنی
.Ar align
بیت‌های کم‌ارزش آدرس برابر با
.Ar offset
باشند).
اگر
.Ar offset
حذف شود، مقدار آن به طور ضمنی 0 در نظر گرفته می‌شود.
برای مثال، اگر
.Dq آدرس فعلی
برابر با $0007 باشد،
.Ql ALIGN 8
آن را روی $0100 تنظیم می‌کند، و
.Ql ALIGN 8 , 10
آن را روی $000A تنظیم می‌کند.
.Pp
.Ql Ic DS Ar size
مقدار
.Dq آدرس فعلی
را به اندازهٔ
.Ar size
افزایش می‌دهد.
این شکاف تخصیص داده نمی‌شود، بنابراین بخش‌های شناور کوچک‌تر می‌توانند بعداً در آنجا قرار گیرند.
.El
.Ss جای‌گذاری بخش‌ها
یک بخش را می‌توان به سادگی با نام بردن آن (با یک رشته) جای‌گذاری کرد.
بانک آن روی بانک فعال و آدرس آن روی
.Dq آدرس فعلی
تنظیم می‌شود.
هرگونه قیدی که بخش از قبل دارد (چه از بخش‌های قبلی اسکریپت پیونددهنده باشد و چه از فایل‌های شیءِ در حال پیوند) باید با آنچه اسکریپت پیونددهنده مشخص می‌کند سازگار باشد: نوع بخش باید مطابقت داشته باشد، شماره بانک بخش (در صورت تعیین) باید با بانک فعال مطابقت داشته باشد، و غیره.
به طور خاص، اگر بخش دارای قید تراز (alignment constraint) باشد، آدرسی که توسط اسکریپت پیونددهنده در آن قرار می‌گیرد باید از آن قید پیروی کند؛ در غیر این صورت، خطا رخ خواهد داد.
.Pp
پس از جای‌گذاری یک بخش،
.Dq آدرس فعلی
به اندازهٔ حجم آن بخش افزایش می‌یابد.
این افزایش نباید از انتهای ناحیهٔ حافظهٔ فعال فراتر رود.
.Pp
بخش باید در فایل‌های شیءِ در حال پیوند تعریف شده باشد، مگر اینکه نام بخش با کلیدواژهٔ
.Ic OPTIONAL
دنبال شود.
.Sh "مثال‌ها (EXAMPLES)"
.Bd -literal -offset indent
; این خط فقط شامل یک توضیح است
ROMX $F            ; شروع یک بانک
  "Some functions" ; نام یک بخش
  ALIGN 8          ; یک دستورالعمل
  "Some \e"array\e""

WRAMX 2            ; شروع یک بانک دیگر
  org $d123        ; یک دستورالعمل دیگر
  "Some variables"
.Ed
.Sh "همچنین ببینید (SEE ALSO)"
.Xr rgbasm 1 ,
.Xr rgbasm 5 ,
.Xr rgblink 1 ,
.Xr rgbfix 1 ,
.Xr rgbgfx 1 ,
.Xr gbz80 7 ,
.Xr rgbds 5 ,
.Xr rgbds 7
.Sh "تاریخچه (HISTORY)"
.Xr rgblink 1
در ابتدا توسط
.An Carsten S\(/orensen
به عنوان بخشی از بستهٔ ASMotor نوشته شد و بعداً توسط
.An Justin Lloyd
در RGBDS باز بسته‌بندی شد.
این ابزار اکنون توسط تعدادی از مشارکت‌کنندگان در
.Lk https://github.com/gbdev/rgbds
نگهداری می‌شود.