نام (NAME)

rgbasm — اسمبلر Game Boy

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

rgbasm [-EhVvw] [-B param] [-b chars] [--color when] [-D name[=value]] [-g chars] [-I path] [-M depend_file] [-MG] [-MC] [-MP] [-MT target_file] [-MQ target_file] [-o out_file] [-P include_file] [-p pad_value] [-Q fix_precision] [-r recursion_depth] [-s features:state_file] [-W warning] [-X max_errors] asmfile

توضیحات (DESCRIPTION)

برنامه rgbasm یک فایل شیء RGB از یک فایل منبع اسمبلی ایجاد می‌کند. قالب فایل شیء در rgbds(5) مستند شده است.

آرگومان‌ها (ARGUMENTS)

rgbasm گزینه‌های معمول کوتاه و بلند مانند -V و --version را می‌پذیرد. گزینه‌هایی که جلوتر در خط فرمان می‌آیند، بر گزینه‌های قبلی برتری می‌یابند، مگر زمانی که گزینه‌های تکراری یک خطا تلقی شوند. گزینه‌ها را می‌توان تا زمانی که مخفف بدون ابهام باشد خلاصه کرد: --verb همان --verbose است، اما --ver نامعتبر است چرا که می‌تواند معادل --version نیز باشد.

مگر اینکه خلاف آن ذکر شده باشد، ارسال ‘-’ (یک خط تیره تنها) به عنوان نام فایل باعث می‌شود rgbasm از ورودی استاندارد (برای فایل‌های ورودی) یا خروجی استاندارد (برای فایل‌های خروجی) استفاده کند. برای لغو این رفتار و باز کردن فایلی در دایرکتوری جاری که واقعاً نام آن ‘-’ است، از ‘./-’ استفاده کنید. استفاده از ورودی یا خروجی استاندارد برای بیش از یک فایل در یک دستور واحد ممکن است نتایج غیرمنتظره‌ای ایجاد کند.

rgbasm اعداد ده‌دهی، شانزده‌شانزدهی (هگزادسیمال)، هشت‌هشتی (اوکتال) و دودویی (باینری) را برای آرگومان‌های عددی گزینه‌ها می‌پذیرد. اعداد ده‌دهی به شکل معمول نوشته می‌شوند؛ اعداد شانزده‌شانزدهی باید پیشوندی با ‘$’ یا ‘0x’ داشته باشند؛ اعداد هشت‌هشتی باید پیشوندی با ‘&’ یا ‘0o’ داشته باشند؛ و اعداد دودویی باید پیشوندی با ‘%’ یا ‘0b’ داشته باشند. (پیشوندهای ‘$’ و ‘&’ احتمالاً نیاز به گریزدهی یا نقل‌قول دارند تا توسط شل تفسیر نشوند.) صفرهای ابتدایی (پس از پیشوند مبنا، در صورت وجود) پذیرفته می‌شوند و حروف به بزرگی و کوچکی حساس نیستند. برای نمونه، همه این موارد معادل یکدیگرند: ‘42’, ‘042’, ‘0x2A’, ‘0X2A’, ‘0x2a’, ‘&52’, ‘0o52’, ‘0O052’, ‘0b00101010’, ‘0B101010’.

گزینه‌های زیر پذیرفته می‌شوند:

-B param, --backtrace param

نحوه چاپ ردگیری مکان‌ها (backtraces) را در صورت بروز هشدارها یا خطاها پیکربندی می‌کند. این پرچم می‌تواند چندین بار با پارامترهای مختلف که به طور معناداری با یکدیگر ترکیب می‌شوند، مشخص شود. اگر param یک عدد مثبت باشد، حداکثر عمق ردگیری را مشخص می‌کند و موارد عمیق‌تر را خلاصه می‌سازد. سایر مقادیر معتبر پارامتر به شرح زیر است:

0: عمق حداکثری ردگیری را محدود نکن؛ این پیش‌فرض است.
all: چاپ تمام مکان‌ها را اجباری کن، حتی مکان‌های «ساکت» را (برای جزئیات بیشتر بخش “Excluding locations from backtraces” در rgbasm(5) را ببینید).
no-all: مکان‌های «ساکت شده» را در ردگیری‌ها چاپ نکن؛ این پیش‌فرض است.
collapse: تمام مکان‌ها را در یک خط چاپ کن.
no-collapse: هر مکان را در یک خط جداگانه چاپ کن؛ این پیش‌فرض است.

-b chars, --binary-digits chars

اجازه می‌دهد علاوه بر مقادیر پیش‌فرض ‘0’ و ‘1’ از دو نویسه دیگر برای ثابت‌های دودویی استفاده شود. نویسه‌های معتبر، اعدادی به غیر از ‘0’ و ‘1 ،’ حروف، ‘. ،’ ‘#’ یا ‘@’ هستند.

--color when

مشخص می‌کند چه زمانی پیام‌های هشدار و خطا با رنگ برجسته شوند: ‘

always
      ،

’ ‘never’ یا ‘auto’. مقدار ‘auto’ استفاده از رنگ‌ها را بر اساس متغیرهای محیطی ‘NO_COLOR’ یا ‘FORCE_COLOR’ یا هدایت خروجی به یک TTY تعیین می‌کند.

-D name[=value], --define name[=value]

یک نماد رشته‌ای به کد منبع کامپایل‌شده اضافه می‌کند. این معادل ‘

name
      EQUS
      "value"

’ در کد است، یا ‘

name
      EQUS
      "1"

’ اگر value مشخص نشده باشد.

-E, --export-all

همه برچسب‌ها را برون‌ریزی می‌کند، از جمله برچسب‌های محلی و مواردی که به آن‌ها ارجاع داده نشده است.

-g chars, --gfx-chars chars

اجازه می‌دهد علاوه بر مقادیر پیش‌فرض ‘0 ،’ ‘1 ،’ ‘2’ و ‘3’ از چهار نویسه دیگر برای ثابت‌های گرافیکی استفاده شود. نویسه‌های معتبر، اعدادی به غیر از ‘0’ تا ‘3 ،’ حروف، ‘. ،’ ‘#’ یا ‘@’ هستند. مقادیر پیش‌فرض 0123 هستند.

-h, --help

متن راهنمای برنامه را چاپ کرده و خارج می‌شود. (اگر متغیر محیطی COLUMNS به صورت غیرصفر تعریف شده باشد، متن راهنما بر اساس مقدار آن سطرشکنی می‌شود؛ در غیر این صورت، در صورت ارسال خروجی به TTY بر اساس پهنای پنجره کنسول سطرشکنی خواهد شد.)

-I path, --include path

یک “مسیر شمول (include path)” جدید اضافه می‌کند؛ path باید به یک دایرکتوری اشاره کند. هنگامی که هر یک از دستورهای INCLUDE (شامل مورد ضمنی ناشی از -P -،) INCBIN یا READFILE فراخوانی شوند، rgbasm ابتدا مسیر ارائه‌شده را از دایرکتوری کاری خود جستجو می‌کند؛ در صورت ناموفق بودن، مجدداً از هر یک از دایرکتوری‌های “include path” به ترتیبی که ارائه شده‌اند تلاش می‌کند.

-M depend_file, --dependfile depend_file

وابستگی‌های make(1) را در depend_file می‌نویسد.

-MG

همراه با -M استفاده می‌شود. این گزینه باعث می‌شود rgbasm فرض کند فایل‌های مفقود به‌طور خودکار تولید می‌شوند: هنگامی که هر یک از دستورهای INCLUDE (شامل مورد ضمنی ناشی از -P -،) INCBIN یا READFILE روی فایلی که وجود ندارد اعمال شود، آن فایل به عنوان یک وابستگی افزوده شده، و سپس rgbasm به جای صدور خطا، به طور عادی خارج می‌شود یا پردازش را ادامه می‌دهد (بسته به اینکه آیا -MC فعال بوده است یا خیر). این ویژگی در به‌روزرسانی خودکار Makefileها استفاده می‌شود.

-MC

گزینه -MG را به طور ضمنی فعال می‌کند. این کار باعث می‌شود rgbasm به جای خروج، پس از مواجهه با یک فایل وابستگی ناموجود، پردازش را ادامه دهد. توجه داشته باشید که این عمل به هیچ وجه توصیه نمی‌شود اگر وابستگی‌های ناموجود بر پردازش‌های بعدی تأثیر بگذارند، برای نمونه با تغییر شاخه شرط یک دستور IF.

-MP

در صورت فعال بودن، یک هدف ساختگی (phony target) را برای هر وابستگی به جز فایل اصلی، به قواعد صادرشده توسط -M اضافه می‌کند. این ویژگی مانع از بروز خطای make(1) در صورت حذف فایل‌های وابستگی می‌شود.

-MT target_file

یک هدف به قواعد صادرشده توسط -M اضافه می‌کند. دقیقاً همان رشته ارائه‌شده، شامل فاصله‌ها و نویسه‌های خاص، نوشته خواهد شد.

-MT
      fileA -MT
      fileB

معادل

-MT
      'fileA fileB'

است. اگر نه این گزینه و نه -MQ مشخص نشده باشند، نام فایل خروجی استفاده می‌شود.

-MQ target_file

مشابه -MT -، اما علاوه بر آن نویسه‌های ویژه make(1) را (عمدتاً ‘$’) گریزدهی می‌کند.

-o out_file, --output out_file

یک فایل شیء را در نام فایل مشخص‌شده می‌نویسد.

-P include_file, --preinclude include_file

یک فایل را از پیش شامل می‌کند. این عمل مشابه این است که دستور ‘

INCLUDE
      "include_file"

’ پیش از فایل ورودی asmfile خوانده شده باشد. چندین فایل را می‌توان به همان ترتیبی که مشخص شده‌اند از پیش شامل کرد.

-p pad_value, --pad-value pad_value

از این مقدار برای دستورالعمل‌های DS در بخش‌های ROM استفاده می‌کند، مگر اینکه بازنویسی شود. مقدار پیش‌فرض 0x00 است.

-Q fix_precision, --q-precision fix_precision

از این مقدار به عنوان دقت اعداد ممیز-ثابت پس از ممیز استفاده می‌کند، مگر اینکه خودشان دقت جداگانه‌ای تعیین کرده باشند. مقدار پیش‌فرض ۱۶ است، بنابراین اعداد ممیز-ثابت به صورت Q16.16 هستند (چرا که اعداد صحیح ۳۲ بیتی هستند). آرگومان می‌تواند با یک ‘.’ شروع شود تا با نمادگذاری Q مطابقت داشته باشد؛ برای نمونه: ‘

-Q
      .16

’.

-r recursion_depth, --recursion-depth recursion_depth

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

-s features:state_file, --state features:state_file

ویژگی‌های مشخص‌شده را بر اساس وضعیت نهایی rgbasm در پایان ورودی آن، در state_file می‌نویسد. ویژگی‌های مورد انتظار زیرمجموعه‌ای جداشده با ویرگول از موارد زیر است:

equ: تمام ثابت‌های عددی را به صورت ‘def name equ value’ می‌نویسد.
var: تمام متغیرها را به صورت ‘def name = value’ می‌نویسد.
equs: تمام ثابت‌های رشته‌ای را به صورت ‘def name equs "value"’ می‌نویسد.
char: تمام نویسه‌ها را به صورت ‘charmap name, value’ می‌نویسد.
macro: تمام ماکروها را به صورت ‘macro name ... endm’ می‌نویسد.
all: مانند equ,var,equs,char,macro عمل می‌کند.

این پرچم می‌تواند چندین بار با زیرمجموعه‌های مختلف ویژگی‌ها مشخص شود تا آن‌ها را در فایل‌های مختلفی بنویسد (بخش مثال‌ها (EXAMPLES) در زیر را ببینید).

-V, --version

نسخه برنامه را چاپ کرده و خارج می‌شود.

-v, --verbose

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

چاپ پیکربندی rgbasm پیش از انجام اقدامات.
چاپ یک اعلان پیش از اقدامات مهم.
چاپ برخی از نتایج میانی اقدامات.
چاپ برخی از اطلاعات اشکال‌زدایی داخلی.
چاپ اطلاعات داخلی با جزئیات کامل.

سطح پرگویی از ۶ فراتر نمی‌رود.

توجه داشته باشید که خروجی پرگو تنها برای خوانده شدن توسط انسان در نظر گرفته شده است و ممکن است بدون اطلاع قبلی بین نسخه‌های مختلف RGBDS تغییر کند؛ تکیه بر این خروجی‌ها در اسکریپت‌ها توصیه نمی‌شود.

-W warning, --warning warning

پرچم هشدار warning را تنظیم می‌کند. در صورتی که warning یک پرچم هشدار ناشناخته باشد، پیام هشداری چاپ خواهد شد. برای فهرستی از هشدارها بخش خطاها (DIAGNOSTICS) را ببینید.

-w

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

-X max_errors, --max-errors max_errors

اگر تعداد خطاها (نه هشدارها) بیشتر از این مقدار باشد، فرآیند اسمبلی را لغو می‌کند؛ -X 0 این رفتار را غیرفعال می‌کند. اگر rgbasm خطاها را در یک ترمینال چاپ کند، مقدار پیش‌فرض ۱۰۰ و در غیر این صورت ۰ است.

@at_file

گزینه‌ها و آرگومان‌های بیشتری را از یک فایل می‌خواند، به گونه‌ای که گویی محتویات آن در خط فرمان ارائه شده‌اند. آرگومان‌ها با فاصله خالی یا خط جدید از هم جدا می‌شوند. خطوطی که با علامت هش (‘#’) آغاز می‌شوند، یادداشت محسوب شده و نادیده گرفته می‌شوند.

هیچ پردازشی توسط شل، مانند بسط نویسه‌های عام یا متغیرها، انجام نمی‌شود. هیچ پشتیبانی برای گریزدهی یا نقل‌قول فاصله‌ها برای گنجاندن در آرگومان‌ها وجود ندارد. گزینه استاندارد ‘--’ برای توقف پردازش گزینه‌ها، پردازش at-file را نیز غیرفعال می‌کند. توجه داشته باشید که گرچه ‘--’ می‌تواند درون یک at-file استفاده شود، اما تنها پردازش گزینه‌ها را درون همان at-file غیرفعال می‌کند و پردازش در دامنه والد ادامه می‌یابد.

خطاها (DIAGNOSTICS)

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

-Werror: تبدیل تمام هشدارها به خطا. می‌توان آن را به صورت -Wno-error نفی کرد تا از تبدیل شدن همه هشدارها به خطا جلوگیری شود.
-Werror=: تبدیل هشدار یا فراهشدار (meta warning) مشخص‌شده به خطا. نام یک هشدار الحاق می‌شود (برای نمونه: -Werror=obsolete -،) و این هشدار به طور ضمنی فعال شده و به خطا تبدیل می‌گردد. می‌توان آن را به صورت -Wno-error= نفی کرد تا حتی در صورت برقراری -Werror -، از تبدیل شدن یک هشدار خاص به خطا جلوگیری شود.

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

-Wall: هشدارهایی را فعال می‌کند که به احتمال زیاد نشان‌دهنده یک خطا یا رفتار نامطلوب هستند و به آسانی قابل رفع می‌باشند.
-Wextra: هشدارهای اضافی را فعال می‌کند که احتمال ایجاد مشکل توسط آن‌ها کمتر است، اما ممکن است همچنان مورد نظر باشند.
-Weverything: دقیقاً تک‌تک هشدارها را فعال می‌کند.

هشدارهای زیر پرچم‌های واقعی هشدار هستند؛ در کنار هر توضیح، پرچم هشدار مربوطه نیز آورده شده است. توجه داشته باشید که هر یک از این پرچم‌ها دارای یک حالت نقیض نیز هستند (برای نمونه، -Wobsolete هشداری را فعال می‌کند که -Wno-obsolete آن را غیرفعال می‌سازد؛ و -Wall هر هشداری را که -Wno-all غیرفعال می‌کند، فعال می‌سازد). در اینجا فقط پرچم‌های غیرپیش‌فرض فهرست شده‌اند. صرف‌نظر از پیشوند “no- ،” ورودی‌ها بر اساس حروف الفبا مرتب شده‌اند.

-Wno-assert: هشدار هنگام شکست اعتبارسنجی‌های از نوع WARN. (برای ASSERT ، بخش “Aborting the assembly process” در rgbasm(5) را ببینید).
-Wbackwards-for: هشدار هنگامی که مقادیر آغاز و پایان حلقه‌های FOR بر اساس مقدار گام جابجا شده باشند. این هشدار توسط -Wall فعال می‌شود.
-Wbuiltin-args: هشدار درباره آرگومان‌های نادرست به توابع توکار، مانند STRSLICE() با اندیس‌های خارج از محدوده رشته. این هشدار توسط -Wall فعال می‌شود.
-Wcharmap-redef: هشدار هنگام تعریف مجدد یک نگاشت charmap. این هشدار توسط -Wall فعال می‌شود.
-Wdiv: هشدار هنگام تقسیم کوچک‌ترین عدد صحیح منفی (2**31-) بر 1-، که به دلیل سرریز عدد صحیح خود آن را بازمی‌گرداند.
-Wempty-data-directive: هشدار هنگامی که DB ، DW یا DL بدون آرگومان در یک بخش ROM استفاده شوند. این هشدار توسط -Wall فعال می‌شود.
-Wempty-macro-arg: هشدار هنگامی که یک آرگومان ماکرو خالی باشد. این هشدار توسط -Wextra فعال می‌شود.
-Wempty-strrpl: هشدار هنگامی که تابع STRRPL() با یک رشته خالی به عنوان آرگومان دوم خود (زیررشته‌ای که باید جایگزین شود) فراخوانی شود. این هشدار توسط -Wall فعال می‌شود.
-Wexport-undefined: هشدار هنگام برون‌ریزی یک نماد تعریف‌نشده. این هشدار توسط -Wall فعال می‌شود.
-Wno-large-constant: هشدار هنگام مواجهه با ثابتی که برای قرارگیری در یک عدد صحیح علامت‌دار ۳۲ بیتی بیش از حد بزرگ است.
-Wmacro-shift: هشدار هنگام جابجایی آرگومان‌های ماکرو به فراتر از محدوده‌شان. این هشدار توسط -Wextra فعال می‌شود.
-Wno-nested-comment: هشدار هنگامی که توالی شروع یادداشت بلوکی ‘/*’ درون یک یادداشت بلوکی پیدا شود. یادداشت‌های بلوکی نمی‌توانند تو در تو باشند، بنابراین اولین ‘*/’ کل یادداشت را پایان می‌دهد.
-Wno-obsolete: هشدار هنگام مواجهه با ویژگی‌های منسوخ‌شده که ممکن است در آینده حذف شوند.
-Wnumeric-string=: هشدار هنگامی که با یک رشته چندنویسه‌ای به عنوان عدد برخورد شود. -Wnumeric-string=0 یا -Wno-numeric-string این هشدار را غیرفعال می‌کند. -Wnumeric-string=1 یا صرفاً -Wnumeric-string درباره رشته‌های طولانی‌تر از چهار نویسه هشدار می‌دهد، زیرا چهار نویسه یا کمتر درون یک عدد صحیح ۳۲ بیتی جای می‌گیرند. -Wnumeric-string=2 در مورد هر رشته چندنویسه‌ای هشدار می‌دهد.
-Wpurge=: هشدار هنگام پاکسازی نمادهایی که احتمالاً ضروری بوده‌اند. -Wpurge=0 یا -Wno-purge این هشدار را غیرفعال می‌کند. -Wpurge=1 هنگام پاکسازی هر نماد صادرشده (صرف‌نظر از نوع آن) هشدار می‌دهد. -Wpurge=2 یا صرفاً -Wpurge همچنین هنگام پاکسازی هر برچسب (حتی اگر صادر نشده باشد) هشدار می‌دهد.
-Wshift: هشدار هنگام جابجایی به راست یک مقدار منفی. به جای آن از تقسیم بر 2**N استفاده کنید.
-Wshift-amount: هشدار هنگامی که عملوندِ یک عمل جابجایی منفی یا بزرگ‌تر از ۳۲ باشد.
-Wtruncation=: هشدار هنگامی که یک برش ضمنی (برای نمونه، db به یک مقدار ۸ بیتی) باعث از دست رفتن برخی بیت‌ها شود. -Wtruncation=0 یا -Wno-truncation این هشدار را غیرفعال می‌کند. -Wtruncation=1 یا صرفاً -Wtruncation زمانی هشدار می‌دهد که یک مقدار N بیتی برابر یا بزرگ‌تر از 2**N یا کوچک‌تر از 2**N- باشد. -Wtruncation=2 همچنین زمانی هشدار می‌دهد که یک مقدار N بیتی کمتر از (1-2**N)- باشد که در کدگذاری متمم دو جای نمی‌گیرد.
-Wunmapped-char=: هشدار هنگامی که یک نویسه تحت تبدیل charmap قرار می‌گیرد اما هیچ نگاشت تعریف‌شده‌ای ندارد. -Wunmapped-char=0 یا -Wno-unmapped-char این هشدار را غیرفعال می‌کند. -Wunmapped-char=1 یا صرفاً -Wunmapped-char تنها زمانی هشدار می‌دهد که charmap فعال خالی نباشد. -Wunmapped-char=2 زمانی هشدار می‌دهد که charmap فعال خالی باشد، و/یا charmap پیش‌فرض ‘main’ نباشد.
-Wunmatched-directive: هشدار هنگامی که یکی از دستورالعمل‌های PUSHC ، PUSHO یا PUSHS دارای POPC ، POPO یا POPS متناظر نباشد. این هشدار توسط -Wextra فعال می‌شود.
-Wunterminated-load: هشدار هنگامی که یک بلوک LOAD با یک ENDL پایان نیافته باشد. این هشدار توسط -Wextra فعال می‌شود.
-Wno-user: هشدار هنگامی که دستور توکار WARN اجرا می‌شود. (برای WARN ، بخش “Aborting the assembly process” در rgbasm(5) را ببینید).

مثال‌ها (EXAMPLES)

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

روش مستقیم:

$ rgbasm -o bar.o
  foo.asm

روش لوله‌کشی (pipes):

$ cat foo.asm | rgbasm -o bar.o
  -

$ rgbasm -o bar.o - <
  foo.asm

فایل شیء حاصل هنوز یک تصویر ROM قابل استفاده نیست—باید ابتدا از طریق rgblink(1) و سپس rgbfix(1) پردازش شود.

نوشتن وضعیت نهایی اسمبلر در یک فایل:

$ rgbasm -s all:state.dump.asm
  foo.asm

یا در چندین فایل:

$ rgbasm -s equ,var:numbers.dump.asm
  -s equs:strings.dump.asm foo.asm

گزارش باگ‌ها (BUGS)

لطفاً اشکالات یا خطاهای موجود در این مستندات را در GitHub گزارش کنید.

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

rgbasm(5), rgblink(1), rgbfix(1), rgbgfx(1), gbz80(7), rgbasm-old(5), rgbds(5), rgbds(7)

تاریخچه (HISTORY)

rgbasm در ابتدا توسط Carsten Sørensen به عنوان بخشی از بسته ASMotor نوشته شد و بعداً توسط Justin Lloyd در RGBDS بازبسته‌بندی شد. این نرم‌افزار اکنون توسط شماری از مشارکت‌کنندگان در https://github.com/gbdev/rgbds نگهداری می‌شود.