.\" Copyright (c) 2026 pkgconf authors (see AUTHORS).
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" This software is provided 'as is' and without any warranty, express or
.\" implied.  In no event shall the authors be liable for any damages arising
.\" from the use of this software.
.Dd June 28, 2026
.Dt PCCRITIC 1
.Os
.Sh "نام (NAME)"
.Nm pccritic
.Nd بررسی و ارزیابی فایل‌های pkg-config
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Op Ar options
.Ar module-or-file ...
.Sh "توضیحات (DESCRIPTION)"
.Nm
فایل‌های
.Xr pc 5
را بررسی می‌کند و یافته‌های کیفی را گزارش می‌دهد، و به هر فایل یک امتیاز از 0 تا 100 و یک رتبه حرفی از A تا F اختصاص می‌دهد.
این ابزار هم به عنوان یک راهنمای تعاملی برای توسعه‌دهندگان بسته‌ها و هم به عنوان آزمونی که می‌تواند در فرایند یکپارچه‌سازی مداوم (CI) اجرا شود، طراحی شده است.
.Pp
هر آرگومان خط فرمان به عنوان یک هدف در نظر گرفته می‌شود.
اگر آرگومانی شامل یک خط مورب (اسلش) باشد یا به
.Pa .pc
ختم شود، به عنوان مسیر یک فایل تفسیر می‌شود؛ در غیر این صورت، دقیقاً همانند روشی که
.Xr pkgconf 1
عمل می‌کند، به عنوان نام یک ماژول از مسیر جستجو تعیین موقعیت می‌شود.
فایلی که
.Xr pkgconf 1
به دلیل جا افتادن یک فیلد الزامی از بارگذاری آن خودداری می‌کند، باز هم مستقیماً اسکن می‌شود تا ناقص‌ترین و خراب‌ترین فایل‌ها نیز بتوانند امتیازدهی شوند.
.Pp
یافته‌ها بر اساس میزان اهمیت و شدت دسته‌بندی می‌شوند.
امتیاز از 100 آغاز می‌شود و هر یافته جریمه مشخصی را کسر می‌کند: 25 برای یک یافته
.Em critical
(بحرانی)، 10 برای یک یافته
.Em major
(عمده)، 4 برای یک یافته
.Em minor
(جزئی)، و 1 برای یک یافته
.Em info
(اطلاعاتی).
نتیجه نهایی در محدوده 0 تا 100 محدود می‌شود.
رتبه‌ها به صورت A برای 90 و بالاتر، B برای 80، C برای 70، D برای 60، و F برای کمتر از 60 اختصاص می‌یابند.
.Pp
این ارزیابی‌ها شامل متاداده‌های الزامی و توصیه‌شده، صحت نسخه، قابلیت جابه‌جایی متغیرهای
.Ic libdir
و
.Ic includedir
، سلامت فیلدهای
.Ic Cflags
و
.Ic Libs
، ارتباط میان
.Ic Requires
و
.Ic Requires.private
، و شیوه قالب‌بندی پایه فایل است.
.Sh "گزینه‌ها (OPTIONS)"
گزینه‌ها به شرح زیر هستند:
.Bl -tag -width indent
.It Fl -about
شماره نسخه، اعلان حق نشر (کپی‌رایت) و مجوز برنامه
.Nm
را در خروجی استاندارد چاپ کرده و خارج می‌شود.
.It Fl -version
شماره نسخه برنامه
.Nm
را در خروجی استاندارد چاپ کرده و خارج می‌شود.
.It Fl -help
یک خلاصه کوتاه از نحوه استفاده را در خروجی استاندارد چاپ کرده و خارج می‌شود.
.It Fl -quiet
به جای فهرست کامل یافته‌ها، تنها امتیاز و رتبه هر هدف را در یک سطر جداگانه چاپ می‌کند.
.It Fl -min-score Ar n
در صورتی که امتیاز هر هدفی کمتر از
.Ar n
باشد، با وضعیتی غیرصفر خارج می‌شود.
این گزینه برای ناموفق کردن یک فرایند یکپارچه‌سازی مداوم هنگام افت کیفیت فایل به زیر یک حد آستانه مفید است.
.It Fl -color Ns Op = Ns Ar when
خروجی رنگی را کنترل می‌کند.
.Ar when
می‌تواند
.Cm auto
(پیش‌فرض)،
.Cm always
یا
.Cm never
باشد.
در حالت
.Cm auto
، رنگ تنها زمانی فعال است که خروجی استاندارد یک ترمینال باشد و متغیر محیطی
.Ev NO_COLOR
تنظیم نشده باشد.
ارائه گزینه
.Fl -color
بدون مقدار، معادل
.Cm always
است.
.It Fl -define-variable Ns = Ns Ar varname Ns = Ns Ar value
متغیر
.Ar varname
را با مقدار
.Ar value
تعریف می‌کند.
این امر بر نحوه گسترش متغیرها در فایل مورد بررسی تأثیر می‌گذارد.
.El
.Sh "وضعیت خروج (EXIT STATUS)"
.Nm
در صورت موفقیت با وضعیت 0 خارج می‌شود.
اگر بارگذاری یک هدف امکان‌پذیر نباشد، خط فرمان نامعتبر باشد، یا گزینه
.Fl -min-score
مشخص شده و امتیاز یک هدف کمتر از حد آستانه باشد، با وضعیت غیرصفر خارج می‌شود.
.Sh "مثال‌ها (EXAMPLES)"
امتیازدهی به یک ماژول نصب‌شده بر اساس نام:
.Pp
.Dl $ pccritic zlib
.Pp
امتیازدهی به یک فایل پیش از نصب و خروج با خطا در صورت کسب رتبه پایین‌تر از C:
.Pp
.Dl $ pccritic --min-score 70 ./mylib.pc
.Pp
خلاصه‌سازی وضعیت تمامی فایل‌های موجود در یک دایرکتوری:
.Pp
.Dl $ pccritic --quiet /usr/lib/pkgconfig/*.pc
.Sh "همچنین ببینید (SEE ALSO)"
.Xr pkgconf 1 ,
.Xr pc 5
.Sh "نویسندگان (AUTHORS)"
.Nm pccritic
توسط نویسندگان pkgconf نوشته شده است.