نام (NAME)

arm-none-eabi-cpp - پیش‌پردازنده C برای معماری ARM

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

cpp [-Dmacro[=defn]...] [-Umacro]
[-Idir...] [-iquotedir...]
[-M|-MM] [-MG] [-MF filename]
[-MP] [-MQ target...]
[-MT target...]
infile [[-o] outfile]

تنها کاربردی‌ترین گزینه‌ها در بالا آورده شده‌اند؛ برای فهرست کامل‌تری از گزینه‌های ویژه پیش‌پردازنده به ادامه مراجعه کنید. علاوه بر این، cpp بیشتر گزینه‌های درایور gcc را که در اینجا فهرست نشده‌اند می‌پذیرد. برای جزئیات به مستندات GCC مراجعه فرمایید.

توضیحات (DESCRIPTION)

پیش‌پردازنده سی (C)، که اغلب با عنوان cpp شناخته می‌شود، یک پردازنده ماکرو است که پیش از کامپایل، به طور خودکار توسط کامپایلر C برای تبدیل برنامه شما استفاده می‌شود. از این رو پردازنده ماکرو نامیده می‌شود که به شما امکان می‌دهد ماکروها را تعریف کنید؛ ماکروها اختصارات کوتاهی برای ساختارهای طولانی‌تر هستند.

پیش‌پردازنده C تنها برای استفاده با کدهای منبع C، C++ و Objective-C در نظر گرفته شده است. در گذشته، به عنوان یک پردازنده متنی عمومی سوءاستفاده شده است. این ابزار در مواجهه با ورودی‌هایی که از قواعد واژگانی C پیروی نمی‌کنند متوقف شده و با خطا روبرو می‌شود. به عنوان مثال، آپوستروف‌ها به عنوان ابتدای ثابت‌های نویسه‌ای در نظر گرفته شده و موجب خطا می‌شوند. همچنین نمی‌توانید به آن برای حفظ ویژگی‌هایی از ورودی که برای زبان‌های خانواده C اهمیتی ندارند تکیه کنید. اگر یک Makefile پیش‌پردازش شود، تمام فاصله‌های تب سخت (hard tabs) حذف شده و Makefile کار نخواهد کرد.

با این حال، شما اغلب می‌توانید از cpp برای مواردی غیر از C نیز با موفقیت استفاده کنید. سایر زبان‌های برنامه‌نویسی شبه‌الگول (مانند Ada و غیره) اغلب بدون مشکل هستند. اسمبلی نیز با رعایت احتیاط همین‌گونه است. حالت -traditional-cpp فاصله‌های خالی بیشتری را حفظ می‌کند و در سایر زمینه‌ها نیز آسان‌گیرتر است. با نوشتن کامنت‌ها به سبک C یا C++ به جای کامنت‌های زبان اصلی، و همچنین با ساده نگه داشتن ماکروها، می‌توان از بسیاری از مشکلات دوری کرد.

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

پیش‌پردازنده‌های C در برخی جزئیات تفاوت دارند. این راهنما به بررسی پیش‌پردازنده GNU C می‌پردازد که فرامجموعه کوچکی از ویژگی‌های استاندارد ISO C را فراهم می‌کند. در حالت پیش‌فرض، پیش‌پردازنده GNU C چند مورد موردنیاز استاندارد را انجام نمی‌دهد. این‌ها ویژگی‌هایی هستند که به ندرت، یا شاید هرگز، استفاده می‌شوند و ممکن است تغییرات شگفت‌آوری در معنای برنامه‌ای که انتظار آنها را ندارد ایجاد کنند. برای دستیابی به استاندارد دقیق ISO C، بسته به اینکه کدام نسخه از استاندارد را می‌خواهید، باید از گزینه‌های -std=c90، -std=c99، -std=c11 یا -std=c17 استفاده کنید. همچنین برای دریافت تمام پیام‌های تشخیصی الزامی، باید از -pedantic نیز استفاده کنید.

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

جهت شفافیت، مگر در مواردی که خلاف آن قید شده باشد، منظور از CPP در این راهنما، GNU CPP است.

گزینه‌ها (OPTIONS)

دستور cpp دو نام فایل را به عنوان آرگومان دریافت می‌کند: infile و outfile. پیش‌پردازنده فایل infile را به همراه سایر فایل‌هایی که با #include مشخص شده‌اند می‌خواند. تمام خروجی تولیدشده توسط ترکیب فایل‌های ورودی در outfile نوشته می‌شود.

هر یک از infile یا outfile می‌تواند - باشد، که برای infile به معنای خواندن از ورودی استاندارد و برای outfile به معنای نوشتن در خروجی استاندارد است. اگر هر یک از فایل‌ها حذف شود، دقیقاً به این معنی است که برای آن فایل - تعیین شده است. همچنین می‌توانید از گزینه -o outfile برای تعیین فایل خروجی استفاده کنید.

مگر در مواردی که خلاف آن قید شده باشد، یا گزینه به = ختم شود، تمام گزینه‌هایی که آرگومان دریافت می‌کنند، آرگومان آنها می‌تواند بلافاصله پس از گزینه، یا با یک فاصله بین گزینه و آرگومان ظاهر شود: -Ifoo و -I foo اثر یکسانی دارند.

بسیاری از گزینه‌ها نام‌های چندحرفی دارند؛ بنابراین چندین گزینه تک‌حرفی را نمی‌توان با هم ادغام کرد: -dM بسیار متفاوت از -d -M است.

-D name

--define-macro=name

--define-macro name

از پیش name را به عنوان یک ماکرو با تعریف 1 تعریف می‌کند.

-D name=definition

--define-macro=name=definition

--define-macro name=definition

محتویات definition نشانه‌گذاری شده و به گونه‌ای پردازش می‌شود که گویی در مرحله سوم ترجمه درون یک دستور #define ظاهر شده است. به طور خاص، تعریف توسط نویسه‌های خط جدیدِ درونی کوتاه می‌شود.

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

اگر می‌خواهید یک ماکروی تابع‌گونه (function-like) در خط فرمان تعریف کنید، فهرست آرگومان‌های آن را درون پرانتزها قبل از علامت مساوی (در صورت وجود) بنویسید. پرانتزها در اکثر شل‌ها معنا دارند، بنابراین باید گزینه را کوت کنید. در sh و csh، قالب -D'name(args...)=definition' کار می‌کند.

گزینه‌های -D و -U به ترتیبی که در خط فرمان داده شده‌اند پردازش می‌شوند. تمام گزینه‌های -imacros file و -include file پس از تمامی گزینه‌های -D و -U پردازش می‌گردند.

-U name

--undefine-macro=name

--undefine-macro name

هرگونه تعریف قبلی از name را، خواه توکار باشد یا با گزینه -D تعیین شده باشد، لغو می‌کند.

-include file

--include=file

--include file

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

اگر چند گزینه -include داده شود، پرونده‌ها به ترتیبی که در خط فرمان آمده‌اند گنجانده می‌شوند.

-imacros file

--imacros=file

--imacros file

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

تمام پرونده‌های مشخص‌شده با -imacros پیش از تمام پرونده‌های مشخص‌شده با -include پردازش می‌شوند.

-undef

هیچ ماکروی مختص سیستم یا مختص GCC را از پیش تعریف نمی‌کند. ماکروهای استاندارد از پیش تعریف‌شده همچنان تعریف‌شده باقی می‌مانند.

-pthread

ماکروهای اضافی مورد نیاز برای استفاده از کتابخانه نخ‌های پازیکس (POSIX threads) را تعریف می‌کند. شما باید از این گزینه به طور هماهنگ هم برای کامپایل و هم برای پیوند (لینک) استفاده کنید. این گزینه در اهداف GNU/Linux، اکثر مشتقات یونیکس، و همچنین روی اهداف Cygwin و MinGW معماری x86 پشتیبانی می‌شود.

-M

--dependencies

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

مگر اینکه به صراحت مشخص شده باشد (با -MT یا -MQ)، نام پرونده شیء از نام پرونده منبع با جایگزینی هر پسوند با پسوند پرونده شیء و حذف هر بخش پوشه پیشین تشکیل می‌شود. اگر پرونده‌های گنجانده‌شده زیادی وجود داشته باشد، قاعده با استفاده از خط جدید-\ به چندین خط تقسیم می‌شود. این قاعده دستوری ندارد.

این گزینه خروجی اشکال‌زدایی پیش‌پردازنده مانند -dM را متوقف نمی‌کند. برای جلوگیری از ترکیب چنین خروجی اشکال‌زدایی با قواعد وابستگی، باید پرونده خروجی وابستگی را به صراحت با -MF مشخص کنید، یا از یک متغیر محیطی مانند DEPENDENCIES_OUTPUT استفاده نمایید. خروجی اشکال‌زدایی همچنان طبق معمول به جریان خروجی استاندارد فرستاده می‌شود.

ارسال -M به راه‌انداز مستلزم -E است و هشدارها را با یک -w ضمنی غیرفعال می‌کند.

-MM

--user-dependencies

مشابه -M است، اما به پرونده‌های هدر موجود در پوشه‌های هدر سیستم و همچنین پرونده‌های هدری که به‌طور مستقیم یا غیرمستقیم از چنین هدری گنجانده شده‌اند، اشاره نمی‌کند.

این بدان معنی است که انتخاب قلاب‌ها یا گیومه‌ها در یک دستورالعمل #include به خودی خود تعیین نمی‌کند که آیا آن هدر در خروجی وابستگی -MM ظاهر می‌شود یا خیر.

-MF file

هنگام استفاده به همراه -M یا -MM، پرونده‌ای را برای نوشتن وابستگی‌ها در آن مشخص می‌کند. اگر هیچ سوییچ -MF داده نشود، پیش‌پردازنده قواعد را به همان جایی می‌فرستد که خروجی پیش‌پردازش‌شده را ارسال می‌کرد.

هنگام استفاده با گزینه‌های راه‌انداز -MD یا -MMD، گزینه -MF پرونده خروجی پیش‌فرض وابستگی را بازنویسی می‌کند.

اگر file برابر - باشد، وابستگی‌ها در stdout نوشته می‌شوند.

-MG

--print-missing-file-dependencies

در ارتباط با گزینه‌ای مانند -M که درخواست تولید وابستگی دارد، -MG فرض می‌کند که پرونده‌های هدر ناموجود پرونده‌های تولیدشده هستند و آن‌ها را بدون ایجاد خطا به فهرست وابستگی‌ها اضافه می‌کند. نام پرونده وابستگی مستقیماً از دستورالعمل "#include" بدون افزودن هیچ مسیری در ابتدا گرفته می‌شود. -MG همچنین خروجی پیش‌پردازش‌شده را متوقف می‌کند، زیرا پرونده هدر ناموجود این خروجی را بی‌استفاده می‌سازد.

این قابلیت در به‌روزرسانی خودکار makefileها استفاده می‌شود.

-Mno-modules

تولید وابستگی را برای رابط‌های ماژول کامپایل‌شده غیرفعال می‌کند.

-MP

این گزینه به CPP دستور می‌دهد که برای هر وابستگی غیر از پرونده اصلی، یک هدف ساختگی اضافه کند، به طوری که هر کدام به چیزی وابسته نباشند. این قواعد ساختگی خطاهایی را دور می‌زنند که در صورت حذف پرونده‌های هدر بدون به‌روزرسانی متناظر Makefile، توسط make ایجاد می‌شوند.

این یک خروجی نمونه است:

test.o: test.c test.h

test.h:

-MT target

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

یک گزینه -MT هدف را دقیقاً برابر با رشته‌ای که مشخص می‌کنید قرار می‌دهد. اگر چندین هدف می‌خواهید، می‌توانید آن‌ها را به عنوان یک آرگومان واحد به -MT مشخص کنید، یا از چندین گزینه -MT استفاده نمایید.

برای مثال، -MT '$(objpfx)foo.o' ممکن است خروجی زیر را بدهد:

$(objpfx)foo.o: foo.c

-MQ target

مشابه -MT است، اما کاراکترهایی را که برای Make خاص هستند نقل‌قول می‌کند. مقدار -MQ '$(objpfx)foo.o' این خروجی را می‌دهد:

$$(objpfx)foo.o: foo.c

هدف پیش‌فرض به‌طور خودکار نقل‌قول می‌شود، گویی با -MQ مشخص شده است.

-MD

--write-dependencies

گزینه -MD معادل -M -MF file است، با این تفاوت که -E در آن ضمنی نیست. راه‌انداز مقدار file را بر اساس داده شدن یا نشدن گزینه -o تعیین می‌کند. اگر داده شده باشد، راه‌انداز از آرگومان آن اما با پسوند .d استفاده می‌کند، در غیر این صورت نام پرونده ورودی را گرفته، بخش‌های پوشه و پسوند را حذف کرده و پسوند .d را اعمال می‌کند.

اگر -MD همراه با -E استفاده شود، هر سوییچ -o به عنوان مشخص‌کننده پرونده خروجی وابستگی در نظر گرفته می‌شود، اما اگر بدون -E استفاده شود، هر -o مشخص‌کننده یک پرونده شیء هدف خواهد بود.

از آنجا که -E ضمنی نیست، -MD می‌تواند برای تولید پرونده خروجی وابستگی به عنوان یک اثر جانبی از فرآیند کامپایل استفاده شود.

-MMD

--write-user-dependencies

مشابه -MD است با این تفاوت که فقط به پرونده‌های هدر کاربر اشاره می‌کند، نه پرونده‌های هدر سیستم.

-fpreprocessed

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

اگر پرونده ورودی دارای یکی از پسوندهای .i، .ii یا .mi باشد، گزینه -fpreprocessed به صورت ضمنی فعال می‌شود. این‌ها پسوندهایی هستند که GCC برای پرونده‌های پیش‌پردازش‌شده ایجادشده توسط -save-temps استفاده می‌کند.

-fdirectives-only

هنگام پیش‌پردازش، دستورالعمل‌ها را پردازش می‌کند، اما ماکروها را بسط نمی‌دهد.

رفتار این گزینه به گزینه‌های -E و -fpreprocessed بستگی دارد.

همراه با -E، پیش‌پردازش به پردازش دستورالعمل‌هایی مانند "#define"، "#ifdef" و "#error" محدود می‌شود. سایر عملیات پیش‌پردازنده مانند بسط ماکرو و تبدیل سه‌نگاره انجام نمی‌شوند. علاوه بر این، گزینه -dD به‌طور ضمنی فعال می‌گردد.

همراه با -fpreprocessed، پیش‌تعریف ماکروهای خط فرمان و اکثر ماکروهای توکار غیرفعال می‌شود. ماکروهایی مانند "__LINE__" که به زمینه وابسته هستند، طبق معمول پردازش می‌شوند. این امر امکان کامپایل پرونده‌هایی را فراهم می‌کند که قبلاً با "-E -fdirectives-only" پیش‌پردازش شده‌اند.

در صورت وجود هر دو گزینه -E و -fpreprocessed، قواعد مربوط به -fpreprocessed اولویت دارند. این کار امکان پیش‌پردازش کامل پرونده‌هایی را که قبلاً با "-E -fdirectives-only" پیش‌پردازش شده‌اند، فراهم می‌کند.

-fdollars-in-identifiers

پذیرش $ در شناسه‌ها.

-fextended-identifiers

پذیرش نام‌های کاراکتر عمومی و کاراکترهای گسترش‌یافته در شناسه‌ها. این گزینه به‌طور پیش‌فرض برای C99 (و نسخه‌های بعدی استاندارد C) و C++ فعال است.

-fno-canonical-system-headers

هنگام پیش‌پردازش، مسیرهای هدر سیستم را با یکسان‌سازی کوتاه نمی‌کند.

-fmax-include-depth=depth

تنظیم حداکثر عمق تودرتویی دستورالعمل #include. مقدار پیش‌فرض 200 است.

-fsearch-include-path[=kind]

جستجوی پرونده‌های ورودی در مسیر #include، نه فقط در پوشه جاری. این گزینه به ویژه در ماژول‌های C++20 مفید است که در آن‌ها هر دو واحد هدر و واحدهای رابط ماژول باید مستقیماً کامپایل شوند:

g++ -c -std=c++20 -fmodules -fsearch-include-path bits/stdc++.h bits/std.cc

مقدار kind به طور پیش‌فرض user است که در مسیر جستجوی #include "..." جستجو می‌کند؛ همچنین می‌توانید برای مسیر جستجوی "#include <...>" به صراحت system را مشخص نمایید.

-ftabstop=width

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

-ftrack-macro-expansion[=level]

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

توجه داشته باشید که "-ftrack-macro-expansion=2" به‌طور پیش‌فرض فعال است.

-fmacro-prefix-map=old=new

هنگام پیش‌پردازش پرونده‌های مقیم در پوشه old، ماکروهای "__FILE__" و "__BASE_FILE__" را طوری بسط می‌دهد که گویی پرونده‌ها در پوشه new قرار دارند. این گزینه می‌تواند برای تغییر یک مسیر مطلق به یک مسیر نسبی با استفاده از . برای new استفاده شود که می‌تواند منجر به ساخت‌های تکرارپذیرتر و مستقل از مکان گردد. این گزینه همچنین بر "__builtin_FILE()" در حین کامپایل تأثیر می‌گذارد. همچنین نگاه کنید به -ffile-prefix-map و -fcanon-prefix-map.

-fexec-charset=charset

مجموعه کاراکترهای اجرایی را که برای ثابت‌های رشته‌ای و کاراکتری استفاده می‌شود، تنظیم می‌کند. مقدار پیش‌فرض UTF-8 است. charset می‌تواند هر کدگذاری پشتیبانی‌شده توسط روال کتابخانه "iconv" سیستم باشد.

-fwide-exec-charset=charset

مجموعه کاراکترهای اجرایی عریض را که برای ثابت‌های رشته‌ای و کاراکتری عریض استفاده می‌شود، تنظیم می‌کند. مقدار پیش‌فرض یکی از UTF-32BE، UTF-32LE، UTF-16BE یا UTF-16LE است، بسته به اینکه کدام یک با عرض "wchar_t" و ترتیب بایت‌های بزرگ‌بایتی یا کوچک‌بایتی مورد استفاده برای تولید کد مطابقت داشته باشد. همانند -fexec-charset، مقدار charset می‌تواند هر کدگذاری پشتیبانی‌شده توسط روال کتابخانه "iconv" سیستم باشد؛ با این حال، با کدگذاری‌هایی که دقیقاً در "wchar_t" جا نمی‌شوند دچار مشکل خواهید شد.

-finput-charset=charset

مجموعه کاراکتر ورودی را تنظیم می‌کند که برای تبدیل از مجموعه کاراکتر پرونده ورودی به مجموعه کاراکتر منبع مورد استفاده توسط GCC به کار می‌رود. مقدار پیش‌فرض UTF-8 است. charset می‌تواند هر کدگذاری پشتیبانی‌شده توسط روال کتابخانه "iconv" سیستم باشد.

اگر مجموعه کاراکتر ورودی UTF-8 باشد و گزینه -Winvalid-utf8 فعال باشد، هشدارهایی درباره دنباله‌های واحد کد ناقص صادر می‌شود. در غیر این صورت، در صورتی که مجموعه کاراکتر ورودی با مجموعه کاراکتر اجرایی مطابقت داشته باشد، هیچ پیام تشخیصی صادر نمی‌شود. اگر آن‌ها متفاوت باشند، دنباله‌های واحد کد ناقص در حین تبدیل کدگذاری به مجموعه کاراکتر اجرایی، منجر به خطا می‌شوند.

-fworking-directory

تولید نشانگرهای خط را در خروجی پیش‌پردازنده فعال می‌کند که به کامپایلر اجازه می‌دهد از پوشه کاری جاری در زمان پیش‌پردازش مطلع شود. هنگامی که این گزینه فعال است، پیش‌پردازنده پس از نشانگر خط اولیه، یک نشانگر خط دوم با پوشه کاری جاری که به دنبال آن دو اسلش قرار دارد صادر می‌کند. هنگامی که این پوشه در ورودی پیش‌پردازش‌شده وجود دارد، GCC از آن به عنوان پوشه‌ای استفاده می‌کند که در برخی قالب‌های اطلاعات اشکال‌زدایی به عنوان پوشه کاری جاری صادر می‌شود. اگر اطلاعات اشکال‌زدایی فعال باشد، این گزینه به‌طور ضمنی فعال است، اما می‌توان با شکل نفی‌شده -fno-working-directory از آن جلوگیری کرد. اگر فلگ -P در خط فرمان وجود داشته باشد، این گزینه هیچ اثری ندارد، زیرا هیچ دستورالعمل "#line" به هیچ وجه صادر نمی‌شود.

-A predicate=answer

--assert predicate=answer

--assert=predicate=answer

یک تصدیق با گزاره predicate و پاسخ answer ایجاد می‌کند. این شکل بر شکل قدیمی‌تر -A predicate(answer) که همچنان پشتیبانی می‌شود ترجیح داده می‌شود، زیرا از کاراکترهای ویژه شل استفاده نمی‌کند.

تصدیق‌ها یک ویژگی منسوخ‌شده در پیش‌پردازنده هستند که تنها برای سازگاری با هدرهای قدیمی سیستم در برخی اهداف پشتیبانی می‌شوند.

-A -predicate=answer

--assert -predicate=answer

--assert=-predicate=answer

یک تصدیق را با گزاره predicate و پاسخ answer لغو می‌کند.

-C

--comments

کامنت‌ها را دور نریزید. تمام کامنت‌ها به پرونده خروجی منتقل می‌شوند، به‌جز کامنت‌های موجود در دایرکتیوهای پردازش‌شده که همراه با خود دایرکتیو حذف می‌شوند.

هنگام استفاده از -C باید برای اثرات جانبی آماده باشید؛ این گزینه باعث می‌شود پیش‌پردازنده با کامنت‌ها به عنوان نشانه‌ها (توکن‌ها)ی مستقل رفتار کند. به عنوان مثال، کامنت‌هایی که در ابتدای خطی قرار می‌گیرند که می‌توانست یک خط دایرکتیو باشد، موجب تبدیل آن خط به یک خط کد منبع معمولی می‌شوند، زیرا اولین توکن روی خط دیگر # نیست.

-CC

--comments-in-macros

کامنت‌ها را دور نریزید، از جمله در زمان بسط ماکرو. این گزینه مانند -C است، با این تفاوت که کامنت‌های درون ماکروها نیز در جایی که ماکرو بسط داده می‌شود به پرونده خروجی منتقل می‌شوند.

علاوه بر اثرات جانبی گزینه -C، گزینه -CC باعث می‌شود تمام کامنت‌های سبک C++ درون یک ماکرو به کامنت‌های سبک C تبدیل شوند. این کار برای جلوگیری از این است که استفاده‌های بعدی از آن ماکرو به‌طور ناخواسته باقی‌مانده خط منبع را کامنت کند.

گزینه -CC معمولاً برای پشتیبانی از کامنت‌های lint استفاده می‌شود.

-P

--no-line-commands

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

-traditional

--traditional

-traditional-cpp

--traditional-cpp

تلاش برای تقلید از رفتار پیش‌پردازنده‌های C پیش از استاندارد، در مقابل پیش‌پردازنده‌های استاندارد ISO C.

توجه داشته باشید که GCC در موارد دیگر تلاشی برای شبیه‌سازی کامپایلر C پیش از استاندارد نمی‌کند، و این گزینه‌ها تنها با سوییچ -E یا هنگام فراخوانی صریح CPP پشتیبانی می‌شوند.

-trigraphs

--trigraphs

پشتیبانی از سه‌نگاره‌های (trigraphs) استاندارد ISO C. این‌ها توالی‌های سه‌کاراکتری هستند که همگی با ?? آغاز می‌شوند و توسط ISO C برای نمایش کاراکترهای تکی تعریف شده‌اند. به عنوان مثال، ??/ بیانگر \ است، بنابراین '??/n' یک ثابت کاراکتری برای خط جدید (newline) است.

به‌طور پیش‌فرض، GCC سه‌نگاره‌ها را نادیده می‌گیرد، اما در حالت‌های منطبق با استاندارد آن‌ها را تبدیل می‌کند. گزینه‌های -std و -ansi را ببینید.

-remap

کد ویژه‌ای را برای دور زدن محدودیت‌های سیستم‌های پرونده‌ای که فقط نام‌های بسیار کوتاه برای پرونده‌ها را مجاز می‌دانند (مانند MS-DOS)، فعال می‌کند.

-H

--trace-includes

نام هر پرونده هدر استفاده‌شده را علاوه بر سایر فعالیت‌های عادی چاپ می‌کند. هر نام با تورفتگی نمایش داده می‌شود تا نشان دهد در چه عمقی از پشته #include قرار دارد. پرونده‌های هدر پیش‌کامپایل‌شده نیز چاپ می‌شوند، حتی اگر نامعتبر تشخیص داده شوند؛ یک پرونده هدر پیش‌کامپایل‌شده نامعتبر با ...x و یک پرونده معتبر با ...! چاپ می‌شود.

-dletters

--dump=letters

--dump letters

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

-fdebug-cpp

این گزینه تنها برای اشکال‌زدایی GCC مفید است. هنگامی که از CPP یا همراه با -E استفاده شود، اطلاعات اشکال‌زدایی مربوط به نقشه‌های موقعیت (location maps) را دامپ می‌کند. هر توکن در خروجی با دامپ نقشه‌ای که مکانش به آن تعلق دارد، مقدم می‌شود.

هنگامی که از GCC بدون -E استفاده شود، این گزینه هیچ اثری ندارد.

-I dir

-iquote dir

-isystem dir

-idirafter dir

--include-directory-after=dir

--include-directory-after dir

--include-directory=dir

--include-directory dir

دایرکتوری dir را به فهرست پوشه‌های مورد جستجو برای پرونده‌های هدر در حین پیش‌پردازش اضافه می‌کند. --include-directory یک نام مستعار برای -I است، در حالی که --include-directory-after نام مستعاری برای -idirafter است.

اگر dir با = یا $SYSROOT آغاز شود، آن‌گاه = یا $SYSROOT با پیشوند sysroot جایگزین می‌شود؛ گزینه‌های --sysroot و -isysroot را ببینید.

پوشه‌های مشخص‌شده با -iquote تنها برای شکل نقل‌قولی (گیومه) دایرکتیو اعمال می‌شوند: "#include "file"". پوشه‌های مشخص‌شده با -I، -isystem یا -idirafter برای جستجوی هر دو دایرکتیو "#include "file"" و "#include <file>" اعمال می‌شوند.

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

-I-

--include-barrier

مسیر include را تقسیم می‌کند. این گزینه منسوخ شده است. لطفاً به‌جای آن برای پوشه‌های -I قبل از -I- از -iquote استفاده کرده و گزینه -I- را حذف کنید.

هر پوشه‌ای که با گزینه‌های -I پیش از -I- مشخص شده باشد، تنها برای هدرهای درخواست‌شده با "#include "file"" جستجو می‌شود؛ آن‌ها برای "#include <file>" جستجو نمی‌شوند. اگر پوشه‌های اضافی با گزینه‌های -I پس از -I- مشخص شوند، آن پوشه‌ها برای تمامی دایرکتیوهای #include جستجو می‌شوند.

علاوه بر این، -I- از استفاده از دایرکتوری پرونده فعلی به عنوان نخستین پوشه جستجو برای "#include "file"" جلوگیری می‌کند. هیچ راهی برای بی‌اثر کردن این ویژگی -I- وجود ندارد.

-iprefix prefix

--include-prefix=prefix

--include-prefix prefix

مقدار prefix را به‌عنوان پیشوند برای گزینه‌های بعدی -iwithprefix مشخص می‌کند. اگر پیشوند نشان‌دهنده یک پوشه باشد، باید / پایانی را نیز قرار دهید.

-iwithprefix dir

-iwithprefixbefore dir

--include-with-prefix=prefix

--include-with-prefix prefix

--include-with-prefix-after=prefix

--include-with-prefix-after prefix

--include-with-prefix-before=prefix

--include-with-prefix-before prefix

مقدار dir را به پیشوندی که پیش‌تر با -iprefix مشخص شده اضافه می‌کند و پوشه حاصل را به مسیر جستجوی include می‌افزاید. -iwithprefixbefore آن را در همان جایی قرار می‌دهد که -I قرار می‌داد؛ -iwithprefix آن را در جایی قرار می‌دهد که -idirafter قرار می‌داد.

--include-with-prefix و --include-with-prefix-after هر دو نام‌های مستعاری برای -iwithprefix هستند، در حالی که --include-with-prefix-before نام مستعاری برای -iwithprefixbefore است.

-isysroot dir

این گزینه مانند گزینه --sysroot است، اما تنها برای فایل‌های هدر اعمال می‌شود (به جز برای مقصدهای Darwin که در آن‌ها هم برای فایل‌های هدر و هم کتابخانه‌ها اعمال می‌گردد). برای اطلاعات بیشتر گزینه --sysroot را ببینید.

-imultilib dir

از dir به‌عنوان یک زیرپوشه از دایرکتوری حاوی هدرهای C++ مختص مقصد استفاده می‌کند.

-imultiarch dir

از dir به‌عنوان یک زیرپوشه از دایرکتوری حاوی هدرهای C++ مختص معماری استفاده می‌کند.

-nostdinc

--no-standard-includes

دایرکتوری‌های استاندارد سیستم را برای یافتن فایل‌های هدر جستجو نمی‌کند. تنها دایرکتوری‌هایی که صراحتاً با گزینه‌های -I، -iquote، -isystem و/یا -idirafter مشخص شده‌اند (و دایرکتوری فایل فعلی، در صورت مناسب بودن) جستجو می‌شوند.

-nostdinc++

فایل‌های هدر را در دایرکتوری‌های استاندارد اختصاصی C++ جستجو نمی‌کند، اما سایر دایرکتوری‌های استاندارد را همچنان جستجو می‌کند. (این گزینه هنگام ساخت کتابخانه C++ استفاده می‌شود.)

--embed-dir=dir

--embed-directory=dir

--embed-directory dir

پوشه dir را به فهرست پوشه‌های مورد جستجو برای دستور پیش‌پردازنده "#embed" یا ماکروی "__has_embed" اضافه می‌کند. هیچ پوشه پیش‌فرضی برای "#embed" وجود ندارد.

اگر dir با = یا $SYSROOT آغاز شود، آنگاه = یا $SYSROOT با پیشوند sysroot جایگزین می‌شود؛ گزینه‌های --sysroot و -isysroot را ببینید.

-Wcomment

-Wcomments

هر زمان که یک توالی شروع توضیح /* در یک توضیح /* ظاهر شود، یا هر زمان که یک بک‌اسلش-خط‌جدید در یک توضیح // ظاهر شود، هشدار می‌دهد. این هشدار با -Wall فعال می‌شود.

-Wtrigraphs

در صورت برخورد با هرگونه سه‌نویسه‌ای (trigraph) که ممکن است معنای برنامه را تغییر دهد هشدار می‌دهد. در مورد سه‌نویسه‌های درون توضیحات هشداری داده نمی‌شود، مگر مواردی که یک خط جدید اسکیپ‌شده تشکیل دهند.

این گزینه به‌طور ضمنی توسط -Wall فعال می‌شود. اگر -Wall داده نشده باشد، این گزینه همچنان فعال است مگر اینکه سه‌نویسه‌ها فعال شده باشند. برای به‌دست آوردن تبدیل سه‌نویسه‌ها بدون هشدار، اما دریافت سایر هشدارهای -Wall، از -trigraphs -Wall -Wno-trigraphs استفاده کنید.

-Wundef

اگر یک شناسه تعریف‌نشده در یک دستور "#if" ارزیابی شود هشدار می‌دهد. چنین شناسه‌هایی با صفر جایگزین می‌شوند.

-Wexpansion-to-defined

هر زمان که defined در بسط یا بازشدن یک ماکرو دیده شود (از جمله حالتی که ماکرو توسط یک دستور #if باز می‌شود) هشدار می‌دهد. چنین کاربردی قابل حمل نیست. این هشدار همچنین با -Wpedantic و -Wextra فعال می‌شود.

-Wunused-macros

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

در مورد ماکروهای توکار، ماکروهای تعریف‌شده در خط فرمان و ماکروهای تعریف‌شده در فایل‌های include هشداری داده نمی‌شود.

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

#if defined the_macro_causing_the_warning
#endif

-Wno-endif-labels

هر زمان که به دنبال یک "#else" یا "#endif" متنی بیاید هشدار نمی‌دهد. این حالت گاهی در برنامه‌های قدیمی‌تر با کدهایی به شکل زیر رخ می‌دهد:

#if FOO
...
#else FOO
...
#endif FOO

دومین و سومین "FOO" باید درون توضیحات (کامنت‌ها) قرار گیرند. این هشدار به‌طور پیش‌فرض روشن است.

محیط (ENVIRONMENT)

این بخش متغیرهای محیطی را شرح می‌دهد که بر نحوه عملکرد CPP تأثیر می‌گذارند. می‌توانید از آن‌ها برای تعیین دایرکتوری‌ها یا پیشوندهایی که هنگام جستجوی فایل‌های include به کار می‌روند، یا برای کنترل خروجی وابستگی‌ها استفاده کنید.

توجه داشته باشید که می‌توانید مکان‌های جستجو را با گزینه‌هایی مانند -I نیز تعیین کنید و خروجی وابستگی‌ها را با گزینه‌هایی مانند -M کنترل نمایید. این گزینه‌ها بر متغیرهای محیطی اولویت دارند و متغیرهای محیطی نیز به نوبه خود بر پیکربندی GCC تقدم دارند.

CPATH

C_INCLUDE_PATH

CPLUS_INCLUDE_PATH

OBJC_INCLUDE_PATH

مقدار هر متغیر فهرستی از دایرکتوری‌ها است که با یک کاراکتر ویژه، بسیار شبیه به PATH، از هم جدا شده‌اند و در آن‌ها به دنبال فایل‌های هدر گشته می‌شود. کاراکتر ویژه، یعنی "PATH_SEPARATOR"، به معماری مقصد وابسته بوده و در زمان ساخت GCC تعیین می‌شود. برای مقصدهای مبتنی بر Microsoft Windows این کاراکتر نقطه-ویرگول (semicolon) و برای تقریباً تمامی دیگر مقصدها دونقطه (colon) است.

متغیر محیطی CPATH فهرستی از دایرکتوری‌ها را مشخص می‌کند تا جستجو شوند طوری که گویی با -I مشخص شده‌اند، اما پس از هر مسیری که با گزینه‌های -I در خط فرمان داده شده باشد. این متغیر محیطی بدون توجه به زبانی که پیش‌پردازش می‌شود مورد استفاده قرار می‌گیرد.

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

در تمامی این متغیرها، یک عنصر خالی به کامپایلر دستور می‌دهد که دایرکتوری کاری فعلی خود را جستجو کند. عناصر خالی می‌توانند در آغاز یا پایان یک مسیر ظاهر شوند. برای نمونه، اگر مقدار CPATH برابر با ":/special/include" باشد، اثری یکسان با -I. -I/special/include خواهد داشت.

DEPENDENCIES_OUTPUT

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

مقدار DEPENDENCIES_OUTPUT می‌تواند صرفاً نام یک فایل باشد، که در این صورت قواعد Make در آن فایل نوشته می‌شوند و نام هدف از روی نام فایل مبدأ حدس زده می‌شود. یا این مقدار می‌تواند به شکل file target باشد، که در این حالت قواعد در فایل file با استفاده از target به‌عنوان نام هدف نوشته می‌شوند.

به عبارت دیگر، این متغیر محیطی معادل ترکیب گزینه‌های -MM و -MF است، همراه با یک سوییچ اختیاری -MT.

SUNPRO_DEPENDENCIES

این متغیر مشابه DEPENDENCIES_OUTPUT است (بالا را ببینید)، با این تفاوت که فایل‌های هدر سیستمی نادیده گرفته نمی‌شوند، بنابراین به جای -MM بر -M دلالت دارد. با این حال، وابستگی به فایل ورودی اصلی نادیده گرفته می‌شود.

SOURCE_DATE_EPOCH

اگر این متغیر تنظیم شده باشد، مقدار آن یک برچسب زمانی یونیکس (UNIX timestamp) را مشخص می‌کند تا به جای تاریخ و زمان فعلی در ماکروهای "__DATE__" و "__TIME__" استفاده شود، تا بدین ترتیب برچسب‌های زمانی تعبیه‌شده تکرارپذیر (reproducible) شوند.

مقدار SOURCE_DATE_EPOCH باید یک برچسب زمانی یونیکس باشد، که به‌صورت تعداد ثانیه‌ها (به استثنای ثانیه‌های کبیسه) از 01 Jan 1970 00:00:00 نمایش‌یافته در قالب ASCII تعریف می‌شود؛ یکسان با خروجی "date +%s" در گنو/لینوکس و سایر سیستم‌هایی که از پسوند %s در دستور "date" پشتیبانی می‌کنند.

این مقدار باید یک برچسب زمانی شناخته‌شده باشد مانند آخرین زمان تغییر مبدأ یا بسته، و باید توسط فرآیند ساخت تنظیم شود.

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

gpl(7)، gfdl(7)، fsf-funding(7)، gcc(1)، و مدخل‌های Info برای cpp و gcc.

کپی‌رایت (COPYRIGHT)

حق نشر (c) ۱۹۸۷-۲۰۲۶ بنیاد نرم‌افزارهای آزاد (Free Software Foundation, Inc.)

اجازه کپی، توزیع و/یا تغییر این سند تحت شرایط مجوز مستندات آزاد گنو (GNU Free Documentation License)، نسخه ۱.۳ یا هر نسخه جدیدتر منتشر شده توسط بنیاد نرم‌افزارهای آزاد داده می‌شود. نسخه‌ای از مجوز در صفحه راهنمای gfdl(7) گنجانده شده است. این راهنما فاقد بخش‌های ناوردا (Invariant Sections) است. متون روی جلد (a) (پایین را ببینید) و متون پشت جلد (b) (پایین را ببینید) هستند.

(a) متن روی جلد FSF عبارت است از:

A GNU Manual

(b) متن پشت جلد FSF عبارت است از:

You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.