Различные спецификации определяют файлы и форматы файлов. Эта спецификация определяет каталоги, в которых должны находиться эти файлы, устанавливая один или более базовых каталогов относительно которых должны располагаться файлы.
Основы
Спецификация XDG Base Directory основывается на следующих концепциях:
Существует единственный базовый каталог, относительно которого должны располагаться файлы с данными пользователя. Этот каталог определён в переменной окружения $XDG_DATA_HOME.
Существует единственный базовый каталог, относительно которого должны располагаться конфигурационные файлы пользователя. Этот каталог определен в переменной окружения $XDG_CONFIG_HOME.
Существуют установленные предпочтения, задающие порядок базовых каталогов, в которых должен производиться поиск файлов с данными. Этот установленный набор каталогов определен в переменной окружения $XDG_DATA_DIRS.
Существуют установленные предпочтения, задающие порядок базовых каталогов, в которых должен производиться поиск конфигурационных файлов. Этот установленный набор каталогов определен в переменной окружения $XDG_CONFIG_DIRS.
Существует единственный базовый каталог, относительно которого должны располагаться несущественные (кэшированные) данные. Этот каталог определен в переменной окружения $XDG_CACHE_HOME.
Переменные окружения
$XDG_DATA_HOME определяет базовый каталог, в котором должны храниться файлы данных пользователя. Если $XDG_DATA_HOME не определена или содержит пустое значение, то по умолчанию должно использоваться значение равное $HOME/.local/share.
$XDG_CONFIG_HOME определяет базовый каталог, в котором должны храниться конфигурационные файлы пользователя. Если $XDG_CONFIG_HOME не определена или содержит пустое значение, то по умолчанию должно использоваться значение равное $HOME/.config.
$XDG_DATA_DIRS определяет порядок предпочтений для базовых каталогов, в которых будет произведен поиск файлов с данными, в дополнение к $XDG_DATA_HOME. Каталоги в переменной $XDG_DATA_DIRS должны быть разделены двоеточием.
Если $XDG_DATA_DIRS не определена или содержит пустое значение, то по умолчанию должно использоваться значение равное /usr/local/share/:/usr/share/.
$XDG_CONFIG_DIRS определяет порядок предпочтений для базовых каталогов, в которых будет произведен поиск конфигурационных файлов, в дополнение к $XDG_CONFIG_HOME. Каталоги в переменной $XDG_CONFIG_DIRS должны быть разделены двоеточием.
Если $XDG_CONFIG_DIRS не определена или содержит пустое значение, то по умолчанию должно использоваться значение равное /etc/xdg.
Порядок базовых каталогов обозначает их важность; первый каталог в списке является наиболее важным. Когда одна и та же информация определена в нескольких местах, то преобладает информация, определенная относительно более важного базового каталога. Базовый каталог, определенный в $XDG_DATA_HOME, считается более важным, чем любой из каталогов, определенных в $XDG_DATA_DIRS. Базовый каталог, определенный в $XDG_CONFIG_HOME, считается более важным, чем любой из каталогов, определенных в $XDG_CONFIG_DIRS.
$XDG_CACHE_HOME определяет базовый каталог, в котором должны храниться несущественные (кэшированные) данные пользователя. Если $XDG_CACHE_HOME не определена или содержит пустое значение, то по умолчанию должно использоваться значение равное $HOME/.cache.
Ссылки на эту спецификацию
Другие спецификации могут ссылаться на данный документ, определяя расположение для файла с данными, как $XDG_DATA_DIRS/subdir/filename. Это подразумевает следующее:
Такой файл должен быть установлен в $datadir/subdir/filename, где $datadir по умолчанию /usr/share.
Специфичная для пользователя версия файла с данными может быть создана в $XDG_DATA_HOME/subdir/filename, принимая во внимание значение по умолчанию для $XDG_DATA_HOME, если $XDG_DATA_HOME не определена.
Поиск файла с данными должен начинаться с ./subdir/filename относительно всех базовых каталогов, определенных в $XDG_DATA_HOME и $XDG_DATA_DIRS. Если переменная окружения не установлена или содержит пустое значение, то вместо нее должно использоваться значение по умолчанию для этой переменной.
Спецификации могут ссылаться на данный документ, определяя расположение конфигурационного файла, как $XDG_CONFIG_DIRS/subdir/filename. Это подразумевает следующее:
По умолчанию конфигурационные файлы должны быть установлены в $sysconfdir/xdg/subdir/filename, где $sysconfdir по умолчанию /etc.
Специфичная для пользователя версия конфигурационного файла может быть создана в $XDG_CONFIG_HOME/subdir/filename, принимая во внимание значение по умолчанию для $XDG_CONFIG_HOME, если $XDG_CONFIG_HOME не определена.
Поиск конфигурационного файла должен начинаться с ./subdir/filename, относительно всех базовых каталогов, указанных в $XDG_CONFIG_HOME и $XDG_CONFIG_DIRS. Если переменная окружения не установлена или содержит пустое значение, то вместо нее должно использоваться значение по умолчанию для этой переменной.
Если, при попытке записи в файл, каталога в котором он должен располагаться не существует, то его следует создать с правами 0700. Если же этот каталог уже существует, то права на него изменять не следует. Приложение должно быть готово к случаю, когда файл не может быть записан, по причине не существующего каталога и когда этот каталог не может быть создан по каким-либо причинам. В этом случае оно может сообщить об ошибке пользователю.
Если при попытке чтения файла он по какой-любой причине недоступен, например из-за отсутствия каталога или файла, или пользователю не разрешено открывать этот файл, тогда обработка файла в этом каталоге должна быть пропущена. Если из-за такого пропуска не был найден обязательно нужный файл, то приложение может сообщить пользователю об ошибке.
Спецификации, которые ссылаются на $XDG_DATA_DIRS или $XDG_CONFIG_DIRS должны определять поведение для случая, когда файл существует сразу в нескольких базовых каталогах. Они могут, к примеру, определить, что следует использовать только файл из наиболее важного каталога, или, как другой пример, они могут определить правила для объединения информации из раличающихся файлов.