نام (NAME)

gcov-tool - ابزار پردازش و مدیریت فایلهای داده پوشش کد gcda آفلاین

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

gcov-tool [-v|--version] [-h|--help]

gcov-tool merge [merge-options] directory1 directory2
[-o|--output directory]
[-v|--verbose]
[-w|--weight w1,w2]

gcov-tool merge-stream [merge-stream-options] [file]
[-v|--verbose]
[-w|--weight w1,w2]

gcov-tool rewrite [rewrite-options] directory
[-n|--normalize long_long_value]
[-o|--output directory]
[-s|--scale float_or_simple-frac_value]
[-v|--verbose]

توضیحات (DESCRIPTION)

دستور gcov-tool ابزاری آفلاین برای پردازش فایل‌های پروفایل پوشش کد gcda مربوط به gcc است.

نسخه فعلی gcov-tool از قابلیت‌های زیر پشتیبانی می‌کند:

ادغام دو مجموعه پروفایل با اعمال ضریب وزنی (weights).
خواندن جریانی از پروفایل‌ها به همراه نام فایل‌های مربوطه و ادغام آن با مجموعه‌ای از پروفایل‌ها با اعمال ضریب وزنی.
خواندن یک مجموعه از پروفایل و بازنویسی محتوای آن. می‌توان مقادیر شمارنده‌ها را مقیاس‌بندی (scale) یا نرمال‌سازی (normalize) کرد.

نمونه‌هایی از موارد کاربرد این ابزار عبارتند از:

جمع‌آوری پروفایل‌ها برای مجموعه‌های مختلف ورودی، و استفاده از این ابزار برای ادغام آنها. می‌توان ضریب وزنی را برای در نظر گرفتن اهمیت نسبی هر ورودی مشخص کرد.
جمع‌آوری پروفایل‌ها از سیستم‌های مقصد فاقد سیستم‌فایل (محیط‌های مستقل یا freestanding). ادغام پروفایل‌های جمع‌آوری‌شده با پروفایل‌های متناظر موجود در سیستم میزبان. می‌توان وزن را برای تعیین اهمیت نسبی هر ورودی مشخص نمود.
بازنویسی پروفایل پس از حذف زیرمجموعه‌ای از فایل‌های gcda، ضمن حفظ یکپارچگی خلاصه (summary) و هیستوگرام (histogram).
همچنین می‌توان از آن برای اشکال‌زدایی کد libgcov استفاده کرد، زیرا این ابزار اکثر کدهای خود را با کتابخانه زمان اجرا به اشتراک می‌گذارد.

توجه داشته باشید که در عملیات ادغام، پروفایل ایجادشده به‌صورت آفلاین ممکن است مقادیر اندک متفاوتی نسبت به پروفایل ادغام‌شده آنلاین داشته باشد. در اینجا فهرستی از تفاوت‌های معمول آورده شده است:

تفاوت هیستوگرام: این ابزار آفلاین پس از ادغام شمارنده‌ها، هیستوگرام را دوباره محاسبه می‌کند؛ بنابراین هیستوگرام حاصل دقیق است. ادغام آنلاین این قابلیت را ندارد -- هیستوگرام از دو هیستوگرام ادغام می‌شود و نتیجه یک تقریب است.
تفاوت چکسام خلاصه (summary checksum): چکسام خلاصه از عملیات CRC32 استفاده می‌کند. مقدار آن به ترتیب پیوند لیست اشیای gcov-info بستگی دارد. این ترتیب در gcov-tool با ترتیب در ادغام آنلاین متفاوت است؛ بنابراین انتظار می‌رود چکسام‌های متفاوتی حاصل شود. این موضوع اهمیتی ندارد زیرا کامپایلر از این چکسام در جایی استفاده نمی‌کند.
تفاوت مقادیر شمارنده پروفایل مقادیر (value profile): برخی مقادیر شمارنده برای پروفایل مقدار وابسته به زمان اجرا هستند، مانند آدرس‌های هیپ (heap). مشاهده مقداری تفاوت در این نوع شمارنده‌ها کاملاً طبیعی است.

گزینهها (OPTIONS)

-h
--help: نمایش راهنمای استفاده از gcov-tool (در خروجی استاندارد) و خروج بدون انجام هرگونه پردازش دیگر.
-v
--version: نمایش شماره نسخه gcov-tool (در خروجی استاندارد) و خروج بدون انجام هرگونه پردازش دیگر.
merge: ادغام دو پوشه پروفایل.

-o directory
--output directory: تنظیم پوشه خروجی پروفایل. نام پوشه خروجی پیش‌فرض merged_profile است.
-v
--verbose: فعال‌سازی حالت پرگویی (verbose).
-w w1,w2
--weight w1,w2: تنظیم وزن‌های ادغام به ترتیب برای directory1 و directory2. وزن پیش‌فرض برای هر دو مقدار 1 است.

merge-stream: جمع‌آوری پروفایل‌ها با نام فایل‌های مربوطه از یک جریان داده gcfn و gcda. جریان داده از فایل مشخص‌شده توسط file یا از stdin خوانده می‌شود. پروفایل‌ها با پروفایل‌های مرتبط در سیستم‌فایل میزبان ادغام می‌شوند. وزن‌های اختیاری نیز هنگام ادغام پروفایل‌ها اعمال می‌گردند.
برای تولید یک جریان داده gcfn و gcda در سیستم مقصد، لطفاً به توابع "__gcov_filename_to_gcfn()" و "__gcov_info_to_gcda()" تعریف‌شده در "#include <gcov.h>" مراجعه کنید.

-v
--verbose: فعال‌سازی حالت پرگویی (verbose).
-w w1,w2
--weight w1,w2: تنظیم وزن‌های ادغام به ترتیب برای پروفایل‌های برگرفته از جریان داده gcfn و gcda و پروفایل‌های متناظر در سیستم‌فایل میزبان. وزن پیش‌فرض برای هر دو مقدار 1 است.

rewrite: خواندن پوشه پروفایل مشخص‌شده و بازنویسی در یک پوشه جدید.

-n long_long_value
--normalize <long_long_value>: نرمال‌سازی پروفایل. مقدار مشخص‌شده، بیشینه مقدار شمارنده در پروفایل جدید است.
-o directory
--output directory: تنظیم پوشه خروجی پروفایل. نام خروجی پیش‌فرض rewrite_profile است.
-s float_or_simple-frac_value
--scale float_or_simple-frac_value: مقیاس‌بندی شمارنده‌های پروفایل. مقدار مشخص‌شده می‌تواند به‌صورت یک مقدار اعشاری ممیز شناور (floating point) یا کسری ساده مانند 1، 2، 2/3 و 5/3 باشد.
-v
--verbose: فعال‌سازی حالت پرگویی (verbose).

overlap: محاسبه امتیاز همپوشانی (overlap score) میان دو پوشه پروفایل مشخص‌شده. امتیاز همپوشانی بر اساس پروفایل‌های کمان (arc profiles) محاسبه می‌شود. این امتیاز به‌صورت مجموع min (p1_counter[i] / p1_sum_all, p2_counter[i] / p2_sum_all) برای تمام شمارنده‌های کمان i تعریف می‌شود، که در آن p1_counter[i] و p2_counter[i] دو شمارنده منطبق بر هم هستند و p1_sum_all و p2_sum_all به ترتیب مجموع مقادیر شمارنده‌ها در پروفایل ۱ و پروفایل ۲ می‌باشند.

-f
--function: چاپ امتیاز همپوشانی در سطح تابع.
-F
--fullname: چاپ نام کامل فایل gcda.
-h
--hotonly: فقط چاپ اطلاعات برای اشیاء/توابع پرکاربرد (hot).
-o
--object: چاپ امتیاز همپوشانی در سطح شیء (object).
-t float
--hot_threshold <float>: تنظیم آستانه برای مقدار شمارنده پرکاربرد (hot).
-v
--verbose: فعال‌سازی حالت پرگویی (verbose).

همچنین ببینید (SEE ALSO)

gpl(7)، gfdl(7)، fsf-funding(7)، gcc(1)، gcov(1) و مدخل Info برای gcc.

حق نشر (COPYRIGHT)

اجازه کپی، توزیع و/یا تغییر این سند تحت شرایط «مجوز مستندات آزاد گنو» (GNU Free Documentation License)، نسخه ۱.۳ یا هر نسخه بعدی منتشرشده توسط بنیاد نرم‌افزارهای آزاد اعطا می‌شود؛ با بخش‌های تغییرناپذیر «GNU General Public License» و «Funding Free Software»، متون روی جلد به شرح (a) (به زیر مراجعه کنید)، و متون پشت جلد به شرح (b) (به زیر مراجعه کنید). نسخه‌ای از این مجوز در صفحه راهنمای gfdl(7) آمده است.

(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.