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

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

-D name=definition

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

اگر پیش‌پردازنده را از طریق پوسته یا برنامه‌های شبیه پوسته اجرا می‌کنید، ممکن است لازم باشد با استفاده از قواعد نقل‌قول (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 را تعریف می‌کند. باید از این گزینه به‌طور یکنواخت هم برای کامپایل و هم برای پیوند دادن (linking) استفاده کنید. این گزینه در اهداف GNU/Linux، بیشتر مشتقات دیگر Unix و همچنین اهداف x86 در Cygwin و MinGW پشتیبانی می‌شود.

-M

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

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

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

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

-MM

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

این بدان معناست که استفاده از قلاب‌های زاویه‌دار یا علامت نقل‌قول در یک دستور #include، به خودی خود تعیین‌کنندهٔ حضور یا عدم حضور آن سرآیند در خروجی وابستگی -MM نخواهد بود.

-MF file

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

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

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

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

-Mno-modules

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

-MP

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

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

test.o: test.c test.h

test.h:

-MT target

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

گزینه -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 به عنوان مشخص‌کننده یک فایل شیء (object) مقصد در نظر گرفته می‌شود.

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

-MMD

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

-fpreprocessed

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

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

-fdirectives-only

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

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

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

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

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

-fdollars-in-identifiers

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

-fextended-identifiers

پذیرش نام‌های نویسه جهانی (universal character names) و نویسه‌های گسترش‌یافته در شناسه‌ها. این گزینه به‌طور پیش‌فرض برای 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]

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

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

-fwide-exec-charset=charset

تنظیم مجموعه نویسه اجرایی عریض (wide execution character set)، مورد استفاده برای ثابت‌های رشته‌ای و نویسه‌ای عریض. پیش‌فرض یکی از گزینه‌های UTF-32BE، UTF-32LE، UTF-16BE یا UTF-16LE است، بسته به این‌که کدام‌یک با عرض "wchar_t" و ترتیب بایت big-endian یا little-endian استفاده‌شده برای تولید کد مطابقت داشته باشد. همانند -fexec-charset، charset می‌تواند هر کدگذاری پشتیبانی‌شده توسط تابع کتابخانه‌ای "iconv" سیستم باشد؛ با این حال، با کدگذاری‌هایی که دقیقاً در "wchar_t" جا نمی‌شوند دچار مشکل خواهید شد..IP "-finput-charset=charset" 4 مجموعه نویسه‌های ورودی را تنظیم می‌کند که برای ترجمه از مجموعه نویسه‌های فایل ورودی به مجموعه نویسه‌های مبدا مورداستفاده GCC به کار می‌رود. اگر محلی‌سازی (locale) مشخص نکند، یا GCC نتواند این اطلاعات را از محلی‌سازی دریافت کند، پیش‌فرض UTF-8 است. این مقدار می‌تواند توسط محلی‌سازی یا این گزینه خط فرمان بازنویسی شود. در حال حاضر در صورت وجود تداخل، گزینه خط فرمان اولویت دارد. charset می‌تواند هر کدگذاری پشتیبانی‌شده توسط روال کتابخانه "iconv" سیستم باشد.

-fworking-directory

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

-A predicate=answer

یک ادعا (assertion) با گزاره 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 رزرو شده‌اند و بنابراین نادیده گرفته می‌شوند. اگر letters مشخص‌شده رفتار متناقض داشته باشند، نتیجه تعریف‌نشده است.

-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

اگر با سه‌نویسه‌هایی (trigraphs) برخورد شود که ممکن است معنای برنامه را تغییر دهند، هشدار می‌دهد. نویسه‌های سه‌تایی درون توضیح‌ها هشدار داده نمی‌شوند، مگر آن‌هایی که یک سطر جدیدِ گریز‌خورده ایجاد کنند.

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

-Wundef

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

-Wexpansion-to-defined

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

-Wunused-macros

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

برای ماکروهای درونی (built-in)، ماکروهای تعریف‌شده در خط فرمان، و ماکروهای تعریف‌شده در فایل‌های include هشداری داده نمی‌شود.

نکته: اگر ماکرویی واقعاً استفاده شده باشد اما فقط در بلوک‌های شرطی نادیده‌گرفته‌شده به کار رفته باشد، پیش‌پردازنده آن را بلااستفاده گزارش می‌کند. برای اجتناب از این هشدار در چنین حالتی، می‌توانید محدودهٔ تعریف ماکرو را مثلاً با انتقال آن به درون نخستین بلوک نادیده‌گرفته‌شده بهبود دهید. روش دیگر این است که یک استفادهٔ ساختگی (dummy) مانند زیر ارائه دهید:

#if defined the_macro_causing_the_warning
#endif

-Wno-endif-labels

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

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

عبارت دوم و سوم "FOO" باید درون توضیح (کامنت) باشند. این هشدار به طور پیش‌فرض روشن است..SH "محیط (ENVIRONMENT)" این بخش متغیرهای محیطی را شرح می‌دهد که بر نحوهٔ عملکرد CPP تأثیر می‌گذارند. می‌توانید از آن‌ها برای مشخص کردن دایرکتوری‌ها یا پیشوندهایی جهت جستجوی فایل‌های include، یا برای کنترل خروجی وابستگی‌ها استفاده کنید.

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

CPATH

C_INCLUDE_PATH

CPLUS_INCLUDE_PATH

OBJC_INCLUDE_PATH

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

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

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

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

DEPENDENCIES_OUTPUT

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

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

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

SUNPRO_DEPENDENCIES

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

SOURCE_DATE_EPOCH

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

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

این مقدار باید یک برچسب زمانی مشخص، مانند آخرین زمان تغییر منبع یا بسته باشد و باید توسط فرآیند ساخت تنظیم شود..SH "همچنین ببینید (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)، نگارش ۱٫۳ یا هر نگارش بعدی منتشرشده توسط بنیاد نرم‌افزار آزاد صادر می‌شود. نسخه‌ای از این مجوز در صفحهٔ راهنمای gfdl(7) گنجانده شده است. این راهنما هیچ بخش ناوردایی ندارد. متن‌های روی جلد (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.