.\" Copyright (c) 2025 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 24, 2026
.Dt BOMTOOL 1
.Os
.Sh "نام (NAME)"
.Nm bomtool
.Nd ابزار بررسی صورت‌مواد نرم‌افزاری (Software Bill of Materials)
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Op Ar options
.Ar module ...
.Sh "توضیحات (DESCRIPTION)"
.Nm
برنامه‌ای است که یک صورت‌مواد نرم‌افزاری
(SBOM)
متنی مبتنی بر SPDX 2.0 را برای مجموعه‌ای مشخص از ماژول‌های pkg-config تولید می‌کند.
خروجی این ابزار در صورت نیاز می‌تواند به سایر قالب‌های SBOM تبدیل شود.
.Sh "گزینه‌ها (OPTIONS)"
گزینه‌ها به شرح زیر هستند:
.Bl -tag -width indent
.It Fl -about
شماره نسخه، اعلان حق نشر (کپی‌رایت) و مجوز برنامهٔ
.Nm
را در خروجی استاندارد چاپ کرده و خارج می‌شود.
بیشتر گزینه‌های دیگر و تمام آرگومان‌های خط فرمان نادیده گرفته می‌شوند.
.It Fl -version
شماره نسخهٔ برنامهٔ
.Nm
را در خروجی استاندارد چاپ کرده و خارج می‌شود.
بیشتر گزینه‌های دیگر و تمام آرگومان‌های خط فرمان نادیده گرفته می‌شوند.
.It Fl -define-variable Ns = Ns Ar varname Ns = Ns Ar value
متغیر
.Ar varname
را با مقدار
.Ar value
تعریف می‌کند.
متغیرها در خروجی پرس‌وجو استفاده می‌شوند، و ممکن است نتایج برخی ماژول‌ها بر اساس وجود تعریف متغیر تغییر کند.
.It Fl -creation-time Ar time
به‌جای زمان کنونی، از
.Ar time
به‌عنوان مقدار فیلد
.Ic Created
در SBOM تولیدشده استفاده می‌کند.
استاندارد SPDX استفاده از زمان با قالب ISO 8601 را توصیه می‌کند، یعنی: YYYY-MM-DDThh:mm:ssZ.
این گزینه نسبت به متغیر محیطی
.Ev SOURCE_DATE_EPOCH
اولویت دارد.
.It Fl -output Ar file
صورت‌مواد نرم‌افزاری (SBOM) تولیدشده را به‌جای خروجی استاندارد، در
.Ar file
می‌نویسد.
.El
.Sh "محیط (ENVIRONMENT)"
.Bl -tag -width indent
.It Ev PKG_CONFIG_DEBUG_SPEW
در صورت تنظیم شدن، پیام‌های اشکال‌زدایی (دیباگ) را در خطای استاندارد (stderr) چاپ می‌کند.
.It Ev PKG_CONFIG_IGNORE_CONFLICTS
در صورت تنظیم شدن، قوانین
.Ic Conflicts
(تداخل‌ها) در ماژول‌ها نادیده گرفته می‌شوند.
این متغیر اثری مشابه با گزینهٔ
.Fl -ignore-conflicts
در
.Xr pkgconf 1
دارد.
.It Ev PKG_CONFIG_LIBDIR
فهرستی جداشده با دو نقطه (:) از دایرکتوری‌های با اولویت پایین که فایل‌های
.Xr pc 5
در آن‌ها جستجو می‌شوند.
مسیر جستجوی ماژول با افزودن این فهرست به انتهای
.Ev PKG_CONFIG_PATH
(که اولویت بالاتری دارد) ساخته می‌شود.
اگر
.Ev PKG_CONFIG_LIBDIR
تعریف نشده باشد، فهرست پیش‌فرض کامپایل‌شده در برنامهٔ
.Nm
از ماکروی پیش‌پردازندهٔ
.Dv PKG_DEFAULT_PATH
به‌جای آن اضافه می‌شود.
اگر
.Ev PKG_CONFIG_LIBDIR
تعریف شده ولی خالی باشد، چیزی اضافه نخواهد شد.
.It Ev PKG_CONFIG_MAXIMUM_TRAVERSE_DEPTH
محدودیتی برای عمق مجاز پیمایش در گراف وابستگی اعمال می‌کند.
.It Ev PKG_CONFIG_PATH
فهرستی جداشده با دو نقطه (:) از دایرکتوری‌های با اولویت بالا که فایل‌های
.Xr pc 5
در آن‌ها جستجو می‌شوند.
.It Ev PKG_CONFIG_PRELOADED_FILES
فهرستی جداشده با دو نقطه (:) از فایل‌های
.Xr pc 5
که پیش از هر فایل pkg-config دیگری بارگذاری می‌شوند.
به این بسته‌ها بالاترین اولویت نسبت به هر فایل
.Xr pc 5
دیگری داده می‌شود که در غیر این صورت بستهٔ مشخص‌شده را ارائه می‌کردند.
.It Ev SOURCE_DATE_EPOCH
اگر تنظیم شده باشد و گزینهٔ
.Fl -creation-time
داده نشده باشد، فیلد
.Ic Created
در SBOM تولیدشده به‌جای زمان کنونی از این برچسب زمانی یونیکس (UNIX timestamp) گرفته می‌شود که امکان تولید بازتولیدپذیر (reproducible) صورت‌مواد نرم‌افزاری را فراهم می‌آورد.
.El
.Sh "کدهای خروج (EXIT STATUS)"
.Ex -std
.Sh "مثال‌ها (EXAMPLES)"
تولید یک SBOM برای بسته‌ای به نام foo:
.Dl $ bomtool foo
.Dl SPDXVersion: SPDX-2.2
.Dl DataLicense: CC0-1.0
.Dl SPDXID: SPDXRef-DOCUMENT
.Dl DocumentName: SBOM-SPDX-fooC641.2.3
.Dl DocumentNamespace: https://spdx.org/spdxdocs/bomtool
.Dl Creator: Tool: bomtool
.Dl [...]
.Sh "همچنین ببینید (SEE ALSO)"
.Xr pc 5 ,
.Xr pkgconf 1
.Sh "نویسندگان (AUTHORS)"
برنامهٔ
.Nm
و این صفحهٔ راهنما توسط نویسندگان
.Nm pkgconf
(پروندهٔ AUTHORS را ببینید) نوشته شده است.