PMCPP(1) General Commands Manual PMCPP(1)

pmcpp - پیش‌پردازنده ساده برای Performance Co-Pilot

pmcpp [-Prs?] [-D name[=value] ...] [-I dir ...] [[infile] [outfile]]

دستور pmcpp یک پیش‌پردازنده بسیار ساده را فراهم می‌کند که در اصل برای دستکاری فایل‌های فضای نام سنجه عملکرد (PMNS) در Performance Co-Pilot (PCP) طراحی شده بود، اما بعداً برای ارائه بلوک‌های شرطی، پردازش گنجاندن فایل (include)، اجرای درجا (in-line) دستورهای پوسته و جایگزینی ماکرو برای فایل‌های دلخواه تعمیم یافت. این ابزار اغلب به طور داخلی برای پردازش فایل(های) PMNS پس از فراخوانی pmLoadNameSpace(3) یا pmLoadASCIINameSpace(3) و همچنین برای پیش‌پردازش فایل‌های پیکربندی pmlogger(1) به کار می‌رود.

خطوط ورودی از infile (یا ورودی استاندارد در صورتی که infile مشخص نشده باشد) خوانده شده، پردازش می‌شوند و در outfile (یا خروجی استاندارد در صورتی که outfile مشخص نشده باشد) نوشته می‌شوند.

تمام توضیحات به سبک C به صورت /* ... */ از جریان ورودی حذف می‌شوند.

هیچ ماکروی از پیش‌تعریف‌شده‌ای برای pmcpp وجود ندارد، اگرچه می‌توان ماکروها را در خط فرمان با استفاده از گزینه -D تعریف کرد، که در آن name و value باید از همان قواعد شرح داده شده در زیر برای دستورالعمل #define پیروی کنند.

دستور pmcpp دستورالعمل‌های زیر را در جریان ورودی می‌پذیرد (مشابه cpp(1)):

  • #include "filename"
    یا
    #include <filename>
    در هر دو حالت، مسیر جستجوی دایرکتوری برای filename ابتدا خودِ filename را بررسی می‌کند، سپس دایرکتوریِ فایل ورودی infile در خط فرمان (در صورت وجود)، و پس از آن هر دایرکتوری مشخص‌شده در آرگومان‌های خط فرمان -I، و در نهایت دایرکتوری $PCP_VAR_DIR/pmns (مورد آخر برای سازگاری عقروعلی با نسخه‌های پیشین pmcpp و کاربرد ضمنی برگرفته از pmLoadASCIINameSpace(3) است). دستورالعمل‌های #include می‌توانند به صورت تودرتو، حداکثر تا عمق ۵ سطح باشند.
  • #shell "command"
    یا
    #shell 'command'
    دستور پوسته command اجرا خواهد شد و خروجی استاندارد آن در جریان داده‌هایی که قرار است توسط pmcpp پردازش شوند درج می‌گردد. از نظر عملکردی، این دستورالعمل مشابه #include است، با این تفاوت که خطوط ورودی به جای یک فایل، از یک command خوانده می‌شوند. دستورالعمل #shell بیشتر برای گنجاندن یا کنار گذاشتن دستورالعمل‌های #define یا #undef بر پایه منطق زمان اجرا در command کاربرد دارد.
  • #define name value
    یا
    #define name "value"
    یا
    #define name 'value'
    مقداری را برای ماکروی name تعریف می‌کند که باید یک نام معتبر به سبک زبان C باشد، بنابراین باید با یک حرف الفبا یا زیرخط آغاز شده و به دنبال آن صفر یا چند کاراکتر الفبایی‌عددی یا زیرخط بیاید. مقدار value اختیاری است (و پیش‌فرض آن یک رشته خالی است). هیچ سازوکار گریز از کاراکتر (escape) وجود ندارد، اما می‌توان از کوتیشن‌های تکی یا دوتایی برای تعریف یک value شامل کاراکترهای خاص یا فاصله‌های سفید افقی تعبیه‌شده (بدون خطوط جدید) استفاده کرد.
  • #undef name
    تعریف ماکروی name را در صورت وجود حذف می‌کند.
  • #ifdef name
    ...
    #endif
    یا
    #ifndef name
    ...
    #endif
    خطوط محصور بسته به این‌که ماکروی name تعریف شده باشد یا خیر، حذف یا گنجانده خواهند شد.
  • #else
    درون یک بلوک #ifdef یا #ifndef، می‌توان از #else برای مشخص کردن خطوطی که در صورت نادرست بودن شرط «if» پیشین باید گنجانده شوند، استفاده کرد.

جایگزینی ماکرو با شکستن جریان ورودی به کلماتی انجام می‌شود که توسط فاصله‌های سفید یا کاراکترهایی که در نام ماکرو معتبر نیستند (یعنی غیرالفبایی‌عددی و غیرزیرخط) از هم جدا شده‌اند. هر کلمه بررسی می‌شود و اگر با نام یک ماکرو مطابقت داشته باشد، با مقدار آن ماکرو جایگزین می‌شود؛ در غیر این صورت کلمه دست‌نخورده باقی می‌ماند..PP به طور کلی به ازای هر خط ورودی، یک خط خروجی وجود دارد؛ اگرچه در صورتی که متن به دلیل مدیریت کامنت‌ها یا دستورهای شرطی حذف شده باشد، این خط ممکن است خالی باشد. هنگامی که تغییری در جریان ورودی ایجاد شود، یک خط خروجی اضافی به این شکل تولید می‌شود:

# lineno "filename"

تا مشخص کند خط خروجی بعدی مربوط به شماره خط lineno از فایل ورودی filename است.

گزینه‌های خط فرمان موجود عبارتند از:

ماکرویی را با یک مقدار اختیاری تعریف می‌کند، همان‌طور که پیش‌تر توضیح داده شد.
یک دایرکتوری اضافی برای جستجوی فایل‌های include.
از تولید خطوط نشانگر شماره خط (linemarker) که در بالا توضیح داده شد جلوگیری می‌کند.
سبک ورودی مورد انتظار را از شبیه به C به شبیه به شل تغییر می‌دهد (جایی که # پیشوند کامنت است). این کار باعث اعمال تغییرات زیر در رفتار pmcpp می‌شود:
  • نویسه پیشوند کنترلی از # به % تغییر می‌یابد؛ بنابراین به عنوان مثال %include به جای #include و %ifdef به جای #ifdef به کار می‌رود.
  • هیچ حذف کامنتی به سبک C انجام نمی‌شود.
کنترل دقیق‌تری روی گسترش ماکرو فراهم می‌کند - این گزینه جایگزینی ماکرو را به کلماتی محدود می‌کند که با الگوهای #name یا #{name} یا در صورت مشخص شدن -s، با %name یا %{name} مطابقت داشته باشند. در این حالت، نام ماکرو name به تنهایی در جریان ورودی هرگز گسترش نخواهد یافت؛ با این حال در خطوط کنترلی (مانند #ifdef) نام ماکرو name باید به تنهایی و بدون نویسه پیشوند یا آکولادها ظاهر شود (به بخش «مثال‌ها (EXAMPLES)» در زیر مراجعه کنید).
-?, --help
نمایش پیام راهنمای استفاده و خروج.

قابلیت‌های مهم cpp(1) که توسط pmcpp پشتیبانی نمی‌شوند عبارتند از:

  • ماکروهای دارای پارامتر - ماکروهای pmcpp تنها از جایگزینی رشته‌ای بدون پارامتر پشتیبانی می‌کنند.
  • #if expr
    ...
    #endif
  • استفاده تو در تو از #ifdef یا #ifndef.
  • حذف کامنت‌های سبک ++C، مانند // comment.
  • بازیابی از خطا - نخستین خطایی که توسط pmcpp شناسایی شود مهلک خواهد بود.
  • گزینه‌های خط فرمان cpp(1) مانند -o، -W، -U و -x.
    دستور: pmcpp
    ورودی خروجی
    # 1 "<stdin>"
    #define MYDOMAIN 27
    root { root {
    foo MYDOMAIN:0:0 foo 27:0:0
    } }

برای مثال‌های زیر، فایل frequencies شامل این خطوط است:

%define dk_freq 1minute
%define cpu_freq '15 sec'
دستور: pmcpp -rs
ورودی خروجی
# get logging frequencies # get logging frequencies
# e.g. dk_freq macro # e.g. dk_freq macro
%include "frequencies"
log mandatory on %dk_freq { log mandatory on 1minute {
disk.dev disk.dev
} }
# note no %want_cpu here # note no %want_cpu here
%ifdef want_cpu
%define cpu_pfx 'kernel.all.cpu.'
log mandatory on %cpu_freq {
%{cpu_pfx}user
%{cpu_pfx}sys
}
%endif
دستور: pmcpp -rs -D want_cpu
ورودی خروجی
# get logging frequencies # get logging frequencies
# e.g. dk_freq macro # e.g. dk_freq macro
%include "frequencies"
log mandatory on %dk_freq { log mandatory on 1min {
disk.dev disk.dev
} }
# note no %want_cpu here # note no %want_cpu here
%ifdef want_cpu
%define cpu_pfx 'kernel.all.cpu.'
log mandatory on %cpu_freq { log mandatory on 15 sec {
%{cpu_pfx}user kernel.all.cpu.user
%{cpu_pfx}sys kernel.all.cpu.sys
} }
%endif
"محیط PCP (PCP ENVIRONMENT)"
متغیرهای محیطی با پیشوند PCP_ برای مقداردهی و تعیین نام فایل‌ها و دایرکتوری‌های مورد استفاده PCP به کار می‌روند.
در هر نصب، فایل /etc/pcp.conf حاوی مقادیر محلی برای این متغیرها است.
متغیر $PCP_CONF می‌تواند برای مشخص کردن یک فایل پیکربندی جایگزین استفاده شود، همان‌طور که در pcp.conf(5) شرح داده شده است.
برای متغیرهای محیطی تأثیرگذار بر ابزارهای PCP، به pmGetOptions(3) مراجعه کنید.
"همچنین ببینید (SEE ALSO)"
cpp (1),
pmLoadASCIINameSpace (3),
pmLoadNameSpace (3),
pcp.conf (5),
pcp.env (5)
و
PMNS (5).
Performance Co-Pilot