genhtml

تولید نمای HTML از فایل‌های داده‌های پوشش LCOV - شامل تحلیل تفاضلی پوشش، دسته‌بندی بر اساس قدمت و نویسنده، و گزینه‌های گوناگون مصورسازی.

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)

دستور genhtml یک نمای HTML از داده‌های پوشش (coverage) موجود در فایل‌های ردگیری (tracefiles) ابزارهای geninfo و lcov که از طریق الگو(های) تطبیق سراسری (glob) tracefile_pattern یافته می‌شوند ایجاد می‌کند. برای شرح قالب tracefile به geninfo(1) <file://../man/geninfo.1.html> مراجعه کنید.

قابلیت‌ها شامل موارد زیر است:

مفاهیم اساسی پوشش تفاضلی و دسته‌بندی بر اساس تاریخ/مالک در مقاله‌ای به نشانی https://arxiv.org/abs/2008.07947 شرح داده شده است.

-h, --help

چاپ یک متن راهنمای کوتاه، سپس خروج.

--version

چاپ شماره نسخه، سپس خروج.

-v, --verbose

افزایش پرگویی (verbosity) پیام‌های اطلاعاتی. این مورد عمدتاً برای اشکال‌زدایی اسکریپت یا جریان کار استفاده می‌شود - برای مثال برای مشخص کردن اینکه کدام فایل‌های داده در کجا پیدا شده‌اند. همچنین پرچم –quiet را ببینید.

-q, --quiet

کاهش پرگویی پیام‌های اطلاعاتی.

کاهش پرگویی برای مثال پیام‌های «پیشرفت» را سرکوب می‌کند - در حالی که چاپ پیام‌های خطا و هشدار همچنان ادامه خواهد داشت.

--debug

افزایش پرگویی «پیام‌های اشکال‌زدایی». این گزینه در درجه اول برای توسعه‌دهندگانی مفید است که قصد توسعه و بهبود مجموعه ابزار lcov را دارند.

--validate

بررسی HTML تولیدشده برای اطمینان از نبودن پیوندهای مرده و فایل‌های استفاده‌نشده در دایرکتوری خروجی. این بررسی‌ها را می‌توان با تنظیم متغیر محیطی LCOV_VALIDATE = 1 نیز فعال کرد. این گزینه در درجه اول برای توسعه‌دهندگانی در نظر گرفته شده است که گزارش HTML را تغییر می‌دهند.

--flat, --hierarchical

استفاده از چیدمان سلسله‌مراتبی مشخص‌شده برای گزارش HTML.

گزارش HTML پیش‌فرض دارای ۳ سطح است:

گزینه --hierarchical گزارشی چندسطحی تولید می‌کند که ساختار دایرکتوری کد منبع را دنبال می‌کند (مشابه ابزار فایل در Microsoft Windows).

گزینه --flat یک گزارش HTML دو سطحی تولید می‌کند:

نمای «مسطح» (flat) می‌تواند تعداد کلیک‌های لازم برای پیمایش در گزارش پوشش را کاهش دهد - اما برای پروژه‌هایی به جز موارد بسیار کوچک با چند فایل منبع محدود، دست‌وپاگیر است. این نما می‌تواند در حالت «بازبینی کد» حتی برای پروژه‌های بسیار بزرگ مفید باشد (گزینه –select-script را ببینید).

اکثر پروژه‌های بزرگ ساختار دایرکتوری منطقی دارند - که این امر قالب گزارش «سلسله‌مراتبی» را مطلوب‌تر می‌سازد. تیم‌های مسئول یک ماژول خاص می‌توانند بر روی یک زیردایرکتوری خاص یا مجموعه‌ای از زیردایرکتوری‌ها تمرکز کنند.

تنها یکی از گزینه‌های --flat یا --hierarchical می‌تواند به طور همزمان مشخص شود.

این گزینه‌ها را می‌توان از طریق فایل پیکربندی lcovrc نیز به صورت دائمی با استفاده از یکی از خطوط زیر تنظیم کرد:

genhtml_hierarchical = 1

یا

genhtml_flat_view = 1

برای جزئیات به lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

-f, --frames

استفاده از قاب‌های HTML (فریم‌ها) برای نمای کد منبع.

در صورت فعال بودن، یک frameset برای هر فایل کد منبع ایجاد می‌شود که نمای کلی کد منبع را به صورت یک تصویر «قابل کلیک» ارائه می‌دهد. توجه داشته باشید که این گزینه تولید خروجی را به طور محسوسی کند می‌کند، زیرا تک‌تک نویسه‌های کد منبع باید یک بار بررسی شوند. همچنین ماژول پرل GD.pm باید برای عملکرد این گزینه نصب باشد (می‌توان آن را از http://www.cpan.org دریافت کرد).

این گزینه از طریق مدخل genhtml_frames در فایل lcovrc نیز قابل کنترل است.

لطفاً توجه داشته باشید که باگی در firefox و chrome وجود دارد که با فعال کردن فریم‌ها، ابرپیوندها را از مدخل جدول خلاصه سطح «دایرکتوری» به اولین خط در فایل مربوطه در آن دسته خاص از کار می‌اندازد - برای مثال به اولین خط «MIS» (گزارش پوشش ساده - گزینه --show-navigation در ادامه را ببینید)، به اولین شاخه «UNC» (گزارش پوشش تفاضلی) و غیره. ابرپیوندها از جدول خلاصه در بالای صفحه «جزئیات منبع» تحت تأثیر قرار نمی‌گیرند.

-s, --show-details

تولید نمای تفصیلی دایرکتوری.

هنگامی که این گزینه فعال باشد، genhtml دو نسخه از هر مدخل فایل منبع در جدول خلاصه مربوطه ایجاد می‌کند:

توجه داشته باشید که نقاط پوشش ناموفق در داده‌های جدول تفکیکی هر آزمون نشان داده نمی‌شوند.

جدول خلاصه مربوطه در صفحه «دایرکتوری» گزارش سه‌سطحی پیش‌فرض genhtml، یا در صفحه سطح بالای گزارش «مسطح» (ببینید genhtml –flat …)، یا در صفحه دایرکتوری والد گزارش «سلسله‌مراتبی» (ببینید genhtml –hierarchical …) قرار دارد.

توجه داشته باشید که این گزینه ممکن است مصرف حافظه را به میزان قابل توجهی افزایش دهد.

-b baseline-file-pattern, --baseline-file baseline-file-pattern

استفاده از داده‌های موجود در فایل‌های یافت‌شده از الگوی baseline-file-pattern به عنوان مبنای (baseline) پوشش.

گزینه --baseline-file می‌تواند چندین بار مشخص شود - برای مثال، اگر برای هر یک از چندین مجموعه آزمون چندین فایل داده رد پا دارید و نمی‌خواهید مرحله اضافی ادغام همه آن‌ها در یک فایل داده تجمیعی واحد را انجام دهید.

فایل‌های داده پوشش مشخص‌شده با baseline-file-pattern خوانده شده و به عنوان مبنایی برای دسته‌بندی تغییرات در پوششِ نمایانده‌شده توسط شمارش‌های پوشش در tracefile-patterns استفاده می‌شوند. اگر baseline-file-pattern یک دایرکتوری باشد، genhtml آن دایرکتوری را برای یافتن تمام فایل‌های با پسوند «.info» جستجو می‌کند. برای چگونگی تغییر این الگو، به بخش info_file_extension در man(5) lcovrc مراجعه کنید.

به طور کلی، هنگامی که یک –baseline-file-pattern را مشخص می‌کنید، باید یک فایل diff با قالب unified diff از طریق --diff-file ارائه دهید. بدون یک فایل diff، ابزار genhtml فرض می‌کند که هیچ تفاوتی در کد منبع بین «baseline» و «current» وجود ندارد. برای مثال: این حالت می‌تواند برای یافتن تغییرات افزایشی ناشی از افزودن آزمون‌های بیشتر، یا برای مقایسه نتایج پوشش بین نسخه‌های gcc، یا بین gcc و llvm به کار رود.

--baseline-title title

استفاده از title به عنوان متن برچسب توصیفی برای منبع داده‌های مبنای پوشش.

--baseline-date date

استفاده از date به عنوان تاریخ جمع‌آوری در قالب متنی برای داده‌های مبنای پوشش. اگر این آرگومان مشخص نشود، پیش‌فرض استفاده از زمان ایجاد اولین فایل تطبیق‌یافته با baseline-file-pattern به عنوان تاریخ مبنا است. اگر چندین فایل مبنا وجود داشته باشد، از تاریخ ایجاد اولین فایل استفاده خواهد شد..TP --current-date date استفاده از date به عنوان تاریخ گردآوری در قالب متنی برای داده‌های خط مبنای پوشش. اگر این آرگومان مشخص نشود، حالت پیش‌فرض استفاده از زمان ایجاد tracefile فعلی است.

--diff-file diff-file

استفاده از diff-file به عنوان تعریفی برای تغییرات فایل مبدأ بین نقاط نمونه‌برداری برای baseline-file-pattern و tracefile(s).

نکته:

تقریباً همیشه ایده بهتری است که پالایش در زمان ثبت یا تجمیع انجام شود - نه در زمان تولید گزارش.

یک فایل ورودی مناسب از نوع “universal diff” برای گزینه --diff-file می‌تواند با استفاده از اسکریپت‌های نمونه «p4udiff» یا «gitdiff» که به عنوان بخشی از این بسته ارائه شده‌اند، یا با استفاده مستقیم از دستورهای سامانه کنترل نسخه ایجاد شود.

اسکریپت‌های نمونه «p4udiff» یا «gitdiff» در مسیرهای زیر قرار دارند:

و

این اسکریپت‌ها صرفاً خروجی ‘p4’ یا ‘git’ را پس‌پردازش می‌کنند تا فایل‌هایی را که مورد نظر نیستند (به‌صورت اختیاری) حذف کنند و فایل‌هایی را که تغییر نکرده‌اند صراحتاً مشخص نمایند.

اسکریپت p4udiff یک شناسه changelist یا رشته حرفی «sandbox» را می‌پذیرد؛ «sandbox» نشان می‌دهد که فایل‌های تغییریافته‌ای وجود دارند که هنوز ثبت (check in) نشده‌اند. برای اطلاعات بیشتر “gitdiff --help” و “p4udiff --help” را ببینید.

سودمند است که فایل‌های تغییرنیافته با خطوطی به شکل زیر مشخص شوند:

diff [optional header strings]
=== file_path

در خروجی p4diff/gitdiff، چرا که این آگاهی به فرونشاندن هشدارهای کاذب ‘path mismatch’ کمک خواهد کرد. مدخل‌های --elide-path-mismatch و --build-directory در زیر را ببینید.

به‌طور کلی، زمانی که --diff-file را مشخص می‌کنید، --baseline-file را نیز تعیین خواهید کرد. فایل‌های baseline_files برای محاسبه تفاوت‌های پوشش (برای مثال افزایش‌ها و کاهش‌ها) میان مبنا و جاری استفاده می‌شوند، در حالی که diff_file برای محاسبه تغییرات کد به کار می‌رود: متن مبدأ میان ‘baseline’ و ‘current’ یکسان است. اگر baseline_files را مشخص کنید اما diff_file را تعیین نکنید، ابزار فرض می‌کند که هیچ تغییر کدی میان مبنا و جاری وجود ندارد. اگر diff_file را مشخص کنید اما هیچ baseline_files مشخص نشود، ابزار فرض می‌کند که هیچ داده پوشش مبنایی وجود ندارد (هیچ کد مبنایی پوشش داده نشده است)؛ در نتیجه کد تغییرنیافته (یعنی کدی که در diff_file ظاهر نمی‌شود) به عنوان GIC (پوشش‌یافته) یا UIC (پوشش‌نیافته) دسته‌بندی می‌شود، در حالی که کد جدید یا تغییریافته به عنوان GNC یا UNC دسته‌بندی خواهد شد.

--annotate-script script

استفاده از script برای دریافت داده‌های حاشیه‌نویسی کد مبدأ.

از این گزینه برای مشخص کردن یک ابزار خارجی یا خط فرمان استفاده کنید که genhtml بتواند از آن برای به دست آوردن داده‌های حاشیه‌نویسی کد مبدأ مانند قدمت و نویسنده آخرین تغییر برای هر خط از کد مبدأ استفاده کند.

این گزینه همچنین به genhtml دستور می‌دهد تا یک جدول خلاصه به سرآیند گزارش HTML اضافه کند که شمارش‌های موجود در دسته‌های مختلف پوشش، مرتبط با هر بازه تاریخی (date bin) را نشان می‌دهد. علاوه بر این، هر خط از کد مبدأ اطلاعات قدمت و مالک را نشان خواهد داد. داده‌های حاشیه‌نویسی همچنین برای پر کردن یک «tooltip» استفاده می‌شوند که هنگام بردن اشاره‌گر ماوس روی کد مبدأ مربوطه نمایان می‌شود. برای جزئیات، مدخل genhtml_annotate_tooltip را در lcovrc(5) <file://../man/lcovrc.5.html> ببینید.

انتظار می‌رود که script مشخص‌شده، اطلاعات قدمت و مالکیت را برای هر خط از کد مبدأ از سامانه مدیریت نسخه به دست آورد و این اطلاعات را در قالبی که در زیر شرح داده شده خروجی دهد.

اگر اسکریپت حاشیه‌نویسی با شکست مواجه شود و خطاهای حاشیه‌نویسی از طریق --ignore-errors نادیده گرفته شوند، آن‌گاه genhtml تلاش خواهد کرد فایل مبدأ را به‌صورت عادی بارگذاری کند. اگر فایل وجود نداشته باشد یا قابل خواندن نباشد، و پرچم --synthesize-missing تعیین شده باشد، genhtml داده‌های ساختگی برای فایل تولید خواهد کرد.

اگر یک اسکریپت حاشیه‌نویسی را مشخص کرده باشید اما هیچ فایلی با موفقیت حاشیه‌نویسی نشود، genhtml خطایی صادر خواهد کرد (زیر را ببینید). این حالت زمانی می‌تواند رخ دهد که، برای مثال، متغیرهای محیطی P4USER، P4CLIENT یا P4PORT شما به درستی تنظیم نشده باشند - برای نمونه، اگر کاربر Jenkins که گزارش‌های پوشش را تولید می‌کند با کاربری که کد را دریافت (check out) کرده و مالک sandbox است یکسان نباشد.

اسکریپت‌های نمونه حاشیه‌نویسی برای Perforce («p4annotate») و git («gitblame») به عنوان بخشی از این بسته در مسیرهای زیر ارائه شده‌اند:

و

توجه داشته باشید که این اسکریپت‌ها حاشیه‌نویسی‌ها را بر اساس نسخه فایلی که در مخزن ثبت شده است (check in) تولید می‌کنند - نه فایل تغییریافته محلی در پوشه ساخت. اگر به حاشیه‌نویسی برای فایل‌های تغییریافته محلی نیاز دارید، می‌توانید تغییرات خود را در P4 بایگانی (shelve) کنید، یا آن‌ها را در یک شاخه محلی در git ثبت نمایید.

ساخت اسکریپت اختصاصی خودتان

هنگام ساخت اسکریپت اختصاصی خود، لطفاً ابتدا بخش Script considerations در بالا را برای قراردادهای عمومی فراخوانی و ملزومات اسکریپت بررسی کنید.

اسکریپت script توسط genhtml با خط فرمان زیر فراخوانی می‌شود:

که در آن

فایل اجرایی script باید برای هر خط در فایل source_file_name، خطی را با قالب زیر به جریان خروجی استاندارد ارسال کند:

که در آن

اسکریپت باید در صورت موفقیت‌آمیز بودن پردازش مقدار 0 (صفر) و در صورت مواجهه با خطا مقداری غیرصفر برگرداند.

--criteria-script script

استفاده از script برای آزمودن معیارهای پذیرش پوشش.

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

یک اسکریپت نمونه برای معیارهای پوشش به عنوان بخشی از این بسته در مسیر زیر ارائه شده است:

اسکریپت نمونه بررسی می‌کند که آیا پوشش خط بالاترین سطح معیار «UNC + LBC + UIC == 0» را برآورده می‌کند یا خیر (کد اضافه‌شده و کدی که به‌تازگی فعال شده باید آزموده شوند، و کد آزموده‌شده موجود نباید به حالت آزموده‌نشده درآید).

به عنوان مثالی دیگر، می‌توان اسکریپت‌هایی ایجاد کرد که با بررسی اینکه آیا نسبت خطوط اجراشده به کل خطوط («(GNC + GIC + CBC) / (GNC + GIC + CBC + UNC + UIC + UBC)») بیشتر از حد آستانه است یا خیر، قابلیت lcov --fail-under-lines را شبیه‌سازی کنند - چه فقط در بالاترین سطح، چه در هر پوشه، یا در هر جای دیگر مورد نظر. به همین ترتیب، معیارها می‌توانند شامل شاخص‌های پوشش انشعاب و تابع نیز باشند.

به‌طور پیش‌فرض اسکریپت معیارها برای همه سطوح سلسله‌مراتب کد مبدأ فراخوانی می‌شود، یعنی: بالاترین سطح (top-level)، پوشه و سطح فایل. گزینه فایل پیکربندی criteria_callback_levels می‌تواند برای محدود کردن سطوح سلسله‌مراتب به هر ترکیبی از سطوح ‘top’، ‘directory’ یا ‘file’ استفاده شود.

مثال:

genhtml --rc criteria_callback_levels=directory,top ...

می‌توانید با استفاده از گزینه فایل پیکربندی criteria_callback_data حجم داده‌های ارسالی به اسکریپت معیارها را افزایش دهید. به‌طور پیش‌فرض، فقط تعداد کل لحاظ می‌شود. مشخص کردن “date” شمارش‌ها به تفکیک بازه تاریخی و “owner” شمارش‌ها به تفکیک بازه مالک را اضافه می‌کند.

مثال:

genhtml --rc criteria_callback_data=date,owner ...

برای جزئیات بیشتر، lcovrc(5) <file://../man/lcovrc.5.html> را ببینید.

ساخت اسکریپت سفارشی خودتان

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

script برای هر فایل کد مبدأ، دایرکتوری برگ (leaf-directory) و نتایج پوشش سطح بالا با خط فرمان زیر اجرا می‌شود:

script [additional_parameters] "name " " type" "coverage_data"

که در آن:

قالب داده‌های JSON به صورت زیر تعریف می‌شود:

{
  "<type>": {
    "found": <count>,
    "hit": <count>,
    "<category>": <count>,
    ...
  },
  "<bin_type>": {
    "<bin_id>" : {
      "found": <count>,
      "hit": <count>,
      "<category>": <count>,
      ...
    },
    ...
  },
  ...
}

که در آن:

توجه داشته باشید که داده‌ها تنها برای انواع پوشش و دسته‌بندی‌های (bins) غیرخالی گزارش می‌شوند.

اسکریپت در صورت برآورده شدن معیارها باید مقدار 0 (صفر) و در غیر این صورت مقداری غیرصفر برگرداند.

در صورت تمایل، اسکریپت می‌تواند یک رشتهٔ خروجی تک‌خطی چاپ کند که در صورت غیرصفر بودن وضعیت بازگشتی، به گزارش خطا (error log) اضافه خواهد شد. علاوه‌بر این، خطوط غیرخالی به لاگ خروجی استاندارد genhtml پیوست می‌شوند.

--version-script script

استفاده از script برای دریافت داده‌های نسخهٔ فایل کد مبدأ.

از این گزینه برای مشخص کردن یک ابزار خارجی یا دستور خط فرمانی استفاده کنید که genhtml بتواند هنگام تولید HTML یا اعمال فیلترهای مبدأ، برای دریافت شناسهٔ نسخهٔ (version ID) فایل کد مبدأ از آن استفاده کند (گزینهٔ --filter را ببینید).

شناسهٔ نسخه می‌تواند یک هش فایل یا شناسهٔ کامیت از سیستم کنترل نسخه باشد. این شناسه برای تطبیق نسخهٔ فایل مبدأ بارگذاری‌شده با نسخه‌ای که برای تولید داده‌های پوشش استفاده شده است (i.e. نسخهٔ فایلی که توسط lcov/geninfo بررسی شده) به کار می‌رود. یکسان بودن نسخه‌های کد مبدأ بسیار مهم است؛ در غیر این صورت ممکن است نتایجی متناقض یا گمراه‌کننده حاصل شود.

عدم تطابق نسخه‌ها معمولاً زمانی رخ می‌دهد که وظایف ثبت، تجمیع و تولید گزارش بین چندین کار (job) مختلف تقسیم شده باشد - e.g. هنگامی که از یک کد مبدأ یکسان در چند پروژه استفاده می‌شود، گزارش پوشش یکپارچه/سراسری مورد نیاز است و پروژه‌ها تصادفاً از نگارش‌های متفاوتی استفاده می‌کنند.

اگر فایل .info (داده‌های پوشش) شما فاقد اطلاعات نسخه است - برای مثال به این دلیل که توسط ابزاری تولید شده که از نسخه‌بندی پشتیبانی نمی‌کرده - می‌توانید از گزینهٔ compute_file_version = 1 در فایل پیکربندی برای تولید بعدی این داده‌ها استفاده کنید. یک راه ساده برای انجام این کار، استفاده از lcov --add-tracefile برای خواندن فایل اصلی، درج اطلاعات نسخه و نوشتن خروجی نهایی است. برای اطلاعات بیشتر lcovrc(5) <file://../man/lcovrc.5.html> را ببینید.

اسکریپت‌های نمونه برای Perforce (با نام «getp4version»)، گیت (با نام «gitversion») و استفاده از هش md5 (با نام «get_signature») همراه با این بسته در مسیرهای زیر ارائه شده‌اند:

و

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

ساخت اسکریپت سفارشی خودتان

هنگام ساخت اسکریپت اختصاصی، لطفاً ابتدا بخش ملاحظات اسکریپت (Script considerations) در بالا را برای بررسی قراردادهای عمومی فراخوانی و نیازمندی‌های اسکریپت مطالعه فرمایید.

«script» هم برای تولید و هم برای مقایسهٔ شناسهٔ نسخه استفاده می‌شود تا حفظ تاریخچه میان فراخوانی‌ها را میسر ساخته یا امکان پردازش‌های پیچیده‌تر جهت احراز برابری را فراهم آورد. این اسکریپت توسط genhtml با یکی از خطوط فرمان زیر اجرا خواهد شد:

--resolve-script script

استفاده از script برای یافتن مسیر فایلی از کد مبدأ که در فایل داده‌های ورودی آمده است، در صورتی که پس از اعمال الگوهای --substitute و جستجو در فهرست --source-directory، فایل مورد نظر پیدا نشود. این گزینه معادل با گزینهٔ resolve_script در فایل پیکربندی است. برای جزئیات بیشتر به lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

--select-script callback

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

این گزینه معادل با گزینهٔ select_script در فایل پیکربندی است. برای جزئیات بیشتر به lcovrc(5) <file://../man/lcovrc.5.html> مراجعه نمایید.

--simplify-script callback

استفاده از callback برای کوتاه/ساده‌سازی نام‌های طولانی و رمزگشایی‌شدهٔ (demangled) توابع و الگوهای ++C تا جدول جزئیات تابع جمع‌وجورتر و خواناتر شود؛ به عنوان مثال، برای حذف نام فضاهای نام (namespaces) تو در تو..sp توجه داشته باشید که ساده‌سازی‌ها تنها بر نحوه نمایش تأثیر می‌گذارند و نام‌های واقعی ذخیره‌شده در پایگاه‌داده پوشش (coverage DB) را تغییر نمی‌دهند. به‌ویژه، نام موجود در پایگاه‌داده (و نه نام ساده‌شده) برای تطبیق با الگوهای –erase-function استفاده می‌شود.

این گزینه معادل گزینه simplify_script در فایل پیکربندی است. برای جزئیات به lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

--unreachable-script module

از module برای تصمیم‌گیری درباره اینکه آیا عبارات شرطی انشعاب (branch) یا شرایط MC/DC خاصی باید از گزارش پوشش حذف شوند یا خیر، استفاده کنید. این گزینه معادل گزینه unreachable_script در فایل پیکربندی است. برای جزئیات به lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

توجه داشته باشید که “module” الزاماً باید یک ماژول Perl باشد.

به بحث پیرامون –unreachable-script در بخش «Script conventions» در بالا، و بخش «Exclusion markers» در geninfo(1) <file://../man/geninfo.1.html> مراجعه کنید.

--checksum

مشخص می‌کند که آیا چک‌سام ذخیره‌شده در tracefile با چک‌سام محاسبه‌شده از کد منبع مقایسه شود یا خیر.

اعتبارسنجی چک‌سام به‌طور پیش‌فرض غیرفعال (disabled) است.

هنگامی که اعتبارسنجی چک‌سام فعال باشد، برای هر خط از کد منبع یک چک‌سام محاسبه شده و با چک‌سام موجود در tracefile «فعلی» (current) مقایسه می‌شود. این کار به جلوگیری از تلاش برای نمایش کدهای منبعی که با کد استفاده‌شده برای تولید داده‌های پوشش یکسان نیستند کمک می‌کند.

توجه داشته باشید که این گزینه تا حدی تحت‌الشعاع گزینه --version-script قرار می‌گیرد - که عملکردی مشابه اما در سطح «کل فایل» دارد.

--fail-under-branches percentage

از این گزینه استفاده کنید تا به genhtml اعلام شود در صورتی که کل پوشش انشعاب کمتر از percentage باشد، با وضعیت ۱ خارج شود. برای جزئیات بیشتر به lcov(1) <file://../man/lcov.1.html> مراجعه کنید.

--fail-under-lines percentage

از این گزینه استفاده کنید تا به genhtml اعلام شود در صورتی که کل پوشش خطوط کمتر از percentage باشد، با وضعیت ۱ خارج شود. برای جزئیات بیشتر به lcov(1) <file://../man/lcov.1.html> مراجعه کنید.

--new-file-as-baseline

به‌طور پیش‌فرض، هنگامی که کدی در خطوط منبع در داده‌های «current» شناسایی شود که در داده‌های «baseline» به‌عنوان کد شناخته نشده بودند، اما متن منبع تغییری نکرده است، نقاط پوشش (coverpoints) آن‌ها در دسته «کد گنجانده‌شده» دسته‌بندی می‌شوند: GIC یا UIC.

با این حال، اگر پیکربندی وظیفه پوشش اخیراً تغییر کرده باشد تا فایل‌های بیشتری را ابزارگذاری (instrument) کند، تمام نقاط پوشش اجرا‌نشده در آن فایل‌ها در دسته GIC قرار می‌گیرند - که ممکن است باعث ناموفق شدن بررسی‌های معیارهای پوشش خاصی شود.

هنگامی که این گزینه مشخص شود، genhtml وانمود می‌کند که داده‌های baseline برای فایل همان داده‌های current است - بنابراین نقاط پوشش به‌عنوان CBC یا UBC دسته‌بندی می‌شوند که بررسی معیارهای پوشش را فعال نمی‌کنند.

لطفاً توجه داشته باشید که نقاط پوشش در فایل تنها زمانی باز‌دسته‌بندی می‌شوند که:

--elide-path-mismatch

دسته‌بندی تفاضلی از مسیرهای فایل برای تطبیق ورودی‌های پوشش از فایل «.info» با ورودی‌های تفاوت فایل در unified-diff-file استفاده می‌کند. اگر ورودی‌ها یکسان نباشند، دسته‌بندی ممکن است نادرست یا نامتعارف باشد.

هنگامی که مسیرها مطابقت نداشته باشند، genhtml پیام‌های خطای «path» تولید می‌کند تا شما را از عدم تطابق‌ها مطلع سازد.

اگر عدم تطابق رخ دهد، بهترین راه حل اصلاح ورودی‌های نادرست در فایل‌های .info و/یا unified-diff-file است. با این حال، اگر اصلاح این ورودی‌ها امکان‌پذیر نباشد، می‌توانید از این گزینه برای تلاش جهت دور زدن خودکار آن‌ها استفاده کنید.

هنگامی که این گزینه مشخص شود، genhtml وانمود خواهد کرد که ورودی unified-diff-file با ورودی‌های فایل .info مطابقت دارد اگر:

برای بحث در مورد نحوه جلوگیری از هشدارهای کاذب و/یا تطبیق‌های نادرست، به مدخل‌های --diff-file و --build-directory مراجعه کنید.

--synthesize-missing

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

هنگام تولید محتوای فایل حاشیه‌نویسی‌شده، genhtml فرض می‌کند که منبع «اکنون» (now) نوشته شده است (بنابراین سن آن صفر است)، نویسنده no.body است و شناسه کامیت برابر با synthesized می‌باشد. این نام‌ها و سن‌ها در گزارش‌های HTML شما ظاهر خواهند شد.

این گزینه معادل پارامتر genhtml_synthesize_missing در فایل پیکربندی است؛ برای جزئیات به lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

--date-bins day[,day,…]

گزینه --date-bins برای تعیین مرزهای سن یا زمان (نقاط برش) جهت دسته‌بندی بر اساس بازه زمانی (date-binning) استفاده می‌شود. انتظار می‌رود هر عنصر age یک عدد صحیح از روزهای قبل از امروز (یا قبل از متغیر محیطی SOURCE_DATE_EPOCH شما، در صورت تنظیم) باشد. اگر –date-bins مشخص نشود، حالت پیش‌فرض استفاده از ۴ بازه سنی است: کمتر از ۷ روز، ۷ تا ۳۰ روز، ۳۰ تا ۱۸۰ روز، و بیش از ۱۸۰ روز. این گزینه معادل گزینه genhtml_date_bins در فایل پیکربندی است. به lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

این آرگومان در صورت عدم وجود source-annotation-script هیچ تأثیری ندارد.

--date-labels string[,string,…]

گزینه --date-labels برای تعیین برچسب‌های مورد استفاده در مدخل‌های جدول «date-bin» در گزارش HTML به کار می‌رود. تعداد برچسب‌ها باید یکی بیشتر از تعداد نقاط برش باشد. در صورت عدم تعیین، پیش‌فرض استفاده از رشته‌های برچسبی است که بازه سنی [from ..to) نگه‌داری‌شده توسط bin مربوطه را مشخص می‌کنند.

یکی از کاربردهای ممکن این گزینه، استفاده از نام‌های انتشار (release) در جدول‌ها است - i.e.، برای مشخص کردن انتشاری که هر خط خاص برای اولین بار در آن ظاهر شده است.

این گزینه معادل گزینه genhtml_date_labels در فایل پیکربندی است. به lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

این آرگومان در صورت عدم وجود source-annotation-script هیچ تأثیری ندارد.

--show-owners [ all ]

اگر از گزینه --show-owners استفاده شود، سربرگ هر گزارش پوشش شامل یک جدول خلاصه خواهد بود که آمار دسته‌های مختلف پوشش را برای هر فردی که در حاشیه‌نویسی سیستم کنترل نسخه به‌عنوان آخرین ویرایشگر خط مربوطه ظاهر شده، نمایش می‌دهد. اگر آرگومان اختیاری «all» مشخص نشود، جدول تنها کاربرانی را نشان می‌دهد که مسئول خطوط کد اجرا‌نشده هستند. اگر آرگومان اختیاری مشخص شود، کاربرانی که مسئول هر خطی از کد هستند نمایش داده خواهند شد. در هر دو حالت، کاربرانی که مسئول خطوط غیرکد (مانند توضیحات) هستند نشان داده نمی‌شوند. این گزینه در صورتی که از --annotate-script استفاده نشود هیچ کاری انجام نمی‌دهد؛ چرا که به اطلاعات کنترل نسخه ارائه‌شده از طریق فراخوانی اسکریپت نیاز دارد.

لطفاً توجه داشته باشید: اگر گزینه all مشخص نشده باشد، جدول خلاصه شامل ردیف‌های «Total» برای تمام دسته‌های تاریخ/مالک که خالی نیستند خواهد بود - اما هیچ مدخل فرعی «File/Directory» برای مواردی که هیچ نقطه پوشش از دست‌رفته‌ای («missed») ندارند وجود نخواهد داشت.

این گزینه معادل پارامتر genhtml_show_owner_table در فایل پیکربندی است؛ برای جزئیات به lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

دستورات کنترلی owner_table_entries و truncate_owner_table در lcovrc می‌توانند برای بهبود خوانایی از طریق محدود کردن تعداد نویسندگانی که در جدول نمایش داده می‌شوند هنگام بالا بودن تعداد آن‌ها، استفاده شوند. برای مثال، اگر پیکربندی شما چنین باشد:

آنگاه جدول مالکان نمایش‌داده‌شده در سطوح بالا (top) و دایرکتوری کوتاه و محدود خواهد شد، در حالی که جدول نمایش‌داده‌شده در سطح فایل («file») فهرست کامل را نشان می‌دهد.

برای جزئیات به lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

--show-noncode

به‌طور پیش‌فرض، نمای جزئیات کد منبع، حاشیه‌نویسی‌های مالک یا تاریخ را در دورترین ستون سمت چپ برای خطوط غیرکد (e.g.، توضیحات) نمایش نمی‌دهد. اگر از گزینه --show-noncode استفاده شود، نمای کد منبع حاشیه‌نویسی‌ها را برای هر دو خطوط کد و غیرکد نشان خواهد داد. این آرگومان در صورت عدم وجود source-annotation-script هیچ تأثیری ندارد.

این گزینه معادل پارامتر genhtml_show_noncode_owners در فایل پیکربندی است؛ برای جزئیات به lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

--show-zero-columns

به‌طور پیش‌فرض، ستون‌هایی که تمام ورودی‌های آن‌ها صفر است از جدول خلاصه در بالای هر صفحه HTML حذف می‌شوند (نشان داده نمی‌شوند). اگر از گزینه --show-zero-columns استفاده شود، آن ستون‌ها نمایش داده خواهند شد.

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

هنگامی که ستون‌ها حذف شوند، جداول جمع‌وجورتر بوده و خواندن آن‌ها آسان‌تر است. این موضوع به‌ویژه در محیط‌های توسعه نسبتاً بالغ که در آن‌ها نقاط پوشش اجرا‌نشده در پروژه بسیار کم است، صادق است.

--show-navigation

به‌طور پیش‌فرض در گزارش‌های پوشش غیرتفاضلی، جدول خلاصه در نمای جزئیات کد منبع شامل هایپرلینک‌هایی از شماره به اولین خط در دسته مربوطه («Hit» یا «Missed») و از مکان فعلی به مکان بعدی در دسته فعلی نیست. (این نمای سنتی یا «legacy» مربوط به گزارش‌های غیرتفاضلی lcov است.)

اگر از گزینه --show-navigation استفاده شود، جدول خلاصه کد منبع همراه با پیوندهای ناوبری ایجاد می‌شود. هایپرلینک‌ها همواره برای گزارش‌های پوشش تفاضلی ایجاد می‌شوند.

این ویژگی به توسعه‌دهندگان امکان می‌دهد مشکلات پوشش را سریع‌تر از حالتی که مجبور به پیمایش و اسکرول باشند، بیابند و درک کنند.

برای توضیحی درباره یک باگ مرورگر که این هایپرلینک‌ها را در شرایط خاص غیرفعال می‌کند، به توضیحات –frames در بالا مراجعه کنید.

پیوندهای ناوبری همیشه در گزارش پوشش تفاضلی فعال هستند.

--show-proportions

در جدول «جزئیات پوشش توابع» (function coverage detail)، درصد خطوط و انشعاب‌های درون تابع را نیز که اجرا شده‌اند نشان می‌دهد.

این ویژگی توسعه‌دهندگان را قادر می‌سازد تا توجه خود را بر روی توابعی متمرکز کنند که بیشترین تأثیر را بر کل پوشش کد دارند.

این ویژگی به‌طور پیش‌فرض غیرفعال است. توجه داشته باشید که این گزینه مستلزم استفاده از نسخه‌ای از کامپایلر است که به اندازه کافی جدید باشد تا از گزارش‌های خط شروع/پایان تابع پشتیبانی کند یا اینکه ابزار را برای استخراج داده‌های مورد نیاز پیکربندی کنید - به بحث derive_function_end_line در lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

--simplified-colors

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

--exclude pattern

پارامتر pattern یک الگوی انطباق glob از نام‌فایل‌ها برای حذف از گزارش است. فایل‌هایی که با الگو مطابقت ندارند در گزارش لحاظ خواهند شد. برای جزئیات به صفحه راهنمای lcov مراجعه کنید.

--include pattern

پارامتر pattern یک الگوی انطباق glob از نام‌فایل‌ها برای گنجاندن در پردازش است. فایل‌هایی که مطابقت ندارند از گزارش کنار گذاشته خواهند شد. برای جزئیات به صفحه راهنمای lcov مراجعه کنید.

--erase-functions regexp

داده‌های پوشش را از خطوطی که درون تابعی قرار دارند که نام آن با regexp ارائه‌شده مطابقت دارد، حذف می‌کند. توجه داشته باشید که این نام، بسته به استفاده یا عدم استفاده از گزینه --demangle-cpp، نام mangled یا demangled خواهد بود.

توجه داشته باشید که این گزینه نیازمند استفاده از نسخه‌ای از کامپایلر است که به اندازه کافی جدید باشد تا از گزارش‌های خط شروع/پایان تابع پشتیبانی کند یا اینکه ابزار را برای استخراج داده‌های مورد نیاز پیکربندی کنید - به بحث derive_function_end_line در lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

--substitute regexp_pattern

عبارت باقاعده پرل regexp_pattern را روی نام‌های فایل منبع که در حین پردازش یافت شده‌اند اعمال می‌کند. این گزینه زمانی مفید است که برخی مسیرهای فایل در فایل .info پایه (baseline) یا فعلی (current) با چیدمان منبع شما مطابقت نداشته و در نتیجه کد منبع یافت نمی‌شود. برای جزئیات بیشتر به صفحه راهنمای lcov مراجعه کنید.

توجه داشته باشید که الگوهای جایگزینی بر روی مدخل‌های –diff-file و همچنین فایل‌های .info پایه و فعلی اعمال می‌شوند.

--omit-lines regexp_pattern

داده‌های پوشش را از خطوطی که محتوای آن‌ها با regexp مطابقت دارد حذف می‌کند.

اگر می‌خواهید داده‌های پوشش خط و انشعاب را برای برخی ساختارهای خاص در کد خود (e.g.، یک ماکروی پیچیده) نادیده بگیرید، از این سوئیچ استفاده کنید. برای جزئیات به صفحه راهنمای lcov مراجعه کنید.

--parallel [integer], -j [integer]

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

همچنین مدخل‌های memory, memory_percentage, max_fork_fails و fork_fail_timeout را در lcovrc(5) <file://../man/lcovrc.5.html> ببینید.

یک نمایه (profile) اجرای از پیش تولیدشده ممکن است به استفاده بهتر از منابع و اجرای موازی سریع‌تر کمک کند. بخش‌های –profile و –history-script در این صفحه راهنما را ببینید.

--memory integer

حداکثر مقدار حافظه مورد استفاده در طول پردازش موازی را بر حسب مگابایت (Mb) مشخص می‌کند. در عمل، اگر این محدودیت نقض شود، فرآیند ()fork را انجام نخواهد داد. مقدار پیش‌فرض 0 (صفر) است - که به معنای عدم وجود محدودیت می‌باشد.

این گزینه ممکن است زمانی مفید باشد که محیط مزرعه محاسباتی (compute farm) محدودیت‌های سفت‌وسختی بر مصرف منابع اعمال می‌کند، به‌گونه‌ای که اگر کار تلاش کند فرآیندهای فرزند موازی بیش از حدی ایجاد کند متوقف (kill) خواهد شد - اما کاربر از قبل نمی‌داند حداکثر مجاز چقدر است. این گزینه ابزار را قادر می‌سازد از حداکثر موازی‌سازی ممکن - تا سقف تعیین‌شده توسط محدودیت حافظه - استفاده کند.

گزینه memory_percentage در فایل پیکربندی روش دیگری را برای تعیین حداکثر مصرف حافظه ارائه می‌دهد. برای جزئیات به راهنمای lcovrc (5) مراجعه کنید.

--filter filters

فهرستی از فیلترهای نقاط پوشش (coverpoint filters) را برای اعمال روی داده‌های ورودی مشخص می‌کند.

توجه داشته باشید که برخی فیلترها تنها برای فایل‌های منبع C/C++ اعمال می‌شوند. genhtml پسوند فایل (مانند «.c»، «.vhd»، etc.) را با زبان منبع آن مرتبط می‌سازد. برای توضیحات مربوط به ارتباط‌های پیش‌فرض و نحوه تغییر آن‌ها، به بخش‌های c_file_extensions و rtl_file_extensions در lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

توجه داشته باشید که فیلترها در صورت لزوم بر روی هر دو نقاط پوشش «branch» و «MC/DC» اعمال می‌شوند: اگر یک فیلتر خاص انشعابی را حذف کند، نقاط پوشش MC/DC متناظر را نیز حذف خواهد کرد - برای مثال، –filter branch در صورتی که هیچ عبارت شرطی در خط مربوطه نباشد، نقاط پوشش MC/DC را حذف می‌کند، و –filter branch_region هر دو نقاط پوشش انشعاب و MC/DC را در ناحیه نشانه‌گذاری‌شده حذف خواهد کرد.

بیشتر فیلترها به کد منبع نیاز دارند؛ در صورتی که فایل منبع در دسترس نباشد، فیلترها اعمال نمی‌شوند. به‌طور مشابه، برای هر فایل منبع، اگر نسخه ثبت‌شده در داده‌های پوشش (فایل «.info») با نسخه موجود در سیستم‌فایل مطابقت نداشته باشد، یک خطای version گزارش می‌شود. در صورت نادیده گرفتن خطای version، فیلترسازی روی فایل ناسازگار اعمال نمی‌شود. برای اطلاعات بیشتر به –version-script مراجعه کنید.

مقدار filters می‌تواند فهرستی از کلیدواژه‌های زیر باشد که با کاما از یکدیگر جدا شده‌اند:

-o, --output-directory output-directory

ایجاد فایل‌ها در output-directory.

از این گزینه استفاده کنید تا به genhtml بگویید فایل‌های حاصل را در دایرکتوری دیگری غیر از دایرکتوری فعلی بنویسد. اگر output-directory وجود نداشته باشد، ایجاد خواهد شد.

توصیه می‌شود از این گزینه استفاده شود زیرا بسته به اندازه پروژه، ممکن است تعداد زیادی فایل و زیردایرکتوری ایجاد شود.

-t, --title title

نمایش title در جدول سربرگ تمامی صفحات.

مقدار title در فیلد «:Test» در جدول سربرگ بالای هر صفحه HTML تولیدشده نوشته می‌شود تا زمینه‌ای را که خروجی خاص در آن ایجاد شده است مشخص کند. به طور پیش‌فرض، این مقدار نام tracefile فعلی است.

یک کاربرد متداول، تعیین نام اجرای آزمون یا یک شناسه سیستم کنترل نسخه (برای مثال changelist در perforce یا SHA در git) است که سطح کدی را که آزمایش شده نشان می‌دهد.

--header-title BANNER

نمایش BANNER در سربرگ تمام صفحات.

مقدار BANNER در بخش سربرگ هر صفحه HTML تولیدشده نوشته می‌شود. به طور پیش‌فرض، این بخش صرفاً این گزارش را به عنوان یک گزارش پوشش LCOV (تفاضلی) معرفی می‌کند.

یک کاربرد متداول، تعیین نام پروژه یا شاخه پروژه و شناسه ساخت Jenkins است.

--footer FOOTER

نمایش FOOTER در پاورقی تمام صفحات.

مقدار FOOTER در بخش پاورقی هر صفحه HTML تولیدشده نوشته می‌شود. پیش‌فرض صرفاً نسخه ابزار LCOV استفاده‌شده برای تولید گزارش را مشخص می‌کند.

-d, --description-file description-file

خواندن توصیف‌های مورد آزمون از description-file.

تمامی توصیف‌های مورد آزمون یافت‌شده در description-file که در فایل داده‌های ورودی به آن‌ها ارجاع داده شده است، خوانده شده و در یک صفحه اضافی نوشته می‌شوند که سپس در خروجی HTML گنجانده می‌شود.

قالب فایل description-file به صورت زیر است:

برای هر مورد آزمون:

نام‌های معتبر مورد آزمون می‌توانند شامل حروف، اعداد و نویسه زیرخط (‘_’) باشند.

-k, --keep-descriptions

عدم حذف توصیف‌های استفاده‌نشده آزمون.

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

این گزینه همچنین می‌تواند به صورت دائمی با استفاده از گزینه فایل پیکربندی genhtml_keep_descriptions تنظیم شود.

-c, --css-file css-file

استفاده از فایل شیوه‌نامه خارجی css-file.

با استفاده از این گزینه، می‌توان یک فایل css. اضافی مشخص کرد که جایگزین فایل پیش‌فرض خواهد شد. این ممکن است در صورتی مفید باشد که رنگ‌های پیش‌فرض چشم‌های شما را اذیت کنند :)

این گزینه همچنین می‌تواند به صورت دائمی با استفاده از گزینه فایل پیکربندی genhtml_css_file تنظیم شود.

--build-directory dirname

برای پشتیبانی از ساختارهای «دایرکتوری ساخت پیوندشده»، افزودن ‘dirname’ به فهرست مکان‌های جستجو برای پیوندهای نمادین (soft links) به فایل‌های منبع - برای نمونه برای مدیریت حالتی که پیوندها به فایل‌های منبع نگهداری‌شده در سیستم کنترل نسخه شما اشاره می‌کنند و در داده‌های --diff-file ظاهر می‌شوند. در این حالت، مسیرها در داده‌های پوشش به احتمال بسیار زیاد به ساختار دیده‌شده توسط کامپایلر هنگام ساخت اشاره دارند - بنابراین تطبیق مجدد آن‌ها با ساختار منبع متناظر در کنترل نسخه به احتمال زیاد موفقیت‌آمیز خواهد بود.

جستجو در dirname برای مسیرهای فایلی که در tracefile ظاهر می‌شوند - احتمالاً پس از اعمال جایگزینی‌ها - و پیوند نمادین هستند. هم مسیر فایل اصلی و هم مسیر فایل پیوندشده به همان مدخل --diff-file متناظر ارجاع داده خواهند شد.

این گزینه را می‌توان چندین بار مشخص کرد تا دایرکتوری‌های بیشتری به مسیر جستجو اضافه شوند.

--source-directory dirname

افزودن ‘dirname’ به فهرست مکان‌های جستجوی فایل‌های منبع.

برای مسیرهای نسبی فایل‌های منبع، برای نمونه مسیرهای یافت‌شده در tracefile یا در diff-file - احتمالاً پس از اعمال جایگزینی‌ها - genhtml ابتدا مسیر را از مبدأ ‘cwd’ (جایی که genhtml اجرا شده است) و سپس از هر نام دایرکتوری جایگزین به ترتیب مشخص‌شده بررسی می‌کند. نخستین مکانی که مطابقت داشته باشد استفاده می‌شود.

این گزینه را می‌توان چندین بار مشخص کرد تا دایرکتوری‌های بیشتری به مسیر جستجوی منبع افزوده شوند.

-p, --prefix prefix

حذف prefix از ابتدای تمام نام‌های دایرکتوری.

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

از این گزینه برای مشخص کردن پیشوندی که می‌خواهید توسط خودتان حذف شود استفاده کنید.

--no-prefix

عدم حذف پیشوند از نام‌های دایرکتوری.

این سوییچ مکانیزم پیشوند توضیح داده شده در بخش قبلی را به طور کامل غیرفعال می‌کند.

این گزینه همچنین می‌تواند به صورت دائمی با استفاده از گزینه فایل پیکربندی genhtml_no_prefix تنظیم شود.

--no-source

عدم ایجاد نمای کد منبع.

اگر نمی‌خواهید برای هر فایل یک نمای کد منبع داشته باشید، از این سوییچ استفاده کنید.

این گزینه همچنین می‌تواند به صورت دائمی با استفاده از گزینه فایل پیکربندی genhtml_no_source تنظیم شود.

--no-html

عدم ایجاد گزارش HTML.

اگر خروجی خاصی از فرایند تولید گزارش پوشش را می‌خواهید - برای نمونه بررسی معیارهای پوشش یا پایگاه‌داده سریالی‌شده پوشش و غیره - اما خود گزارش HTML پوشش را نیاز ندارید، از این سوییچ استفاده کنید.

--num-spaces spaces

تغییر ظاهر تب‌ها در نمای منبع بر اساس spaces.

در صورت تنظیم روی 0، تب‌ها و رفتار آن‌ها بر اساس پیش‌فرض مرورگر خواهد بود.

مقادیر منفی، پهنای نمایش‌داده‌شده را در نمای منبع به تعداد spaces فاصله (space) تنظیم می‌کنند.

مقادیر مثبت، تب‌ها را با spaces فاصله جایگزین خواهند کرد.

مقدار پیش‌فرض 8 است.

این گزینه همچنین می‌تواند به صورت دائمی با استفاده از گزینه فایل پیکربندی genhtml_num_spaces تنظیم شود.

--highlight

برجسته‌سازی خطوط دارای داده‌های پوشش که فقط تبدیل شده‌اند (converted-only).

از این گزینه در کنار گزینه --diff در lcov استفاده کنید تا خطوطی را برجسته کنید که فقط در مجموعه‌داده‌های تبدیل‌شده از نسخه‌های پیشین کد منبع پوشش داده شده‌اند.

این گزینه همچنین می‌تواند به صورت دائمی با استفاده از گزینه فایل پیکربندی genhtml_highlight تنظیم شود.

--legend

گنجاندن راهنمای رنگ‌ها در خروجی HTML.

از این گزینه استفاده کنید تا راهنمایی که مفهوم کدگذاری رنگ‌ها را شرح می‌دهد در خروجی HTML حاصل گنجانده شود.

این گزینه همچنین می‌تواند به صورت دائمی با استفاده از گزینه فایل پیکربندی genhtml_legend تنظیم شود..TP --html-prolog prolog-file خواندن دیباچه (prolog) سفارشی HTML از prolog-file.

از این گزینه برای جایگزینی دیباچه پیش‌فرض HTML (بخش ابتدایی کد منبع HTML تا و با احتساب برچسب <body>) با محتویات prolog-file استفاده کنید. در متن prolog، هنگام تولید یک صفحه، کلمات زیر جایگزین خواهند شد:

این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی genhtml_html_prolog در فایل پیکربندی به طور دائم تنظیم شود.

--html-epilog epilog-file

خواندن مؤخره (epilog) سفارشی HTML از epilog-file.

از این گزینه برای جایگزینی مؤخره پیش‌فرض HTML (بخش پایانی کد منبع HTML شامل </body>) با محتویات epilog-file استفاده کنید.

درون متن مؤخره، هنگام تولید یک صفحه، کلمات زیر جایگزین خواهند شد:

این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی genhtml_html_epilog در فایل پیکربندی به طور دائم تنظیم شود.

--html-extension extension

استفاده از پسوند فایل سفارشی برای صفحه‌های HTML تولیدشده.

این گزینه در مواردی مفید است که برای رندر صحیح صفحات حاصل، به پسوندهای نام فایل متفاوتی نیاز باشد (مثلاً php). توجه داشته باشید که یک «.» بین نام فایل و پسوند مشخص‌شده با این گزینه درج خواهد شد.

این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی genhtml_html_extension در فایل پیکربندی به طور دائم تنظیم شود.

--html-gzip

فشرده‌سازی تمام فایل‌های html تولیدشده با gzip و افزودن یک فایل .htaccess که gzip-encoding را مشخص می‌کند در دایرکتوری خروجی ریشه.

اگر می‌خواهید در فضای وب‌سرور خود صرفه‌جویی کنید از این گزینه استفاده نمایید. این قابلیت نیازمند وب‌سروری با پشتیبانی از .htaccess و مرورگری با پشتیبانی از html فشرده‌شده با gzip است.

این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی genhtml_html_gzip در فایل پیکربندی به طور دائم تنظیم شود.

--sort-tables, --no-sort

مشخص کردن اینکه آیا نماهای مرتب‌شده از نمای کلی فایل‌ها و دایرکتوری‌ها گنجانده شود یا خیر.

از --sort-tables برای گنجاندن نماهای مرتب‌شده یا از --no-sort برای عدم درج آن‌ها استفاده کنید. نماهای مرتب‌شده به طور پیش‌فرض فعال هستند.

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

این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی genhtml_sort در فایل پیکربندی به طور دائم تنظیم شود.

--function-coverage, --no-function-coverage

مشخص کردن نمایش یا عدم نمایش خلاصه‌های پوشش توابع در خروجی HTML.

از --function-coverage برای فعال‌سازی خلاصه‌های پوشش توابع یا از --no-function-coverage برای غیرفعال کردن آن استفاده کنید. خلاصه پوشش توابع به طور پیش‌فرض فعال است.

این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی genhtml_function_coverage در فایل پیکربندی به طور دائم تنظیم شود.

هنگامی که خلاصه‌های پوشش توابع فعال باشند، هر صفحه نمای کلی شامل تعداد توابع یافت‌شده و فراخوانی‌شده (hit) به ازای هر فایل یا دایرکتوری، به همراه نرخ پوشش حاصل خواهد بود. علاوه بر این، هر نمای کد منبع شامل پیوندی به صفحه‌ای خواهد بود که تمام توابع یافت‌شده در آن فایل به علاوه تعداد فراخوانی‌های مربوط به آن توابع را فهرست می‌کند. صفحه پوشش تابع، داده‌ها را برای هر نام مستعار (alias) از هر تابع گروه‌بندی کرده و بر اساس نام یا تعداد اجرا مرتب می‌کند. نام نمایانگر گروه توابع، کوتاه‌ترین نام است (یعنی دارای کمترین نویسه است).

در صورت استفاده از پوشش تفاضلی (differential coverage) و نسخه کامپایلر به اندازه کافی جدید که هم خط شروع و هم خط پایان توابع را گزارش می‌کند (مثلاً gcc/9 و جدیدتر)، توابعی که هر یک از خطوط کد منبع آن‌ها تغییر کرده باشد، «جدید» در نظر گرفته می‌شوند. با نسخه‌های قدیمی‌تر کامپایلر، توابع تنها در صورتی «جدید» در نظر گرفته می‌شوند که امضای تابع تغییر کرده باشد یا کل تابع جدید باشد.

--branch-coverage, --no-branch-coverage

مشخص کردن نمایش یا عدم نمایش داده‌های پوشش شاخه در خروجی HTML.

از --branch-coverage برای فعال‌سازی نمایش پوشش شاخه یا از --no-branch-coverage برای غیرفعال کردن آن استفاده کنید. نمایش داده‌های پوشش شاخه به طور پیش‌فرض غیرفعال است.

هنگامی که نمایش پوشش شاخه فعال باشد، هر صفحه نمای کلی شامل تعداد شاخه‌های یافت‌شده و طی‌شده به ازای هر فایل یا دایرکتوری، به همراه نرخ پوشش حاصل خواهد بود. علاوه بر این، هر نمای کد منبع شامل یک ستون اضافی خواهد بود که تمام شاخه‌های یک خط را به همراه نشانگری مبنی بر اینکه آیا شاخه طی شده (taken) یا خیر فهرست می‌کند. شاخه‌ها در قالب زیر نشان داده می‌شوند:

' + ': شاخه حداقل یک بار طی شده است
' - ': شاخه طی نشده است
' # ': بلوک پایه‌ای شامل شاخه هرگز اجرا نشده است

توجه داشته باشید که ممکن است همیشه ارتباط دادن شاخه‌ها به عبارت‌های متناظر در کد منبع ممکن نباشد: در طول کامپایل، GCC ممکن است برای تولید کد بهتر، شاخه‌ها را جابه‌جا کرده یا برخی از آن‌ها را حذف کند.

این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی branch_coverage در فایل پیکربندی به طور دائم تنظیم شود.

--mcdc-coverage

مشخص کردن نمایش داده‌های پوشش شرط/تصمیم اصلاح‌شده (MC/DC) در خروجی HTML.

نمایش داده‌های MC/DC به طور پیش‌فرض غیرفعال است.

پوشش MC/DC در نسخه‌های GCC 14.2 به بالا، یا LLVM 18.1 به بالا پشتیبانی می‌شود.

برای جزئیات مربوط به دریافت داده‌های MC/DC در LLVM به llvm2lcov --help مراجعه کنید.

هنگامی که نمایش MC/DC فعال باشد، هر صفحه نمای کلی شامل تعداد عبارت‌های MC/DC یافت‌شده و اجراشده به ازای هر فایل یا دایرکتوری - دو جهت به ازای هر عبارت - به همراه نرخ پوشش حاصل خواهد بود. علاوه بر این، هر نمای کد منبع شامل یک ستون اضافی خواهد بود که تمام عبارات و جهت‌های شرط یک خط را به همراه نشانگری مبنی بر اینکه آیا شرط حساس شده (sensitized) است یا خیر، فهرست می‌کند. شرط‌ها در قالب زیر نمایش داده می‌شوند:

توجه داشته باشید در صورتی که شرط یک عبارت ساده باشد، پوشش شاخه و MC/DC یکسان هستند - مثلاً:

if (enable) ...

توجه داشته باشید که در صورت نیاز، فیلترها هم بر نقاط پوشش «branch» و هم بر نقاط پوشش «MC/DC» اعمال می‌شوند: اگر فیلتر خاصی شاخه‌ای را حذف کند، نقاط پوشش مربوط به MC/DC آن را نیز حذف خواهد کرد. بخش --filter در بالا را ببینید.

این گزینه همچنین می‌تواند با استفاده از گزینه پیکربندی mcdc_coverage در فایل پیکربندی به طور دائم تنظیم شود. به lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

توجه داشته باشید که نقاط پوشش MC/DC توسط GCC و LLVM به طور متفاوتی تعریف می‌شوند.

--demangle-cpp [ param ]

مشخص کردن اینکه آیا نام توابع C++ رمزگشایی (demangle) شوند یا خیر.

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

در صورت فراخوانی بدون پارامتر، genhtml از c++filt برای رمزگشایی استفاده خواهد کرد. این نیازمند نصب بودن ابزار c++filt است (به c++filt(1) مراجعه کنید).

اگر param مشخص شده باشد، به عنوان ابزاری در نظر گرفته می‌شود که باید برای رمزگشایی کد منبع فراخوانی شود. گزینه --demangle-cpp می‌تواند چندین بار برای مشخص کردن ابزار رمزگشایی و مجموعه‌ای از گزینه‌های خط فرمان که به ابزار ارسال می‌شوند استفاده شود - مشابه نحوه عملکرد پارامتر -Xlinker در gcc. در این حالت، فراخوان (callback) شما به صورت | demangle_param0 demangle_param1 … اجرا خواهد شد. توجه داشته باشید که ابزار demangle به عنوان یک لوله (pipe) فراخوانی می‌شود و انتظار می‌رود از stdin بخواند و در stdout بنویسد.

--msg-log [ log_file_name ]

مشخص کردن مکانی برای ذخیره پیام‌های خطا و هشدار (علاوه بر نوشتن در STDERR). اگر log_file_name مشخص نشود، مکان پیش‌فرض استفاده خواهد شد.

--ignore-errors errors

مشخص کردن فهرستی از خطاها که پس از رخ دادن آن‌ها پردازش ادامه می‌یابد.

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

errors می‌تواند فهرستی از کلیدواژه‌های زیر باشد که با کاما از یکدیگر جدا شده‌اند:

توجه داشته باشید که برخی پیام‌های خطا ناشی از مسائلی هستند که احتمالاً خودتان نمی‌توانید آن‌ها را برطرف کنید - برای نمونه، باگ‌هایی در زنجیره ابزار شما که منجر به ایجاد داده‌های پوشش inconsistent در پایگاه‌داده می‌شوند (به بالا مراجعه کنید). در این موارد، پس از بررسی پیام‌ها، ممکن است بخواهید کد خاطی یا کل فایل خاطی را مستثنی کنید، یا صرفاً پیام‌ها را نادیده بگیرید - چه با تبدیل به هشدار و چه با نادیده‌گیری (suppress) کامل آن‌ها. راهکار دیگر این است که به genhtml درباره تعداد پیام‌هایی که انتظار دارید اطلاع دهید - تا در صورتی که تغییری رخ داد و تعداد پیام‌ها متفاوت شد به شما هشدار دهد و متوجه شوید که باید پیام‌ها را مجدداً بازبینی کنید. پرچم –expect-message-count را در ادامه ببینید.

همچنین برای بررسی پارامتر «max_message_count» که می‌تواند برای کنترل تعداد هشدارهای صادرشده پیش از نادیده‌گیری تمام پیام‌های بعدی استفاده شود، به ‘lcovrc(5) <file://../man/lcovrc.5.html>’ مراجعه کنید. این پارامتر می‌تواند برای کاهش حجم فایل لاگ به کار رود.

--expect-message-count message_type:expr[,message_type:expr]

محدودیتی برای genhtml در مورد تعداد پیام‌های یک یا چند نوع که انتظار می‌رود در طول اجرا تولید شوند، مشخص می‌کند. توجه داشته باشید که این مجموع شامل _همه_ پیام‌های نوع مشخص‌شده است - از جمله پیام‌هایی که سرکوب و نادیده گرفته شده‌اند. اگر شرط برقرار نباشد، خطایی از نوع count (به بالا مراجعه کنید) ایجاد می‌شود. مقدار message_type یکی از شناسه‌های پیام توصیف‌شده در بالا است و expr می‌تواند یکی از موارد زیر باشد:

برای نمونه:

--expect-message-count inconsistent:5

بیان می‌کند که ما دقیقاً انتظار ۵ پیام از نوع «inconsistent» را داریم.

--expect-message-count inconsistent:%C==5

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

--expect-message-count 'inconsistent : %C > 6 && %C <= 10'

بیان می‌کند که ما انتظار داریم تعداد پیام‌ها در محدوده (6:10] باشد. (توجه داشته باشید که اگر می‌خواهید با افزودن فاصله به عبارت خود خوانایی آن را افزایش دهید، ممکن است قرار دادن عبارت در علامت نقل‌قول جهت جلوگیری از تفسیر فاصله‌ها توسط شل شما ضروری باشد.)

چندین محدودیت را می‌توان با استفاده از یک فهرست جداشده با کاما یا با تکرار چندباره این گزینه مشخص کرد.

این پرچم معادل گزینه پیکربندی expect_message_count است. برای جزئیات بیشتر درباره نحو عبارات و چگونگی تفسیر آن‌ها، lcovrc(5) <file://../man/lcovrc.5.html> را ببینید. تعداد پیام‌های نوع مورد نظر پیش از ارزیابی عبارت، در آن جایگزین می‌شود.

--keep-going

در صورت بروز خطا متوقف نشو: برای تولید نتیجه، حتی با وجود نقص و اشکال، تلاش کن.

این گزینه خط فرمان متناظر با گزینه stop_on_error در lcovrc است. برای جزئیات بیشتر lcovrc(5) <file://../man/lcovrc.5.html> را ببینید.

--config-file config-file

فایل پیکربندی مورد استفاده را مشخص می‌کند. برای جزئیات قالب فایل و گزینه‌ها، lcovrc(5) <file://../man/lcovrc.5.html> را ببینید. همچنین برای جزئیات چگونگی فراخوانی یک فایل پیکربندی درون فایلی دیگر، مدخل config_file را در همان صفحه راهنما مطالعه کنید..sp هنگامی که این گزینه مشخص شود، نه فایل پیکربندی سراسری سیستم /etc/lcovrc و نه فایل پیکربندی اختصاصی کاربر ~/.lcovrc خوانده نخواهند شد.

این گزینه ممکن است زمانی مفید باشد که نیاز به اجرای هم‌زمان چندین نمونه از genhtml با گزینه‌های فایل پیکربندی متفاوت وجود دارد.

توجه داشته باشید که این گزینه باید به‌طور کامل مشخص شود - مخفف‌سازی پشتیبانی نمی‌شود.

--profile [ profile-data-file ]

به ابزار اعلام می‌کند تا عملکرد و سایر داده‌های پیکربندی را ثبت و پیگیری کند. اگر profile-data-file اختیاری مشخص نشود، داده‌های پروفایل در فایلی به نام genhtml.json در دایرکتوری خروجی نوشته می‌شوند.

داده‌های پروفایل در صورتی که در تلاش برای بهینه‌سازی پیاده‌سازی lcov هستید مفید است (نگاه کنید به $LCOV_ROOT/share/lcov/support-scripts/spreadsheet.py)، و همچنین می‌تواند اجرای سریع‌تر «genhtml –parallel» را ممکن سازد (بخش «–history-script» این صفحهٔ راهنما را ببینید).

--history-script script

به ابزار اعلام می‌کند تا از داده‌های عملکرد حاصل از یک کار (job) قبلی برای پیش‌بینی مصرف منابع توسط کار فعلی استفاده کند. این کار ممکن است بخش‌بندی بهتری را برای برقراری بار کاری متعادل‌تر میان ریسه‌های (threads) موازی فراهم کند - و در نتیجه زمان واقعی اجرا (wall clock) را بهبود بخشد.

یک منبع رایج برای previous-profile-data-file، داده‌های پروفایل تولیدشده بر اثر اجرای قبلی مجموعه آزمون‌های رگرسیون است. به $LCOV_ROOT/share/lcov/example و $LCOV_ROOT/share/lcov/support-scripts/history.pm در نسخهٔ نصب‌شده (یا .../example در مخزن سورس‌کد) مراجعه کنید.

--rc keyword = value

بازنویسی یک دستورالعمل پیکربندی.

از این گزینه برای مشخص کردن عبارت keyword = value استفاده کنید که دستورالعمل پیکربندی متناظر در فایل پیکربندی lcovrc را بازنویسی می‌کند. می‌توانید این گزینه را چند بار مشخص کنید تا چندین دستورالعمل پیکربندی بازنویسی شوند. برای مشاهدهٔ فهرستی از کلیدواژه‌های موجود و معنای آن‌ها به lcovrc(5) <file://../man/lcovrc.5.html> مراجعه کنید.

--precision num

نمایش نرخ‌های پوشش با num رقم بعد از نقطهٔ اعشار.

مقدار پیش‌فرض ۱ است.

این گزینه همچنین می‌تواند با استفاده از گزینهٔ genhtml_precision در فایل پیکربندی، به‌صورت دائمی پیکربندی شود.

--merge-aliases

توابعی که فایل/سطر آن‌ها یکسان است، نام مستعار (alias) یکدیگر در نظر گرفته می‌شوند؛ genhtml از کوتاه‌ترین نام در فهرست نام‌های مستعار (کمترین تعداد نویسه) به عنوان سرشاخه استفاده می‌کند.

این گزینه هر گروه از نام‌های مستعار را به عنوان یک شیء واحد می‌شمارد - بنابراین تعداد «تابع» برابر با تعداد گروه‌های متمایز تابع خواهد بود، نه تعداد کل نام‌های مستعار همهٔ توابع - و آن‌ها را به صورت گروهی در جدول جزئیات تابع نمایش می‌دهد.

توجه داشته باشید که این گزینه تنها در صورتی تأثیرگذار است که "--filter function"; بر روی پایگاه‌دادهٔ پوشش اعمال شده باشد.

این پارامتر می‌تواند از طریق گزینهٔ merge_function_aliases در فایل پیکربندی تنظیم شود. به man(5) lcovrc مراجعه کنید.

--suppress-aliases

نادیده گرفتن فهرست نام‌های مستعار در جدول جزئیات تابع.

توابعی که فایل/سطر آن‌ها یکسان است، نام مستعار در نظر گرفته می‌شوند؛ genhtml از کوتاه‌ترین نام در فهرست نام‌های مستعار (کمترین تعداد نویسه) به عنوان سرشاخه استفاده می‌کند.

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

توجه داشته باشید که این گزینه تنها زمانی تأثیر دارد که "--filter function"; روی پایگاه‌دادهٔ پوشش اعمال شده باشد.

این پارامتر می‌تواند از طریق گزینهٔ merge_function_aliases در فایل پیکربندی تنظیم شود. به man(5) lcovrc مراجعه کنید.

--forget-test-names

اگر غیرصفر باشد، نام‌های آزمایه (testcase) در فایل .info نادیده گرفته می‌شوند - i.e.، با تمام داده‌های پوشش به گونه‌ای رفتار می‌شود که گویی از یک آزمایهٔ یکسان آمده‌اند. این کار می‌تواند در صورتی که کاربر نیازی به خلاصهٔ پوشش بر اساس هر آزمایه در گزارش‌ها نداشته باشد، عملکرد را بهبود بخشیده و مصرف حافظه را کاهش دهد.

این گزینه همچنین می‌تواند با استفاده از گزینهٔ forget_testcase_names در فایل پیکربندی به‌طور دائمی پیکربندی شود.

--missed

نمایش تعداد خطوط، توابع، شاخه‌ها و عبارات MC/DC پوشش‌داده‌نشده.

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

هنگامی که همراه با –sort-tables مشخص شود، نماهای فایل و دایرکتوری بر اساس تعداد موارد پوشش‌داده‌نشده مرتب خواهند شد.

این گزینه همچنین می‌تواند با استفاده از گزینهٔ genhtml_missed در فایل پیکربندی به‌صورت دائمی پیکربندی شود.

--dark-mode

استفاده از طرح رنگی «روشن روی پس‌زمینهٔ تاریک» به‌جای طرح پیش‌فرض «تاریک روی پس‌زمینهٔ روشن».

هدف از این گزینه، کاهش خستگی چشم ناشی از تماشای متن تیره بر روی صفحهٔ نمایش روشن - به‌ویژه در شب - است.

--tempdir dirname

نوشتن داده‌های موقت و میانی در دایرکتوری مشخص‌شده. پیش‌فرض «/tmp» است.

--preserve

نگه‌داری فایل‌های داده‌های میانی تولیدشده توسط مراحل مختلف ابزار - e.g.، جهت اشکال‌زدایی. به‌طور پیش‌فرض، این فایل‌ها حذف می‌شوند.

--save

رونوشت برداشتن از unified-diff-file, baseline_trace_files, و tracefile(s) در دایرکتوری خروجی.

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

--sort-input

تعیین این‌که آیا نام فایل‌ها قبل از دریافت و/یا تجمیع مرتب شوند یا خیر. مرتب‌سازی برخی از انواع تفاوت‌های خروجی وابسته به ترتیب پردازش را کاهش می‌دهد. بخش sort_input را در lcovrc(5) <file://../man/lcovrc.5.html> ببینید.

--serialize file_name

ذخیرهٔ پایگاه‌دادهٔ پوشش در file_name.

این فایل با قالب «Storable» مربوط به Perl است.

توجه داشته باشید که این گزینه ممکن است میزان حافظهٔ مورد نیاز genhtml را به‌طور چشمگیری افزایش دهد، چرا که حجم زیادی از داده‌ها باید در حافظه نگه‌داری شوند.

اسکریپت‌های نمونه ساخت داده –diff-file:

ماژول‌های Perl نمونه کال‌بک –annotate-script:

ماژول‌های Perl نمونه کال‌بک –criteria-script:

ماژول Perl نمونه کال‌بک –simplify-script:

ماژول‌های Perl و اسکریپت‌های نمونه کال‌بک –version-script: