ALPM-REPO-DESCV2(5) راهنمای قالب‌های فایل ALPM-REPO-DESCV2(5)

alpm-repo-descv2 - قالب فایل برای نمایش فراداده‌های بسته‌های مبتنی بر ALPM در مخازن بسته (نسخه ۲)

قالب alpm-repo-desc یک قالب متنی است که فراداده‌های یک بسته منفرد را در نسخه‌ای مشخص در یک مخزن نمایش می‌دهد. هر فایل ویژگی‌های گوناگون یک فایل alpm-package را توصیف می‌کند، از جمله نام، نسخه، وابستگی‌ها، اندازه، اطلاعات مجوز و موارد دیگر. برای فهرست کامل ویژگی‌ها به بخش‌ها مراجعه کنید.

مجموع تمامی فایل‌های alpm-repo-desc در یک alpm-repo-db وضعیت فعلی مخزن را توصیف می‌کنند (یعنی چه بسته‌هایی در چه نسخه‌ای در دسترس هستند).

یک سیستم‌عامل متکی بر Arch Linux Package Management یک یا چند فایل alpm-repo-db را نگهداری می‌کند که هر یک شامل یک فایل alpm-repo-desc به ازای هر بسته هستند؛ هر یک از این فایل‌ها desc نامیده شده و در پوشه‌ای منحصربه‌فرد برای هر بسته قرار دارند. به طور مشخص‌تر، نرم‌افزارهای مدیریت بسته مانند pacman و ابزارهای مرتبط از این قالب فایل برای نمونه جهت حل وابستگی‌ها و نمایش اطلاعات بسته‌های alpm-package در مخازن استفاده می‌کنند.

داده‌های موجود در یک فایل alpm-repo-desc از یک alpm-package مشتق شده‌اند. بخش عمده‌ای از فراداده‌های آن از داده‌های PKGINFO بسته سرچشمه می‌گیرد. یک فایل alpm-repo-desc معمولاً توسط نرم‌افزارهای مدیریت‌کننده یک alpm-repo، مانند repo-add ایجاد می‌شود.

قالب فایل توصیف‌شده در این سند نباید با قالب فایل alpm-db-desc اشتباه گرفته شود، که در چارچوب یک پایگاه‌داده libalpm استفاده می‌شود و مجموعه متفاوتی از فراداده‌ها را حمل می‌کند، اما معمولاً آن هم desc نامیده می‌شود.

قالب alpm-repo-desc در چندین نسخه وجود دارد. اطلاعات موجود در این سند مربوط به نسخه ۲ است، که نسخه فعلی بوده و با انتشار pacman 6.1.0 در تاریخ 2024-03-04 معرفی شده است.

یک فایل alpm-repo-desc فایلی با کدگذاری UTF-8 و جداشده با خط جدید است که از مجموعه‌ای از بخش‌ها تشکیل شده است.

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

خطوط خالی میان بخش‌ها نادیده گرفته می‌شوند.

بخش %MD5SUM% حذف شده است. بخش %PGPSIG% به صورت اختیاری درآمده است.

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

هر بخش پس از خط سربرگ بخش، تنها اجازه قرارگیری یک مقدار مختص بخش را می‌دهد. به عنوان استثنایی بر این قاعده، بخش‌های %LICENSE%، %GROUPS%، %CHECKDEPENDS%، %DEPENDS%، %OPTDEPENDS%، %REPLACES%، %CONFLICTS% و %PROVIDES% می‌توانند بیش از یک مقدار مختص بخش داشته باشند.

نام فایل alpm-package (مانند example-1.2.3-any.pkg.tar.zst).

یک alpm-package-name، که نشان‌دهنده نام یک بسته است (مانند example).

یک alpm-package-base که پایه بسته را که بسته از آن سرچشمه می‌گیرد نشان می‌دهد. اگر یک بسته alpm-split-package نباشد، مقدار آن همانند مقدار بخش %NAME% است. اگر یک بسته alpm-split-package باشد، مقدار آن ممکن است با مقدار بخش %NAME% متفاوت باشد.

یک alpm-package-version (full یا full with epoch) که نشان‌دهنده نسخه یک بسته است (مانند 1.0-1).

توضیحات بسته. مقدار یک رشته UTF-8 با طول صفر یا چند نویسه است (مانند A project used for something). اگر توضیحات خالی باشد، این بخش می‌تواند حذف شود.

یک alpm-package-group که نشان‌دهنده یک گروه سراسری در توزیع است که بسته در آن قرار دارد. ممکن است یک یا چند مقدار وجود داشته باشد. اگر بسته در هیچ گروهی نباشد، این بخش حذف می‌شود.

مقدار با یک رشته UTF-8 نمایش داده می‌شود. اگرچه امکان استفاده از یک رشته UTF-8 وجود دارد، اما اکیداً توصیه می‌شود که به جای آن از قالب alpm-package-name برای مقدار استفاده شود، زیرا مدیران بسته ممکن است از گروه بسته برای نصب کل گروه بسته‌ها استفاده کنند.

اندازه بسته فشرده‌شده alpm-package بر حسب بایت. مقدار یک عدد صحیح غیرمنفی است (مانند 1818463).

اندازه محتویات بسته (فشرده‌نشده و بازشده) بر حسب بایت. مقدار یک عدد صحیح غیرمنفی است که اندازه مطلق محتویات بسته را نشان می‌دهد؛ فایل‌های دارای چندین پیوند سخت (hardlink) تنها یک‌بار شمرده می‌شوند (مانند 181849963).

خلاصه درهم‌ساز SHA-256[2] از فایل alpm-package. این رشته شامل ۶۴ نویسه شانزده‌شانزدهی (هگزادسیمال) است (مانند b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c).

یک امضای OpenPGP[4] با کدگذاری اختیاری base64[3] برای فایل alpm-package (مانند iHUEABYKAB0WIQRizHP4hOUpV7L92IObeih9mi7GCAUCaBZuVAAKCRCbeih9mi7GCIlMAP9ws/jU4f580ZRQlTQKvUiLbAZOdcB7mQQj83hD1Nc/GwD/WIHhO1/OQkpMERejUrLo3AgVmY3b4/uGhx9XufWEbgE=). ابزار ایجادکننده فایل alpm-repo-desc ممکن است ترجیح دهد بازنمایی امضا را درج نکند، که در این صورت از این بخش صرف‌نظر می‌شود.

نشانی وب (URL) برای پروژه بسته. مقدار یک URL معتبر یا یک رشته خالی است (مانند https://example.org). اگر توضیحات خالی باشد، این بخش می‌تواند حذف شود.

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

هر مقدار نشان‌دهنده یک شناسه مجوز است، که رشته‌ای با طول غیرصفر است (مانند GPL). اگرچه به جز طول رشته هیچ محدودیت خاصی برای مقدار اعمال نمی‌شود، اما اکیداً توصیه می‌شود که از عبارات مجوز SPDX استفاده شود (مانند GPL-3.0-or-later یا Apache-2.0 OR MIT). برای اطلاعات بیشتر به فهرست مجوزهای SPDX[5] مراجعه کنید.

معماری بسته (برای اطلاعات بیشتر به alpm-architecture مراجعه کنید). مقدار باید از مجموعه نویسه‌های الفبایی-عددی و ‘_‘ تشکیل شده باشد (مانند x86_64 یا any).

تاریخی که ساخت بسته در آن آغاز شده است. مقدار باید عددی بوده و نشان‌دهنده ثانیه‌های سپری‌شده از مبدأ زمانی (Epoch)، معروف به ‘زمان یونیکس’ باشد (مانند 1729181726).

شناسه کاربری (User ID) موجودیتی که بسته را ساخته است. این مقدار برای جستجوی هویت در نظر گرفته شده و نمایانگر یک شناسه کاربری OpenPGP[6] است. به این ترتیب، مقدار یک رشته کدگذاری‌شده با UTF-8 است که بر اساس عرف از یک نام و یک نشانی ایمیل تشکیل شده و با ساختار توصیف‌شده در RFC 28227 مطابقت دارد.

یک مؤلفه مجازی یا بسته دیگر، که این بسته هنگام نصب جایگزین آن می‌شود. ممکن است یک یا چند مقدار وجود داشته باشد. اگر بسته جایگزین چیزی نشود، این بخش حذف می‌شود. مقدار یک alpm-package-relation از نوع replacement است (مانند example یا example=1.0.0).

یک مؤلفه مجازی یا بسته دیگر، که این بسته با آن تداخل دارد. ممکن است یک یا چند مقدار وجود داشته باشد. اگر بسته با چیزی تداخل نداشته باشد، این بخش حذف می‌شود. مقدار یک alpm-package-relation از نوع conflict است (مانند example یا example=1.0.0).

یک مؤلفه مجازی یا بسته دیگر، که این بسته آن را فراهم می‌کند. ممکن است یک یا چند مقدار وجود داشته باشد. اگر بسته چیزی فراهم نکند، این بخش حذف می‌شود. مقدار یک alpm-package-relation از نوع provision است (مانند example یا example=1.0.0).

یک وابستگی زمان اجرای بسته (مؤلفه مجازی یا بسته). ممکن است یک یا چند مقدار وجود داشته باشد. اگر بسته هیچ وابستگی زمان اجرایی نداشته باشد، این بخش حذف می‌شود. مقدار یک alpm-package-relation از نوع run-time dependency است (مانند example یا example=1.0.0).

یک وابستگی اختیاری بسته (virtual component یا package). ممکن است یک یا چند مقدار وجود داشته باشد. اگر بسته هیچ وابستگی اختیاری نداشته باشد، این بخش حذف می‌شود. مقدار یک alpm-package-relation از نوع optional dependency است (مانند example یا example: this is a description).

یک وابستگی برای ساخت نرم‌افزار بالادستی بسته. ممکن است یک یا چند مقدار وجود داشته باشد. اگر بسته هیچ وابستگی برای ساخت نداشته باشد، این بخش حذف می‌شود. مقدار یک alpm-package-relation از نوع build dependency است (مانند example یا example=1.0.0).

یک وابستگی برای اجرای آزمون‌های پروژه بالادستی بسته. ممکن است یک یا چند مقدار وجود داشته باشد. اگر بسته هیچ وابستگی برای آزمون نداشته باشد، این بخش حذف می‌شود. مقدار یک alpm-package-relation از نوع test dependency است (مانند example یا example=1.0.0).

یک مثال کامل از یک فایل alpm-repo-desc برای بسته‌ای به نام example در نسخه 1.0.0-1:

%FILENAME%
example-1.0.0-1-any.pkg.tar.zst
%NAME%
example
%BASE%
example
%VERSION%
1.0.0-1
%DESC%
An example package
%GROUPS%
example-group
other-group
%CSIZE%
1818463
%ISIZE%
18184634
%SHA256SUM%
b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
%PGPSIG%
iHUEABYKAB0WIQRizHP4hOUpV7L92IObeih9mi7GCAUCaBZuVAAKCRCbeih9mi7GCIlMAP9ws/jU4f580ZRQlTQKvUiLbAZOdcB7mQQj83hD1Nc/GwD/WIHhO1/OQkpMERejUrLo3AgVmY3b4/uGhx9XufWEbgE=
%URL%
https://example.org
%LICENSE%
MIT
Apache-2.0
%ARCH%
x86_64
%BUILDDATE%
1729181726
%PACKAGER%
Foobar McFooface <foobar@mcfooface.org>
%REPLACES%
other-pkg-replaced
%CONFLICTS%
other-pkg-conflicts
%PROVIDES%
example-component
%DEPENDS%
glibc
gcc-libs
%OPTDEPENDS%
bash: for a script
%MAKEDEPENDS%
cmake
%CHECKDEPENDS%
bats

یک مثال حداقلی از یک فایل alpm-repo-desc برای یک alpm-meta-package به نام example-meta در نسخه 1.0.0-1:

%FILENAME%
example-meta-1.0.0-1-any.pkg.tar.zst
%NAME%
example-meta
%BASE%
example-meta
%VERSION%
1.0.0-1
%DESC%
An example meta package
%CSIZE%
4634
%ISIZE%
0
%SHA256SUM%
b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c
%URL%
https://example.org
%LICENSE%
GPL-3.0-or-later
%ARCH%
any
%BUILDDATE%
1729181726
%PACKAGER%
Foobar McFooface <foobar@mcfooface.org>

libalpm(3), BUILDINFO(5), PKGBUILD(5), PKGINFO(5), alpm-db-desc(5), alpm-architecture(7), alpm-meta-package(7), alpm-package(7), alpm-package-name(7), alpm-package-relation(7), alpm-package-version(7), alpm-repo-db(7), alpm-split-package(7), pacman(8), repo-add(8)

1.
نویسه‌های اسکی قابل چاپ (printable ASCII characters)
https://en.wikipedia.org/wiki/ASCII#Printable_characters
2.
SHA-256
https://en.wikipedia.org/wiki/SHA-2
3.
Base64
https://en.wikipedia.org/wiki/Base64
4.
امضای OpenPGP (OpenPGP signature)
https://openpgp.dev/book/signing_data.html#detached-signatures
5.
فهرست مجوزهای SPDX (SPDX License List)
https://spdx.org/licenses
6.
شناسه کاربری OpenPGP (OpenPGP User ID)
https://openpgp.dev/book/certificates.html#user-ids
7.
RFC 2822
https://www.rfc-editor.org/rfc/rfc2822
2024-03-04 ALPM