portals.conf(5) File Formats Manual portals.conf(5)

portals.conf - پیکربندی پورتال میزکار XDG

$XDG_CONFIG_HOME/xdg-desktop-portal/{*-}portals.conf

$XDG_CONFIG_DIRS/xdg-desktop-portal/{*-}portals.conf

/etc/xdg-desktop-portal/{*-}portals.conf

$XDG_DATA_HOME/xdg-desktop-portal/{*-}portals.conf

$XDG_DATA_DIRS/xdg-desktop-portal/{*-}portals.conf

/usr/share/xdg-desktop-portal/{*-}portals.conf

برنامهٔ xdg-desktop-portal از یک فایل پیکربندی برای تعیین این‌که کدام بک‌اند پورتال باید برای ارائهٔ پیاده‌سازی رابط درخواستی استفاده شود، بهره می‌برد. این سازوکار بسیار شبیه به مشخصات freedesktop.org برای "ارتباط میان انواع MIME و برنامه‌ها" (mime-apps) است.

محیط‌های میزکار و توزیع‌کنندگان سیستم‌عامل باید پیکربندی پیش‌فرضی را برای بک‌اندهای پورتال انتخابی خود در /usr/share/xdg-desktop-portal/DESKTOP-portals.conf ارائه دهند، که در آن DESKTOP نام محیط میزکار همان‌گونه است که در متغیر محیطی XDG_CURRENT_DESKTOP پس از تبدیل حروف بزرگ ASCII به حروف کوچک ظاهر می‌شود. برای نمونه، KDE باید فایل /usr/share/xdg-desktop-portal/kde-portals.conf را ارائه دهد.

کاربران می‌توانند با نوشتن یک فایل ~/.config/xdg-desktop-portal/portals.conf این پیش‌فرض‌ها را بازنویسی (override) کنند، یا برای یک محیط میزکار که در حالت عادی پشتیبانی نمی‌شود، پیکربندی فراهم نمایند. کاربران بیش از یک محیط میزکار می‌توانند از نام‌های فایل مختص به میزکار مانند kde-portals.conf استفاده کنند که تنها در محیط میزکار مربوطه استفاده خواهد شد.

به همین ترتیب، مدیران سیستم می‌توانند یک پیکربندی پیش‌فرض برای تمام کاربران در /etc/xdg-desktop-portal/DESKTOP-portals.conf یا /etc/xdg-desktop-portal/portals.conf فراهم کنند.

مکان‌های زیر برای یافتن پیکربندی جستجو می‌شوند (بیشترین اولویت در ابتدا):

  • $XDG_CONFIG_HOME، با پیش‌فرض ~/.config
  • هر شاخه در $XDG_CONFIG_DIRS، با پیش‌فرض /etc/xdg
  • مسیر sysconfdir در زمان ساخت برای xdg-desktop-portal، معمولاً /etc
  • $XDG_DATA_HOME، با پیش‌فرض ~/.local/share (تنها جهت سازگاری با سایر مشخصات جستجو می‌شود؛ نوشتن پیکربندی در اینجا توصیه نمی‌شود)
  • هر شاخه در $XDG_DATA_DIRS، با پیش‌فرض /usr/local/share:/usr/share
  • مسیر datadir در زمان ساخت برای xdg-desktop-portal، معمولاً /usr/share

در هر یک از این مکان‌ها، برای هر نام محیط میزکار فهرست‌شده در متغیر محیطی XDG_CURRENT_DESKTOP، برنامهٔ xdg-desktop-portal وجود فایل xdg-desktop-portal/DESKTOP-portals.conf را بررسی می‌کند که در آن DESKTOP نام محیط میزکار با حروف کوچک است. اگر فایل پیکربندی مختص به محیط میزکار یافت نشود، فایل غیرمختص به میزکار xdg-desktop-portal/portals.conf خوانده خواهد شد. برای نمونه، اگر XDG_CURRENT_DESKTOP روی Budgie:GNOME تنظیم شده باشد، برنامهٔ xdg-desktop-portal به دنبال xdg-desktop-portal/budgie-portals.conf، xdg-desktop-portal/gnome-portals.conf و xdg-desktop-portal/portals.conf به همان ترتیب خواهد گشت.

قالب فایل پیکربندی پورتال‌ها همان قالب .ini است که توسط فایل‌های واحد systemd یا فایل‌های desktop برنامه‌ها استفاده می‌شود.

[preferred]

گروه اصلی پیکربندی برای پورتال‌های ترجیحی.

کلیدهای زیر می‌توانند در گروه preferred وجود داشته باشند:

default (رشته)

بک‌اند پورتال پیش‌فرض برای استفاده در تمامی رابط‌ها، مگر اینکه رابط به صراحت ذکر شده باشد.

org.freedesktop.impl.portal.* (رشته)

یکی از پیاده‌سازی‌های معتبر واسط پورتال ارائه‌شده توسط xdg-desktop-portal.

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

none

هیچ پیاده‌سازی پورتالی برای این واسط ارائه نشود.

*

از اولین پیاده‌سازی پورتال یافت‌شده به ترتیب الفبایی (lexicographical) استفاده شود.

[preferred]
# Use xdg-desktop-portal-gtk for every portal interface...
default=gtk
# ... except for the ScreenCast interface
org.freedesktop.impl.portal.ScreenCast=gnome

XDG_CURRENT_DESKTOP

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

XDG_CONFIG_HOME

فایل portals.conf مربوط به هر کاربر در این شاخه قرار دارد. مقدار پیش‌فرض $HOME/.config است.

XDG_CONFIG_DIRS

فهرستی جداشده با دونقطه از شاخه‌های پیکربندی سیستمی و شاخه‌های پیکربندی ثانویهٔ کاربری. مقدار پیش‌فرض /etc/xdg است.

XDG_DATA_HOME

شاخهٔ داده‌های کاربری که جهت سازگاری با سایر مشخصات جستجو می‌شود. مقدار پیش‌فرض $HOME/.local/share است.

XDG_DATA_DIRS

فهرستی جداشده با دونقطه از شاخه‌های دادهٔ سیستمی و شاخه‌های دادهٔ ثانویهٔ کاربری. مقدار پیش‌فرض /usr/local/share:/usr/share است.