GPROFNG-ARCHIVE(1) دستورات کاربر GPROFNG-ARCHIVE(1)

gprofng-archive - بایگانی داده‌های حاصل از پروفایل‌بندی با ابزار gprofng

gprofng archive [گزینه‌ها] experiment

ابزار gprofng archive فایل‌های باینری و کدهای منبع برنامه‌ی هدف را درون دایرکتوری آزمایش (experiment) بایگانی می‌کند تا داده‌های آزمایش مستقل و قابل‌انتقال به سیستم‌های دیگر باشند.

به‌طور پیش‌فرض، فایل‌های باینری در زمان ثبت داده‌ها ذخیره می‌شوند، اما کدهای منبع برنامه در آزمایش ذخیره نمی‌شوند. این ابزار امکان می‌دهد این رویه را تغییر دهید و بعداً فایل‌ها و مؤلفه‌های لازم را به آزمایش بیفزایید.

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

چاپ شماره نسخه و خروج.
نمایش راهنمای استفاده و خروج.
تعیین نحوه بایگانی فایل‌های باینری و سایر پرونده‌ها. علاوه بر غیرفعال‌کردن این سازوکار (off) یا بایگانی همه اشیاء بارگذاری و سورس‌ها (on)، سایر گزینه‌ها امکان انتخاب دقیق‌تر مؤلفه‌ها را فراهم می‌کنند.

تمامی این مقادیر بایگانی را فعال می‌کنند، اما هر کلیدواژه مشخص می‌سازد دقیقاً چه مواردی انتخاب شوند: تمام اشیاء بارگذاری (ldobjects)، تمام فایل‌های منبع (src)، اشیاء بارگذاری مرتبط با شمارنده برنامه (usedldobjects) یا فایل‌های منبع مرتبط با شمارنده برنامه (used[src]). حالت پیش‌فرض -a ldobjects است.

مشخص‌کردن مسیر مطلق (path) به یک بایگانی مشترک (common archive). بایگانی مشترک پوشه‌ای است که فایل‌های بایگانی‌شده در آن نگهداری می‌شوند. اگر این پوشه وجود نداشته باشد، به‌طور خودکار ایجاد می‌شود. فایل‌ها در پوشه بایگانی مشترک ذخیره شده و یک پیوند نمادین (Symbolic Link) به آن‌ها در بایگانی آزمایش قرار می‌گیرد.
اجبار در نوشتن یا بازنویسی فایل‌های .archive. تمام فایل‌های بایگانی‌شده قبلی حذف شده و مجدداً بازسازی می‌شوند؛ مگر اینکه از گزینه -n یا -m استفاده شده باشد، یا اینکه آزمایش یک زیرآزمایش باشد.
تنها فایل‌های منبع، اشیاء کامپایل‌شده (Object) و فایل‌های اطلاعات اشکال‌زدایی را بایگانی می‌کند که نام مسیر کامل آن‌ها با عبارت باقاعده استاندارد پازیکس (regex) تطابق داشته باشد.
فقط آزمایش نام‌برده‌شده را بایگانی می‌کند و فرآیندها یا آزمایش‌های زیرمجموعه آن را نادیده می‌گیرد.
جلوگیری از چاپ هشدارها در خروجی خطای استاندارد (stderr). هشدارها در فایل .archive درون دایرکتوری آزمایش ثبت می‌شوند و در خروجی دستور gprofng display text قابل مشاهده خواهند بود.
تعیین مکان یک بایگانی مشترک از طریق مسیر نسبی (path). بایگانی مشترک پوشه‌ای حاوی فایل‌های بایگانی‌شده است و اگر وجود نداشته باشد ایجاد می‌شود. فایل‌ها در این دایرکتوری ذخیره شده و پیوندی نمادین به آن‌ها در بایگانی آزمایش ثبت می‌شود.
تعیین نحوه بایگانی فایل‌های منبع. مقادیر مجاز برای آرگومان selection عبارتند از:
هیچ فایل منبعی بایگانی نشود.
تمام فایل‌های منبع و اشیائی که یافت شوند بایگانی شوند.
فقط فایل‌های منبع و اشیائی بایگانی شوند که برای توابع مرتبط با آن‌ها داده‌ای در آزمایش ثبت شده باشد و در دسترس باشند.

به‌طور پیش‌فرض، فایل‌های منبع برنامه در دایرکتوری آزمایش بایگانی نمی‌شوند. در صورت استفاده از گزینه -s all یا -s used, سورس‌ها و فایل‌های شیء بایگانی می‌شوند. این گزینه‌ها تضمین می‌کنند که فایل‌های منبع در آزمایش حفظ شوند؛ حتی اگر کدهای منبع اصلی تغییر کنند یا بعداً دردسترس نباشند.

چنانچه فایل‌های بایگانی پیدا نشوند، می‌توانید دستور addpath یا pathmap (یا هر دو) را در فایل .er.rc درج کنید تا مسیر فایل‌های ناموجود مشخص شود.

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

  • اگر برنامه در حال پروفایل‌بندی پیش از پایان عادی کار خود لغو یا متوقف شود.
  • اگر یک فرآیندِ در حال اجرا (Running Process) پروفایل شود.
  • اگر فرآیند بایگانی در زمان پروفایل‌بندی صراحتاً غیرفعال شده باشد؛ برای مثال با استفاده از گزینه -a off در دستور gprofng collect app.

در این حالت‌ها، باید ابزار gprofng archive را به صورت دستی و الزاماً روی همان سیستمی که داده‌های آزمایش ثبت شده‌اند اجرا کنید.

بایگانی داده‌های آزمایش حین جمع‌آوری اطلاعات، به‌ویژه در برنامه‌هایی با فرآیندهای فرزند پرشمار، بار پردازشی بالایی تحمیل می‌کند. در چنین وضعیتی، راهکار کارآمدتر این است که هنگام گردآوری داده‌ها گزینه -a off را به کار ببرید. پس از اتمام اجرای برنامه، می‌توانید با اجرای دستور همراه با گزینه -s all داده‌ها را بایگانی کنید. این کار تمام فایل‌های اجرایی و منبع را در آزمایش ذخیره خواهد کرد.

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

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

برخی از برنامه‌های جاوا اشیاء اشتراکی را درون فایل‌های jar نگهداری می‌کنند. این اشیاء به‌طور پیش‌فرض بایگانی نمی‌شوند. برای بایگانی اشیاء درون فایل‌های jar، دستور addpath را در فایل .er.rc قرار دهید. این دستور باید مسیر فایل jar را همراه با نام خود فایل مشخص سازد. فایل .er.rc باید در پوشه خانگی کاربر یا دایرکتوری والد آزمایش ذخیره شود.

به‌طور پیش‌فرض، فایل‌های منبع برنامه در آزمایش بایگانی نمی‌شوند. با اجرای دستور gprofng archive همراه با گزینه -s all یا -s used روی هر آزمایش، می‌توانید کدهای منبع را در آزمایش ذخیره کنید.

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

اگر چند آرگومان -s در خط فرمان مشخص شود، آخرین آرگومان اعمال خواهد شد. چنانچه -s هم در خط فرمان وارد شود و هم در متغیر محیطی مقداردهی شده باشد، مقدار تعیین‌شده در متغیر محیطی اولویت خواهد داشت.

توجه داشته باشید که اگر بایگانی خودکار فایل‌های منبع حین گردآوری داده‌ها با استفاده از متغیر GPROFNG_ARCHIVE یا گزینه‌های -a src و -a usedsrc فعال شده باشد، توصیه می‌شود با اجرای دستور gprofng archive -s all یا gprofng archive -s used اطمینان یابید که فایل‌های منبع به‌درستی شناسایی و ذخیره شده‌اند.

  • گزینه‌های -d و -r ناسازگار با یکدیگر بوده و نمی‌توانند هم‌زمان استفاده شوند.
  • هنگام استفاده از گزینه -d یا -r, می‌توانید متغیر محیطی GPROFNG_ARCHIVE_COMMON_DIR را برای تعیین مکان بایگانی مشترک به کار ببرید. این قابلیت هنگام نوشتن اسکریپت‌های پروفایل‌بندی برنامه بسیار سودمند است.
  • اگر بیش از یک گزینه -s در خط فرمان مشخص شود یا در متغیر محیطی تعریف گردد، مقادیر تمام آن‌ها باید یکسان باشد؛ در غیر این صورت gprofng archive با خطا متوقف می‌شود.
  • این ابزار توانایی پردازش آزمایش‌های ضبط‌شده با نسخه‌های قدیمی‌تر را ندارد. اجرای آن روی چنین آزمایش‌هایی پیام هشدار چاپ خواهد کرد. همواره از نسخه‌ای از gprofng archive استفاده کنید که آزمایش با همان نسخه ضبط شده است.

gprofng(1), gprofng-collect-app(1), gprofng-display-html(1), gprofng-display-src(1), gprofng-display-text(1)

راهنمای کاربری ابزار gprofng در قالب کتابچه راهنمای Texinfo نگهداری می‌شود. در صورت نصب بودن برنامه‌های info و gprofng, با دستور زیر می‌توانید به این مستندات دسترسی داشته باشید:

info gprofng

حق نشر © 2022-2026 بنیاد نرم‌افزارهای آزاد (Free Software Foundation, Inc.)

اجازه نسخه‌برداری، توزیع و/یا تغییر این سند تحت شرایط مجوز مستندات آزاد گنو (GNU Free Documentation License)، نسخه ۱.۳ یا هر نسخه جدیدتر منتشرشده توسط بنیاد نرم‌افزارهای آزاد داده می‌شود؛ بدون بخش‌های تغییرناپذیر، بدون متون روی جلد و بدون متون پشت جلد. نسخه‌ای از این مجوز در بخشی با عنوان "GNU Free Documentation License" قرار گرفته است.

2026-08-11 binutils-2.47