نام (NAME)

kcov - تحلیل پوشش کد برای برنامه‌های کامپایل‌شده و اسکریپت‌های Python

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

kcov [options] out-dir in-file [args-for-executable...]

kcov --merge outdir <path-to-coverage> [path-to-more-coverage...]

توضیحات (DESCRIPTION)

این صفحهٔ راهنما به طور خلاصه دستور kcov را شرح می‌دهد. kcov یک ابزار آزمون پوشش کد برای باینری‌های ELF، اسکریپت‌های Python و اسکریپت‌های شل است. این ابزار امکان جمع‌آوری اطلاعات پوشش کد را از فایل‌های اجرایی بدون نیاز به رهنمودهای ویژهٔ کامپایلر فراهم کرده و به صورت مداوم از برنامه‌های طولانی‌مدت خروجی تولید می‌کند.

برای مستندات بیشتر، به صفحهٔ گیت‌هاب در https://github.com/SimonKagstrom/kcov مراجعه کنید.

گزینه‌ها (OPTIONS)

-p, --pid=PID: ردیابی PID به جای اجرای فایل اجرایی (ارائهٔ فایل اجرایی در این حالت اختیاری است). در این حالت، جمع‌آوری پوشش برای کتابخانه‌های اشتراکی کار نخواهد کرد.
-l, --limits=low,high: تنظیم حد پایین/بالا برای پوشش کد (پیش‌فرض: 25,75).
--include-path=P1[,P2...]: فهرستی جداشده با کاما از مسیرهایی که باید در گزارش گنجانده شوند.
--exclude-path=P1[,P2...]: فهرستی جداشده با کاما از مسیرهایی که باید از گزارش مستثنی شوند.
--include-pattern=P1[,P2...]: فهرستی جداشده با کاما از الگوهای مسیر برای گنجاندن در گزارش.
--exclude-pattern=P1[,P2...]: فهرستی جداشده با کاما از الگوهای مسیر برای مستثنی کردن از گزارش.
--exclude-line=P1[,P2...]: فهرستی جداشده با کاما از الگوهای خطوط برای مستثنی کردن (علامت‌گذاری به عنوان غیرکد).
--exclude-region=START:END[,START1:END1...]: فهرستی جداشده با کاما از الگوهای محدودهٔ خطوط جهت مستثنی کردن (علامت‌گذاری به عنوان غیرکد). محدوده با START آغاز شده و با END پایان می‌یابد.
--clean: عدم انباشت داده‌های حاصل از چندین بار اجرا.
--collect-only: تنها داده‌های پوشش جمع‌آوری شوند و خروجی HTML/Cobertura تولید نشود.
--dump-summary: نمایش خلاصه‌ای مختصر از پوشش کد روی stdout پس از پایان اجرا.
--report-only: تنها خروجی HTML/Cobertura ایجاد شود و داده‌ای جمع‌آوری نشود.
--merge: ادغام نتایج چندین بار اجرای kcov. در این حالت به جای برنامه‌ای برای سنجش، مسیرهای خروجی اجراهای پیشین باید در خط فرمان یا از طریق یک نویسهٔ عام (*) مشخص شوند.
--coveralls-id=id: بارگذاری داده‌ها روی coveralls.io با استفاده از repo_token محرمانه یا شناسهٔ کار سرویس Travis CI (id). اگر طول شناسه برابر یا بیشتر از ۳۲ نویسه باشد، به عنوان repo_token در نظر گرفته می‌شود.
--strip-path=path: اگر تنظیم نشود، طولانی‌ترین مسیر مشترک حذف خواهد شد.

گزینه‌های نامعمول (UNCOMMON OPTIONS)

--path-strip-level=N: تعداد سطوح مسیر جهت نمایش برای مسیرهای مشترک (پیش‌فرض: 2).
--skip-solibs: صرف‌نظر کردن از جمع‌آوری پوشش برای کتابخانه‌های اشتراکی (بهبود کارایی).
--verify: بررسی اینکه نقاط توقف (breakpoints) روی مرزهای دستورالعمل‌ها تنظیم شده باشند. این کار سرعت اجرا را بسیار کاهش می‌دهد، اما می‌تواند اشکالاتی را که کامپایلر داده‌های DWARF نامعتبر تولید کرده است شناسایی کند.
--exit-first-process: خروج هنگام اتمام اولین فرایند؛ یعنی رعایت رفتار دیمن‌ها (daemons). رفتار پیش‌فرض این است که پس از خروج آخرین فرایند به کنسول بازگردد.
--cobertura-only: تنها تولید خروجی cobertura به صورت cov.xml در دایرکتوری خروجی. کاربرد در نظر گرفته شده برای مثال برای vscode coverage gutters است، جایی که دایرکتوری خروجی می‌تواند به مکانی در دایرکتوری پروژه اشاره کند تا پوشش با کمترین فایل‌های زائد حاصل شود.
--python-parser=PARSER: تنظیم مفسر python برای استفاده در برنامه‌های Python (پیش‌فرض python است). می‌تواند برای اجرا با Python 3 در سیستم‌هایی که Python 2 پیش‌فرض است استفاده شود.
--bash-parser=PARSER: تنظیم مفسر bash برای اسکریپت‌های شل (پیش‌فرض /bin/bash است).
--bash-method=METHOD: استفاده از روش جمع‌آوری METHOD برای اسکریپت‌های bash. این روش می‌تواند PS4 (برای استفاده از متغیر محیطی PS4) یا DEBUG (برای استفاده از تلهٔ DEBUG) باشد.
--bash-handle-sh-invocation: مدیریت فراخوانی‌های اسکریپت‌های /bin/sh از طریق استفاده از یک کتابخانهٔ بارگذاری‌شده با LD_PRELOAD که جایگزین execve می‌شود (به این معنی که /bin/sh به صورت /bin/bash اجرا می‌شود). روی برخی سیستم‌ها به خوبی کار نمی‌کند، بنابراین پیش‌فرض بر عدم استفاده از آن است.
--bash-dont-parse-binary-dir: ابزار Kcov دایرکتوری فایل باینری را برای اسکریپت‌های دیگر بررسی کرده و آن‌ها را به گزارش اضافه می‌کند. اگر این رفتار را نمی‌خواهید، این گزینه آن را غیرفعال می‌کند.
--bash-parse-files-in-dir=P1[,P2...]: پیمایش دایرکتوری‌ها برای یافتن اسکریپت‌های bash.
--bash-tracefd-closeexec: اجبار به ردیابی نشدن فرزندان از طریق پیکربندی توصیف‌گر فایل ردیابی به صورت غیرقابل‌تکثیر با LD_PRELOAD. روی برخی سیستم‌ها دارای باگ است.
--replace-src-path=P1:P2: جایگزینی مسیر فایل منبع P1 با P2، در صورت پیدا شدن.
--system-record: انجام ابزاردقیق‌سازی سراسری سیستم روی یک sysroot، و ایجاد باینری‌های وصله‌شده‌ای که داده‌های پوشش را جمع‌آوری می‌کنند. برای اطلاعات بیشتر در مورد ابزاردقیق‌سازی سراسری سیستم به doc/full-system-instrumentation.md مراجعه کنید.
--system-report: تولید خروجی پوشش برای یک اجرای پوشش سراسری سیستم.
--debug=level: تنظیم سطح دیباگ، 0...31 (به عنوان ماسک). پیش‌فرض 0 برای عدم نمایش خروجی دیباگ است.
--output-interval=MS: تنظیم بازهٔ زمانی نوشتن خروجی بر حسب میلی‌ثانیه. مقدار پیش‌فرض 5000 است.
--configure=KEY=VAL: پیکربندی جفت‌های کلید/مقدار گزینه‌های داخلی. برای گزینه‌های پیکربندی ممکن، --help --uncommon-options را ببینید.
--patchelf=CMD: برای حالت سیستم، دستور patchelf را تعیین می‌کند (پیش‌فرض patchelf).

مثال‌ها (EXAMPLES)

بررسی پوشش کد برای ./frodo و تولید خروجی HTML در /tmp/kcov و خروجی cobertura در /tmp/kcov/frodo/cobertura.xml

kcov /tmp/kcov ./frodo

بررسی پوشش کد برای ./frodo اما تنها با گنجاندن فایل‌های منبعی که نام آن‌ها حاوی رشتهٔ src/frodo است

kcov --include-pattern=src/frodo /tmp/kcov ./frodo

مشابه بالا اما با تفکیک مراحل جمع‌آوری و گزارش‌گیری (شاید روی دو رایانهٔ مختلف)

kcov --collect-only /tmp/kcov ./frodo

kcov --report-only --include-pattern=src/frodo /tmp/kcov ./frodo

خروجی HTML (HTML OUTPUT)

خروجی HTML خطوط اجراشده و اجرا‌نشدهٔ کد منبع را نمایش می‌دهد. برخی خطوط می‌توانند به چندین نقطهٔ ابزاردقیق‌سازی متصل شوند، برای نمونه در توابع درون‌خطی (inlined) (جایی که هر درون‌خطی‌سازی آن‌ها یک نقطهٔ ابزاردقیق‌سازی مجزا ایجاد می‌کند). این مورد در ستون سمت چپ برای مثال به صورت 1/3 نشان داده می‌شود، به این معنی که یکی از سه نقطهٔ ابزاردقیق‌سازی اجرا شده است.

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

خروجی کوبرتورا (COBERTURA OUTPUT)

ابزار Kcov همچنین داده‌ها را در قالب Cobertura XML خروجی می‌دهد که امکان ادغام خروجی kcov در Jenkins را فراهم می‌آورد (نگاه کنید به https://cobertura.github.io/cobertura و https://www.jenkins.io).

خروجی Cobertura در فایلی به نام out-path/exec-filename/cobertura.xml قرار می‌گیرد.

خروجی JSON (JSON OUTPUT)

ابزار Kcov یک فایل json بسیار عمومی تولید می‌کند که شامل درصد کل پوشش‌یافته برای یک دستور منفرد و تعداد خطوط ابزاردقیق‌سازی‌شده و پوشش‌یافته است. همچنین خلاصه‌ای از هر فایل منبع به همراه درصد و تعداد خطوط در آن گنجانده شده است. این قابلیت امکان ادغام آسان با GitlabCI را فراهم می‌کند (نگاه کنید به https://docs.gitlab.com/ce/user/project/pipelines/settings.html).

خروجی JSON در فایلی به نام out-path/exec-filename/coverage.json قرار می‌گیرد.

نویسندگان (AUTHORS)

ابزار Kcov توسط Simon Kagstrom با گسترش bcov اثر Thomas Neumann نوشته شده است.

این صفحهٔ راهنما توسط Michael Tautschnig <mt@debian.org> برای پروژهٔ دبیان نوشته شده است (اما ممکن است توسط دیگران نیز به کار گرفته شود).