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

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

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

-undef

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

-pthread

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

-M

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

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

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

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

-MM

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

این بدان معناست که استفاده از علامت‌های کوچکتر/بزرگتر (angle brackets) یا نقل‌قول دوتایی در دستورالعمل #include، به‌خودی‌خود تعیین‌کنندهٔ نمایش یا عدم نمایش آن سرآیند در خروجی وابستگی -MM نیست.

-MF file

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

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

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

-MG

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

این قابلیت در به‌روزرسانی خودکار makefileها مورد استفاده قرار می‌گیرد..IP "-Mno-modules" 4 تولید وابستگی برای رابط‌های ماژول کامپایل‌شده را غیرفعال می‌کند.

-MP

این گزینه به CPP دستور می‌دهد تا برای هر وابستگی به غیر از فایل اصلی، یک هدف ساختگی (phony target) اضافه کند، که باعث می‌شود هر کدام به هیچ‌چیز وابسته نباشند. این قواعد ساختگی خطاهایی را دور می‌زنند که 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

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

-fno-canonical-system-headers

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

-fmax-include-depth=depth

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

-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) را مشخص می‌کند. این به پیش‌پردازنده کمک می‌کند تا شماره ستون‌ها را در هشدارها یا خطاها به درستی گزارش دهد، حتی اگر در خط از نویسه تب استفاده شده باشد. اگر مقدار کمتر از ۱ یا بیشتر از ۱۰۰ باشد، گزینه نادیده گرفته می‌شود. مقدار پیش‌فرض ۸ است.

-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 بهره برد که می‌تواند منجر به ایجاد ساخت‌های بازتولیدپذیرتر (reproducible) و مستقل از مکان شود. این گزینه همچنین بر "__builtin_FILE()" در حین کامپایل اثر می‌گذارد. همچنین نگاه کنید به -ffile-prefix-map و -fcanon-prefix-map.

-fexec-charset=charset

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

-fwide-exec-charset=charset

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

-finput-charset=charset

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

-fworking-directory

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

-A predicate=answer

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

-C

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

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

-CC

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

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

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

-P

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

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

-dletters

تعیین می‌کند که در طول کامپایل، رونوشت‌های اشکال‌زدایی (debugging dumps) مطابق با 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- وجود ندارد..IP "-iprefix prefix" 4 مقدار 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) یافت شوند که ممکن است معنای برنامه را تغییر دهند، هشدار می‌دهد. سه‌نگاره‌های درون کامنت‌ها هشداری در پی ندارند، به‌جز آن‌هایی که یک خط‌جدید گریزدار (escaped newline) تشکیل می‌دهند.

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

-Wundef

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

-Wexpansion-to-defined

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

-Wunused-macros

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

ماکروهای توکار (built-in)، ماکروهای تعریف‌شده در خط فرمان، و ماکروهای تعریف‌شده در فایل‌های 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 را مشخص می‌کند تا به‌جای تاریخ و زمان فعلی در ماکروهای "__DATE__" و "__TIME__" استفاده شود، تا برچسب‌های زمانی تعبیه‌شده بازتولیدپذیر (reproducible) گردند.

مقدار 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) گنجانده شده است. این راهنما فاقد هرگونه بخش ناوردا (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.