نام (NAME)

cpp - پیش‌پردازنده C

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

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

در بالا تنها کاربردی‌ترین گزینه‌ها آورده شده‌اند؛ برای دیدن فهرست کامل‌تری از گزینه‌های ویژهٔ پیش‌پردازنده، به ادامه متن مراجعه کنید. علاوه بر این، cpp بیشتر گزینه‌های گرداننده (driver) gcc را می‌پذیرد که در اینجا فهرست نشده‌اند. برای جزئیات بیشتر به مستندات GCC مراجعه کنید..SH "توضیحات (DESCRIPTION)" پیش‌پردازندهٔ C که اغلب با نام cpp شناخته می‌شود، یک پردازندهٔ ماکرو است که به‌طور خودکار توسط کامپایلر C برای دگرگون‌سازی برنامهٔ شما پیش از کامپایل به کار می‌رود. به این دلیل پردازندهٔ ماکرو نامیده می‌شود که به شما امکان می‌دهد ماکروها را تعریف کنید؛ ماکروها اختصارات کوتاهی برای سازه‌های طولانی‌تر هستند.

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

با این وجود، در اغلب موارد می‌توانید برای مواردی غیر از C نیز با موفقیت از cpp استفاده کنید. سایر زبان‌های برنامه‌نویسی شبه‌آلگول معمولاً امن هستند (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

--define-macro=name

--define-macro name

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

-D name=definition

--define-macro=name=definition

--define-macro name=definition

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

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

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

-M

--dependencies

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

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

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

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

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

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

test.o: test.c test.h

test.h:

-MT target

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

گزینه -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 به‌طور ضمنی اعمال نمی‌شود. گرداننده (driver) file را بر اساس اینکه آیا گزینه -o داده شده است یا خیر تعیین می‌کند. اگر داده شده باشد، گرداننده از آرگومان آن با پسوند .d استفاده می‌کند، در غیر این صورت نام فایل ورودی را گرفته، هر مؤلفه دایرکتوری و پسوند آن را حذف کرده، و پسوند .d را اعمال می‌کند.

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

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

-MMD

--write-user-dependencies

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

-fpreprocessed

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

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

-fdirectives-only

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

رفتار این گزینه به گزینه‌های -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]

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

توجه داشته باشید که "-ftrack-macro-expansion=2" به‌طور پیش‌فرض فعال است..IP -fmacro-prefix-map=old=new 4 هنگام پیش‌پردازش فایل‌های مستقر در دایرکتوری old، ماکروهای "__FILE__" و "__BASE_FILE__" را طوری بسط می‌دهد که گویی فایل‌ها در دایرکتوری new قرار دارند. از این گزینه می‌توان برای تبدیل یک مسیر مطلق به یک مسیر نسبی با استفاده از . به جای new بهره برد که می‌تواند منجر به ساخت‌های بازتولیدپذیرتر (reproducible builds) و مستقل از مکان شود. این گزینه همچنین بر "__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" جا نمی‌شوند با مشکل مواجه خواهید شد.

-finput-charset=charset

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

اگر مجموعه نویسه ورودی UTF-8 باشد، در صورت فعال بودن -Winvalid-utf8 هشدارهایی درباره دنباله‌های واحد کد ناصحیح (ill-formed code unit sequences) صادر می‌شود. در غیر این صورت، وقتی مجموعه نویسه ورودی با مجموعه نویسه اجرایی مطابقت داشته باشد، هیچ پیام تشخیصی صادر نمی‌شود. اگر آن‌ها متفاوت باشند، دنباله‌های واحد کد ناصحیح در حین تبدیل کد به مجموعه نویسه اجرایی منجر به خطا می‌شوند.

-fworking-directory

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

-A predicate=answer

--assert predicate=answer

--assert=predicate=answer

یک گزاره شرطی (assertion) با محمول 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

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

-traditional

--traditional

-traditional-cpp

--traditional-cpp

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

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

-trigraphs

--trigraphs

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

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

-remap

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

-H

--trace-includes

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

-dletters

--dump=letters

--dump letters

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

-fdebug-cpp

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

هنگامی که از 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 مشخص نشده باشد، این گزینه همچنان فعال است مگر اینکه trigraphها فعال شده باشند. برای تبدیل trigraph بدون هشدار، اما دریافت سایر هشدارهای -Wall، از -trigraphs -Wall -Wno-trigraphs استفاده کنید.

-Wundef

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

-Wexpansion-to-defined

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

-Wunused-macros

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

برای ماکروهای توکار (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 files) جستجو می‌شوند. این نویسهٔ ویژه، "PATH_SEPARATOR"، وابسته به مقصد (target-dependent) است و هنگام ساخت GCC تعیین می‌شود. برای مقصدهای مبتنی بر Microsoft Windows، این نویسه یک نقطه‌ویرگول (semicolon) است و برای تقریباً تمامی مقصدهای دیگر دو‌نقطه (colon) می‌باشد.

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

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

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

DEPENDENCIES_OUTPUT

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

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

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

SUNPRO_DEPENDENCIES

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

SOURCE_DATE_EPOCH

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

مقدار SOURCE_DATE_EPOCH باید یک برچسب زمان یونیکس باشد، تعریف‌شده به عنوان تعداد ثانیه‌ها (بدون احتساب ثانیه‌های کبیسه) از 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)

کپی‌رایت (c) 1987-2026 Free Software Foundation, Inc.

اجازه‌ی نسخه‌برداری، توزیع و/یا تغییر این سند تحت شرایط «مجوز مستندات آزاد گنو» (GNU Free Documentation License)، نگارش 1.3 یا هر نگارش بعدیِ منتشرشده توسط بنیاد نرم‌افزارهای آزاد (Free Software Foundation) اعطا می‌شود. نسخه‌ای از این مجوز در صفحهٔ راهنمای gfdl(7) گنجانده شده است. این راهنما هیچ بخش تغییرناپذیری (Invariant Sections) ندارد. متن‌های روی جلد (a) (پایین را ببینید) و متن‌های پشت جلد (b) (پایین را ببینید) هستند.

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

یک راهنمای گنو

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

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