.\" Man page generated from reStructuredText .\" by the Docutils 0.23 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "GENHTML" "1" "2026-07-07" "2.5" "LCOV" .SH "نام (NAME)" genhtml \- مستندات genhtml .SH "نام (NAME)" .INDENT 0.0 .TP .B genhtml تولید نمای HTML از فایل‌های داده‌های پوشش LCOV \- شامل تحلیل تفاضلی پوشش، دسته‌بندی بر اساس قدمت و نویسنده، و گزینه‌های گوناگون مصورسازی. .UNINDENT .SH "خلاصه دستور (SYNOPSIS)" .INDENT 0.0 .INDENT 3.5 .sp .EX genhtml [ \-h | \-\-help ] [ \-\-version ] [ \-q | \-\-quiet ] [ \-v | \-\-verbose ] [ \-\-debug ] [ \-\-validate ] [ \-s | \-\-show\-details ] [ \-f | \-\-frames ] [ \-b | \-\-baseline\-file baseline\-file\-pattern ] [ \-o | \-\-output\-directory output\-directory ] [ \-\-header\-title banner ] [ \-\-footer string ] [ \-t | \-\-title title ] [ \-d | \-\-description\-file description\-file ] [ \-k | \-\-keep\-descriptions ] [ \-c | \-\-css\-file css\-file ] [ \-p | \-\-prefix prefix ] [ \-\-no\-prefix ] [ \-\-build\-directory directory ] [ \-\-source\-directory dirname ] [ \-\-no\-source ] [ \-\-no\-html ] [ \-\-num\-spaces num ] [ \-\-highlight ] [ \-\-legend ] [ \-\-html\-prolog prolog\-file ] [ \-\-html\-epilog epilog\-file ] [ \-\-html\-extension extension ] [ \-\-html\-gzip ] [ \-\-sort\-tables ] [ \-\-no\-sort ] [ \-\-function\-coverage ] [ \-\-no\-function\-coverage ] [ \-\-branch\-coverage ] [ \-\-no\-branch\-coverage ] [ \-\-mcdc\-coverage ] [ \-\-demangle\-cpp [ param ] ] [ \-\-msg\-log [ log_file_name ] ] [ \-\-ignore\-errors errors ] [ \-\-expect\-message\-count message_type=expr[,message_type=expr..] ] [ \-\-keep\-going ] [ \-\-config\-file config\-file ] [ \-\-profile [ profile\-file ] ] [ \-\-history\-script callback ] [ \-\-rc keyword = value ] [ \-\-precision num ] [ \-\-missed ] [ \-\-merge\-aliases ] [ \-\-suppress\-aliases ] [ \-\-forget\-test\-names ] [ \-\-dark\-mode ] [ \-\-baseline\-title title ] [ \-\-baseline\-date date ] [ \-\-current\-date date ] [ \-\-diff\-file diff\-file ] [ \-\-annotate\-script script ] [ \-\-context\-script script ] [ \-\-criteria\-script script ] [ \-\-version\-script script ] [ \-\-resolve\-script script ] [ \-\-select\-script script ] [ \-\-simplify\-script script ] [ \-\-unreachable\-script module ] [ \-\-checksum ] [ \-\-fail\-under\-branches percentage ] [ \-\-fail\-under\-lines percentage ] [ \-\-new\-file\-as\-baseline ] [ \-\-elide\-path\-mismatch ] [ \-\-synthesize\-missing ] [ \-\-date\-bins day[,day,...] ] [ \-\-date\-labels string[,string,...] ] [ \-\-show\-owners [ all ] ] [ \-\-show\-noncode ] [ \-\-show\-zero\-columns ] [ \-\-show\-navigation ] [ \-\-show\-proportions ] [ \-\-simplified\-colors ] [ \-\-hierarchical ] [ \-\-flat ] [ \-\-filter filters ] [ \-\-include glob_pattern ] [ \-\-exclude glob_pattern ] [ \-\-erase\-functions regexp_pattern ] [ \-\-substitute regexp_pattern ] [ \-\-omit\-lines regexp_pattern ] [ \-\-parallel | \-j [ integer ] ] [ \-\-memory integer_num_Mb ] [ \-\-tempdir dirname ] [ \-\-preserve ] [ \-\-save ] [ \-\-sort\-input ] [ \-\-serialize serialize_output_file ] tracefile_pattern(s) .EE .UNINDENT .UNINDENT.SH "توضیحات (DESCRIPTION)" .sp دستور \fBgenhtml\fP یک نمای HTML از داده‌های پوشش (coverage) موجود در فایل‌های ردگیری (tracefiles) ابزارهای \fBgeninfo\fP و \fBlcov\fP که از طریق الگو(های) تطبیق سراسری (glob) \fItracefile_pattern\fP یافته می‌شوند ایجاد می‌کند. برای شرح قالب tracefile به \fBgeninfo(1) \%\fP مراجعه کنید. .sp قابلیت‌ها شامل موارد زیر است: .INDENT 0.0 .IP \(bu 2 مقایسهٔ پوشش تفاضلی در برابر داده‌های پوشش مبنا (baseline) .IP \(bu 2 حاشیه‌نویسی گزارش‌ها با اطلاعات تاریخ و مالک («دسته‌بندی» یا “binning”) .UNINDENT .sp مفاهیم اساسی پوشش تفاضلی و دسته‌بندی بر اساس تاریخ/مالک در مقاله‌ای به نشانی \fIhttps://arxiv.org/abs/2008.07947\fP شرح داده شده است. .SS "پوشش تفاضلی (Differential coverage)" .sp پوشش تفاضلی دو نسخه از کد منبع \- نسخهٔ مبنا (baseline) و نسخهٔ جاری \- و نیز نتایج پوشش هر یک را مقایسه می‌کند تا کد را به دسته‌های مختلف تقسیم‌بندی کند. .sp برای ایجاد گزارش پوشش تفاضلی، \fBgenhtml\fP به موارد زیر نیاز دارد: .INDENT 0.0 .IP 1. 3 یک یا چند \fIbaseline\-files\fP که از طریق \fB\-\-baseline\-file\fP مشخص شده باشند، و .IP 2. 3 یک فایل وصله (patch) با قالب یکپارچه (unified format) که با \fB\-\-diff\-file\fP مشخص شده باشد\&. .UNINDENT .sp هر دو مورد \fItracefile_pattern\fP و \fIbaseline\-file\fP به عنوان الگوهای تطبیق glob در نظر گرفته می‌شوند که با یک یا چند فایل تطبیق می‌یابند. .sp تفاوت پوشش بین مجموعهٔ \fItracefiles\fP و \fIbaseline\-files\fP، خط‌به‌خط بر اساس تغییرات در ۲ جنبه دسته‌بندی می‌شود: .INDENT 0.0 .IP 1. 3 \fBنتایج پوشش آزمون (Test coverage results)\fP: یک خط کد می‌تواند آزموده‌شده (1)، آزموده‌نشده (0) یا استفاده‌نشده (#) باشد. یک خط استفاده‌نشده خطی از کد منبع است که هیچ دادهٔ پوشش مرتبطی ندارد؛ برای مثال به دلیل یک دستور غیرفعال #ifdef. .IP 2. 3 \fBتغییرات کد منبع (Source code changes)\fP: یک خط می‌تواند بدون تغییر، افزوده‌شده (+ =>) یا حذف‌شده (=> \-) باشد. توجه داشته باشید که قالب diff\-file مورد استفاده توسط \fBgenhtml\fP تغییرات در خطوط را به صورت حذف خط قدیمی و افزودن خط جدید گزارش می‌کند. .UNINDENT .sp در ادامه ۱۲ دستهٔ حاصل بر اساس اولویت مرتب شده‌اند (با این فرض که بررسی کد آزموده‌نشده مهم‌تر از کد آزموده‌شده است و کد جدید اولویت بالاتری نسبت به کد قدیمی دارد): .INDENT 0.0 .TP \fBUNC\fP Uncovered New Code (کد جدید پوشش‌نیافته) (+ => 0): کد تازه افزوده‌شده آزموده نشده است. .TP \fBLBC\fP Lost Baseline Coverage (از دست رفتن پوشش مبنا) (1 => 0): کد بدون تغییر دیگر آزموده نمی‌شود. .TP \fBUIC\fP Uncovered Included Code (کد گنجانده‌شدهٔ پوشش‌نیافته) (# => 0): کدی که پیش‌تر استفاده نشده بود، آزموده نشده است. .TP \fBUBC\fP Uncovered Baseline Code (کد مبنای پوشش‌نیافته) (0 => 0): کد بدون تغییر، قبلاً آزموده نشده بود و اکنون نیز آزموده نشده است. .TP \fBGBC\fP Gained Baseline Coverage (کسب پوشش مبنا) (0 => 1): کد بدون تغییر اکنون آزموده شده است. .TP \fBGIC\fP Gained Included Coverage (کسب پوشش گنجانده‌شده) (# => 1): کدی که پیش‌تر استفاده نشده بود، اکنون آزموده شده است. .TP \fBGNC\fP Gained New Coverage (کسب پوشش جدید) (+ => 1): کد تازه افزوده‌شده آزموده شده است. .TP \fBCBC\fP Covered Baseline Code (کد مبنای پوشش‌یافته) (1 => 1): کد بدون تغییر قبلاً آزموده شده بود و همچنان آزموده می‌شود. .TP \fBEUB\fP Excluded Uncovered Baseline (مبنای پوشش‌نیافتهٔ مستثنی‌شده) (0 => #): کدی که قبلاً آزموده نشده بود، اکنون استفاده‌نشده است. .TP \fBECB\fP Excluded Covered Baseline (مبنای پوشش‌یافتهٔ مستثنی‌شده) (1 => #): کدی که قبلاً آزموده شده بود، اکنون استفاده‌نشده است. .TP \fBDUB\fP Deleted Uncovered Baseline (مبنای پوشش‌نیافتهٔ حذف‌شده) (0 => \-): کدی که قبلاً آزموده نشده بود، حذف شده است. .sp نکته: از آنجا که این خطوط در نسخهٔ جاری کد منبع نمایش داده نمی‌شوند، تنها در جدول خلاصهٔ طبقه‌بندی نشان داده می‌شوند. .TP \fBDCB\fP Deleted Covered Baseline (مبنای پوشش‌یافتهٔ حذف‌شده) (1 => \-): کدی که قبلاً آزموده شده بود، حذف شده است. .sp نکته: از آنجا که این خطوط در نسخهٔ جاری کد منبع نمایش داده نمی‌شوند، تنها در جدول خلاصهٔ طبقه‌بندی نشان داده می‌شوند. .UNINDENT .sp گزارش پوشش تفاضلی، بخش‌های دسته‌بندی‌شده را در نمای کد منبع با رنگ‌هایی منحصربه‌فرد برای هر یک رنگ‌آمیزی می‌کند. می‌توانید از گزینهٔ \fB\-\-simplified\-colors\fP استفاده کنید تا در عوض، از یک رنگ برای کد «پوشش‌یافته» (covered) و از رنگی دیگر برای کد «بدون پوشش» (uncovered) استفاده شود..SS دسته‌بندی تاریخ و مالک (Date and owner binning) .sp \fBدسته‌بندی تاریخ\fP گزارش‌های پوشش را با اطلاعات مربوط به زمان آخرین تغییر نشانه‌گذاری می‌کند تا کدهای تازه اضافه‌شده یا تغییر‌یافته‌ای را که آزمایش نشده‌اند، از کدهای قدیمی‌تر و فرضا پایداری که آن‌ها هم آزمایش نشده‌اند متمایز سازد. \fBدسته‌بندی مالک\fP نشانه‌گذاری‌هایی برای مشخص کردن پدیدآورندهٔ تغییرات اضافه می‌کند. .sp هم گزارش سن کد و هم مالکیت آن می‌تواند برای تقویت تلاش‌های تیمی در حفظ انضباط پوشش آزمون به کار رود؛ این کار با برجسته‌سازی کاستی‌های پوشش در کدهای اخیراً تغییریافته، حتی در غیاب داده‌های پایهٔ پوشش (baseline coverage) انجام می‌شود. .sp برای فعال‌سازی دسته‌بندی تاریخ و مالک، باید از گزینهٔ \fB\-\-annotate\-script\fP جهت تعیین اسکریپتی که اطلاعات سن و مالکیت خطوط کد منبع را ارائه می‌دهد استفاده شود. .sp برای هر خط از منبع، سن برابر با بازهٔ زمانی از آخرین تاریخ تغییر است و مالک، هویت کاربری است که مسئول آخرین تغییر در آن خط بوده است. .sp مجموع کل پوشش خطوط و شمارش‌های هر یک از ۱۲ ردهٔ طبقه‌بندی برای هر یک از بازه‌های سنی مشخص‌شده گردآوری می‌شوند (گزینهٔ \fB\-\-date\-bins\fP را در زیر ببینید). .SS قراردادهای اسکریپت (Script conventions) .sp برخی از گزینه‌های \fBgenhtml\fP نام یک اسکریپت یا ابزار خارجی را به عنوان آرگومان دریافت می‌کنند. این اسکریپت‌ها سپس به عنوان بخشی از تابع مربوطه اجرا می‌شوند. این موارد شامل گزینه‌های زیر است: .INDENT 0.0 .INDENT 3.5 .sp .EX \-\-annotate\-script \-\-context\-script \-\-criteria\-script \-\-history\-script \-\-resolve\-script \-\-select\-script \-\-simplify\-script \-\-unreachable\-script \-\-version\-script .EE .UNINDENT .UNINDENT .sp با وجود این‌که هر اسکریپت عملکرد مجزایی انجام می‌دهد، جنبه‌های مشترکی در شیوهٔ مدیریت این گزینه‌ها وجود دارد: .INDENT 0.0 .IP 1. 3 اگر نام اسکریپت فراخوانی (callback) به \fB\&.pm\fP ختم شود، اسکریپت یک ماژول Perl در نظر گرفته می‌شود. .sp یک ماژول Perl ممکن است نسبت به یک اسکریپت خارجی مزایای عملکردی ارائه دهد، زیرا تنها یک بار کامپایل شده و در مفسر بارگذاری می‌شود و می‌تواند وضعیت درونی را بارگذاری و حفظ کند. .sp انتظار می‌رود این ماژول متد \(lqnew\(rq را ارائه دهد که با نام اسکریپت و پارامترهای اسکریپت (در صورت وجود) به عنوان آرگومان فراخوانی می‌شود. انتظار می‌رود شیئی را بازگرداند که چندین متد استاندارد را پیاده‌سازی می‌کند: .sp \fB$callback_obj =\fP \fIpackagename\fP \fB\->new(perl_module_file, args);\fP .INDENT 3.0 .TP .B version\-script \fB$version = $callback_obj\->extract_version($source_file_ename);\fP .sp \fB$match = $version\->check_version($old_version, $new_version, $source_file_name);\fP .sp در صورتی که کلیدهای نگارش به همان فایل اشاره داشته باشند، انتظار می‌رود \fI$match\fP برابر با ۱ (true) و در غیر این صورت ۰ (false) باشد. .TP .B \fI$version\fP رشته‌ای است که یک شناسهٔ یکتا از نگارش خاصی از فایل را نشان می‌دهد. .UNINDENT .sp پیاده‌سازی‌های نمونه را در \fB*$|TOOL_NAME|_HOME/share/lcov/support\-scripts/gitversion.pm\fP و \fB$|TOOL_NAME|_HOME/share/lcov/support\-scripts/getp4version.pm\fP\& ببینید. .INDENT 3.0 .TP .B annotate\-script \fB($status, $array) = $callback_obj\->annotate($source_file_name);\fP .sp که در آن: .INDENT 7.0 .TP .B \fI$status\fP در صورت موفقیت دستور، ۰ و در غیر این صورت مقداری غیر صفر است. \fI$status\fP به همان شیوه‌ای که کد بازگشتی حاصل از \(lqsystem(..)\(rq عمل می‌کند تفسیر می‌شود. .TP .B \fI$array\fP فهرستی از داده‌های خط به صورت زیر است: .sp \fB[$text, $abbrev, $full_name, $when, $changelist]\fP\&. .UNINDENT .sp و: .INDENT 7.0 .TP .B \fI$text\fP متن کد منبع خط مربوطه است (بدون کاراکتر خط جدید پایانی). .TP .B \fI$abbrev\fP «نام مخفف نویسنده» مسئول این خط کد است. این نامی است که در جدول‌های گوناگون HTML استفاده خواهد شد. برای مثال، جهت رعایت ایجاز یا خوانایی، ممکن است بخواهید دامنه را از نام توسعه‌دهندگانی که درون سازمان شما هستند حذف کنید. اگر نویسندهٔ مرتبطی وجود نداشته باشد، مقدار باید \fI\(dqNONE\(dq\fP باشد. .TP .B \fI$full_name\fP «نام کامل نویسنده» است که در نکات راهنمای (tooltips) نشانه‌گذاری استفاده می‌شود. مدخل \fIgenhtml_annotate_tooltip\fP را در \fBlcovrc(5) \%\fP\& ببینید. اگر نام کامل و نام مخفف یکسان باشند، \fI$fullname\fP می‌تواند \fIundef\fP باشد. .TP .B \fI$when\fP مهر زمانی مرتبط با جدیدترین ویرایش خط مربوطه است و در صورت عدم وجود زمان مرتبط، می‌تواند برابر با \fI\(dqNONE\(dq\fP باشد. .TP .B \fI$changelist\fP شناسهٔ ثبت (commit) مرتبط با جدیدترین تغییر در این خط است، یا در صورتی که ثبتی وجود نداشته باشد، \fI\(dqNONE\(dq\fP خواهد بود. .UNINDENT .UNINDENT .sp پیاده‌سازی‌های نمونه را در \fB$|TOOL_NAME|_HOME/share/lcov/support\-scripts/gitblame.pm\fP و \fB$|TOOL_NAME|_HOME/share/lcov/support\-scripts/p4annotate.pm\fP\& ببینید. .INDENT 3.0 .TP .B context\-script \fB$hash = $callback_obj\->context();\fP .sp که در آن \fI$hash\fP ارجاعی به یک درهم‌سازی (hash) از جفت‌های کلید/مقدار است که برای شما معنی‌دار هستند. این داده در پایگاه‌دادهٔ \fIprofile\fP ذخیره می‌شود. برای اطلاعات بیشتر بخش \(lqprofile\(rq را در \fBlcovrc(5) \%\fP ببینید. .sp اگر فراخوانی شما یک ماژول Perl نیست \- برای مثال یک اسکریپت شل است \- آنگاه باید رشته‌ای را بازگرداند که نخستین کلمه در هر خط کلید و مابقی آن داده‌های مرتبط باشد. اگر کلیدی تکرار شود، رشته‌های دادهٔ مربوطه که با خط جدید از هم جدا شده‌اند، به یکدیگر الحاق می‌شوند. .sp اگر تنها قصد ثبت اطلاعات سیستم را دارید، احتمالاً یک فراخوانی شل کافی است. اگر می‌خواهید هرگونه اطلاعات خاص ابزار یا اطلاعات داخلی را ثبت کنید، باید یک ماژول Perl پیاده‌سازی کنید تا فراخوانی شما قادر به دسترسی به این اطلاعات باشد. .sp توجه داشته باشید که سازندهٔ (constructor) فراخوانی \fIcontext\-script\fP شما (یا هر فراخوانی دیگر) می‌تواند اقدامات اضافی لازم را انجام دهد \- برای مثال نوشتن فایل‌های اضافی، پرس‌وجو یا تعیین اطلاعات مربوط به ابزار، \fIغیره\fP. مثلاً نمونه پیاده‌سازی زیر گزینه‌ای برای افزودن نظر به فایل .info تولیدشده دارد. .sp پیاده‌سازی نمونه را در \fB$|TOOL_NAME|_HOME/share/lcov/support\-scripts/context.pm\fP\& ببینید. .TP .B criteria\-script \fB($status, $array) = $callback_obj\->check_criteria($obj_name, $type, $json);\fP .sp که در آن: .INDENT 7.0 .TP .B \fI$obj_name\fP نام فایل یا دایرکتوری منبع است، یا \(lqtop\(rq شیئی که معیارهای پوشش آن در حال بررسی است. .TP .B \fI$type\fP نوع شیء است \- یکی از موارد \fI\(dqfile\(dq\fP، \fI\(dqdirectory\(dq\fP یا \fI\(dqtop\(dq\fP\&. .TP .B \fI$json\fP داده‌های پوشش مرتبط با این شیء در قالب JSON است \- زیر را ببینید. .TP .B \fI$status\fP وضعیت بازگشتی عملیات است که مشابه وضعیت فراخوانی \fIannotate\fP شرح‌داده‌شده در بالا تفسیر می‌شود. .TP .B \fI$array\fP ارجاعی به یک فهرست (احتمالاً خالی) از رشته‌ها است که توسط genhtml گزارش خواهند شد. انتظار می‌رود این رشته‌ها توضیح دهند که چرا معیارهای پوشش ناموفق بوده‌اند. .UNINDENT .sp پیاده‌سازی‌های نمونه را در \fB$|TOOL_NAME|_HOME/share/lcov/support\-scripts/criteria.pm\fP\& ببینید. .TP .B history\-script \fB$cpu_seconds = $callback_obj\->history($element_name)\fP .sp که در آن \fI$cpu_seconds\fP زمان پیش‌بینی‌شده برای پردازش \fI$element_name\fP است یا اگر پیش‌بینی وجود نداشته باشد یا عنصر ناشناخته باشد، \fIundef\fP است. .sp نمونه پیاده‌سازی \fBscripts/history.pm\fP را ببینید، که از داده‌های \fI–profile\fP تولیدشده در اجرای پیشین \fBgenhtml\fP برای پیش‌بینی زمان مورد نیاز این بار استفاده می‌کند. .sp این پیش‌بینی ممکن است توازن بار را بهبود بخشد \- و بدین ترتیب عملکرد کلی زمان اجرا را ارتقا دهد (\fIیعنی\fP از آنجا که منتظر تکمیل یک کار سنگین و طولانی نخواهیم ماند در حالی که تمام ریسه‌های دیگر بیکار هستند). .TP .B resolve\-script \fB$newpath = $callback_obj\->resolve($source_file_name)\fP .sp که در آن \fI$newpath\fP مسیر درست به فایل منبع مشخص‌شده است، یا در صورتی که فایل منبع توسط فراخوانی پیدا نشود، \fIundef\fP خواهد بود. .TP .B simplify\-script \fB$new_func_name = $callback_obj\->simplify($orig_func_name)\fP .sp که در آن \fI$new_func_name\fP نام تابعی است که در جدول جزئیات تابع ظاهر می‌شود و \fI$orig_func_name\fP نام تابع (احتمالاً ساده‌سازی‌شده/demangled) موجود در پایگاه‌دادهٔ پوشش است. .sp توجه داشته باشید که نام تغییریافته تنها در جدول «جزئیات تابع» (function detail) استفاده می‌شود و اطلاعات موجود در پایگاه‌دادهٔ پوشش را تغییر نمی‌دهد. .TP .B unreachable\-script \fB$data_changed = $callback_obj\->exclude($type, $source, $summary, $testdata);\fP .sp که در آن \fI$data_changed\fP در صورتی که داده‌های پوشش در فراخوانی تغییر کرده باشد غیر صفر است، \fI$type\fP برابر با \(lqbranch\(rq یا \(lqmcdc\(rq است، \fI$source\fP یک شیء \(lqReadCurrentSource\(rq است، \fI$summary\fP خلاصهٔ پوشش در تمام موارد آزمون است، و \fI$testdata\fP داده‌های پوشش به ازای هر مورد آزمون است. .sp نمونه پیاده‌سازی \fB\&.../scripts/unreach.pm\fP را برای یک فراخوانی نمونهٔ ساده ببینید که از نشانه‌گذاری‌های کد منبع برای تعیین عبارات انشعاب و/یا شرایط MC/DC مستثنی‌شده استفاده می‌کند. برای راهنمای استفاده از اسکریپت، توضیحات بالای فایل را ببینید. .sp تجسم تحلیل‌های پیشرفته‌ترِ دسترسی‌ناپذیری آسان است. برای نمونه، می‌توان به جای تکیه بر نشانه‌گذاری کاربر، از داده‌های دسترسی‌پذیریِ کامپایلر یا ابزاری دیگر بهره برد. .sp توجه داشته باشید که فراخوانی \fI–unreachable\-script\fP باید یک ماژول Perl باشد. برخلاف سایر فراخوانی‌ها، اسکریپت‌های عمومی پشتیبانی نمی‌شوند. .UNINDENT .IP 2. 3 گزینه می‌تواند به عنوان یک رشتهٔ منفردِ جداشده با \fIsplit_char\fP مشخص شود که به کلمات تقسیم می‌شود (به \fBlcovrc(5) \%\fP مراجعه کنید)، یا به صورت فهرستی از آرگومان‌ها. خط فرمان حاصل برای اجرا به یک مفسر شل فرستاده می‌شود. خط فرمان شامل مسیر اسکریپت و به دنبال آن پارامترهای اختیاری اضافی است که با فاصله از هم جدا شده‌اند. در صورتی که مسیر اسکریپت یا هر یک از پارامترها حاوی فاصله یا نویسه‌های ویژهٔ شل باشد، باید دقت کافی در نقل‌قول‌گذاری مناسب به کار رود. .sp توجه داشته باشید که فراخوانی‌های ماژول باید از طریق متد \(lqlist\(rq فراخوانی شوند: آن‌ها نمی‌توانند به عنوان یک فایل اجرایی با مجموعه‌ای از آرگومان‌های جداشده با فاصله فراخوانی شوند. .sp جهت سهولت: ماژول فراخوانی شما ممکن است نیاز به پیاده‌سازی \(lqsplit_char\(rq اختصاصی خود داشته باشد تا بتوانید بدون تداخل با سازوکار جداسازی genhtml، چندین پارامتر را به فراخوانی ارسال کنید. .IP 3. 3 اگر یک گزینه چندین بار مشخص شود، پارامترها تفکیک \fIنمی‌شوند\fP، بلکه صرفاً برای ساخت خط فرمان به هم متصل می‌گردند \- مثال‌های زیر را ببینید. .sp جهت سادگی و درک آسان‌تر: خط فرمان شما باید تمام آرگومان‌ها را به‌طور جداگانه یا همگی را به عنوان فهرستی جداشده با کاما منتقل کند \- نه ترکیبی از هر دو. .IP 4. 3 دستور \fBgenhtml\fP هر پارامتر اضافی مشخص‌شده از طریق آرگومان‌های گزینه را بین مسیر اسکریپت و پارامترهای مورد نیاز تابعِ اسکریپت قرار می‌دهد. .UNINDENT .sp مثال: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5.sp .EX genhtml \-\-annotate\-script /bin/script.sh \-\-annotate\-script arg0 ... .EE .UNINDENT .UNINDENT .sp منجر به همان فراخوانی بازگشتی (callback) می‌شود مانند: .INDENT 0.0 .INDENT 3.5 .sp .EX genhtml \-\-annotate\-script \(dq/bin/script.sh arg0\(dq ... .EE .UNINDENT .UNINDENT .sp یا .INDENT 0.0 .INDENT 3.5 .sp .EX genhtml \-\-annotate\-script /bin/script.sh,arg0 ... .EE .UNINDENT .UNINDENT .sp توجه داشته باشید که شکل نخست ارجح است. .UNINDENT .UNINDENT .sp فراخوانی بازگشتی حاصل از \fBgenhtml\fP این خط فرمان را اجرا می‌کند: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .EX /bin/script.sh arg0 *source_file_name* .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp به‌طور مشابه .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .EX genhtml \-\-annotate\-script */bin/myMoodule.pm* \-\-annotate\-script arg0 \-\-annotate\-script arg1 ... .EE .UNINDENT .UNINDENT .sp یا .INDENT 0.0 .INDENT 3.5 .sp .EX genhtml \-\-annotate\-script */bin/myMoodule.pm,arg0,arg1* .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp منجر به این می‌شود که \fBgenhtml\fP دستور زیر را اجرا کند: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .EX $annotateCallback = myModule\->new(arg0, arg1); .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp تا شیء کلاس مقداردهی اولیه شود \- در حالی که \fIarg0\fP و \fIarg1\fP به صورت رشته ارسال شده‌اند \- و سپس دستور زیر اجرا شود: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .EX ($status, $arrayRef) = $annotateCallback(*source_file_name*); .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp تا اطلاعات حاشیه‌نویسی (annotation) بازیابی گردد. .sp در مقابل، دستور .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .EX genhtml \-\-annotate\-script */bin/myMoodule.pm* \-\-annotate\-script arg0,arg1 ... .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp منجر به این خواهد شد که \fBgenhtml\fP شیء callback را از طریق دستور زیر مقداردهی اولیه کند: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .EX $annotateCallback = myModule\->new(\(dqarg0,arg1\(dq); .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp که در آن \(lqarg0,arg1\(rq به عنوان یک رشتهٔ منفردِ جداشده با کاما ارسال می‌شود. .sp به‌طور مشابه، دستور .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .EX genhtml \-\-annotate\-script */bin/myMoodule.pm,arg0* \-\-annotate\-script arg1 ... .EE .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp به احتمال بسیار زیاد هنگامی که genhtml تلاش می‌کند اسکریپتی به نام \fB/bin/mymodule.pm,arg0\fP را بیابد، منجر به خطا خواهد شد\&. .sp توجه داشته باشید در صورتی که گزینهٔ \fB\-\-parallel\fP مشخص شده باشد، ممکن است چندین نمونه از هر اسکریپت به‌طور هم‌زمان اجرا شوند. بنابراین هر اسکریپت یا باید بازورود (reentrant) باشد یا در صورت لزوم، سازوکار همگام‌سازی (synchronization) مورد نیاز خود را فراهم کند. .sp به‌ویژه اگر callback شما از طریق یک ماژول perl پیاده‌سازی شده باشد: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 شیء کلاس مرتبط با ماژول، یک بار (در فرایند والد) مقداردهی اولیه خواهد شد .IP \(bu 2 فراخوانی callback در فرایند فرزند (احتمالاً به‌طور هم‌زمان با سایر فرایندهای فرزند) رخ خواهد داد. .UNINDENT .sp در نتیجه: اگر callback شما نیاز دارد داده‌ها را به فرایند والد بازگرداند، لازم است سازوکار ارتباطی مناسبی را برای این کار فراهم نمایید. .UNINDENT .UNINDENT.SH "کال‌بک‌ها و اجرای موازی (CALLBACKS AND PARALLEL EXECUTION)" .sp از آنجا که ممکن است کال‌بک‌ها نیاز به ثبت داده داشته باشند \- \fIبرای مثال\fP برای گزارش خطا یا خلاصه اقدامات در زمان اجرای موازی \- ابزار \fBgenhtml\fP (و \fBlcov\fP و \fBgeninfo\fP) می‌توانند متدهای کال‌بک اختیاری خاصی را فراخوانی کنند: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fB$callback\->start()\fP .UNINDENT .sp زمانی فراخوانی می‌شود که فرایند فرزند شروع به اجرا می‌کند. از این متد می‌توان برای ثبت وضعیت اولیه استفاده کرد \- \fIبرای مثال\fP برای صفر کردن شمارش رویدادها در این فرزند. این متد اختیاری است. .INDENT 0.0 .IP \(bu 2 \fBmy $data = $callback\->save()\fP .UNINDENT .sp زمانی فراخوانی می‌شود که پردازش کامل شده باشد، دقیقاً پیش از خروج فرایند فرزند. متغیر اسکالر \fI$data\fP که توسط متد \fI$callback\fP\fB\->save()\fP شما بازگردانده شده است، هنگام پایان کار فرایند فرزند (reap شدن) به متد \fI$callback\fP\fB\->restore()\fP تحویل داده می‌شود. .INDENT 0.0 .IP \(bu 2 \fB$callback\->restore($data)\fP .UNINDENT .sp در فرایند والد و هنگام پایان کار فرایند فرزند فراخوانی می‌شود. \fI$data\fP داده‌ای است که هنگام فراخوانی متد \fI$callback\fP\fB\->save()\fP شما در فرزند بازگردانده شده بود. (سریال‌سازی/دی‌سریال‌سازی در پشت صحنه انجام گرفته است.) .INDENT 0.0 .IP \(bu 2 \fB$callback\->finalize()\fP .UNINDENT .sp در فرایند والد زمانی که تمام محاسبات کامل شده و والد در حال آماده‌سازی گزارش نتایج نهایی است فراخوانی می‌شود. این متد اختیاری است. .sp توجه داشته باشید که برخلاف سایر متدهای کال‌بک توصیف‌شده در این بخش، \fIfinalize()\fP هم در زمینه‌های اجرای موازی و هم سریالی فراخوانی می‌شود. .UNINDENT .UNINDENT .sp توجه داشته باشید که کال‌بک شما در صورت پیاده‌سازی \fB$callback\->save()\fP باید حتماً \fB$callback\->restore()\fP را نیز پیاده‌سازی کند\&. متدهای \fB$callback\->start()\fP و \fB$callback\->finalize()\fP اختیاری هستند: اگر پیاده‌سازی شده باشند، فراخوانی خواهند شد. .sp این متدها فقط برای کال‌بک‌هایی که به عنوان ماژول‌های Perl پیاده‌سازی شده‌اند در دسترس هستند. اگر کال‌بک شما (برای مثال) به عنوان یک اسکریپت اجرایی پیاده‌سازی شده است \- در انتقال داده بین والد/فرزند به هر شکلی که ترجیح می‌دهید آزاد هستید. .SS ملاحظات تکمیلی .sp اگر از گزینه \fB\-\-criteria\-script\fP استفاده شود، genhtml از اسکریپت مشخص‌شده برای بررسی برآورده شدن معیارهای پوشش استفاده خواهد کرد \- و در صورتی که معیارها برآورده نشوند، وضعیت خروج غیرصفر بازگردانده و پیامی را چاپ می‌کند. .sp گزینه \fB\-\-version\-script\fP برای بررسی این موضوع استفاده می‌شود که آیا نسخه‌های یکسان/سازگار کد منبع نمایش داده می‌شوند که برای جمع‌آوری داده‌های پوشش به کار رفته بودند یا خیر؛ و همچنین برای تأیید اینکه از همان کد منبع برای جمع‌آوری اطلاعات پوششِ در حال ادغام استفاده شده و نسخه منبع مورد استفاده در فیلترسازی با نسخه تولیدکننده داده سازگار است. .sp فایل‌های خروجی HTML در دایرکتوری کاری جاری ایجاد می‌شوند مگر اینکه از گزینه \fB\-\-output\-directory\fP استفاده شود. اگر \fItracefile\fP یا \fIbaseline\-file\fP با «.gz» پایان یابد، فرض می‌شود که با GZIP فشرده شده است و ابزار gunzip برای باز کردن فشرده‌سازی آن به صورت شفاف به کار گرفته خواهد شد. .sp توجه داشته باشید که تمام فایل‌های کد منبع باید دقیقاً در همان مسیر فایل‌سیستمی که کامپایل شده‌اند موجود و قابل خواندن باشند، و تمام ارجاعات مسیر در فایل‌های داده ورودی «.info» و «diff» باید دقیقاً مطابقت داشته باشند (\fIیعنی\fP تطابق رشته‌ای دقیق). .sp علاوه بر این، اسکریپت‌های \fB\-\-version\-script\fP، \fB\-\-annotate\-script\fP و \fB\-\-criteria\-script\fP از رشته‌های مسیر یکسانی استفاده می‌کنند. با این حال، به گزینه‌های \fB\-\-substitute\fP و \fB\-\-resolve\-script\fP برای سازوکاری جهت تنظیم مسیرهای استخراج‌شده مراجعه کنید تا با ساختار منبع و/یا سیستم کنترل نسخه شما مطابقت پیدا کنند. .sp می‌توانید از گزینه پیکربندی \fIcheck_existence_before_callback\fP استفاده کنید تا ابزار قبل از فراخوانی کال‌بک \fB\-\-version\-script\fP یا \fB\-\-annotate\-script\fP، وجود فایل را بررسی کند. برای جزئیات به \fBlcovrc(5) \%\fP مراجعه کنید. .SS گزینه‌های تکمیلی .sp از گزینه \fB\-\-diff\-file\fP برای ارائه یک فایل یکپارچه (unified diff) استفاده کنید که تغییرات کد منبع را بین نسخه استفاده‌شده برای کامپایل و جمع‌آوری فایل‌های رد پای مبنا، و نسخه استفاده‌شده برای کامپایل و جمع‌آوری فایل‌های رد پای جاری نشان می‌دهد. .sp از گزینه \fB\-\-css\-file\fP برای تغییر چیدمان و رنگ‌های خروجی HTML تولیدشده استفاده کنید. فایل‌ها بسته به نرخ پوشش مرتبط، با رنگ‌های متفاوتی علامت‌گذاری می‌شوند. .sp به طور پیش‌فرض، حدود پوشش برای پوشش کم، متوسط و بالا به ترتیب روی ۰\-۷۵٪، ۷۵\-۹۰٪ و ۹۰\-۱۰۰٪ تنظیم شده‌اند. برای تغییر این مقادیر، از گزینه‌های فایل پیکربندی استفاده کنید: .INDENT 0.0 .INDENT 3.5 \fIgenhtml_hi_limit\fP و \fIgenhtml_med_limit\fP .UNINDENT .UNINDENT .sp یا حدود مختص به هر نوع پوشش: .INDENT 0.0 .INDENT 3.5 \fIgenhtml_line_hi_limit\fP و \fIgenhtml_line_med_limit\fP \fIgenhtml_branch_hi_limit\fP و \fIgenhtml_branch_med_limit\fP \fIgenhtml_function_hi_limit\fP و \fIgenhtml_function_med_limit\fP .UNINDENT .UNINDENT .sp برای جزئیات به \fBlcovrc(5) \%\fP مراجعه کنید. .sp همچنین توجه داشته باشید که هنگام نمایش درصدها، 0% و 100% تنها زمانی چاپ می‌شوند که مقادیر به ترتیب دقیقاً 0% و 100% باشند. سایر مقادیری که به طور معمول به 0% یا 100% گرد می‌شوند، در عوض به عنوان نزدیک‌ترین مقدار غیرمرزی چاپ خواهند شد. این رفتار مطابق با عملکرد ابزار \fBgcov(1) \%\fP است. .sp به طور پیش‌فرض، گزارش‌های \fBgenhtml\fP شامل داده‌های پوشش خط و تابع خواهند بود. داده‌های شاخه یا MC/DC به طور پیش‌فرض نمایش داده نمی‌شوند؛ می‌توانید به ترتیب از گزینه‌های \fB\-\-branch\-coverage\fP و \fB\-\-mcdc\-coverage\fP برای فعال کردن پوشش شاخه یا MC/DC استفاده کنید \- یا می‌توانید با افزودن تنظیمات مناسب به فایل پیکربندی lcov شخصی، گروهی یا سراسری خود، پوشش شاخه را برای همیشه فعال نمایید. برای جزئیات به بخش‌های \fIbranch_coverage\fP و \fImcdc_coverage\fP در \fBlcovrc(5) \%\fP مراجعه کنید. .SH "گزینه‌ها (OPTIONS)" .sp به طور کلی، (تقریباً) تمام گزینه‌های \fBgenhtml\fP را می‌توان در فایل پیکربندی شخصی، گروهی، پروژه یا سراسری نیز مشخص کرد \- برای جزئیات به \fBlcovrc(5) \%\fP مراجعه کنید. .INDENT 0.0 .TP .B \fB\-h\fP, \fB\-\-help\fP چاپ یک متن راهنمای کوتاه، سپس خروج. .TP .B \fB\-\-version\fP چاپ شماره نسخه، سپس خروج. .TP .B \fB\-v\fP, \fB\-\-verbose\fP افزایش پرگویی (verbosity) پیام‌های اطلاعاتی. این مورد عمدتاً برای اشکال‌زدایی اسکریپت یا جریان کار استفاده می‌شود \- \fIبرای مثال\fP برای مشخص کردن اینکه کدام فایل‌های داده در کجا پیدا شده‌اند. همچنین پرچم –quiet را ببینید. .TP .B \fB\-q\fP, \fB\-\-quiet\fP کاهش پرگویی پیام‌های اطلاعاتی. .sp کاهش پرگویی برای مثال پیام‌های «پیشرفت» را سرکوب می‌کند \- در حالی که چاپ پیام‌های خطا و هشدار همچنان ادامه خواهد داشت. .TP .B \fB\-\-debug\fP افزایش پرگویی «پیام‌های اشکال‌زدایی». این گزینه در درجه اول برای توسعه‌دهندگانی مفید است که قصد توسعه و بهبود مجموعه ابزار lcov را دارند. .TP .B \fB\-\-validate\fP بررسی HTML تولیدشده برای اطمینان از نبودن پیوندهای مرده و فایل‌های استفاده‌نشده در دایرکتوری خروجی. این بررسی‌ها را می‌توان با تنظیم متغیر محیطی \fBLCOV_VALIDATE = 1\fP نیز فعال کرد\&. این گزینه در درجه اول برای توسعه‌دهندگانی در نظر گرفته شده است که گزارش HTML را تغییر می‌دهند. .TP .B \fB\-\-flat\fP, \fB\-\-hierarchical\fP استفاده از چیدمان سلسله‌مراتبی مشخص‌شده برای گزارش HTML. .sp گزارش HTML پیش‌فرض دارای ۳ سطح است: .INDENT 7.0 .IP 1. 3 \fBسطح بالا (top\-level)\fP: جدول تمام دایرکتوری‌ها، .IP 2. 3 \fBدایرکتوری (directory)\fP: جدول فایل‌های منبع در یک دایرکتوری، و .IP 3. 3 \fBجزئیات فایل منبع (source file detail)\fP: کد منبع حاشیه‌نویسی‌شده. .UNINDENT .sp گزینه \fB\-\-hierarchical\fP گزارشی چندسطحی تولید می‌کند که ساختار دایرکتوری کد منبع را دنبال می‌کند (مشابه ابزار فایل در Microsoft Windows). .sp گزینه \fB\-\-flat\fP یک گزارش HTML دو سطحی تولید می‌کند: .INDENT 7.0 .IP 1. 3 \fBسطح بالا (top\-level)\fP: جدول تمام فایل‌های منبع پروژه، و .IP 2. 3 \fBجزئیات فایل منبع (source file detail)\fP: کد منبع حاشیه‌نویسی‌شده. .UNINDENT .sp نمای «مسطح» (flat) می‌تواند تعداد کلیک‌های لازم برای پیمایش در گزارش پوشش را کاهش دهد \- اما برای پروژه‌هایی به جز موارد بسیار کوچک با چند فایل منبع محدود، دست‌وپاگیر است. این نما می‌تواند در حالت «بازبینی کد» حتی برای پروژه‌های بسیار بزرگ مفید باشد (گزینه \fI–select\-script\fP را ببینید). .sp اکثر پروژه‌های بزرگ ساختار دایرکتوری منطقی دارند \- که این امر قالب گزارش «سلسله‌مراتبی» را مطلوب‌تر می‌سازد. تیم‌های مسئول یک ماژول خاص می‌توانند بر روی یک زیردایرکتوری خاص یا مجموعه‌ای از زیردایرکتوری‌ها تمرکز کنند. .sp تنها یکی از گزینه‌های \fB\-\-flat\fP یا \fB\-\-hierarchical\fP می‌تواند به طور همزمان مشخص شود. .sp این گزینه‌ها را می‌توان از طریق فایل پیکربندی lcovrc نیز به صورت دائمی با استفاده از یکی از خطوط زیر تنظیم کرد: .sp \fIgenhtml_hierarchical\fP = 1 .sp یا .sp \fIgenhtml_flat_view\fP = 1 .sp برای جزئیات به \fBlcovrc(5) \%\fP مراجعه کنید. .TP .B \fB\-f\fP, \fB\-\-frames\fP استفاده از قاب‌های HTML (فریم‌ها) برای نمای کد منبع. .sp در صورت فعال بودن، یک frameset برای هر فایل کد منبع ایجاد می‌شود که نمای کلی کد منبع را به صورت یک تصویر «قابل کلیک» ارائه می‌دهد. توجه داشته باشید که این گزینه تولید خروجی را به طور محسوسی کند می‌کند، زیرا تک‌تک نویسه‌های کد منبع باید یک بار بررسی شوند. همچنین ماژول پرل GD.pm باید برای عملکرد این گزینه نصب باشد (می‌توان آن را از \% دریافت کرد). .sp این گزینه از طریق مدخل \fIgenhtml_frames\fP در فایل \fBlcovrc\fP نیز قابل کنترل است. .sp لطفاً توجه داشته باشید که باگی در firefox و chrome وجود دارد که با فعال کردن فریم‌ها، ابرپیوندها را از مدخل جدول خلاصه سطح «دایرکتوری» به اولین خط در فایل مربوطه در آن دسته خاص از کار می‌اندازد \- \fIبرای مثال\fP به اولین خط «MIS» (گزارش پوشش ساده \- گزینه \fI\-\-show\-navigation\fP در ادامه را ببینید)، به اولین شاخه «UNC» (گزارش پوشش تفاضلی) و غیره. ابرپیوندها از جدول خلاصه در بالای صفحه «جزئیات منبع» تحت تأثیر قرار نمی‌گیرند. .TP .B \fB\-s\fP, \fB\-\-show\-details\fP تولید نمای تفصیلی دایرکتوری. .sp هنگامی که این گزینه فعال باشد، \fBgenhtml\fP دو نسخه از هر مدخل فایل منبع در جدول خلاصه مربوطه ایجاد می‌کند: .INDENT 7.0 .IP \(bu 2 نسخه‌ای حاوی اطلاعات استاندارد به همراه پیوندی به نسخه «دقیق» (detailed)، و .IP \(bu 2 نسخه دومی که شامل تعداد نقاط پوشش (coverpoints) اجراشده توسط هر مورد آزمون (testcase) است. .UNINDENT .sp توجه داشته باشید که نقاط پوشش ناموفق در داده‌های جدول تفکیکی هر آزمون نشان داده نمی‌شوند. .sp جدول خلاصه مربوطه در صفحه «دایرکتوری» گزارش سه‌سطحی پیش‌فرض genhtml، یا در صفحه سطح بالای گزارش «مسطح» (ببینید \fIgenhtml –flat …\fP)، یا در صفحه دایرکتوری والد گزارش «سلسله‌مراتبی» (ببینید \fIgenhtml –hierarchical …\fP) قرار دارد. .sp توجه داشته باشید که این گزینه ممکن است مصرف حافظه را به میزان قابل توجهی افزایش دهد. .TP .B \fB\-b\fP \fIbaseline\-file\-pattern\fP, \fB\-\-baseline\-file\fP \fIbaseline\-file\-pattern\fP استفاده از داده‌های موجود در فایل‌های یافت‌شده از الگوی \fIbaseline\-file\-pattern\fP به عنوان مبنای (baseline) پوشش. .sp گزینه \fB\-\-baseline\-file\fP می‌تواند چندین بار مشخص شود \- برای مثال، اگر برای هر یک از چندین مجموعه آزمون چندین فایل داده رد پا دارید و نمی‌خواهید مرحله اضافی ادغام همه آن‌ها در یک فایل داده تجمیعی واحد را انجام دهید. .sp فایل‌های داده پوشش مشخص‌شده با \fIbaseline\-file\-pattern\fP خوانده شده و به عنوان مبنایی برای دسته‌بندی تغییرات در پوششِ نمایانده‌شده توسط شمارش‌های پوشش در \fItracefile\-patterns\fP استفاده می‌شوند\&. اگر \fIbaseline\-file\-pattern\fP یک دایرکتوری باشد، genhtml آن دایرکتوری را برای یافتن تمام فایل‌های با پسوند «.info» جستجو می‌کند. برای چگونگی تغییر این الگو، به بخش \fIinfo_file_extension\fP در \fBman(5) lcovrc\fP مراجعه کنید. .sp به طور کلی، هنگامی که یک \fI–baseline\-file\-pattern\fP را مشخص می‌کنید، باید یک فایل diff با قالب unified diff از طریق \fB\-\-diff\-file\fP ارائه دهید\&. بدون یک فایل diff، ابزار genhtml فرض می‌کند که هیچ تفاوتی در کد منبع بین «baseline» و «current» وجود ندارد. برای مثال: این حالت می‌تواند برای یافتن تغییرات افزایشی ناشی از افزودن آزمون‌های بیشتر، یا برای مقایسه نتایج پوشش بین نسخه‌های gcc، یا بین gcc و llvm به کار رود. .TP .B \fB\-\-baseline\-title\fP \fItitle\fP استفاده از \fItitle\fP به عنوان متن برچسب توصیفی برای منبع داده‌های مبنای پوشش. .TP .B \fB\-\-baseline\-date\fP \fIdate\fP استفاده از \fIdate\fP به عنوان تاریخ جمع‌آوری در قالب متنی برای داده‌های مبنای پوشش. اگر این آرگومان مشخص نشود، پیش‌فرض استفاده از زمان ایجاد اولین فایل تطبیق‌یافته با \fIbaseline\-file\-pattern\fP به عنوان تاریخ مبنا است. اگر چندین فایل مبنا وجود داشته باشد، از تاریخ ایجاد اولین فایل استفاده خواهد شد..TP .B \fB\-\-current\-date\fP \fIdate\fP استفاده از \fIdate\fP به عنوان تاریخ گردآوری در قالب متنی برای داده‌های خط مبنای پوشش. اگر این آرگومان مشخص نشود، حالت پیش‌فرض استفاده از زمان ایجاد \fItracefile\fP فعلی است\&. .TP .B \fB\-\-diff\-file\fP \fIdiff\-file\fP استفاده از \fIdiff\-file\fP به عنوان تعریفی برای تغییرات فایل مبدأ بین نقاط نمونه‌برداری برای \fIbaseline\-file\-pattern\fP و \fItracefile(s)\fP\&. .sp نکته: .INDENT 7.0 .IP \(bu 2 اگر در طول ایجاد یک گزارش پوشش تفاضلی (differential coverage report) پالایه‌ها اعمال شوند (بخش \fI\-\-filter\fP در زیر را ببینید)، آن‌گاه این پالایه‌ها علاوه بر \fIcurrent coverage data\fP (داده‌های پوشش جاری)، بر روی \fIbaseline coverage data\fP (داده‌های پوشش مبنا؛ بخش \fI\-\-baseline\-file\fP در بالا را ببینید) نیز اعمال خواهند شد\&. مهم است که \fIdiff\-file\fP تمام تغییرات کد مبدأ را به دقت منعکس کند تا داده‌های پوشش مبنا بتوانند به درستی پالایش شوند. .IP \(bu 2 بهترین شیوه استفاده از یک فراخوانی برگشتی (callback) \fI\-\-version\-script\fP است تا تطابق نسخه‌های مبدأ پیش از اعمال پالایش مبتنی بر مبدأ راستی‌آزمایی شود. .UNINDENT .sp تقریباً همیشه ایده بهتری است که پالایش در زمان ثبت یا تجمیع انجام شود \- نه در زمان تولید گزارش. .sp یک فایل ورودی مناسب از نوع \fI\(lquniversal diff\(rq\fP برای گزینه \fI\-\-diff\-file\fP می‌تواند با استفاده از اسکریپت‌های نمونه «p4udiff» یا «gitdiff» که به عنوان بخشی از این بسته ارائه شده‌اند، یا با استفاده مستقیم از دستورهای سامانه کنترل نسخه ایجاد شود. .sp اسکریپت‌های نمونه «p4udiff» یا «gitdiff» در مسیرهای زیر قرار دارند: .INDENT 7.0 .INDENT 3.5 \fBscripts/p4udiff\fP .UNINDENT .UNINDENT .sp و .INDENT 7.0 .INDENT 3.5 \fBscripts/gitdiff\fP .UNINDENT .UNINDENT .sp این اسکریپت‌ها صرفاً خروجی ‘p4’ یا ‘git’ را پس‌پردازش می‌کنند تا فایل‌هایی را که مورد نظر نیستند (به‌صورت اختیاری) حذف کنند و فایل‌هایی را که تغییر نکرده‌اند صراحتاً مشخص نمایند. .sp اسکریپت \fBp4udiff\fP یک شناسه changelist یا رشته حرفی «sandbox» را می‌پذیرد؛ «sandbox» نشان می‌دهد که فایل‌های تغییریافته‌ای وجود دارند که هنوز ثبت (check in) نشده‌اند. برای اطلاعات بیشتر “\fIgitdiff \-\-help\fP” و “\fIp4udiff \-\-help\fP” را ببینید. .sp سودمند است که فایل‌های تغییرنیافته با خطوطی به شکل زیر مشخص شوند: .INDENT 7.0 .INDENT 3.5 .sp .EX diff [optional header strings] === file_path .EE .UNINDENT .UNINDENT .sp در خروجی p4diff/gitdiff، چرا که این آگاهی به فرونشاندن هشدارهای کاذب ‘path mismatch’ کمک خواهد کرد. مدخل‌های \fB\-\-elide\-path\-mismatch\fP و \fB\-\-build\-directory\fP در زیر را ببینید. .sp به‌طور کلی، زمانی که \fB\-\-diff\-file\fP را مشخص می‌کنید، \fB\-\-baseline\-file\fP را نیز تعیین خواهید کرد\&. فایل‌های \fIbaseline_files\fP برای محاسبه تفاوت‌های پوشش (\fIبرای مثال\fP افزایش‌ها و کاهش‌ها) میان مبنا و جاری استفاده می‌شوند، در حالی که \fIdiff_file\fP برای محاسبه تغییرات کد به کار می‌رود: متن مبدأ میان ‘baseline’ و ‘current’ یکسان است. اگر \fIbaseline_files\fP را مشخص کنید اما \fIdiff_file\fP را تعیین نکنید، ابزار فرض می‌کند که هیچ تغییر کدی میان مبنا و جاری وجود ندارد. اگر \fIdiff_file\fP را مشخص کنید اما هیچ \fIbaseline_files\fP مشخص نشود، ابزار فرض می‌کند که هیچ داده پوشش مبنایی وجود ندارد (هیچ کد مبنایی پوشش داده نشده است)؛ در نتیجه کد تغییرنیافته (\fIیعنی\fP کدی که در \fIdiff_file\fP ظاهر نمی‌شود) به عنوان GIC (پوشش‌یافته) یا UIC (پوشش‌نیافته) دسته‌بندی می‌شود، در حالی که کد جدید یا تغییریافته به عنوان GNC یا UNC دسته‌بندی خواهد شد. .TP .B \fB\-\-annotate\-script\fP \fIscript\fP استفاده از \fIscript\fP برای دریافت داده‌های حاشیه‌نویسی کد مبدأ. .sp از این گزینه برای مشخص کردن یک ابزار خارجی یا خط فرمان استفاده کنید که \fBgenhtml\fP بتواند از آن برای به دست آوردن داده‌های حاشیه‌نویسی کد مبدأ مانند قدمت و نویسنده آخرین تغییر برای هر خط از کد مبدأ استفاده کند. .sp این گزینه همچنین به \fBgenhtml\fP دستور می‌دهد تا یک جدول خلاصه به سرآیند گزارش HTML اضافه کند که شمارش‌های موجود در دسته‌های مختلف پوشش، مرتبط با هر بازه تاریخی (date bin) را نشان می‌دهد. علاوه بر این، هر خط از کد مبدأ اطلاعات قدمت و مالک را نشان خواهد داد. داده‌های حاشیه‌نویسی همچنین برای پر کردن یک «tooltip» استفاده می‌شوند که هنگام بردن اشاره‌گر ماوس روی کد مبدأ مربوطه نمایان می‌شود. برای جزئیات، مدخل \fIgenhtml_annotate_tooltip\fP را در \fBlcovrc(5) \%\fP ببینید. .sp انتظار می‌رود که \fIscript\fP مشخص‌شده، اطلاعات قدمت و مالکیت را برای هر خط از کد مبدأ از سامانه مدیریت نسخه به دست آورد و این اطلاعات را در قالبی که در زیر شرح داده شده خروجی دهد. .sp اگر اسکریپت حاشیه‌نویسی با شکست مواجه شود و خطاهای حاشیه‌نویسی از طریق \fB\-\-ignore\-errors\fP نادیده گرفته شوند، آن‌گاه \fBgenhtml\fP تلاش خواهد کرد فایل مبدأ را به‌صورت عادی بارگذاری کند. اگر فایل وجود نداشته باشد یا قابل خواندن نباشد، و پرچم \fB\-\-synthesize\-missing\fP تعیین شده باشد، \fBgenhtml\fP داده‌های ساختگی برای فایل تولید خواهد کرد. .sp اگر یک اسکریپت حاشیه‌نویسی را مشخص کرده باشید اما هیچ فایلی با موفقیت حاشیه‌نویسی نشود، \fBgenhtml\fP خطایی صادر خواهد کرد (زیر را ببینید). این حالت زمانی می‌تواند رخ دهد که، برای مثال، متغیرهای محیطی P4USER، P4CLIENT یا P4PORT شما به درستی تنظیم نشده باشند \- \fIبرای نمونه\fP، اگر کاربر Jenkins که گزارش‌های پوشش را تولید می‌کند با کاربری که کد را دریافت (check out) کرده و مالک sandbox است یکسان نباشد. .sp اسکریپت‌های نمونه حاشیه‌نویسی برای Perforce («p4annotate») و git («gitblame») به عنوان بخشی از این بسته در مسیرهای زیر ارائه شده‌اند: .INDENT 7.0 .INDENT 3.5 \fBscripts/p4annotate\fP .UNINDENT .UNINDENT .sp و .INDENT 7.0 .INDENT 3.5 \fBscripts/gitblame\fP .UNINDENT .UNINDENT .sp توجه داشته باشید که این اسکریپت‌ها حاشیه‌نویسی‌ها را بر اساس نسخه فایلی که در مخزن ثبت شده است (check in) تولید می‌کنند \- نه فایل تغییریافته محلی در پوشه ساخت. اگر به حاشیه‌نویسی برای فایل‌های تغییریافته محلی نیاز دارید، می‌توانید تغییرات خود را در P4 بایگانی (shelve) کنید، یا آن‌ها را در یک شاخه محلی در git ثبت نمایید. .sp \fBساخت اسکریپت اختصاصی خودتان\fP .sp هنگام ساخت اسکریپت اختصاصی خود، لطفاً ابتدا بخش \fBScript considerations\fP در بالا را برای قراردادهای عمومی فراخوانی و ملزومات اسکریپت بررسی کنید. .sp اسکریپت \fIscript\fP توسط genhtml با خط فرمان زیر فراخوانی می‌شود: .INDENT 7.0 .INDENT 3.5 \fBscript\fP \fI[additional_parameters]\fP \fIsource_file_name\fP .UNINDENT .UNINDENT .sp که در آن .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBscript\fP فایل اجرایی اسکریپت است .TP .B \fBadditional_parameters\fP شامل هرگونه پارامتر اختیاری مشخص‌شده است (بخش \fBScript conventions\fP در بالا را ببینید) .TP .B \fBsource_file_name\fP نام فایل کد مبدأ است .UNINDENT .UNINDENT .UNINDENT .sp فایل اجرایی \fIscript\fP باید برای هر خط در فایل \fIsource_file_name\fP، خطی را با قالب زیر به جریان خروجی استاندارد ارسال کند: .INDENT 7.0 .INDENT 3.5 \fIcommit_id\fP | \fIauthor_data\fP | \fIdate\fP | \fIsource_code\fP .UNINDENT .UNINDENT .sp که در آن .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBcommit_id\fP شناسه‌ای است که آخرین تغییر اعمال‌شده روی خط را مشخص می‌کند یا در صورتی که این فایل در سامانه کنترل نسخه شما ثبت نشده باشد، مقدار آن NONE است. .sp اگر \fBcommit_id\fP مقدار \fINONE\fP باشد، \fBgenhtml\fP فایل را به عنوان «با موفقیت حاشیه‌نویسی‌نشده» در نظر می‌گیرد و در غیر این صورت آن را «با موفقیت حاشیه‌نویسی‌شده» لحاظ می‌کند. .TP .B \fBauthor_data\fP نویسنده آخرین تغییر را مشخص می‌کند. .sp جهت سازگاری عقبروی با پیاده‌سازی‌های موجود annotate\-script، دو قالب برای \fIauthor_data\fP پشتیبانی می‌شود: .INDENT 7.0 .IP \(bu 2 \fIstring\fP: رشته‌ای که هم به عنوان ‘نام مخفف’ (استفاده‌شده به عنوان نام ‘owner’ در خروجی HTML و بازخوانی‌ها) و هم به عنوان ‘نام کامل’ (استفاده‌شده در بازخوانی‌های tooltip) به کار می‌رود .IP \(bu 2 \fIabbrev_string;full_name\fP: رشته \fIauthor_data\fP شامل هر دو مقدار ‘نام مخفف’ و ‘نام کامل’ است \- که با یک نویسه نقطه\-ویرگول (‘;’) از هم جدا شده‌اند. .sp این ویژگی زمانی کاربرد دارد که در حال تولید گزارش‌های پوشش برای مؤلفه‌های نرم‌افزاری متن‌باز هستید که در آن‌ها مشارکت‌کنندگان بیرونی (‘External’) متعددی وجود دارند و نمی‌خواهید آن‌ها را در جدول‌های خلاصه ‘owner’ تفکیک کنید، اما با این حال تمایل دارید بدانید نویسنده واقعی چه کسی بوده است. (برای مشاهده مثال، اسکریپت بازخوانی \fBgitblame\fP را ببینید.) .UNINDENT .TP .B \fBdate\fP تاریخ آخرین تغییر در قالب W3CDTF است (\-\-
T::) .TP .B \fBsource_code\fP کد مبدأ آن خط است .UNINDENT .UNINDENT .UNINDENT .sp اسکریپت باید در صورت موفقیت‌آمیز بودن پردازش مقدار 0 (صفر) و در صورت مواجهه با خطا مقداری غیرصفر برگرداند. .TP .B \fB\-\-criteria\-script\fP \fIscript\fP استفاده از \fIscript\fP برای آزمودن معیارهای پذیرش پوشش. .sp از این گزینه برای تعیین یک ابزار خارجی یا خط فرمان استفاده کنید که \fBgenhtml\fP بتواند برای بررسی اینکه آیا نتایج پوشش معیارهای پذیرش سفارشی را برآورده می‌کنند یا خیر، از آن استفاده نماید. نتایج بررسی معیارها در سیاهه‌ خروجی استاندارد \fBgenhtml\fP نمایش داده می‌شوند\&. اگر حداقل یکی از بررسی‌ها ناموفق باشد، \fBgenhtml\fP پس از تکمیل پردازش خود با یک کد خروج غیرصفر خارج خواهد شد. .sp یک اسکریپت نمونه برای معیارهای پوشش به عنوان بخشی از این بسته در مسیر زیر ارائه شده است: .INDENT 7.0 .INDENT 3.5 \fBscripts/criteria\fP .UNINDENT .UNINDENT .sp اسکریپت نمونه بررسی می‌کند که آیا پوشش خط بالاترین سطح معیار «UNC + LBC + UIC == 0» را برآورده می‌کند یا خیر (کد اضافه‌شده و کدی که به‌تازگی فعال شده باید آزموده شوند، و کد آزموده‌شده موجود نباید به حالت آزموده‌نشده درآید). .sp به عنوان مثالی دیگر، می‌توان اسکریپت‌هایی ایجاد کرد که با بررسی اینکه آیا نسبت خطوط اجراشده به کل خطوط («(GNC + GIC + CBC) / (GNC + GIC + CBC + UNC + UIC + UBC)») بیشتر از حد آستانه است یا خیر، قابلیت \fBlcov \-\-fail\-under\-lines\fP را شبیه‌سازی کنند \- چه فقط در بالاترین سطح، چه در هر پوشه، یا در هر جای دیگر مورد نظر. به همین ترتیب، معیارها می‌توانند شامل شاخص‌های پوشش انشعاب و تابع نیز باشند. .sp به‌طور پیش‌فرض اسکریپت معیارها برای همه سطوح سلسله‌مراتب کد مبدأ فراخوانی می‌شود، \fIیعنی\fP: بالاترین سطح (top\-level)، پوشه و سطح فایل. گزینه فایل پیکربندی \fIcriteria_callback_levels\fP می‌تواند برای محدود کردن سطوح سلسله‌مراتب به هر ترکیبی از سطوح ‘top’، ‘directory’ یا ‘file’ استفاده شود. .sp مثال: .INDENT 7.0 .INDENT 3.5 .sp .EX genhtml \-\-rc criteria_callback_levels=directory,top ... .EE .UNINDENT .UNINDENT .sp می‌توانید با استفاده از گزینه فایل پیکربندی \fIcriteria_callback_data\fP حجم داده‌های ارسالی به اسکریپت معیارها را افزایش دهید\&. به‌طور پیش‌فرض، فقط تعداد کل لحاظ می‌شود. مشخص کردن “date” شمارش‌ها به تفکیک بازه تاریخی و “owner” شمارش‌ها به تفکیک بازه مالک را اضافه می‌کند. .sp مثال: .INDENT 7.0 .INDENT 3.5.sp .EX genhtml \-\-rc criteria_callback_data=date,owner ... .EE .UNINDENT .UNINDENT .sp برای جزئیات بیشتر، \fBlcovrc(5) \%\fP را ببینید. .sp \fBساخت اسکریپت سفارشی خودتان\fP .sp هنگام ایجاد اسکریپت اختصاصی، لطفاً ابتدا بخش \fBملاحظات اسکریپت (Script considerations)\fP در بالا را برای آگاهی از قراردادهای عمومی فراخوانی و نیازمندی‌های اسکریپت مطالعه کنید. .sp \fIscript\fP برای هر فایل کد مبدأ، دایرکتوری برگ (leaf-directory) و نتایج پوشش سطح بالا با خط فرمان زیر اجرا می‌شود: .INDENT 7.0 .INDENT 3.5 .sp .EX script [additional_parameters] \(dqname \(dq \(dq type\(dq \(dqcoverage_data\(dq .EE .UNINDENT .UNINDENT .sp که در آن: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBscript\fP فایل اجرایی اسکریپت است .TP .B \fBadditional_parameters\fP شامل هرگونه پارامتر اختیاری مشخص‌شده است (بخش \fBقراردادهای اسکریپت (Script conventions)\fP در بالا را ببینید) .TP .B \fBname\fP نام شیئی است که معیارهای پوشش باید برای آن بررسی شود؛ یعنی نام فایل کد مبدأ، نام دایرکتوری، یا «top» در صورتی که اسکریپت برای داده‌های بالاترین سطح فراخوانی شده باشد .TP .B \fBtype\fP نوع شیء کد مبدأ است که معیارهای پوشش باید برای آن بررسی شود؛ یعنی یکی از مقادیر «file»، «directory» یا «top» .TP .B \fBcoverage_data\fP یا یک هش از داده‌های پوشش است یا یک نمایش JSON از هش داده‌های پوشش شیء کد مبدأ مربوطه. اگر تابع فراخوان بازگشتی (callback) یک ماژول Perl باشد، شیء هش به آن ارسال می‌شود؛ در غیر این صورت، یک نمایش JSON از آن داده‌ها به آن ارسال می‌گردد. .UNINDENT .UNINDENT .UNINDENT .sp قالب داده‌های JSON به صورت زیر تعریف می‌شود: .INDENT 7.0 .INDENT 3.5 .sp .EX { \(dq\(dq: { \(dqfound\(dq: , \(dqhit\(dq: , \(dq\(dq: , ... }, \(dq\(dq: { \(dq\(dq : { \(dqfound\(dq: , \(dqhit\(dq: , \(dq\(dq: , ... }, ... }, ... } .EE .UNINDENT .UNINDENT .sp که در آن: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBtype\fP نوع پوشش را با یکی از مقادیر «line»، «function» یا «branch» مشخص می‌کند .TP .B \fBbin_type\fP نوع پوشش بر پایهٔ دسته‌بندی (per-bin) را با یکی از مقادیر «line_age»، «function_age» یا «branch_age» برای داده‌های بازهٔ تاریخ (date-bin)، و «line_owners» یا «branch_owners» برای داده‌های مبتنی بر مالک (owner-bin) مشخص می‌کند .TP .B \fBbin_id\fP نمایهٔ بازهٔ تاریخ را برای داده‌های date-bin و شناسهٔ مالک را برای داده‌های owner-bin مشخص می‌کند. .TP .B \fBfound\fP تعداد خطوط، توابع یا شاخه‌های یافت‌شده را مشخص می‌کند .TP .B \fBhit\fP تعداد خطوط، توابع یا شاخه‌های اجراشده (hit) را مشخص می‌کند .TP .B \fBcategory\fP تعداد خطوط، توابع یا شاخه‌هایی را مشخص می‌کند که در دسته‌بندی معین قرار می‌گیرند (بخش \fBپوشش تفاضلی (Differential coverage)\fP در بالا را ببینید) .UNINDENT .UNINDENT .UNINDENT .sp توجه داشته باشید که داده‌ها تنها برای انواع پوشش و دسته‌بندی‌های (bins) غیرخالی گزارش می‌شوند. .sp اسکریپت در صورت برآورده شدن معیارها باید مقدار 0 (صفر) و در غیر این صورت مقداری غیرصفر برگرداند. .sp در صورت تمایل، اسکریپت می‌تواند یک رشتهٔ خروجی تک‌خطی چاپ کند که در صورت غیرصفر بودن وضعیت بازگشتی، به گزارش خطا (error log) اضافه خواهد شد. علاوه‌بر این، خطوط غیرخالی به لاگ خروجی استاندارد genhtml پیوست می‌شوند. .TP .B \fB\-\-version\-script\fP \fIscript\fP استفاده از \fIscript\fP برای دریافت داده‌های نسخهٔ فایل کد مبدأ. .sp از این گزینه برای مشخص کردن یک ابزار خارجی یا دستور خط فرمانی استفاده کنید که \fBgenhtml\fP بتواند هنگام تولید HTML یا اعمال فیلترهای مبدأ، برای دریافت شناسهٔ نسخهٔ (version ID) فایل کد مبدأ از آن استفاده کند (گزینهٔ \fB\-\-filter\fP را ببینید). .sp شناسهٔ نسخه می‌تواند یک هش فایل یا شناسهٔ کامیت از سیستم کنترل نسخه باشد. این شناسه برای تطبیق نسخهٔ فایل مبدأ بارگذاری‌شده با نسخه‌ای که برای تولید داده‌های پوشش استفاده شده است (\fIi.e.\fP نسخهٔ فایلی که توسط lcov/geninfo بررسی شده) به کار می‌رود. یکسان بودن نسخه‌های کد مبدأ بسیار مهم است؛ در غیر این صورت ممکن است نتایجی متناقض یا گمراه‌کننده حاصل شود. .sp عدم تطابق نسخه‌ها معمولاً زمانی رخ می‌دهد که وظایف ثبت، تجمیع و تولید گزارش بین چندین کار (job) مختلف تقسیم شده باشد \- \fIe.g.\fP هنگامی که از یک کد مبدأ یکسان در چند پروژه استفاده می‌شود، گزارش پوشش یکپارچه/سراسری مورد نیاز است و پروژه‌ها تصادفاً از نگارش‌های متفاوتی استفاده می‌کنند. .sp اگر فایل .info (داده‌های پوشش) شما فاقد اطلاعات نسخه است \- برای مثال به این دلیل که توسط ابزاری تولید شده که از نسخه‌بندی پشتیبانی نمی‌کرده \- می‌توانید از گزینهٔ \fIcompute_file_version\fP = 1 در فایل پیکربندی برای تولید بعدی این داده‌ها استفاده کنید. یک راه ساده برای انجام این کار، استفاده از \fBlcov\fP \fI\-\-add\-tracefile\fP برای خواندن فایل اصلی، درج اطلاعات نسخه و نوشتن خروجی نهایی است. برای اطلاعات بیشتر \fBlcovrc(5) \%\fP را ببینید. .sp اسکریپت‌های نمونه برای Perforce (با نام «getp4version»)، گیت (با نام «gitversion») و استفاده از هش md5 (با نام «get_signature») همراه با این بسته در مسیرهای زیر ارائه شده‌اند: .INDENT 7.0 .INDENT 3.5 \fBscripts/getp4version\fP .sp \fBscripts/gitversion\fP .UNINDENT .UNINDENT .sp و .INDENT 7.0 .INDENT 3.5 \fBscripts/get_signature\fP .UNINDENT .UNINDENT .sp توجه داشته باشید که هنگام استخراج، ادغام و نمایش داده‌های پوشش باید از همان اسکریپت/مکانیسم یکسان برای تعیین نسخهٔ فایل استفاده کنید؛ در غیر این صورت ممکن است گزارش‌های کاذبی مبنی بر عدم تطابق دریافت نمایید. .sp \fBساخت اسکریپت سفارشی خودتان\fP .sp هنگام ساخت اسکریپت اختصاصی، لطفاً ابتدا بخش \fBملاحظات اسکریپت (Script considerations)\fP در بالا را برای بررسی قراردادهای عمومی فراخوانی و نیازمندی‌های اسکریپت مطالعه فرمایید. .sp \fI«script»\fP هم برای تولید و هم برای مقایسهٔ شناسهٔ نسخه استفاده می‌شود تا حفظ تاریخچه میان فراخوانی‌ها را میسر ساخته یا امکان پردازش‌های پیچیده‌تر جهت احراز برابری را فراهم آورد. این اسکریپت توسط \fBgenhtml\fP با یکی از خطوط فرمان زیر اجرا خواهد شد: .INDENT 7.0 .IP 1. 3 تعیین شناسهٔ نسخهٔ فایل مبدأ .sp \fBscript\fP \fIsource_file_name\fP .sp اسکریپت باید شناسهٔ نسخهٔ \fIsource_file_name\fP را در stdout بنویسد و وضعیت خروج 0 را برگرداند. اگر فایل نسخه‌بندی نشده باشد، باید یک رشتهٔ خالی بنویسد و با وضعیت 0 خارج شود. .IP 2. 3 مقایسه شناسه‌های نسخهٔ فایل مبدأ .sp \fBscript \-\-compare\fP \fIsource_file_name\fP \fIsource_file_id\fP \fIinfo_file_id\fP .sp که در آن: .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .TP .B “source_file_name” نام فایل کد مبدأ است .TP .B “source_file_id “ شناسهٔ نسخه‌ای است که از فراخوانی «script source_file_name» بازگردانده شده است .TP .B “info_file_id “ شناسهٔ نسخه‌ای است که در فایل .info متناظر یافت شده است .UNINDENT .UNINDENT .UNINDENT .sp در صورتی که شناسه‌ها با یکدیگر همخوانی نداشته باشند، باید مقداری غیرصفر برگرداند. .UNINDENT .TP .B \fB\-\-resolve\-script\fP \fIscript\fP استفاده از \fIscript\fP برای یافتن مسیر فایلی از کد مبدأ که در فایل داده‌های ورودی آمده است، در صورتی که پس از اعمال الگوهای \fI\-\-substitute\fP و جستجو در فهرست \fI\-\-source\-directory\fP، فایل مورد نظر پیدا نشود. این گزینه معادل با گزینهٔ \fIresolve_script\fP در فایل پیکربندی است. برای جزئیات بیشتر به \fBlcovrc(5) \%\fP مراجعه کنید. .TP .B \fB\-\-select\-script\fP \fIcallback\fP استفاده از \fIcallback\fP برای تصمیم‌گیری دربارهٔ این که آیا یک خط مبدأ معین اهمیت دارد و باید در داده‌های خروجی/گزارش تولیدشده گنجانده شود یا خیر. .sp این گزینه معادل با گزینهٔ \fIselect_script\fP در فایل پیکربندی است. برای جزئیات بیشتر به \fBlcovrc(5) \%\fP مراجعه نمایید. .TP .B \fB\-\-simplify\-script\fP \fIcallback\fP استفاده از \fIcallback\fP برای کوتاه/ساده‌سازی نام‌های طولانی و رمزگشایی‌شدهٔ (demangled) توابع و الگوهای ++C تا جدول جزئیات تابع جمع‌وجورتر و خواناتر شود؛ به عنوان مثال، برای حذف نام فضاهای نام (namespaces) تو در تو..sp توجه داشته باشید که ساده‌سازی‌ها تنها بر نحوه نمایش تأثیر می‌گذارند و نام‌های واقعی ذخیره‌شده در پایگاه‌داده پوشش (coverage DB) را تغییر نمی‌دهند. به‌ویژه، نام موجود در پایگاه‌داده (و نه نام ساده‌شده) برای تطبیق با الگوهای \fI–erase\-function\fP استفاده می‌شود. .sp این گزینه معادل گزینه \fIsimplify_script\fP در فایل پیکربندی است. برای جزئیات به \fBlcovrc(5) \%\fP مراجعه کنید. .TP .B \fB\-\-unreachable\-script\fP \fImodule\fP از \fImodule\fP برای تصمیم‌گیری درباره اینکه آیا عبارات شرطی انشعاب (branch) یا شرایط MC/DC خاصی باید از گزارش پوشش حذف شوند یا خیر، استفاده کنید. این گزینه معادل گزینه \fIunreachable_script\fP در فایل پیکربندی است. برای جزئیات به \fBlcovrc(5) \%\fP مراجعه کنید. .sp توجه داشته باشید که \fI“module”\fP الزاماً باید یک ماژول Perl باشد. .sp به بحث پیرامون \fI–unreachable\-script\fP در بخش \fI«Script conventions»\fP در بالا، و بخش \fI«Exclusion markers»\fP در \fBgeninfo(1) \%\fP\& مراجعه کنید. .TP .B \fB\-\-checksum\fP مشخص می‌کند که آیا چک‌سام ذخیره‌شده در tracefile با چک‌سام محاسبه‌شده از کد منبع مقایسه شود یا خیر. .sp اعتبارسنجی چک‌سام به‌طور پیش‌فرض غیرفعال (\fBdisabled\fP) است. .sp هنگامی که اعتبارسنجی چک‌سام فعال باشد، برای هر خط از کد منبع یک چک‌سام محاسبه شده و با چک‌سام موجود در tracefile «فعلی» (current) مقایسه می‌شود. این کار به جلوگیری از تلاش برای نمایش کدهای منبعی که با کد استفاده‌شده برای تولید داده‌های پوشش یکسان نیستند کمک می‌کند. .sp توجه داشته باشید که این گزینه تا حدی تحت‌الشعاع گزینه \fB\-\-version\-script\fP قرار می‌گیرد \- که عملکردی مشابه اما در سطح «کل فایل» دارد. .TP .B \fB\-\-fail\-under\-branches\fP \fIpercentage\fP از این گزینه استفاده کنید تا به genhtml اعلام شود در صورتی که کل پوشش انشعاب کمتر از \fIpercentage\fP باشد، با وضعیت ۱ خارج شود. برای جزئیات بیشتر به \fBlcov(1) \%\fP\& مراجعه کنید. .TP .B \fB\-\-fail\-under\-lines\fP \fIpercentage\fP از این گزینه استفاده کنید تا به genhtml اعلام شود در صورتی که کل پوشش خطوط کمتر از \fIpercentage\fP باشد، با وضعیت ۱ خارج شود. برای جزئیات بیشتر به \fBlcov(1) \%\fP\& مراجعه کنید. .TP .B \fB\-\-new\-file\-as\-baseline\fP به‌طور پیش‌فرض، هنگامی که کدی در خطوط منبع در داده‌های «current» شناسایی شود که در داده‌های «baseline» به‌عنوان کد شناخته نشده بودند، اما متن منبع تغییری نکرده است، نقاط پوشش (coverpoints) آن‌ها در دسته «کد گنجانده‌شده» دسته‌بندی می‌شوند: \fIGIC\fP یا \fIUIC\fP\&. .sp با این حال، اگر پیکربندی وظیفه پوشش اخیراً تغییر کرده باشد تا فایل‌های بیشتری را ابزارگذاری (instrument) کند، تمام نقاط پوشش اجرا‌نشده در آن فایل‌ها در دسته \fIGIC\fP قرار می‌گیرند \- که ممکن است باعث ناموفق شدن بررسی‌های معیارهای پوشش خاصی شود. .sp هنگامی که این گزینه مشخص شود، genhtml وانمود می‌کند که داده‌های baseline برای فایل همان داده‌های current است \- بنابراین نقاط پوشش به‌عنوان \fICBC\fP یا \fIUBC\fP دسته‌بندی می‌شوند که بررسی معیارهای پوشش را فعال نمی‌کنند. .sp لطفاً توجه داشته باشید که نقاط پوشش در فایل تنها زمانی باز‌دسته‌بندی می‌شوند که: .INDENT 7.0 .IP \(bu 2 هیچ داده «baseline» برای هیچ نقطه پوششی در این فایل وجود نداشته باشد، و .IP \(bu 2 تاریخ فایل قبل از baseline باشد: قدیمی‌ترین خط در فایل قدیمی‌تر از فایل داده «baseline» (یا مقدار تعیین‌شده توسط گزینه \fB\-\-baseline\-date\fP) باشد. .UNINDENT .TP .B \fB\-\-elide\-path\-mismatch\fP دسته‌بندی تفاضلی از مسیرهای فایل برای تطبیق ورودی‌های پوشش از فایل «.info» با ورودی‌های تفاوت فایل در unified\-diff\-file استفاده می‌کند. اگر ورودی‌ها یکسان نباشند، دسته‌بندی ممکن است نادرست یا نامتعارف باشد. .sp هنگامی که مسیرها مطابقت نداشته باشند، genhtml پیام‌های خطای «path» تولید می‌کند تا شما را از عدم تطابق‌ها مطلع سازد. .sp اگر عدم تطابق رخ دهد، بهترین راه حل اصلاح ورودی‌های نادرست در فایل‌های .info و/یا unified\-diff\-file است. با این حال، اگر اصلاح این ورودی‌ها امکان‌پذیر نباشد، می‌توانید از این گزینه برای تلاش جهت دور زدن خودکار آن‌ها استفاده کنید. .sp هنگامی که این گزینه مشخص شود، genhtml وانمود خواهد کرد که ورودی unified\-diff\-file با ورودی‌های فایل .info مطابقت دارد اگر: .INDENT 7.0 .IP \(bu 2 همان مسیر در هر دو فایل .info مربوط به «baseline» و «current» یافت شود، و .IP \(bu 2 نام پایه (basename) مسیر در فایل .info و مسیر در unified\-diff\-file یکسان باشد، و .IP \(bu 2 تنها یک ورودی تطبیق‌نیافته unified\-diff\-file با آن basename وجود داشته باشد. .UNINDENT .sp برای بحث در مورد نحوه جلوگیری از هشدارهای کاذب و/یا تطبیق‌های نادرست، به مدخل‌های \fB\-\-diff\-file\fP و \fB\-\-build\-directory\fP مراجعه کنید. .TP .B \fB\-\-synthesize\-missing\fP در صورتی که فایل منبع وجود نداشته باشد، محتوای فایل ساختگی (جعلی) تولید می‌کند. این گزینه می‌تواند برای دور زدن خطاهای حاشیه‌نویسی که در غیر این صورت مهلک هستند، استفاده شود. .sp هنگام تولید محتوای فایل حاشیه‌نویسی‌شده، \fBgenhtml\fP فرض می‌کند که منبع «اکنون» (now) نوشته شده است (بنابراین سن آن صفر است)، نویسنده \fIno.body\fP است و شناسه کامیت برابر با \fIsynthesized\fP\& می‌باشد. این نام‌ها و سن‌ها در گزارش‌های HTML شما ظاهر خواهند شد. .sp این گزینه معادل پارامتر \fIgenhtml_synthesize_missing\fP در فایل پیکربندی است؛ برای جزئیات به \fBlcovrc(5) \%\fP مراجعه کنید. .TP .B \fB\-\-date\-bins\fP \fIday[,day,…]\fP گزینه \fB\-\-date\-bins\fP برای تعیین مرزهای سن یا زمان (نقاط برش) جهت دسته‌بندی بر اساس بازه زمانی (date-binning) استفاده می‌شود. انتظار می‌رود هر عنصر \fIage\fP یک عدد صحیح از روزهای قبل از امروز (یا قبل از متغیر محیطی SOURCE_DATE_EPOCH شما، در صورت تنظیم) باشد. اگر \fI–date\-bins\fP مشخص نشود، حالت پیش‌فرض استفاده از ۴ بازه سنی است: کمتر از ۷ روز، ۷ تا ۳۰ روز، ۳۰ تا ۱۸۰ روز، و بیش از ۱۸۰ روز. این گزینه معادل گزینه \fIgenhtml_date_bins\fP در فایل پیکربندی است. به \fBlcovrc(5) \%\fP\& مراجعه کنید. .sp این آرگومان در صورت عدم وجود \fIsource\-annotation\-script\fP\& هیچ تأثیری ندارد. .TP .B \fB\-\-date\-labels\fP \fIstring[,string,…]\fP گزینه \fB\-\-date\-labels\fP برای تعیین برچسب‌های مورد استفاده در مدخل‌های جدول «date\-bin» در گزارش HTML به کار می‌رود. تعداد برچسب‌ها باید یکی بیشتر از تعداد نقاط برش باشد. در صورت عدم تعیین، پیش‌فرض استفاده از رشته‌های برچسبی است که بازه سنی \fI[from ..to)\fP نگه‌داری‌شده توسط bin مربوطه را مشخص می‌کنند. .sp یکی از کاربردهای ممکن این گزینه، استفاده از نام‌های انتشار (release) در جدول‌ها است \- \fIi.e.\fP، برای مشخص کردن انتشاری که هر خط خاص برای اولین بار در آن ظاهر شده است. .sp این گزینه معادل گزینه \fIgenhtml_date_labels\fP در فایل پیکربندی است. به \fBlcovrc(5) \%\fP\& مراجعه کنید. .sp این آرگومان در صورت عدم وجود \fIsource\-annotation\-script\fP\& هیچ تأثیری ندارد. .TP .B \fB\-\-show\-owners\fP [ \fIall\fP ] اگر از گزینه \fB\-\-show\-owners\fP استفاده شود، سربرگ هر گزارش پوشش شامل یک جدول خلاصه خواهد بود که آمار دسته‌های مختلف پوشش را برای هر فردی که در حاشیه‌نویسی سیستم کنترل نسخه به‌عنوان آخرین ویرایشگر خط مربوطه ظاهر شده، نمایش می‌دهد. اگر آرگومان اختیاری «all» مشخص نشود، جدول تنها کاربرانی را نشان می‌دهد که مسئول خطوط کد اجرا‌نشده هستند. اگر آرگومان اختیاری مشخص شود، کاربرانی که مسئول هر خطی از کد هستند نمایش داده خواهند شد. در هر دو حالت، کاربرانی که مسئول خطوط غیرکد (مانند توضیحات) هستند نشان داده نمی‌شوند. این گزینه در صورتی که از \fB\-\-annotate\-script\fP استفاده نشود هیچ کاری انجام نمی‌دهد؛ چرا که به اطلاعات کنترل نسخه ارائه‌شده از طریق فراخوانی اسکریپت نیاز دارد. .sp لطفاً توجه داشته باشید: اگر گزینه \fIall\fP مشخص نشده باشد، جدول خلاصه شامل ردیف‌های «Total» برای تمام دسته‌های تاریخ/مالک که خالی نیستند خواهد بود \- اما هیچ مدخل فرعی «File/Directory» برای مواردی که هیچ نقطه پوشش از دست‌رفته‌ای («missed») ندارند وجود نخواهد داشت. .sp این گزینه معادل پارامتر \fIgenhtml_show_owner_table\fP در فایل پیکربندی است؛ برای جزئیات به \fBlcovrc(5) \%\fP مراجعه کنید. .sp دستورات کنترلی \fIowner_table_entries\fP و \fItruncate_owner_table\fP در lcovrc می‌توانند برای بهبود خوانایی از طریق محدود کردن تعداد نویسندگانی که در جدول نمایش داده می‌شوند هنگام بالا بودن تعداد آن‌ها، استفاده شوند. برای مثال، اگر پیکربندی شما چنین باشد: .INDENT 7.0 .INDENT 3.5 \fIowner_table_entries\fP = 5 .sp \fItruncate_owner_table\fP = top,directory .UNINDENT .UNINDENT .sp آنگاه جدول مالکان نمایش‌داده‌شده در سطوح بالا (top) و دایرکتوری کوتاه و محدود خواهد شد، در حالی که جدول نمایش‌داده‌شده در سطح فایل («file») فهرست کامل را نشان می‌دهد. .sp برای جزئیات به \fBlcovrc(5) \%\fP مراجعه کنید. .TP .B \fB\-\-show\-noncode\fP به‌طور پیش‌فرض، نمای جزئیات کد منبع، حاشیه‌نویسی‌های مالک یا تاریخ را در دورترین ستون سمت چپ برای خطوط غیرکد (\fIe.g.\fP، توضیحات) نمایش نمی‌دهد. اگر از گزینه \fB\-\-show\-noncode\fP استفاده شود، نمای کد منبع حاشیه‌نویسی‌ها را برای هر دو خطوط کد و غیرکد نشان خواهد داد. این آرگومان در صورت عدم وجود \fIsource\-annotation\-script\fP\& هیچ تأثیری ندارد. .sp این گزینه معادل پارامتر \fIgenhtml_show_noncode_owners\fP در فایل پیکربندی است؛ برای جزئیات به \fBlcovrc(5) \%\fP مراجعه کنید. .TP .B \fB\-\-show\-zero\-columns\fP به‌طور پیش‌فرض، ستون‌هایی که تمام ورودی‌های آن‌ها صفر است از جدول خلاصه در بالای هر صفحه HTML حذف می‌شوند (نشان داده نمی‌شوند). اگر از گزینه \fB\-\-show\-zero\-columns\fP استفاده شود، آن ستون‌ها نمایش داده خواهند شد. .sp هنگامی که ستون‌ها حفظ شوند، همه جداول عرض یکسانی خواهند داشت یا حاوی تعداد ستون‌های یکسانی خواهند بود \- که ممکن است در برخی موقعیت‌ها یک مزیت به شمار آید. .sp هنگامی که ستون‌ها حذف شوند، جداول جمع‌وجورتر بوده و خواندن آن‌ها آسان‌تر است. این موضوع به‌ویژه در محیط‌های توسعه نسبتاً بالغ که در آن‌ها نقاط پوشش اجرا‌نشده در پروژه بسیار کم است، صادق است. .TP .B \fB\-\-show\-navigation\fP به‌طور پیش‌فرض در گزارش‌های پوشش غیرتفاضلی، جدول خلاصه در نمای جزئیات کد منبع شامل هایپرلینک‌هایی از شماره به اولین خط در دسته مربوطه («Hit» یا «Missed») و از مکان فعلی به مکان بعدی در دسته فعلی نیست. (این نمای سنتی یا «legacy» مربوط به گزارش‌های غیرتفاضلی lcov است.) .sp اگر از گزینه \fB\-\-show\-navigation\fP استفاده شود، جدول خلاصه کد منبع همراه با پیوندهای ناوبری ایجاد می‌شود. هایپرلینک‌ها همواره برای گزارش‌های پوشش تفاضلی ایجاد می‌شوند. .sp این ویژگی به توسعه‌دهندگان امکان می‌دهد مشکلات پوشش را سریع‌تر از حالتی که مجبور به پیمایش و اسکرول باشند، بیابند و درک کنند. .sp برای توضیحی درباره یک باگ مرورگر که این هایپرلینک‌ها را در شرایط خاص غیرفعال می‌کند، به توضیحات \fI–frames\fP در بالا مراجعه کنید. .sp پیوندهای ناوبری همیشه در گزارش پوشش تفاضلی فعال هستند. .TP .B \fB\-\-show\-proportions\fP در جدول «جزئیات پوشش توابع» (function coverage detail)، درصد خطوط و انشعاب‌های درون تابع را نیز که اجرا شده‌اند نشان می‌دهد. .sp این ویژگی توسعه‌دهندگان را قادر می‌سازد تا توجه خود را بر روی توابعی متمرکز کنند که بیشترین تأثیر را بر کل پوشش کد دارند. .sp این ویژگی به‌طور پیش‌فرض غیرفعال است. توجه داشته باشید که این گزینه مستلزم استفاده از نسخه‌ای از کامپایلر است که به اندازه کافی جدید باشد تا از گزارش‌های خط شروع/پایان تابع پشتیبانی کند یا اینکه ابزار را برای استخراج داده‌های مورد نیاز پیکربندی کنید \- به بحث \fIderive_function_end_line\fP در \fBlcovrc(5) \%\fP\& مراجعه کنید. .TP .B \fB\-\-simplified\-colors\fP به‌طور پیش‌فرض، هر دسته تفاضلی در نمای جزئیات کد منبع به‌طور منحصربه‌فردی رنگ‌آمیزی می‌شود. با این گزینه، تنها از دو رنگ استفاده می‌شود: یکی برای کد پوشش‌داده‌شده و دیگری برای کد پوشش‌داده‌نشده. توجه داشته باشید که کدهای ECB و EUB نه پوشش‌داده‌شده هستند و نه پوشش‌داده‌نشده \- بنابراین ممکن است تشخیص آن‌ها در نمای کد منبع دشوار باشد، زیرا با رنگ پس‌زمینه معمولی نمایش داده خواهند شد. .TP .B \fB\-\-exclude\fP \fIpattern\fP پارامتر pattern یک الگوی انطباق glob از نام‌فایل‌ها برای حذف از گزارش است. فایل‌هایی که با الگو مطابقت \fBندارند\fP در گزارش لحاظ خواهند شد. برای جزئیات به صفحه راهنمای lcov مراجعه کنید. .TP .B \fB\-\-include\fP \fIpattern\fP پارامتر pattern یک الگوی انطباق glob از نام‌فایل‌ها برای گنجاندن در پردازش است. فایل‌هایی که مطابقت ندارند از گزارش کنار گذاشته خواهند شد. برای جزئیات به صفحه راهنمای lcov مراجعه کنید. .TP .B \fB\-\-erase\-functions\fP \fIregexp\fP داده‌های پوشش را از خطوطی که درون تابعی قرار دارند که نام آن با regexp ارائه‌شده مطابقت دارد، حذف می‌کند. توجه داشته باشید که این نام، بسته به استفاده یا عدم استفاده از گزینه \fB\-\-demangle\-cpp\fP، نام mangled یا demangled خواهد بود. .sp توجه داشته باشید که این گزینه نیازمند استفاده از نسخه‌ای از کامپایلر است که به اندازه کافی جدید باشد تا از گزارش‌های خط شروع/پایان تابع پشتیبانی کند یا اینکه ابزار را برای استخراج داده‌های مورد نیاز پیکربندی کنید \- به بحث \fIderive_function_end_line\fP در \fBlcovrc(5) \%\fP\& مراجعه کنید. .TP .B \fB\-\-substitute\fP \fIregexp_pattern\fP عبارت باقاعده پرل \fIregexp_pattern\fP را روی نام‌های فایل منبع که در حین پردازش یافت شده‌اند اعمال می‌کند. این گزینه زمانی مفید است که برخی مسیرهای فایل در فایل .info پایه (baseline) یا فعلی (current) با چیدمان منبع شما مطابقت نداشته و در نتیجه کد منبع یافت نمی‌شود. برای جزئیات بیشتر به صفحه راهنمای lcov مراجعه کنید. .sp توجه داشته باشید که الگوهای جایگزینی بر روی مدخل‌های \fI–diff\-file\fP و همچنین فایل‌های .info پایه و فعلی اعمال می‌شوند. .TP .B \fB\-\-omit\-lines\fP \fIregexp_pattern\fP داده‌های پوشش را از خطوطی که محتوای آن‌ها با \fIregexp\fP\& مطابقت دارد حذف می‌کند. .sp اگر می‌خواهید داده‌های پوشش خط و انشعاب را برای برخی ساختارهای خاص در کد خود (\fIe.g.\fP، یک ماکروی پیچیده) نادیده بگیرید، از این سوئیچ استفاده کنید. برای جزئیات به صفحه راهنمای lcov مراجعه کنید. .TP .B \fB\-\-parallel\fP [\fIinteger\fP], \fB\-j\fP [\fIinteger\fP] میزان موازی‌سازی مورد استفاده در طول پردازش را مشخص می‌کند (حداکثر تعداد فرآیندهای فرزند ایجادشده با fork). اگر پارامتر اختیاری عدد صحیح موازی‌سازی صفر باشد یا مشخص نشود، از تمام هسته‌های موجود در سیستم استفاده می‌شود. پیش‌فرض، استفاده از یک فرآیند واحد است (بدون موازی‌سازی). .sp همچنین مدخل‌های \fImemory, memory_percentage, max_fork_fails\fP و \fIfork_fail_timeout\fP را در \fBlcovrc(5) \%\fP\& ببینید. .sp یک نمایه (profile) اجرای از پیش تولیدشده ممکن است به استفاده بهتر از منابع و اجرای موازی سریع‌تر کمک کند. بخش‌های \fI–profile\fP و \fI–history\-script\fP در این صفحه راهنما را ببینید. .TP .B \fB\-\-memory\fP \fIinteger\fP حداکثر مقدار حافظه مورد استفاده در طول پردازش موازی را بر حسب مگابایت (Mb) مشخص می‌کند. در عمل، اگر این محدودیت نقض شود، فرآیند ()fork را انجام نخواهد داد. مقدار پیش‌فرض 0 (صفر) است \- که به معنای عدم وجود محدودیت می‌باشد. .sp این گزینه ممکن است زمانی مفید باشد که محیط مزرعه محاسباتی (compute farm) محدودیت‌های سفت‌وسختی بر مصرف منابع اعمال می‌کند، به‌گونه‌ای که اگر کار تلاش کند فرآیندهای فرزند موازی بیش از حدی ایجاد کند متوقف (kill) خواهد شد \- اما کاربر از قبل نمی‌داند حداکثر مجاز چقدر است. این گزینه ابزار را قادر می‌سازد از حداکثر موازی‌سازی ممکن \- تا سقف تعیین‌شده توسط محدودیت حافظه \- استفاده کند. .sp گزینه \fImemory_percentage\fP در فایل پیکربندی روش دیگری را برای تعیین حداکثر مصرف حافظه ارائه می‌دهد. برای جزئیات به راهنمای \fBlcovrc (5)\fP مراجعه کنید. .TP .B \fB\-\-filter\fP \fIfilters\fP فهرستی از فیلترهای نقاط پوشش (coverpoint filters) را برای اعمال روی داده‌های ورودی مشخص می‌کند. .sp توجه داشته باشید که برخی فیلترها تنها برای فایل‌های منبع C/C++ اعمال می‌شوند. \fBgenhtml\fP پسوند فایل (مانند «.c»، «.vhd»، \fIetc.\fP) را با زبان منبع آن مرتبط می‌سازد. برای توضیحات مربوط به ارتباط‌های پیش‌فرض و نحوه تغییر آن‌ها، به بخش‌های \fIc_file_extensions\fP و \fIrtl_file_extensions\fP در \fBlcovrc(5) \%\fP مراجعه کنید. .sp توجه داشته باشید که فیلترها در صورت لزوم بر روی هر دو نقاط پوشش «branch» و «MC/DC» اعمال می‌شوند: اگر یک فیلتر خاص انشعابی را حذف کند، نقاط پوشش MC/DC متناظر را نیز حذف خواهد کرد \- برای مثال، \fI–filter branch\fP در صورتی که هیچ عبارت شرطی در خط مربوطه نباشد، نقاط پوشش MC/DC را حذف می‌کند، و \fI–filter branch_region\fP هر دو نقاط پوشش انشعاب و MC/DC را در ناحیه نشانه‌گذاری‌شده حذف خواهد کرد. .sp بیشتر فیلترها به کد منبع نیاز دارند؛ در صورتی که فایل منبع در دسترس نباشد، فیلترها اعمال نمی‌شوند. به‌طور مشابه، برای هر فایل منبع، اگر نسخه ثبت‌شده در داده‌های پوشش (فایل «.info») با نسخه موجود در سیستم‌فایل مطابقت نداشته باشد، یک خطای \fIversion\fP گزارش می‌شود. در صورت نادیده گرفتن خطای \fIversion\fP، فیلترسازی روی فایل ناسازگار اعمال نمی‌شود. برای اطلاعات بیشتر به \fI–version\-script\fP مراجعه کنید. .sp مقدار \fIfilters\fP می‌تواند فهرستی از کلیدواژه‌های زیر باشد که با کاما از یکدیگر جدا شده‌اند: .INDENT 7.0.TP .B branch: نادیده گرفتن شمارش انشعاب‌ها برای خطوط کد منبع C/C++ که به نظر نمی‌رسد شامل عبارات شرطی باشند. این انشعاب‌ها ممکن است به طور خودکار توسط کامپایلر تولید شده باشند (\fIبرای نمونه\fP، از طریق مدیریت استثنائات در C++) \- و برای کاربران اهمیتی ندارند. این گزینه هیچ تأثیری ندارد مگر اینکه از \fB\-\-branch\-coverage\fP استفاده شده باشد. .sp همچنین ببینید \fBlcovrc(5) \%\fP \- که چندین متغیر مؤثر بر پالایش انشعاب را شرح می‌دهد: \fIfilter_lookahead\fP و \fIfilter_bitwise_conditional\fP\&. .sp رایج‌ترین کاربرد برای پالایش انشعاب، حذف انشعاب‌های تولیدشده توسط کامپایلر مربوط به گرداننده‌های استثنای C++ است. برای روشی جهت حذف تمامی انشعاب‌های استثنای شناسایی‌شده، گزینه no_exception_branch را در \fBlcovrc(5) \%\fP ببینید. .TP .B brace: نادیده گرفتن شمارش پوشش خطی روی آکولاد بسته بلوک کد C/C++، در صورتی که خط فقط شامل یک آکولاد بسته باشد و خط قبلی شمارش یکسانی داشته باشد یا اگر آکولاد بسته شمارش صفر داشته و خط قبلی شمارش غیرصفر داشته باشد، یا آکولاد بسته بدنه یک عبارت شرطی نباشد. .sp به نظر می‌رسد این خطوط در خروجی gcov ظاهر و ناپدید می‌شوند \- و باعث می‌شوند پوشش تفاضلی (differential coverage) مقادیر ساختگی برای LBC و/یا GIC و/یا UIC گزارش کند. شمارش ساختگی LBC یا UIC مشکل‌ساز است زیرا ارزیابی پسرفت خودکاری که از معیار قبولی «LBC + UIC + UNC == 0» استفاده می‌کند، شکست خواهد خورد. .TP .B blank: نادیده گرفتن خطوطی که فقط شامل نویسه‌های فاصله خالی (یا فاصله خالی + کامنت‌ها) هستند و شمارش «اصابت» (hit) آن‌ها صفر است. به نظر می‌رسد این موارد آثار ساختگی در gcov و مربوط به کدهای تولیدشده توسط کامپایلر باشند \- مانند گرداننده‌های استثنا و فراخوانی مخرب‌ها در انتهای حوزه (scope) \- و می‌توانند معیارهای پوشش تفاضلی را دچار سردرگمی کنند. .sp اگر گزینه \fIfilter_blank_aggressive\fP = 1 در lcovrc فعال باشد، خطوط خالی صرف‌نظر از اینکه شمارش «اصابت» آن‌ها صفر باشد یا خیر، نادیده گرفته خواهند شد. پالایش تهاجمی ممکن است در داده‌های پوشش تولیدشده توسط LLVM که معمولاً شامل تعداد زیادی از این خطوط است، مفید باشد. .TP .B directive: نادیده گرفتن خطوطی که شبیه به پیش‌پردازنده‌های کامپایلر C هستند: #ifdef، #include، #define و \fIغیره\fP. این خطوط گاهی اوقات توسط \fIllvm\-cov\fP هنگام تبدیل داده‌های پروفایل LLVM به قالب LCOV گنجانده می‌شوند. .TP .B exception: مستثنی کردن انشعاب‌های مربوط به مدیریت استثنائات C++ از پوشش انشعاب. شناسایی و حذف انشعاب‌های استثنای C++ به نشانه‌گذاری صحیح آن‌ها توسط کامپایلر/زنجیره‌ابزار شما در داده‌های پوشش تولیدشده بستگی دارد. بخش \fIno_exception_branch\fP در \fBlcovrc(5) \%\fP را ببینید. .TP .B initializer: مستثنی کردن خطوطی که به نظر می‌رسد بخشی از یک std::initializer_list در C++ هستند. .TP .B line: نام مستعار برای «–filter brace,blank». .TP .B mcdc: حذف نقطه پوشش (coverpoint) مربوط به MC/DC که شامل یک عبارت واحد است، در صورتی که نقطه پوشش ‘branch’ در همان خط وجود داشته باشد. نقاط پوشش تک‌عنصری MC/DC با انشعاب متناظر یکسان هستند \- به جز در مواردی که ارزیابی عبارت در زمان کامپایل انجام می‌شود، به عنوان نمونه در یک تابع قالب (template function). .TP .B orphan: حذف انشعاب‌هایی که به صورت تنها و مجزا ظاهر می‌شوند \- \fIیعنی\fP انشعاب فقط یک مقصد دارد و بنابراین نمی‌تواند یک شرط باشد. .sp این موارد بیشتر در نتیجه پالایش انشعاب‌های استثنا رخ می‌دهند. .TP .B range: نادیده گرفتن نقاط پوشش خط و انشعاب در خطوط خارج از محدوده/خطوطی که شماره خط آن‌ها فراتر از انتهای فایل مبدأ است. به نظر می‌رسد این موارد آثار ساختگی gcov ناشی از نمونه‌سازی ماکرو در آخرین خط فایل باشند. .TP .B region: اعمال دستورات LCOV_EXCL_START/LCOV_EXCL_STOP/LCOV_EXCL_LINE و LCOV_UNREACHABLE_START/LCOV_UNREACHABLE_STOP/LCOV_UNREACHABLE_LINE موجود در متن منبع روی نقاط پوشش یافت‌شده در فایل‌های info. فعلی و پایه (baseline). این گزینه ممکن است در مواردی که کد منبع در طول ‘lcov –capture …’ یافت نشده اما اکنون در دسترس است، مفید باشد. .TP .B branch_region: اعمال دستورات LCOV_EXCL_BR_START/LCOV_EXCL_BR_STOP/LCOV_EXCL_BR_LINE موجود در متن منبع روی نقاط پوشش یافت‌شده در فایل‌های info. فعلی و پایه (baseline). این گزینه مشابه گزینه ‘region در بالا است \- اما فقط روی نقاط پوشش انشعاب اعمال می‌شود. .TP .B function: ترکیب داده‌ها برای هر تابع «یکتا» که در همان فایل/خط تعریف شده است. به نظر می‌رسد \fIgeninfo/gcov\fP دارای اشکالی هستند که برای یک تابع چندین مدخل ایجاد می‌کنند. این قابلیت همچنین تمامی نمونه‌های یک تابع قالب/متد قالب یکسان را ادغام می‌کند. .TP .B trivial: حذف توابع بدیهی (trivial) و نقاط پوشش مرتبط با آن‌ها. توابع «بدیهی» توابعی هستند که بدنه آن‌ها خالی است یا شامل هیچ دستوری نیستند. معمولاً این توابع شامل متدهای تولیدشده توسط کامپایلر (\fIبرای نمونه\fP سازنده‌های پیش‌فرض و عملگرهای انتساب) و همچنین بسته‌بندی‌های مقداردهی اولیه ایستا و غیره هستند. .sp توجه داشته باشید که پالایه \fItrivial\fP نیازمند اطلاعات خط پایانی تابع است \- و بنابراین مستلزم آن است که از نسخه کامپایلری استفاده کنید که به اندازه کافی جدید باشد تا از گزارش‌های خط شروع/پایان پشتیبانی کند (\fIبرای نمونه\fP gcc/9 یا جدیدتر) یا اینکه به lcov/genhtml/geninfo امکان دهید تا این اطلاعات را استخراج کنند: .sp در \fBlcovrc(5) \%\fP، تنظیم \fIderive_function_end_line\fP و همچنین تنظیم \fItrivial_function_threshold\fP را ببینید. اولی برای فعال یا غیرفعال کردن محاسبه خط پایانی استفاده می‌شود، و دومی برای تغییر میزان نگاه‌به‌جلو (lookahead) جهت تعیین خالی بودن بدنه تابع به کار می‌رود. همچنین تنظیمات \fIlcov_filter_parallel\fP و \fIlcov_filter_chunk_size\fP را مشاهده کنید که ممکن است در صورت زیاد بودن تعداد فایل‌های پردازشی، عملکرد پردازنده را بهبود بخشند. .UNINDENT .TP .B \fB\-o\fP, \fB\-\-output\-directory\fP \fIoutput\-directory\fP ایجاد فایل‌ها در \fIoutput\-directory\fP\&. .sp از این گزینه استفاده کنید تا به \fBgenhtml\fP بگویید فایل‌های حاصل را در دایرکتوری دیگری غیر از دایرکتوری فعلی بنویسد. اگر \fIoutput\-directory\fP وجود نداشته باشد، ایجاد خواهد شد. .sp توصیه می‌شود از این گزینه استفاده شود زیرا بسته به اندازه پروژه، ممکن است تعداد زیادی فایل و زیردایرکتوری ایجاد شود. .TP .B \fB\-t\fP, \fB\-\-title\fP \fItitle\fP نمایش \fItitle\fP در جدول سربرگ تمامی صفحات. .sp مقدار \fItitle\fP در فیلد «:Test» در جدول سربرگ بالای هر صفحه HTML تولیدشده نوشته می‌شود تا زمینه‌ای را که خروجی خاص در آن ایجاد شده است مشخص کند. به طور پیش‌فرض، این مقدار نام tracefile فعلی است. .sp یک کاربرد متداول، تعیین نام اجرای آزمون یا یک شناسه سیستم کنترل نسخه (برای مثال changelist در perforce یا SHA در git) است که سطح کدی را که آزمایش شده نشان می‌دهد. .TP .B \fB\-\-header\-title\fP \fIBANNER\fP نمایش \fIBANNER\fP در سربرگ تمام صفحات. .sp مقدار \fIBANNER\fP در بخش سربرگ هر صفحه HTML تولیدشده نوشته می‌شود. به طور پیش‌فرض، این بخش صرفاً این گزارش را به عنوان یک گزارش پوشش LCOV (تفاضلی) معرفی می‌کند. .sp یک کاربرد متداول، تعیین نام پروژه یا شاخه پروژه و شناسه ساخت Jenkins است. .TP .B \fB\-\-footer\fP \fIFOOTER\fP نمایش \fIFOOTER\fP در پاورقی تمام صفحات. .sp مقدار \fIFOOTER\fP در بخش پاورقی هر صفحه HTML تولیدشده نوشته می‌شود. پیش‌فرض صرفاً نسخه ابزار LCOV استفاده‌شده برای تولید گزارش را مشخص می‌کند. .TP .B \fB\-d\fP, \fB\-\-description\-file\fP \fIdescription\-file\fP خواندن توصیف‌های مورد آزمون از \fIdescription\-file\fP\&. .sp تمامی توصیف‌های مورد آزمون یافت‌شده در \fIdescription\-file\fP که در فایل داده‌های ورودی به آن‌ها ارجاع داده شده است، خوانده شده و در یک صفحه اضافی نوشته می‌شوند که سپس در خروجی HTML گنجانده می‌شود. .sp قالب فایل \fIdescription\-file\fP به صورت زیر است: .sp برای هر مورد آزمون: .INDENT 7.0 .INDENT 3.5 TN: TD: .UNINDENT .UNINDENT .sp نام‌های معتبر مورد آزمون می‌توانند شامل حروف، اعداد و نویسه زیرخط (‘_’) باشند. .TP .B \fB\-k\fP, \fB\-\-keep\-descriptions\fP عدم حذف توصیف‌های استفاده‌نشده آزمون. .sp توصیف‌های یافت‌شده در فایل توصیف حفظ می‌شوند، حتی اگر داده‌های پوشش نشان دهند که مورد آزمون مرتبط هیچ خطی از کد را پوشش نداده است. .sp این گزینه همچنین می‌تواند به صورت دائمی با استفاده از گزینه فایل پیکربندی \fIgenhtml_keep_descriptions\fP تنظیم شود. .TP .B \fB\-c\fP, \fB\-\-css\-file\fP \fIcss\-file\fP استفاده از فایل شیوه‌نامه خارجی \fIcss\-file\fP\&. .sp با استفاده از این گزینه، می‌توان یک فایل css. اضافی مشخص کرد که جایگزین فایل پیش‌فرض خواهد شد. این ممکن است در صورتی مفید باشد که رنگ‌های پیش‌فرض چشم‌های شما را اذیت کنند :) .sp این گزینه همچنین می‌تواند به صورت دائمی با استفاده از گزینه فایل پیکربندی \fIgenhtml_css_file\fP تنظیم شود. .TP .B \fB\-\-build\-directory\fP \fIdirname\fP برای پشتیبانی از ساختارهای «دایرکتوری ساخت پیوندشده»، افزودن ‘dirname’ به فهرست مکان‌های جستجو برای پیوندهای نمادین (soft links) به فایل‌های منبع \- \fIبرای نمونه\fP برای مدیریت حالتی که پیوندها به فایل‌های منبع نگهداری‌شده در سیستم کنترل نسخه شما اشاره می‌کنند و در داده‌های \fI\-\-diff\-file\fP ظاهر می‌شوند. در این حالت، مسیرها در داده‌های پوشش به احتمال بسیار زیاد به ساختار دیده‌شده توسط کامپایلر هنگام ساخت اشاره دارند \- بنابراین تطبیق مجدد آن‌ها با ساختار منبع متناظر در کنترل نسخه به احتمال زیاد موفقیت‌آمیز خواهد بود. .sp جستجو در \fIdirname\fP برای مسیرهای فایلی که در \fItracefile\fP ظاهر می‌شوند \- احتمالاً پس از اعمال جایگزینی‌ها \- و پیوند نمادین هستند. هم مسیر فایل اصلی و هم مسیر فایل پیوندشده به همان مدخل \fI\-\-diff\-file\fP متناظر ارجاع داده خواهند شد. .sp این گزینه را می‌توان چندین بار مشخص کرد تا دایرکتوری‌های بیشتری به مسیر جستجو اضافه شوند. .TP .B \fB\-\-source\-directory\fP \fIdirname\fP افزودن ‘dirname’ به فهرست مکان‌های جستجوی فایل‌های منبع. .sp برای مسیرهای نسبی فایل‌های منبع، \fIبرای نمونه\fP مسیرهای یافت‌شده در \fItracefile\fP یا در \fIdiff\-file\fP \- احتمالاً پس از اعمال جایگزینی‌ها \- \fBgenhtml\fP ابتدا مسیر را از مبدأ ‘cwd’ (جایی که genhtml اجرا شده است) و سپس از هر نام دایرکتوری جایگزین به ترتیب مشخص‌شده بررسی می‌کند. نخستین مکانی که مطابقت داشته باشد استفاده می‌شود. .sp این گزینه را می‌توان چندین بار مشخص کرد تا دایرکتوری‌های بیشتری به مسیر جستجوی منبع افزوده شوند. .TP .B \fB\-p\fP, \fB\-\-prefix\fP \fIprefix\fP حذف \fIprefix\fP از ابتدای تمام نام‌های دایرکتوری. .sp از آنجا که فهرست‌های حاوی نام‌های طولانی فایل به سختی خوانده می‌شوند، مکانیزمی پیاده‌سازی شده است که به طور خودکار تلاش می‌کند تمام نام‌های دایرکتوری در صفحه مرور کلی را که با یک پیشوند مشترک شروع می‌شوند، کوتاه کند. به طور پیش‌فرض، این کار با استفاده از الگوریتمی انجام می‌شود که پیشوندی را می‌یابد که با اعمال آن، مجموع تعداد نویسه‌های حاصل از تمام نام‌های دایرکتوری به حداقل برسد. .sp از این گزینه برای مشخص کردن پیشوندی که می‌خواهید توسط خودتان حذف شود استفاده کنید. .TP .B \fB\-\-no\-prefix\fP عدم حذف پیشوند از نام‌های دایرکتوری. .sp این سوییچ مکانیزم پیشوند توضیح داده شده در بخش قبلی را به طور کامل غیرفعال می‌کند. .sp این گزینه همچنین می‌تواند به صورت دائمی با استفاده از گزینه فایل پیکربندی \fIgenhtml_no_prefix\fP تنظیم شود. .TP .B \fB\-\-no\-source\fP عدم ایجاد نمای کد منبع. .sp اگر نمی‌خواهید برای هر فایل یک نمای کد منبع داشته باشید، از این سوییچ استفاده کنید. .sp این گزینه همچنین می‌تواند به صورت دائمی با استفاده از گزینه فایل پیکربندی \fIgenhtml_no_source\fP تنظیم شود. .TP .B \fB\-\-no\-html\fP عدم ایجاد گزارش HTML. .sp اگر خروجی خاصی از فرایند تولید گزارش پوشش را می‌خواهید \- \fIبرای نمونه\fP بررسی معیارهای پوشش یا پایگاه‌داده سریالی‌شده پوشش و \fIغیره\fP \- اما خود گزارش HTML پوشش را نیاز ندارید، از این سوییچ استفاده کنید. .TP .B \fB\-\-num\-spaces\fP \fIspaces\fP تغییر ظاهر تب‌ها در نمای منبع بر اساس \fIspaces\fP\&. .sp در صورت تنظیم روی 0، تب‌ها و رفتار آن‌ها بر اساس پیش‌فرض مرورگر خواهد بود. .sp مقادیر منفی، پهنای نمایش‌داده‌شده را در نمای منبع به تعداد \fIspaces\fP فاصله (space) تنظیم می‌کنند. .sp مقادیر مثبت، تب‌ها را با \fIspaces\fP فاصله جایگزین خواهند کرد. .sp مقدار پیش‌فرض 8 است. .sp این گزینه همچنین می‌تواند به صورت دائمی با استفاده از گزینه فایل پیکربندی \fIgenhtml_num_spaces\fP تنظیم شود. .TP .B \fB\-\-highlight\fP برجسته‌سازی خطوط دارای داده‌های پوشش که فقط تبدیل شده‌اند (converted-only). .sp از این گزینه در کنار گزینه \fB\-\-diff\fP در \fBlcov\fP استفاده کنید تا خطوطی را برجسته کنید که فقط در مجموعه‌داده‌های تبدیل‌شده از نسخه‌های پیشین کد منبع پوشش داده شده‌اند. .sp این گزینه همچنین می‌تواند به صورت دائمی با استفاده از گزینه فایل پیکربندی \fIgenhtml_highlight\fP تنظیم شود. .TP .B \fB\-\-legend\fP گنجاندن راهنمای رنگ‌ها در خروجی HTML. .sp از این گزینه استفاده کنید تا راهنمایی که مفهوم کدگذاری رنگ‌ها را شرح می‌دهد در خروجی HTML حاصل گنجانده شود. .sp این گزینه همچنین می‌تواند به صورت دائمی با استفاده از گزینه فایل پیکربندی \fIgenhtml_legend\fP تنظیم شود..TP .B \fB\-\-html\-prolog\fP \fIprolog\-file\fP خواندن دیباچه (prolog) سفارشی HTML از \fIprolog\-file\fP\&. .sp از این گزینه برای جایگزینی دیباچه پیش‌فرض HTML (بخش ابتدایی کد منبع HTML تا و با احتساب برچسب ) با محتویات \fIprolog\-file\fP استفاده کنید. در متن prolog، هنگام تولید یک صفحه، کلمات زیر جایگزین خواهند شد: .INDENT 7.0 .TP .B \fB@pagetitle@\fP عنوان صفحه. .TP .B \fB@basedir@\fP یک مسیر نسبی به دایرکتوری پایه (\fIمثلاً\fP برای یافتن فایل‌های css). .UNINDENT .sp این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی \fIgenhtml_html_prolog\fP در فایل پیکربندی به طور دائم تنظیم شود. .TP .B \fB\-\-html\-epilog\fP \fIepilog\-file\fP خواندن مؤخره (epilog) سفارشی HTML از \fIepilog\-file\fP\&. .sp از این گزینه برای جایگزینی مؤخره پیش‌فرض HTML (بخش پایانی کد منبع HTML شامل ) با محتویات \fIepilog\-file\fP استفاده کنید. .sp درون متن مؤخره، هنگام تولید یک صفحه، کلمات زیر جایگزین خواهند شد: .INDENT 7.0 .TP .B \fB@basedir@\fP یک مسیر نسبی به دایرکتوری پایه (\fIمثلاً\fP برای یافتن فایل‌های css). .UNINDENT .sp این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی \fIgenhtml_html_epilog\fP در فایل پیکربندی به طور دائم تنظیم شود. .TP .B \fB\-\-html\-extension\fP \fIextension\fP استفاده از پسوند فایل سفارشی برای صفحه‌های HTML تولیدشده. .sp این گزینه در مواردی مفید است که برای رندر صحیح صفحات حاصل، به پسوندهای نام فایل متفاوتی نیاز باشد (\fIمثلاً\fP php). توجه داشته باشید که یک «.» بین نام فایل و پسوند مشخص‌شده با این گزینه درج خواهد شد. .sp این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی \fIgenhtml_html_extension\fP در فایل پیکربندی به طور دائم تنظیم شود. .TP .B \fB\-\-html\-gzip\fP فشرده‌سازی تمام فایل‌های html تولیدشده با gzip و افزودن یک فایل .htaccess که gzip\-encoding را مشخص می‌کند در دایرکتوری خروجی ریشه. .sp اگر می‌خواهید در فضای وب‌سرور خود صرفه‌جویی کنید از این گزینه استفاده نمایید. این قابلیت نیازمند وب‌سروری با پشتیبانی از .htaccess و مرورگری با پشتیبانی از html فشرده‌شده با gzip است. .sp این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی \fIgenhtml_html_gzip\fP در فایل پیکربندی به طور دائم تنظیم شود. .TP .B \fB\-\-sort\-tables\fP, \fB\-\-no\-sort\fP مشخص کردن اینکه آیا نماهای مرتب‌شده از نمای کلی فایل‌ها و دایرکتوری‌ها گنجانده شود یا خیر. .sp از \fB\-\-sort\-tables\fP برای گنجاندن نماهای مرتب‌شده یا از \fB\-\-no\-sort\fP برای عدم درج آن‌ها استفاده کنید. نماهای مرتب‌شده به طور پیش‌فرض \fBفعال\fP هستند. .sp هنگامی که نماهای مرتب‌شده فعال باشند، هر صفحه نمای کلی شامل پیوندهایی به نماهایی از آن صفحه خواهد بود که بر اساس نرخ پوشش مرتب شده‌اند. .sp این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی \fIgenhtml_sort\fP در فایل پیکربندی به طور دائم تنظیم شود. .TP .B \fB\-\-function\-coverage\fP, \fB\-\-no\-function\-coverage\fP مشخص کردن نمایش یا عدم نمایش خلاصه‌های پوشش توابع در خروجی HTML. .sp از \-\-function\-coverage برای فعال‌سازی خلاصه‌های پوشش توابع یا از \-\-no\-function\-coverage برای غیرفعال کردن آن استفاده کنید. خلاصه پوشش توابع به طور پیش‌فرض \fBفعال\fP است. .sp این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی \fIgenhtml_function_coverage\fP در فایل پیکربندی به طور دائم تنظیم شود. .sp هنگامی که خلاصه‌های پوشش توابع فعال باشند، هر صفحه نمای کلی شامل تعداد توابع یافت‌شده و فراخوانی‌شده (hit) به ازای هر فایل یا دایرکتوری، به همراه نرخ پوشش حاصل خواهد بود. علاوه بر این، هر نمای کد منبع شامل پیوندی به صفحه‌ای خواهد بود که تمام توابع یافت‌شده در آن فایل به علاوه تعداد فراخوانی‌های مربوط به آن توابع را فهرست می‌کند. صفحه پوشش تابع، داده‌ها را برای هر نام مستعار (alias) از هر تابع گروه‌بندی کرده و بر اساس نام یا تعداد اجرا مرتب می‌کند. نام نمایانگر گروه توابع، کوتاه‌ترین نام است (\fIیعنی\fP دارای کمترین نویسه است). .sp در صورت استفاده از پوشش تفاضلی (differential coverage) و نسخه کامپایلر به اندازه کافی جدید که هم خط شروع و هم خط پایان توابع را گزارش می‌کند (\fIمثلاً\fP gcc/9 و جدیدتر)، توابعی که هر یک از خطوط کد منبع آن‌ها تغییر کرده باشد، «جدید» در نظر گرفته می‌شوند. با نسخه‌های قدیمی‌تر کامپایلر، توابع تنها در صورتی «جدید» در نظر گرفته می‌شوند که امضای تابع تغییر کرده باشد یا کل تابع جدید باشد. .TP .B \fB\-\-branch\-coverage\fP, \fB\-\-no\-branch\-coverage\fP مشخص کردن نمایش یا عدم نمایش داده‌های پوشش شاخه در خروجی HTML. .sp از \fB\-\-branch\-coverage\fP برای فعال‌سازی نمایش پوشش شاخه یا از \fB\-\-no\-branch\-coverage\fP برای غیرفعال کردن آن استفاده کنید. نمایش داده‌های پوشش شاخه به طور پیش‌فرض \fBغیرفعال\fP است. .sp هنگامی که نمایش پوشش شاخه فعال باشد، هر صفحه نمای کلی شامل تعداد شاخه‌های یافت‌شده و طی‌شده به ازای هر فایل یا دایرکتوری، به همراه نرخ پوشش حاصل خواهد بود. علاوه بر این، هر نمای کد منبع شامل یک ستون اضافی خواهد بود که تمام شاخه‌های یک خط را به همراه نشانگری مبنی بر اینکه آیا شاخه طی شده (taken) یا خیر فهرست می‌کند. شاخه‌ها در قالب زیر نشان داده می‌شوند: .INDENT 7.0 .INDENT 3.5 .sp .EX \(aq + \(aq: شاخه حداقل یک بار طی شده است \(aq \- \(aq: شاخه طی نشده است \(aq # \(aq: بلوک پایه‌ای شامل شاخه هرگز اجرا نشده است .EE .UNINDENT .UNINDENT .sp توجه داشته باشید که ممکن است همیشه ارتباط دادن شاخه‌ها به عبارت‌های متناظر در کد منبع ممکن نباشد: در طول کامپایل، GCC ممکن است برای تولید کد بهتر، شاخه‌ها را جابه‌جا کرده یا برخی از آن‌ها را حذف کند. .sp این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی \fIbranch_coverage\fP در فایل پیکربندی به طور دائم تنظیم شود. .TP .B \fB\-\-mcdc\-coverage\fP مشخص کردن نمایش داده‌های پوشش شرط/تصمیم اصلاح‌شده (MC/DC) در خروجی HTML. .sp نمایش داده‌های MC/DC به طور پیش‌فرض \fBغیرفعال\fP است. .sp پوشش MC/DC در نسخه‌های GCC 14.2 به بالا، یا LLVM 18.1 به بالا پشتیبانی می‌شود. .sp برای جزئیات مربوط به دریافت داده‌های MC/DC در LLVM به \fIllvm2lcov \-\-help\fP مراجعه کنید. .sp هنگامی که نمایش MC/DC فعال باشد، هر صفحه نمای کلی شامل تعداد عبارت‌های MC/DC یافت‌شده و اجراشده به ازای هر فایل یا دایرکتوری \- دو جهت به ازای هر عبارت \- به همراه نرخ پوشش حاصل خواهد بود. علاوه بر این، هر نمای کد منبع شامل یک ستون اضافی خواهد بود که تمام عبارات و جهت‌های شرط یک خط را به همراه نشانگری مبنی بر اینکه آیا شرط حساس شده (sensitized) است یا خیر، فهرست می‌کند. شرط‌ها در قالب زیر نمایش داده می‌شوند: .INDENT 7.0 .TP .B T: جهت True زیرعبارت حساس شده است: اگر مقدار این زیرعبارت false می‌بود، نتیجه شرط متفاوت می‌شد. .TP .B t: جهت True زیرعبارت حساس \fBنشده است\fP: در صورت متفاوت بودن مقدار زیرعبارت، نتیجه شرط تغییر نمی‌کرد. .TP .B F: جهت False زیرعبارت حساس شده است: اگر مقدار این زیرعبارت true می‌بود، نتیجه شرط متفاوت می‌شد. .TP .B f: جهت False زیرعبارت حساس \fBنشده است\fP: در صورت متفاوت بودن مقدار زیرعبارت، نتیجه شرط تغییر نمی‌کرد. .UNINDENT .sp توجه داشته باشید در صورتی که شرط یک عبارت ساده باشد، پوشش شاخه و MC/DC یکسان هستند \- \fIمثلاً\fP: .INDENT 7.0 .INDENT 3.5 .sp .EX if (enable) ... .EE .UNINDENT .UNINDENT .sp توجه داشته باشید که در صورت نیاز، فیلترها هم بر نقاط پوشش «branch» و هم بر نقاط پوشش «MC/DC» اعمال می‌شوند: اگر فیلتر خاصی شاخه‌ای را حذف کند، نقاط پوشش مربوط به MC/DC آن را نیز حذف خواهد کرد. بخش \fI\-\-filter\fP در بالا را ببینید. .sp این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی \fImcdc_coverage\fP در فایل پیکربندی به طور دائم تنظیم شود. به \fBlcovrc(5) \%\fP مراجعه کنید. .sp توجه داشته باشید که نقاط پوشش MC/DC توسط GCC و LLVM به طور متفاوتی تعریف می‌شوند. .INDENT 7.0 .TP .B GCC: حساسیت شرط را نسبت به مقادیر «true» و «false» برای هر عبارت تشکیل‌دهنده (برگ) به طور مستقل ارزیابی می‌کند. .sp به این معنی که: این پرسش را ارزیابی می‌کند: آیا اگر \fIاین\fP عبارت تشکیل‌دهنده از true به false (که در بالا جهت «true» نامیده شد) یا از false به true (که در بالا جهت «false» نامیده شد) تغییر کند، نتیجه شرط تغییر می‌کند؟ .sp برای مثال، عبارت \fIA || B\fP نسبت به \fIA==true\fP حساس است هنگامی که \fIB==false\fP باشد، اما هنگامی که \fIB==true\fP باشد نسبت به \fIA==true\fP حساس نیست. .TP .B LLVM: یک زیرعبارت را پوشش‌داده‌شده ثبت می‌کند اگر و تنها اگر جفتی از ارزیابی‌های شرط وجود داشته باشد به طوری که شرط برای هر دو مقدار «true» و «false» آن زیرعبارت حساس شده باشد. این در مستندات LLVM به عنوان یک \fIindependence pair\fP تعریف شده است. .sp به این معنی که: مورد آزمون برای اینکه توسط LLVM پوشش‌داده‌شده علامت‌گذاری شود باید هر دو مقدار را حساس کند، در حالی که GCC هر یک را به طور مستقل علامت‌گذاری خواهد کرد. در نتیجه: در گزارش‌های \fBlcov\fP تولیدشده توسط LLVM، یا هر دو حساس‌سازی «true» و «false» پوشش داده می‌شوند، یا هیچ‌کدام پوشش داده نخواهند شد. .sp مثال‌های موجود در مورد آزمون \fI…/tests/lcov/mcdc\fP را ببینید. .UNINDENT .TP .B \fB\-\-demangle\-cpp\fP [ \fIparam\fP ] مشخص کردن اینکه آیا نام توابع C++ رمزگشایی (demangle) شوند یا خیر. .sp اگر می‌خواهید نام‌های داخلی توابع C++ را برای نمایش در صفحه نمای کلی توابع HTML به قالبی خوانا برای انسان تبدیل کنید، از این گزینه استفاده نمایید. .sp در صورت فراخوانی بدون پارامتر، genhtml از \fIc++filt\fP برای رمزگشایی استفاده خواهد کرد. این نیازمند نصب بودن ابزار c++filt است (به \fBc++filt(1)\fP مراجعه کنید). .sp اگر \fIparam\fP مشخص شده باشد، به عنوان ابزاری در نظر گرفته می‌شود که باید برای رمزگشایی کد منبع فراخوانی شود. گزینه \fB\-\-demangle\-cpp\fP می‌تواند چندین بار برای مشخص کردن ابزار رمزگشایی و مجموعه‌ای از گزینه‌های خط فرمان که به ابزار ارسال می‌شوند استفاده شود \- مشابه نحوه عملکرد پارامتر \fI\-Xlinker\fP در gcc. در این حالت، فراخوان (callback) شما به صورت \fI| demangle_param0 demangle_param1 …\fP اجرا خواهد شد. توجه داشته باشید که ابزار demangle به عنوان یک لوله (pipe) فراخوانی می‌شود و انتظار می‌رود از stdin بخواند و در stdout بنویسد. .TP .B \fB\-\-msg\-log\fP [ \fIlog_file_name\fP ] مشخص کردن مکانی برای ذخیره پیام‌های خطا و هشدار (علاوه بر نوشتن در STDERR). اگر \fIlog_file_name\fP مشخص نشود، مکان پیش‌فرض استفاده خواهد شد. .TP .B \fB\-\-ignore\-errors\fP \fIerrors\fP مشخص کردن فهرستی از خطاها که پس از رخ دادن آن‌ها پردازش ادامه می‌یابد. .sp از این گزینه برای مشخص کردن فهرستی از کلاس‌های خطا استفاده کنید که پس از وقوع آن‌ها \fBgenhtml\fP باید به جای متوقف کردن عملیات، پردازش را با یک پیام هشدار ادامه دهد. برای فرونشاندن پیام هشدار، کلاس خطا را دوبار مشخص کنید. .sp \fIerrors\fP می‌تواند فهرستی از کلیدواژه‌های زیر باشد که با کاما از یکدیگر جدا شده‌اند: .INDENT 7.0 .TP .B annotate: دستور \fB\-\-annotate\-script\fP وضعیت خروج غیرصفر بازگردانده است \- احتمالاً خطای مسیر فایل یا خطایی مرتبط است. نمایش کد منبع HTML صحیح نخواهد بود و ممکن است اطلاعات مالکیت/تاریخ موجود نباشد. .TP .B branch: شناسه شاخه (دومین فیلد در مدخل «BRDA» فایل .info) از توالی مورد انتظار اعداد صحیح پیروی نمی‌کند. .TP .B callback: خطای اسکریپت annotate، version، یا criteria. .TP .B category: دسته‌بندی شماره خطوط در فایل .info نادرست است، بنابراین شماره خط مربوط به پوشش شاخه، یک خط اجرایی از کد منبع از آب درنمی‌آید. .TP .B child: فرآیند فرزند در حین اجرای \fI\-\-parallel\fP کد خروج غیرصفر بازگردانده است. این موضوع معمولاً نشان می‌دهد که فرآیند فرزند با خطایی مواجه شده است: فایل لاگ دقیقاً بالای این پیام را بررسی کنید. در مقابل: خطای \fIparallel\fP نشان‌دهنده یک استثنای غیرمنتظره/مدیریت‌نشده در فرآیند فرزند است \- نه یک خطای «معمول» lcov. .TP .B count: تعداد بیش از حدی از پیام‌ها برای کلاسی خاص گزارش شده است \- پیام‌های بعدی از آن نوع فرونشانده خواهند شد. این حد را می‌توان توسط متغیر «max_message_count» کنترل کرد. به \fBlcovrc(5) \%\fP مراجعه کنید. .TP .B corrupt: فایل داده‌های پوشش مخدوش/غیرقابل‌خواندن پیدا شده است..TP .B deprecated: شما در حال استفاده از یک گزینه منسوخ‌شده هستید. این گزینه در انتشار آتی حذف خواهد شد \- بنابراین باید اسکریپت‌های خود را همین حالا اصلاح کنید. .TP .B empty: فایل وصله (patch) مشخص‌شده توسط آرگومان \fB\-\-diff\-file\fP حاوی هیچ تفاوتی نیست. اگر هیچ تغییری در کد منبع بین «baseline» و «current» رخ نداده باشد (برای مثال، تنها تغییر، اصلاح یک Makefile بوده است) این حالت ممکن است مشکلی نداشته باشد \- یا ممکن است نشان‌دهنده یک قالب فایل پشتیبانی‌نشده باشد. .TP .B excessive: داده‌های پوشش آزمون شما شامل تعداد «hit» به طرز مشکوکی زیاد است که بعید است صحیح باشد \- احتمالاً نشان‌دهنده وجود باگ در زنجیره ابزار (toolchain) شما است. برای جزئیات بیشتر، بخش \fIexcessive_count_threshold\fP را در \fBlcovrc(5) \%\fP ببینید. .TP .B fork: ناتوان در ایجاد فرآیند فرزند در طول اجرای \fI–parallel\fP. .sp اگر این پیام نادیده گرفته شود (\fI–ignore\-errors fork\fP)، آن‌گاه genhtml مدت کوتاهی منتظر مانده و سپس اجرای ناموفق را دوباره امتحان می‌کند. .sp اگر همچنان با خطا مواجه می‌شوید، یا اجرای موازی را غیرفعال کرده یا کاهش دهید، یک محدودیت حافظه تعیین کنید، یا سرور بزرگ‌تری را برای اجرای این وظیفه اختصاص دهید. .TP .B format: سینتکس یا مقدار غیرمنتظره‌ای در فایل .info یافت شد \- برای نمونه، مواجهه با عدد منفی یا شماره خط صفر. .TP .B inconsistent: این خطا نشان می‌دهد که داده‌های پوشش شما به صورت درونی ناسازگار هستند: دو یا چند ادعای متناقض و مانعة‌الجمع وجود دارد. برای نمونه: .INDENT 7.0 .IP \(bu 2 فایل‌ها جابه‌جا شده‌اند یا تاریخچه مخزن ارائه‌شده توسط داده‌های \fB\-\-diff\-file\fP با داده‌های پوشش سازگار نیست؛ برای مثال، یک خطِ «درج‌شده» دارای داده‌های پوشش baseline است. این مشکلات احتمالاً ناشی از پردازش ناسازگار در داده‌های «diff» در مقایسه با داده‌های پوشش «baseline» و «current» است (برای نمونه، استفاده از نسخه‌های منبع متفاوت برای جمع‌آوری داده‌ها اما حاشیه‌نویسی نادرست آن تفاوت‌ها)، یا ناشی از رفتار ناسازگار در اسکریپت «annotate». استفاده از یک \fB\-\-version\-script\fP را برای جلوگیری از عدم تطابق نسخه‌ها مد نظر قرار دهید. .IP \(bu 2 دو یا چند فایل داده \fBgcov\fP یا فایل «.info» از \fBlcov\fP خطوط پایانی متفاوتی را برای یک تابع گزارش می‌کنند. این مسئله احتمالاً ناشی از یک باگ در gcc/gcov یا عدم تطابق نسخه کد منبع است. .INDENT 2.0 .INDENT 3.5 در این حالت، اگر خطای \fI“inconsistent”\fP نادیده گرفته شود، ابزار بزرگ‌ترین عدد را به عنوان خط پایان تابع ثبت خواهد کرد. .UNINDENT .UNINDENT .IP \(bu 2 دو یا چند فایل داده \fBgcov\fP یا فایل «.info» از \fBlcov\fP خطوط آغازین متفاوتی را برای یک تابع گزارش می‌کنند. این مسئله احتمالاً ناشی از یک باگ در gcc/gcov یا عدم تطابق نسخه کد منبع است. .INDENT 2.0 .INDENT 3.5 در این حالت، اگر خطای \fI“inconsistent”\fP نادیده گرفته شود، ابزار تنها نخستین تعریف تابعی را که پردازش کرده است نگه می‌دارد. .UNINDENT .UNINDENT .IP \(bu 2 رکوردهای اعلان تابع/نام مستعار ناهمخوان یافت شدند: .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 (قالب LCOV سازگار با نسخه‌های پیشین) رکورد شمارش اجرای تابع ( \fIFNDA\fP ) بدون رکورد اعلان تابع متناظر ( \fIFN\fP ). .IP \(bu 2 (قالب LCOV بهبودیافته) رکورد نام مستعار تابع ( \fIFNA\fP ) بدون رکورد اعلان تابع متناظر ( \fIFLN\fP ). .UNINDENT .UNINDENT .UNINDENT .IP \(bu 2 عبارت شاخه (فیلد سوم در مدخل «BRDA» فایل .info) مربوط به داده‌های ادغام همخوانی ندارد .INDENT 2.0 .INDENT 3.5 اگر این خطا نادیده گرفته شود، از رکورد خاطی صرف‌نظر می‌شود. .UNINDENT .UNINDENT .UNINDENT .TP .B internal: مشکل درونی ابزار شناسایی شد. لطفاً این باگ را به همراه یک مورد آزمون (testcase) گزارش دهید. .TP .B mismatch: اطلاعات نادرست یا ناسازگار در داده‌های پوشش و/یا کد منبع یافت شد \- برای نمونه، کد منبع شامل دستورالعمل‌های استثنای (exclusion directives) همپوشان است. .TP .B missing: تمام نقاط پوشش (coverpoints) مرتبط با فایل‌های منبعی که پیدا نشده‌اند یا خواندنی نیستند حذف می‌شوند. این عمل معادل افزودن یک الگوی \fI–exclude\fP برای هر فایلی است که پیدا نمی‌شود. .sp اگر یک فراخوان (callback) با \fI–resolve\-script\fP مشخص شده باشد، در صورتی که فایل به صورت محلی قابل مشاهده نباشد و فراخوان رشته خالی "" یا «undef» برگرداند، فایل به عنوان missing در نظر گرفته می‌شود \- در غیر این صورت missing تلقی نخواهد شد. .TP .B negative: تعداد دفعات اجرای («hit») منفی یافت شد. .sp توجه داشته باشید که مقادیر منفی ممکن است به دلیل یک باگ شناخته‌شده در GCC ایجاد شده باشند \- ببینید: .INDENT 7.0 .INDENT 3.5 .sp .EX https://gcc.gnu.org/bugzilla/show_bug.cgi?id=68080 .EE .UNINDENT .UNINDENT .sp و کامپایل کردن با «\-fprofile\-update=atomic» را امتحان کنید. لازم است کدها را مجدداً کامپایل کرده، آزمون‌های خود را دوباره اجرا نموده و داده‌های پوشش را دوباره ثبت کنید. .TP .B package: یک بسته perl مورد نیاز بر روی سیستم شما نصب نشده است. در برخی موارد، امکان نادیده گرفتن این پیام و ادامه کار وجود دارد \- هرچند در این حالت برخی ویژگی‌ها غیرفعال خواهند شد. .TP .B parallel: انواع مختلف خطاهای مربوط به پردازش موازی \- \fIبه عنوان مثال\fP یک فرآیند فرزند به دلیل خطا متوقف شده است. پیام خطای متناظر بلافاصله قبل از خطای \fIparallel\fP در فایل لاگ ظاهر می‌شود. اگر خطایی در رابطه با اجرای موازی مشاهده کردید که به نظر نامعتبر می‌رسد، شاید ایده خوبی باشد که پرچم –parallel را حذف کرده و دوباره امتحان کنید. اگر حذف این پرچم منجر به نتیجه متفاوتی شد، لطفاً مشکل را (به همراه یک مورد آزمون) گزارش دهید تا ابزار اصلاح شود. .TP .B path: نام فایل در فایل \fB\-\-diff\-file\fP وجود دارد اما در داده‌های ردگیری (trace) مربوط به baseline یا current مشاهده نمی‌شود. این موارد ممکن است ناشی از مشکلات نگاشت (mapping) باشد \- مانند تفاوت مسیر فایل در tracefile در مقایسه با فایل diff. .TP .B range: داده‌های پوشش به شماره خطی اشاره دارند که از تعداد خطوط موجود در فایل منبع بزرگ‌تر است. این مشکل می‌تواند ناشی از عدم تطابق نسخه یا اشکالی در داده‌های \fIgcov\fP باشد. .TP .B source: فایل کد منبع برای یک مجموعه داده یافت نشد. .TP .B unmapped: داده‌های پوشش برای یک خط مشخص یافت نمی‌شود؛ احتمالاً به این دلیل که کد منبع پیدا نشده است، یا نگاشت شماره خط در فایل .info اشتباه است. .sp این حالت زمانی رخ می‌دهد که فایل منبع استفاده‌شده در تولید HTML با فایل استفاده‌شده برای تولید داده‌های پوشش یکسان نباشد \- برای مثال، خطوطی اضافه یا حذف شده باشند. .TP .B unreachable: یک نقطه پوشش (خط، شاخه، تابع، یا MC/DC) درون یک ناحیه «غیرقابل دسترس» (unreachable) اجرا شده است (hit خورده است)؛ یا کد، یا جایگذاری دستورالعمل، یا هر دو اشتباه هستند. اگر خطا نادیده گرفته شود، بسته به مقدار پارامتر پیکربندی \fIretain_unreachable_coverpoints_if_executed\fP، نقطه پوشش خاطی حفظ می‌شود (مستثنی نمی‌شود) یا خیر. برای اطلاعات بیشتر، \fBlcovrc(5) \%\fP و بخش \fI“Exclusion markers”\fP از \fBgeninfo(1) \%\fP را ببینید. .TP .B unsupported: ویژگی درخواستی در این پیکربندی ابزار پشتیبانی نمی‌شود. برای نمونه، استثنا کردن محدوده خطوط شروع/پایان تابع از برخی ویژگی‌های GCOV استفاده می‌کند که در نسخه‌های قدیمی‌تر GCC در دسترس نیستند. .TP .B unused: الگوی include/exclude/erase/substitute/omit با هیچ مسیر فایلی مطابقت پیدا نکرد. .TP .B usage: استفاده پشتیبانی‌نشده شناسایی شد \- \fIمانند\fP ترکیب پشتیبانی‌نشده‌ای از گزینه‌ها. .TP .B utility: ابزاری که در حین پردازش فراخوانی شده بود، کد خطا بازگرداند (\fIبرای مثال\fP، دستور «find» با یک پوشه غیرقابل خواندن مواجه شد). .TP .B version: مقایسه انجام‌شده توسط –version\-script نشان‌دهنده عدم تطابق است (مقدار غیر صفر بازگردانده است). به احتمال زیاد نسخه فایلی که در استخراج داده‌های پوشش استفاده شده با نسخه کد منبع یافت‌شده متفاوت است. حاشیه‌نویسی‌های فایل ممکن است نادرست باشند. .UNINDENT .sp توجه داشته باشید که برخی پیام‌های خطا ناشی از مسائلی هستند که احتمالاً خودتان نمی‌توانید آن‌ها را برطرف کنید \- برای نمونه، باگ‌هایی در زنجیره ابزار شما که منجر به ایجاد داده‌های پوشش \fIinconsistent\fP در پایگاه‌داده می‌شوند (به بالا مراجعه کنید). در این موارد، پس از بررسی پیام‌ها، ممکن است بخواهید کد خاطی یا کل فایل خاطی را مستثنی کنید، یا صرفاً پیام‌ها را نادیده بگیرید \- چه با تبدیل به هشدار و چه با نادیده‌گیری (suppress) کامل آن‌ها. راهکار دیگر این است که به \fBgenhtml\fP درباره تعداد پیام‌هایی که انتظار دارید اطلاع دهید \- تا در صورتی که تغییری رخ داد و تعداد پیام‌ها متفاوت شد به شما هشدار دهد و متوجه شوید که باید پیام‌ها را مجدداً بازبینی کنید. پرچم \fI–expect\-message\-count\fP را در ادامه ببینید. .sp همچنین برای بررسی پارامتر «max_message_count» که می‌تواند برای کنترل تعداد هشدارهای صادرشده پیش از نادیده‌گیری تمام پیام‌های بعدی استفاده شود، به ‘\fBlcovrc(5) \%\fP’ مراجعه کنید. این پارامتر می‌تواند برای کاهش حجم فایل لاگ به کار رود. .TP .B \fB\-\-expect\-message\-count message_type:expr[,message_type:expr]\fP محدودیتی برای \fBgenhtml\fP در مورد تعداد پیام‌های یک یا چند نوع که انتظار می‌رود در طول اجرا تولید شوند، مشخص می‌کند. توجه داشته باشید که این مجموع شامل _همه_ پیام‌های نوع مشخص‌شده است \- از جمله پیام‌هایی که سرکوب و نادیده گرفته شده‌اند. اگر شرط برقرار نباشد، خطایی از نوع \fIcount\fP (به بالا مراجعه کنید) ایجاد می‌شود. مقدار \fImessage_type\fP یکی از شناسه‌های پیام توصیف‌شده در بالا است و \fIexpr\fP می‌تواند یکی از موارد زیر باشد: .INDENT 7.0 .IP \(bu 2 یک عدد صحیح \- به این معنی تفسیر می‌شود که دقیقاً باید همان تعداد پیام از نوع متناظر وجود داشته باشد، یا .IP \(bu 2 یک عبارت Perl شامل زیررشته \fB%C\fP؛ مقدار %C با تعداد کل پیام‌های نوع متناظر جایگزین شده و سپس ارزیابی می‌شود. اگر نتیجه غیر صفر باشد شرط برآورده شده و در غیر این صورت برآورده نشده است. .UNINDENT .sp برای نمونه: .INDENT 7.0 .INDENT 3.5 .sp .EX \-\-expect\-message\-count inconsistent:5 .EE .UNINDENT .UNINDENT .sp بیان می‌کند که ما دقیقاً انتظار ۵ پیام از نوع «inconsistent» را داریم. .INDENT 7.0 .INDENT 3.5 .sp .EX \-\-expect\-message\-count inconsistent:%C==5 .EE .UNINDENT .UNINDENT .sp نیز بیان می‌کند که ما دقیقاً ۵ پیام از این نوع را انتظار داریم، اما این مقدار با استفاده از نحو عبارت مشخص شده است. .INDENT 7.0 .INDENT 3.5 .sp .EX \-\-expect\-message\-count \(aqinconsistent : %C > 6 && %C <= 10\(aq .EE .UNINDENT .UNINDENT .sp بیان می‌کند که ما انتظار داریم تعداد پیام‌ها در محدوده (6:10] باشد. (توجه داشته باشید که اگر می‌خواهید با افزودن فاصله به عبارت خود خوانایی آن را افزایش دهید، ممکن است قرار دادن عبارت در علامت نقل‌قول جهت جلوگیری از تفسیر فاصله‌ها توسط شل شما ضروری باشد.) .sp چندین محدودیت را می‌توان با استفاده از یک فهرست جداشده با کاما یا با تکرار چندباره این گزینه مشخص کرد. .sp این پرچم معادل گزینه پیکربندی \fIexpect_message_count\fP است. برای جزئیات بیشتر درباره نحو عبارات و چگونگی تفسیر آن‌ها، \fBlcovrc(5) \%\fP را ببینید. تعداد پیام‌های نوع مورد نظر پیش از ارزیابی عبارت، در آن جایگزین می‌شود. .TP .B \fB\-\-keep\-going\fP در صورت بروز خطا متوقف نشو: برای تولید نتیجه، حتی با وجود نقص و اشکال، تلاش کن. .sp این گزینه خط فرمان متناظر با گزینه \fIstop_on_error\fP در lcovrc است. برای جزئیات بیشتر \fBlcovrc(5) \%\fP را ببینید. .TP .B \fB\-\-config\-file\fP \fIconfig\-file\fP فایل پیکربندی مورد استفاده را مشخص می‌کند. برای جزئیات قالب فایل و گزینه‌ها، \fBlcovrc(5) \%\fP را ببینید. همچنین برای جزئیات چگونگی فراخوانی یک فایل پیکربندی درون فایلی دیگر، مدخل \fIconfig_file\fP را در همان صفحه راهنما مطالعه کنید..sp هنگامی که این گزینه مشخص شود، نه فایل پیکربندی سراسری سیستم /etc/lcovrc و نه فایل پیکربندی اختصاصی کاربر ~/.lcovrc خوانده نخواهند شد. .sp این گزینه ممکن است زمانی مفید باشد که نیاز به اجرای هم‌زمان چندین نمونه از \fBgenhtml\fP با گزینه‌های فایل پیکربندی متفاوت وجود دارد. .sp توجه داشته باشید که این گزینه باید به‌طور کامل مشخص شود \- مخفف‌سازی پشتیبانی نمی‌شود. .TP .B \fB\-\-profile\fP [ \fIprofile\-data\-file\fP ] به ابزار اعلام می‌کند تا عملکرد و سایر داده‌های پیکربندی را ثبت و پیگیری کند. اگر \fIprofile\-data\-file\fP اختیاری مشخص نشود، داده‌های پروفایل در فایلی به نام \fIgenhtml.json\fP در دایرکتوری خروجی نوشته می‌شوند. .sp داده‌های پروفایل در صورتی که در تلاش برای بهینه‌سازی پیاده‌سازی \fBlcov\fP هستید مفید است (نگاه کنید به \fB$LCOV_ROOT/share/lcov/support\-scripts/spreadsheet.py\fP)، و همچنین می‌تواند اجرای سریع‌تر «genhtml –parallel» را ممکن سازد (بخش «–history\-script» این صفحهٔ راهنما را ببینید). .TP .B \fB\-\-history\-script\fP \fIscript\fP به ابزار اعلام می‌کند تا از داده‌های عملکرد حاصل از یک کار (job) قبلی برای پیش‌بینی مصرف منابع توسط کار فعلی استفاده کند. این کار ممکن است بخش‌بندی بهتری را برای برقراری بار کاری متعادل‌تر میان ریسه‌های (threads) موازی فراهم کند \- و در نتیجه زمان واقعی اجرا (wall clock) را بهبود بخشد. .sp یک منبع رایج برای \fIprevious\-profile\-data\-file\fP، داده‌های پروفایل تولیدشده بر اثر اجرای قبلی مجموعه آزمون‌های رگرسیون است. به \fB$LCOV_ROOT/share/lcov/example\fP و \fB$LCOV_ROOT/share/lcov/support\-scripts/history.pm\fP در نسخهٔ نصب‌شده (یا \fB\&.../example\fP در مخزن سورس‌کد) مراجعه کنید. .TP .B \fB\-\-rc\fP \fIkeyword\fP = \fIvalue\fP بازنویسی یک دستورالعمل پیکربندی. .sp از این گزینه برای مشخص کردن عبارت \fIkeyword\fP = \fIvalue\fP استفاده کنید که دستورالعمل پیکربندی متناظر در فایل پیکربندی lcovrc را بازنویسی می‌کند. می‌توانید این گزینه را چند بار مشخص کنید تا چندین دستورالعمل پیکربندی بازنویسی شوند. برای مشاهدهٔ فهرستی از کلیدواژه‌های موجود و معنای آن‌ها به \fBlcovrc(5) \%\fP مراجعه کنید. .TP .B \fB\-\-precision\fP \fInum\fP نمایش نرخ‌های پوشش با \fInum\fP رقم بعد از نقطهٔ اعشار. .sp مقدار پیش‌فرض ۱ است. .sp این گزینه همچنین می‌تواند با استفاده از گزینهٔ \fIgenhtml_precision\fP در فایل پیکربندی، به‌صورت دائمی پیکربندی شود\&. .TP .B \fB\-\-merge\-aliases\fP توابعی که فایل/سطر آن‌ها یکسان است، نام مستعار (alias) یکدیگر در نظر گرفته می‌شوند؛ \fBgenhtml\fP از کوتاه‌ترین نام در فهرست نام‌های مستعار (کمترین تعداد نویسه) به عنوان سرشاخه استفاده می‌کند. .sp این گزینه هر گروه از نام‌های مستعار را به عنوان یک شیء واحد می‌شمارد \- بنابراین تعداد «تابع» برابر با تعداد گروه‌های متمایز تابع خواهد بود، نه تعداد کل نام‌های مستعار همهٔ توابع \- و آن‌ها را به صورت گروهی در جدول جزئیات تابع نمایش می‌دهد. .sp توجه داشته باشید که این گزینه تنها در صورتی تأثیرگذار است که \fB\(dq\-\-filter function\(dq\fP بر روی پایگاه‌دادهٔ پوشش اعمال شده باشد. .sp این پارامتر می‌تواند از طریق گزینهٔ \fImerge_function_aliases\fP در فایل پیکربندی تنظیم شود. به \fBman(5) lcovrc\fP مراجعه کنید\&. .TP .B \fB\-\-suppress\-aliases\fP نادیده گرفتن فهرست نام‌های مستعار در جدول جزئیات تابع. .sp توابعی که فایل/سطر آن‌ها یکسان است، نام مستعار در نظر گرفته می‌شوند؛ \fBgenhtml\fP از کوتاه‌ترین نام در فهرست نام‌های مستعار (کمترین تعداد نویسه) به عنوان سرشاخه استفاده می‌کند. .sp تعداد نام‌های مستعار می‌تواند زیاد باشد، برای مثال به دلیل الگوهای نمونه‌سازی‌شده (instantiated templates) \- که می‌تواند خواندن نتایج پوشش توابع را دشوار کند. این گزینه فهرست نام‌های مستعار را حذف می‌کند و تمرکز بر روی عدد کلی پوشش توابع را که احتمالاً مهم‌تر است، آسان‌تر می‌سازد. .sp توجه داشته باشید که این گزینه تنها زمانی تأثیر دارد که \fB\(dq\-\-filter function\(dq\fP روی پایگاه‌دادهٔ پوشش اعمال شده باشد. .sp این پارامتر می‌تواند از طریق گزینهٔ \fImerge_function_aliases\fP در فایل پیکربندی تنظیم شود. به \fBman(5) lcovrc\fP مراجعه کنید\&. .TP .B \fB\-\-forget\-test\-names\fP اگر غیرصفر باشد، نام‌های آزمایه (testcase) در فایل .info نادیده گرفته می‌شوند \- \fIi.e.\fP، با تمام داده‌های پوشش به گونه‌ای رفتار می‌شود که گویی از یک آزمایهٔ یکسان آمده‌اند. این کار می‌تواند در صورتی که کاربر نیازی به خلاصهٔ پوشش بر اساس هر آزمایه در گزارش‌ها نداشته باشد، عملکرد را بهبود بخشیده و مصرف حافظه را کاهش دهد. .sp این گزینه همچنین می‌تواند با استفاده از گزینهٔ \fIforget_testcase_names\fP در فایل پیکربندی به‌طور دائمی پیکربندی شود\&. .TP .B \fB\-\-missed\fP نمایش تعداد خطوط، توابع، شاخه‌ها و عبارات MC/DC پوشش‌داده‌نشده. .sp از این گزینه برای تغییر صفحات نمای کلی استفاده کنید تا تعداد خطوط، توابع، شاخه‌ها، یا عبارات MC/DC که اجرا نشده‌اند نمایش داده شود. این مقادیر با اعداد منفی نشان داده می‌شوند. .sp هنگامی که همراه با –sort\-tables مشخص شود، نماهای فایل و دایرکتوری بر اساس تعداد موارد پوشش‌داده‌نشده مرتب خواهند شد. .sp این گزینه همچنین می‌تواند با استفاده از گزینهٔ \fIgenhtml_missed\fP در فایل پیکربندی به‌صورت دائمی پیکربندی شود\&. .TP .B \fB\-\-dark\-mode\fP استفاده از طرح رنگی «روشن روی پس‌زمینهٔ تاریک» به‌جای طرح پیش‌فرض «تاریک روی پس‌زمینهٔ روشن». .sp هدف از این گزینه، کاهش خستگی چشم ناشی از تماشای متن تیره بر روی صفحهٔ نمایش روشن \- به‌ویژه در شب \- است. .TP .B \fB\-\-tempdir\fP \fIdirname\fP نوشتن داده‌های موقت و میانی در دایرکتوری مشخص‌شده. پیش‌فرض «/tmp» است. .TP .B \fB\-\-preserve\fP نگه‌داری فایل‌های داده‌های میانی تولیدشده توسط مراحل مختلف ابزار \- \fIe.g.\fP، جهت اشکال‌زدایی. به‌طور پیش‌فرض، این فایل‌ها حذف می‌شوند. .TP .B \fB\-\-save\fP رونوشت برداشتن از \fIunified\-diff\-file, baseline_trace_files,\fP و \fItracefile(s)\fP در دایرکتوری خروجی. .sp نگه‌داشتن رونوشت فایل‌های داده‌های ورودی ممکن است به اشکال‌زدایی خطاها یا بازتولید مجدد فایل‌های گزارش در آینده کمک کند. .TP .B \fB\-\-sort\-input\fP تعیین این‌که آیا نام فایل‌ها قبل از دریافت و/یا تجمیع مرتب شوند یا خیر. مرتب‌سازی برخی از انواع تفاوت‌های خروجی وابسته به ترتیب پردازش را کاهش می‌دهد. بخش \fIsort_input\fP را در \fBlcovrc(5) \%\fP ببینید\&. .TP .B \fB\-\-serialize\fP \fIfile_name\fP ذخیرهٔ پایگاه‌دادهٔ پوشش در \fIfile_name\fP\&. .sp این فایل با قالب «Storable» مربوط به Perl است. .sp توجه داشته باشید که این گزینه ممکن است میزان حافظهٔ مورد نیاز \fIgenhtml\fP را به‌طور چشمگیری افزایش دهد، چرا که حجم زیادی از داده‌ها باید در حافظه نگه‌داری شوند. .UNINDENT.SH "فایل‌ها (FILES)" .INDENT 0.0 .TP .B \fI/etc/lcovrc\fP فایل پیکربندی سراسری سیستم. .TP .B \fI~/.lcovrc\fP فایل پیکربندی مختص هر کاربر. .UNINDENT .sp اسکریپت‌های نمونه ساخت داده \fI–diff\-file\fP: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBscripts/p4udiff\fP اسکریپت نمونه برای استفاده با \fB\-\-diff\-file\fP که یک فایل unified diff را از طریق \fBPerforce\fP\& ایجاد می‌کند. .TP .B \fBscripts/gitdiff\fP اسکریپت نمونه برای استفاده با \fB\-\-diff\-file\fP که یک فایل unified diff را از طریق \fBgit\fP\& ایجاد می‌کند. .UNINDENT .UNINDENT .UNINDENT .sp ماژول‌های Perl نمونه کال‌بک \fI–annotate\-script\fP: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBscripts/p4annotate.pm\fP اسکریپت نمونه نوشته‌شده به‌صورت ماژول Perl برای استفاده با \fB\-\-annotate\-script\fP که داده‌های حاشیه‌نویسی را از طریق \fBPerforce\fP\& فراهم می‌کند. .TP .B \fBscripts/gitblame.pm\fP اسکریپت نمونه نوشته‌شده به‌صورت ماژول Perl برای استفاده با \fB\-\-annotate\-script\fP که داده‌های حاشیه‌نویسی را از طریق git فراهم می‌کند. .UNINDENT .UNINDENT .UNINDENT .sp ماژول‌های Perl نمونه کال‌بک \fI–criteria\-script\fP: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBscripts/criteria.pm\fP اسکریپت نمونه نوشته‌شده به‌صورت ماژول Perl برای استفاده با \fB\-\-criteria\-script\fP که بررسی «UNC + LBC + UIC == 0» را پیاده‌سازی می‌کند. .TP .B \fBscripts/threshold.pm\fP اسکریپت نمونه نوشته‌شده به‌صورت ماژول Perl برای بررسی حداقل پوشش قابل‌قبول خط و/یا شاخه و/یا تابع MC/DC. برای مثال، ویژگی .sp \fI“genhtml –fail_under_lines 75 …”\fP .sp می‌تواند در عوض به‌صورت زیر محقق شود: .sp \fI“genhtml –criteria\-script scripts/threshold.pm,–line,75 …”\fP .UNINDENT .UNINDENT .UNINDENT .sp ماژول Perl نمونه کال‌بک \fI–simplify\-script\fP: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBscripts/simplify.pm\fP اسکریپت نمونه نوشته‌شده به‌صورت ماژول Perl برای استفاده با \fB\-\-simplify\-script\fP که جایگزینی‌های عبارت باقاعده را برای ساده‌سازی نام توابع پیاده‌سازی می‌کند. .UNINDENT .UNINDENT .UNINDENT .sp ماژول‌های Perl و اسکریپت‌های نمونه کال‌بک \fI–version\-script\fP: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fBscripts/getp4version\fP اسکریپت نمونه برای استفاده با \fB\-\-version\-script\fP که شناسه‌های نسخه را از طریق \fBPerforce\fP\& به دست می‌آورد. .TP .B \fBscripts/P4version.pm\fP یک ماژول Perl با کارکردی مشابه \fBgetp4version\fP اما با کارایی بالاتر. .TP .B \fBscripts/get_signature\fP اسکریپت نمونه برای استفاده با \fB\-\-version\-script\fP که از md5hash به‌عنوان شناسه‌های نسخه استفاده می‌کند. .TP .B \fBscripts/gitversion.pm\fP یک ماژول Perl برای استفاده با \fB\-\-version\-script\fP که شناسه‌های نسخه را از \fBgit\fP\& دریافت می‌کند. .TP .B \fBscripts/batchGitVersion.pm\fP یک ماژول Perl با کارکردی مشابه \fBgitversion.pm\fP اما با کارایی بالاتر. .UNINDENT .UNINDENT .UNINDENT.SH "نویسندگان (AUTHORS)" .sp Peter Oberparleiter <\%> .INDENT 0.0 .TP .B Henry Cox <\%> پوشش تفاضلی و دسته‌بندی بر اساس تاریخ/مالک، فیلترسازی، مدیریت خطا، بخش‌های اجرای موازی، .UNINDENT .SH "همچنین ببینید (SEE ALSO)" .sp \fBlcov(1) \%\fP, \fBlcovrc(5) \%\fP, \fBgeninfo(1) \%\fP, \fBllvm2lcov(1) \%\fP, \fBperl2lcov(1) \%\fP, \fBpy2lcov(1) \%\fP, \fBgendesc(1) \%\fP, \fBgcov(1) \%\fP .sp \fIhttps://github.com/linux\-test\-project/lcov\fP .SH "کپی‌رایت و تکثیر (COPYRIGHT)" 2024-2026, LCOV Project .\" End of generated man page.