NAME

file.pc — قالب پروندههای pkg-config برای مدیریت پرچمهای کامپایلر و کتابخانهها

DESCRIPTION

پرونده‌های pkg-config سازوکاری سودمند را برای ذخیره‌سازی اطلاعات گوناگون درباره کتابخانه‌ها و بسته‌ها در یک سیستم مشخص فراهم می‌کنند. اطلاعات ذخیره‌شده توسط پرونده‌های .pc شامل پرچم‌های کامپایلر و پیونددهنده (linker) لازم برای استفاده از یک کتابخانه معین، و همچنین سایر فراداده‌های مرتبط است.

این پرونده‌های .pc توسط ابزاری به نام pkg-config پردازش می‌شوند که pkgconf یک پیاده‌سازی از آن است.

FILE SYNTAX

پرونده .pc از قالبی الهام‌گرفته از RFC822 پیروی می‌کند. توضیحات با یک علامت پوند، هش یا مربع (#) آغاز می‌شوند و انتساب متغیرها مشابه پوسته استاندارد POSIX است. ویژگی‌ها با استفاده از بندهایی (stanzas) به سبک RFC822 تعریف می‌شوند.

VARIABLES

تعریف متغیرها با یک رشته الفبایی-عددی آغاز می‌شود، به دنبال آن علامت مساوی (=) می‌آید و سپس مقداری که متغیر باید در بر داشته باشد.

ارجاع به متغیرها همیشه به صورت "${variable}" نوشته می‌شود. اسکیپ کردن رشته لغوی "${" به صورت "$${" امکان‌پذیر است.

PROPERTIES

ویژگی‌ها با استفاده از بندهایی به سبک RFC822 تنظیم می‌شوند که شامل یک کلیدواژه، به دنبال آن علامت دونقطه (:) و سپس مقداری است که ویژگی باید بر روی آن تنظیم گردد. جایگزینی متغیرها بدون توجه به نوع ویژگی همیشه انجام می‌شود.

سه نوع ویژگی وجود دارد:

Literal

ویژگی بر روی متن صریح مقدار تنظیم خواهد شد.

Dependency List

ویژگی بر روی فهرستی از وابستگی‌های تجزیه‌شده از متن تنظیم خواهد شد. فهرست‌های وابستگی توسط این نحو ABNF تعریف می‌شوند:

package-list = *WSP *( package-spec *( package-sep ) )
package-sep  = WSP / ","
package-spec = package-key [ ver-op package-version ]
ver-op       = "<" / "<=" / "=" / "!=" / ">=" / ">"

Fragment List

ویژگی بر روی فهرستی از قطعات (fragments) تجزیه‌شده از متن تنظیم خواهد شد. متن ورودی باید در قالبی باشد که برای ارسال به یک پوسته POSIX بدون هیچ‌گونه بسط پوسته پس از انجام جایگزینی متغیرها مناسب باشد.

متن با استفاده از قوانین جداسازی کلمات پوسته POSIX نشانه‌گذاری (tokenise) می‌شود: فاصله‌های خالی نقل‌قول‌نشده قطعات را جدا می‌کنند، نقل‌قول‌های تکی و جفتی متن را گروه‌بندی می‌نمایند، و یک بک‌اسلش نویسه پس از خود را اسکیپ می‌کند. یک نقل‌قول که خود اسکیپ نشده باشد به عنوان جداکننده نقل‌قول مصرف می‌شود و در قطعه حاصل ظاهر نمی‌شود. برای گنجاندن لغوی یک ابرنویسه (metacharacter) پوسته — مانند نقل‌قول، فاصله خالی، براکت، آکولاد یا نویسه تطبیق سراسری (glob) — در یک قطعه، آن را با بک‌اسلش اسکیپ کنید تا در فرآیند نشانه‌گذاری دست‌نخورده باقی بماند.

برای نمونه، جهت ارسال آرگومان زیر به زنجیره ابزار (toolchain):

-sFUNCS=["fnA","fnB"]

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

Libs: -sFUNCS=[\"fnA\",\"fnB\"]

در خروجی، این ابرنویسه‌ها مجدداً اسکیپ می‌شوند تا هنگام نشانه‌گذاری خروجی توسط مصرف‌کننده با همان قوانین جداسازی کلمات پوسته، قطعه اصلی بازیابی شود؛ یادداشت مربوط به اسکیپ کردن خروجی را در pkgconf(1) ببینید.

KEYWORDS

Name: نام نمایشی بسته. (اجباری؛ متن صریح)
Version: نسخه بسته. (اجباری؛ متن صریح)
Description: توضیحی درباره بسته. (اجباری؛ متن صریح)
URL: یک نشانی وب به صفحه اینترنتی بسته. این مورد برای پیشنهاد مکانی که می‌توان نسخه‌های جدیدتر بسته را از آنجا دریافت کرد به کار می‌رود. (اجباری؛ متن صریح)
Cflags: پرچم‌های کامپایلر لازم. این پرچم‌ها بدون توجه به اینکه آیا کامپایل ایستا (static) درخواست شده است یا خیر، همیشه به کار می‌روند. (اختیاری؛ فهرست قطعات)
Cflags.private: پرچم‌های کامپایلر لازم فقط برای کامپایل ایستا. (اختیاری؛ فهرست قطعات؛ افزونه pkgconf؛ معرفی‌شده در pkgconf 0.9.3)
Cflags.shared: پرچم‌های کامپایلر لازم فقط برای کامپایل اشتراکی (shared). (اختیاری؛ فهرست قطعات؛ افزونه pkgconf؛ معرفی‌شده در pkgconf 3.0.0)
Copyright: بیانیه تایید حق نشر (کپی‌رایت). (اختیاری؛ متن صریح؛ افزونه pkgconf؛ معرفی‌شده در pkgconf 1.9.3)
Libs: پرچم‌های پیونددهنده (linking) لازم برای این بسته. کتابخانه‌هایی که این بسته برای پیوند دادن به آن‌ها وابسته است و به عنوان وابستگی توصیف نشده‌اند، باید در اینجا مشخص شوند. (اختیاری؛ فهرست قطعات)
Libs.private: پرچم‌های پیونددهنده لازم برای این بسته که فقط هنگام پیوند دادن ایستا (statically) مورد نیاز هستند. کتابخانه‌هایی که این بسته برای پیوند دادن ایستا به آن‌ها وابسته است و به عنوان وابستگی توصیف نشده‌اند، باید در اینجا مشخص شوند. (اختیاری؛ فهرست قطعات)
Libs.shared: پرچم‌های پیونددهنده لازم برای این بسته که فقط هنگام پیوند دادن پویا (dynamically) مورد نیاز هستند. کتابخانه‌هایی که این بسته برای پیوند دادن پویا به آن‌ها وابسته است و به عنوان وابستگی توصیف نشده‌اند، باید در اینجا مشخص شوند. (اختیاری؛ فهرست قطعات؛ افزونه pkgconf؛ معرفی‌شده در pkgconf 3.0.0)
Link.ABI: فهرستی جداشده با کاما از برچسب‌هایی که رابط‌های باینری برنامه (ABI) را توصیف می‌کنند که مصرف‌کننده باید این بسته را در برابر آن‌ها پیوند دهد، مانند c++ یا fortran. برچسب‌ها به بزرگی و کوچکی حروف حساس نیستند و به حروف کوچک تبدیل (نرمال‌سازی) می‌شوند. این ویژگی به سیستم ساخت اجازه می‌دهد هنگامی که یک بسته، یا یکی از وابستگی‌های آن، در زبانی پیاده‌سازی شده باشد که ABI آن با C تفاوت دارد، گرداننده پیونددهنده و زمان اجرای مناسب را انتخاب کند. مجموعه برچسب‌ها در سراسر بستار وابستگی‌ها به همان شیوه Libs اجتماع می‌شوند: برچسب‌های خود بسته و برچسب‌های ویژگی عمومی Requires آن همیشه اعمال می‌شوند، در حالی که برچسب‌های Requires.private تنها زمانی اعمال می‌گردند که وابستگی‌های خصوصی پیوند داده شوند. برخلاف بارگذاری کتابخانه در زمان اجرا، سازگاری ABI رابط ارائه‌شده به طور یکسان برای پیوند اشتراکی و ایستا اعمال می‌شود. بسته‌ای که فاقد ویژگی Link.ABI باشد، به عنوان c در نظر گرفته می‌شود. (اختیاری؛ افزونه pkgconf؛ معرفی‌شده در pkgconf 3.0.0)
License: برچسب مجوز اظهارشده SPDX که باید بر روی بسته داده‌شده اعمال شود. باید تلاش شود تا برچسب مجوز صحیح SPDX برای بسته از فهرست مجوزهای SPDX تعیین شود. اگر نام استاندارد مجوز در دسترس نیست، از برچسب LicenseRef استفاده کنید. برای جزئیات پیچیده مجوزدهی، از نمادگذاری عبارات SPDX بهره ببرید. امکان تخصیص چندین برچسب مجوز در پرونده pc وجود دارد، که در هنگام رندر کردن خروجی با یک 'AND' با یکدیگر ادغام می‌شوند. (اختیاری؛ متن صریح؛ افزونه pkgconf؛ معرفی‌شده در pkgconf 1.9.0)
License.file: یک مسیر مطلق در سیستم‌فایل به پرونده نصب‌شده حاوی متن کامل مجوز برای این بسته. مسیر باید به پرونده مجوزی که روی سیستم نصب شده اشاره کند، به گونه‌ای که دقیقاً با نسخه و پیکربندی شرح‌داده‌شده توسط این پرونده .pc مطابقت داشته باشد؛ ارجاعات متغیرهای pkgconf مانند ${prefix} یا ${datadir} که به مسیرهای مطلق بسط می‌یابند، می‌توانند مورد استفاده قرار گیرند. مسیرهای نسبی پشتیبانی نمی‌شوند. این مقدار نباید یک نشانی وب (URL) باشد: از Source برای ارجاع به یک مکان بالادستی استفاده کنید. (اختیاری؛ متن صریح؛ افزونه pkgconf؛ معرفی‌شده در pkgconf 3.0.0)
Maintainer: اطلاعات تماس ترجیحی برای نگه‌دارنده بسته. این مقدار باید در قالب یک نام به همراه یک نشانی رایانامه یا وبگاه باشد. (اختیاری؛ متن صریح؛ افزونه pkgconf؛ معرفی‌شده در pkgconf 1.9.3)
Source: برچسب اظهارشده downloadLocation در SPDX که باید بر روی بسته داده‌شده اعمال شود. منبع (Source) باید یک شناسه منبع (URI) حاوی tarball با نسخه دقیق، یا مخزنی حاوی برچسب نسخه‌ای یکسان با نسخه ذکرشده در برچسب version باشد. همچنین می‌تواند یک URI همراه با هش باشد که نقطه دقیق انتشار کد منبع است. (اختیاری؛ متن صریح؛ افزونه pkgconf؛ معرفی‌شده در pkgconf 3.0.0)
Requires: وابستگی‌های لازمی که باید برای قابل استفاده بودن بسته برآورده شوند. تمامی وابستگی‌ها باید برآورده شوند، در غیر این صورت پیاده‌سازی pkg-config نباید از بسته استفاده کند. (اختیاری؛ فهرست وابستگی‌ها)
Requires.internal: وابستگی‌های لازمی که باید برای قابل استفاده بودن بسته جهت پیوند ایستا برآورده شوند. تفاوت‌های اصلی در مقایسه با Requires.private این است که CFLAGS شامل نخواهد شد و حل‌کننده (solver) هنگام حل کردن وابستگی‌ها صرفاً برای CFLAGS، این وابستگی را در نظر نخواهد گرفت. (اختیاری؛ فهرست وابستگی‌ها؛ افزونه pkgconf؛ معرفی‌شده در pkgconf 1.5.0)
Requires.private: وابستگی‌های لازمی که باید برای قابل استفاده بودن بسته جهت گنجاندن هدرها و پیوند ایستا برآورده شوند. تمامی وابستگی‌ها باید برآورده شوند، در غیر این صورت پیاده‌سازی pkg-config نباید از بسته برای گنجاندن هدرها و پیوند ایستا استفاده کند. (اختیاری؛ فهرست وابستگی‌ها)
Requires.shared: وابستگی‌های لازمی که تنها در شرایط غیرایستا پیمایش می‌شوند. این ویژگی به بسته امکان می‌دهد وابستگی‌هایی را بیان کند که تنها زمانی مرتبط هستند که به عنوان یک کتابخانه اشتراکی به کار می‌رود. (اختیاری؛ فهرست وابستگی‌ها؛ افزونه pkgconf؛ معرفی‌شده در pkgconf 3.0.0)
Conflicts: وابستگی‌هایی که نباید برقرار باشند تا بسته قابل استفاده باشد. اگر هر بسته‌ای در راه‌حل وابستگی پیشنهادی با هر یک از وابستگی‌های موجود در فهرست Conflicts مطابقت داشته باشد، بسته مورد نظر قابل استفاده نخواهد بود. (اختیاری؛ فهرست وابستگی‌ها)
Provides: وابستگی‌هایی که ممکن است توسط یک بسته جایگزین ارائه شوند. اگر بسته‌ای پیدا نشود، تمام مجموعه بسته‌ها برای یافتن ارائه‌دهندگانی که بتوانند با وابستگی درخواست‌شده مطابقت داشته باشند، پویش می‌شود. (اختیاری؛ فهرست وابستگی‌ها؛ افزونه pkgconf؛ معرفی‌شده در pkgconf 1.1.0)

EXTENSIONS

قابلیت‌هایی که به عنوان افزونه pkgconf علامت‌گذاری شده‌اند تنها تضمین می‌شود که با پیاده‌سازی pkgconf از pkg-config کار کنند. سایر پیاده‌سازی‌ها ممکن است از این افزونه‌ها پشتیبانی کنند یا نکنند.

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

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

به عنوان نمونه:

Requires: pkgconf >= 3.0.0
Libs.shared: ...

EXAMPLES

نمونه‌ای از یک پرونده .pc:

# این یک توضیح است
prefix=/home/kaniini/pkg   # تعریف یک متغیر
exec_prefix=${prefix}      # تعریف متغیری دیگر با جایگزینی
libdir=${exec_prefix}/lib
includedir=${prefix}/include

Name: libfoo                                  # نام خوانا برای انسان
Description: an example library called libfoo # توضیحات خوانا برای انسان
Copyright: Copyright (c) 2022 pkgconf project authors
License: Apache-2.0
Maintainer: the pkgconf project <http://www.pkgconf.org>
Version: 1.0
URL: http://www.pkgconf.org
Requires: libbar > 2.0.0
Conflicts: libbaz <= 3.0.0
Libs: -L${libdir} -lfoo
Libs.private: -lm
Cflags: -I${includedir}/libfoo