نام (NAME)

or1k-elf-cpp - پیش‌پردازنده C برای معماری OpenRISC

خلاصه دستور (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 پیش‌پردازش شود، تمام تب‌های واقعی حذف می‌شوند و Makefile کار نخواهد کرد.

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

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

پیش‌پردازنده‌های C در برخی جزئیات متفاوت هستند. این راهنما به پیش‌پردازنده GNU C می‌پردازد، که فرامجموعه کوچکی از ویژگی‌های C استاندارد ISO را فراهم می‌آورد. در حالت پیش‌فرض، پیش‌پردازنده GNU C چند موردی را که استاندارد الزام کرده انجام نمی‌دهد؛ این‌ها ویژگی‌هایی هستند که به ندرت، یا شاید هرگز، استفاده نمی‌شوند و ممکن است تغییرات شگفت‌آوری در معنای برنامه‌ای که انتظار آن‌ها را ندارد ایجاد نمایند. برای به دست آوردن C دقیقاً منطبق بر استاندارد ISO، باید بسته به نسخه استانداردی که می‌خواهید، از گزینه‌های -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

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

-D name=definition

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

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

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

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

-U name

لغو هرگونه تعریف پیشین برای name، چه توکار باشد چه با گزینه -D تعیین شده باشد.

-include file

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

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

-imacros file

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

تمام فایل‌های تعیین‌شده با -imacros پیش از تمام فایل‌های تعیین‌شده با -include پردازش می‌شوند.

-undef

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

-pthread

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

-M

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

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

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

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

-MM

مانند -M است اما به فایل‌های سرآیندی که در دایرکتوری‌های سرآیند سیستم وجود دارند یا فایل‌های سرآیندی که مستقیماً یا غیرمستقیم از چنین سرآیندی گنجانده شده‌اند اشاره نمی‌کند.

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

-MF file

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

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

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

-MG

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

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

-Mno-modules

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

-MP

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

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

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 خاص است علامت‌گذاری (quote) می‌کند. -MQ '$(objpfx)foo.o' چنین خروجی می‌دهد:

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

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

-MD

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

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

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

-MMD

همانند -MD است، با این تفاوت که تنها فایل‌های سرآیند کاربر را ذکر می‌کند، نه فایل‌های سرآیند سیستم.

-fpreprocessed

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

اگر فایل ورودی یکی از پسوندهای .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

هنگام پیش‌پردازش، مسیرهای سرآیند سیستم با متعارف‌سازی (canonicalization) کوتاه نشوند.

-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 "..."" جستجو می‌کند؛ شما همچنین می‌توانید صراحتاً system را برای مسیر جستجوی "#include <...>" مشخص کنید.

-ftabstop=width

تنظیم فاصله بین ایستگاه‌های تب (tab stops). این به پیش‌پردازنده کمک می‌کند تا شماره ستون‌های صحیح را در هشدارها یا خطاها گزارش کند، حتی اگر تب‌هایی در خط وجود داشته باشند. اگر مقدار کمتر از 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

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

-finput-charset=charset

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

-fworking-directory

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

-A predicate=answer

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

-A -predicate=answer

لغو یک ادعا با گزاره predicate و پاسخ answer.

-C

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

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

-CC

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

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

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

-P

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

-traditional

-traditional-cpp

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

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

-trigraphs

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

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

-remap

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

-H

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

-dletters

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

-fdebug-cpp

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

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

-I dir

-iquote dir

-isystem dir

-idirafter dir

افزودن دایرکتوری dir به فهرست دایرکتوری‌هایی که برای فایل‌های سرآیند در طول پیش‌پردازش جستجو می‌شوند.

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

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

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

-I-

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

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

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

-iprefix prefix

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

-iwithprefix dir

-iwithprefixbefore dir

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

-isysroot dir

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

-imultilib dir

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

-nostdinc

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

-nostdinc++

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

--embed-dir=dir

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

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

-Wcomment

-Wcomments

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

-Wtrigraphs

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

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

-Wundef

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

-Wexpansion-to-defined

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

-Wunused-macros

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

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

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

#if defined the_macro_causing_the_warning
#endif

-Wno-endif-labels

عدم ارسال هشدار هر زمان که پس از یک "#else" یا "#endif" متن قرار گیرد. این مورد گاهی در برنامه‌های قدیمی‌تر با کدهایی به شکل زیر پیش می‌آید:

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

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

محیط (ENVIRONMENT)

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

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

CPATH

C_INCLUDE_PATH

CPLUS_INCLUDE_PATH

OBJC_INCLUDE_PATH

مقدار هر متغیر فهرستی از دایرکتوری‌ها است که با یک نویسه ویژه، دقیقاً مانند PATH، از هم جدا شده‌اند و در آن‌ها برای یافتن فایل‌های سرآیند جستجو می‌شود. نویسه ویژه، "PATH_SEPARATOR"، وابسته به هدف است و در زمان ساخت GCC تعیین می‌شود. برای اهداف مبتنی بر مایکروسافت ویندوز یک نقطه-ویرگول (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 (در بالا) است، با این تفاوت که فایل‌های سرآیند سیستم نادیده گرفته نمی‌شوند، بنابراین مستلزم -M است به جای -MM. با این حال، وابستگی به فایل ورودی اصلی حذف می‌شود.

SOURCE_DATE_EPOCH

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

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

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

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

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

حق نشر (COPYRIGHT)

Copyright (c) 1987-2025 Free Software Foundation, Inc.

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

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

A GNU Manual

(ب) متن پشت جلد 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.