Arch package guidelines (Русский)

From ArchWiki
Состояние перевода: На этой странице представлен перевод статьи Arch package guidelines. Дата последней синхронизации: 26 августа 2023. Вы можете помочь синхронизировать перевод, если в английской версии произошли изменения.

При создании пакетов для Arch Linux придерживайтесь рекомендаций по созданию пакетов, приведённых ниже, особенно если вы собираетесь отправить новый пакет в Arch Linux. Вам также следует ознакомиться с руководствами PKGBUILD(5) и makepkg(8).

Прототип PKGBUILD

# Maintainer: Ваше Имя <вашапочта@domain.com>
pkgname=НАЗВАНИЕ
pkgver=ВЕРСИЯ
pkgrel=1
pkgdesc=""
arch=()
url=""
license=('GPL')
groups=()
depends=()
makedepends=()
optdepends=()
provides=()
conflicts=()
replaces=()
backup=()
options=()
install=
changelog=
source=($pkgname-$pkgver.tar.gz)
noextract=()
md5sums=() #заполняется автоматически через updpkgsums

build() {
  cd "$pkgname-$pkgver"

  ./configure --prefix=/usr
  make
}

package() {
  cd "$pkgname-$pkgver"

  make DESTDIR="$pkgdir/" install
}

Другие прототипы можно найти в /usr/share/pacman/ из пакета pacman.

Этикет оформления пакетов

  • Пакеты никогда не должны устанавливаться в /usr/local/.
  • Не вводите новые переменные или функции в скрипты сборки PKGBUILD, если возможно собрать пакет без них, так как они могут конфликтовать с переменными и функциями, используемыми в само́м makepkg.
  • Если абсолютно необходима новая переменная или новая функция, добавьте перед её именем подчёркивание (_), например,
    _customvariable=
  • Избегайте использования /usr/libexec/ для чего-либо. Вместо этого используйте /usr/lib/$pkgname/.
  • Поле packager из мета-файла пакета может быть настроено создателем пакета путём изменения соответствующей опции в файле /etc/makepkg.conf или переопределено в файле ~/.makepkg.conf.
  • Не используйте подпрограммы makepkg (например, error, msg, msg2, plain, warning), так как они могут измениться в любой момент. Для печати данных используйте printf или echo.
  • Все важные сообщения должны выводиться во время установки с помощью файла .install. Например, если пакет требует дополнительной настройки для работы, следует включить указания.
  • Зависимости — самая распространённая ошибка при создании пакета. Пожалуйста, уделите время их тщательной проверке, например, запустив ldd на динамических исполняемых файлах, проверив инструменты, требуемые скриптами, или посмотрев документацию к программе. В этом вам может помочь утилита namcap. Она может анализировать как PKGBUILD, так и готовый пакет и предупредит вас о неправильных разрешениях, отсутствующих или лишних зависимостях и других распространённых ошибках.
  • Любые необязательные зависимости, которые не нужны для запуска пакета или его общего функционирования, не должны включаться в массив depends; вместо этого информация должна быть добавлена в массив optdepends:
optdepends=('cups: printing support'
            'sane: scanners support'
            'libgphoto2: digital cameras support'
            'alsa-lib: sound support'
            'giflib: GIF images support'
            'libjpeg: JPEG images support'
            'libpng: PNG images support')
Приведённый выше пример взят из пакета wine. Информация optdepends автоматически выводится при установке/обновлении, поэтому не следует хранить такую информацию в файлах .install.
  • При создании описания пакета не пишите в нём само имя пакета. Например, «Nedit — текстовый редактор для X11» можно упростить до «Текстовый редактор для X11». Также старайтесь, чтобы описания не превышали ~80 символов.
  • Старайтесь, чтобы длина строки в PKGBUILD не превышала ~100 символов.
  • По возможности удаляйте пустые строки из PKGBUILD (provides, replaces и т.д.).
  • Общепринятой практикой является сохранение порядка полей PKGBUILD, как показано выше. Однако это не является обязательным, поскольку единственным требованием в данном контексте является правильный синтаксис bash.
  • Оборачивайте в кавычки переменные, которые могут содержать пробелы, такие как "$pkgdir" и "$srcdir".
  • Для обеспечения целостности пакетов убедитесь, что переменные целостности содержат правильные значения. Их можно обновить с помощью инструмента updpkgsums(8).

Именование пакета

  • Имена пакетов могут содержать только буквы, цифры и символы @, ., _, +, -. Имена не должны начинаться с дефисов или точек. Все буквы должны быть строчными.
  • Имена пакетов не должны иметь суффикс с мажорным номером версии (например, нам не нужен libfoo2, если upstream называет его libfoo v2.3.4) в случае, если ожидается, что библиотека и её зависимости будут использовать последнюю версию библиотеки с каждым соответствующим релизом upstream. Однако для некоторых программ или зависимостей этого ожидать нельзя. В прошлом это было особенно верно для наборов инструментов виджетов, таких как GTK и Qt. Программы, зависящие от них, обычно не могут быть тривиально портированы на новую мажорную версию. В таких случаях имена пакетов должны содержать суффикс основной версии (например, gtk2, gtk3, qt4, qt5). Для случаев, когда большинство зависимостей могут обновиться на новую версию, а некоторые не могут (например, программа без исходного кода, требующая libpng12 или что-то подобное), устаревшая версия пакета может называться libfoo1, в то время как текущая версия — просто libfoo.

Версионирование пакетов

  • Версии пакетов (то есть PKGBUILD#pkgver) должны совпадать с версией, выпущенной автором. Версии могут включать буквы, если это необходимо (например, версия nmap — 2.54BETA32). Теги версий не должны включать дефисы!. Только буквы, цифры и точки.
  • Номера релизов (то есть PKGBUILD#pkgrel) являются специфичными для пакетов Arch Linux. Они позволяют пользователям различать более новые и более старые сборки пакетов. Когда новая версия пакета выпускается впервые, счётчик релизов начинается с 1. Затем, по мере внесения исправлений и оптимизаций, пакет будет перевыпущен для публики Arch Linux, и номер релиза будет увеличиваться. Когда выходит новая версия программы — счётчик релизов пакета обнуляется до 1. Теги номеров релизов пакетов следуют тем же ограничениям именования, что и теги версий.

Зависимости пакетов

  • Не полагайтесь на транзитивные зависимости, так как они могут сломаться, если одна из зависимостей будет обновлена.
  • Перечислите все зависимости от библиотек. Чтобы определить их, можно использовать find-libdeps(1) (часть devtools).

Связи между пакетами

  • Не добавляйте $pkgname в PKGBUILD#provides, так как он всегда неявно предоставляется пакетом.
  • Перечислите все библиотеки, содержащиеся в пакете, в PKGBUILD#provides (например, 'libsomething.so'). Для их идентификации можно использовать find-libprovides(1) (часть devtools).

Исходники пакетов

  • По возможности следует использовать HTTPS источники (https:// для архивов, git+https:// для git).
  • Исходники должны быть проверены с помощью PGP-подписей везде, где это возможно (это может повлечь за собой сборку из git-тегов вместо архива, если upstream подписывает коммиты и теги, но не архивы)
  • При сборке из git-тега вместо имени тега используйте хэш объекта, полученный командой git rev-parse:
_tag=1234567890123456789012345678901234567890 # git rev-parse "v$pkgver"
source=(git+https://$url.git?signed#tag=$_tag)

pkgver() {
    cd "$pkgname"
    git describe
}
Пример такого подхода можно найти в пакете gitea. Причина такой практики в том, что теги могут быть изменены через force push, после чего они станут указывать на другой коммит, что повлияет на сборку пакета. Использование хэша обеспечивает целостность исходных текстов, так как force push тега изменяет его хэш. Использование функции pkgver() предотвращает случайное обновление pkgver без обновления _tag.
  • Не снижайте безопасность или проверку целостности пакета (например, удалением проверки контрольной суммы или проверки подписи PGP) из-за поломки апстрима или исчезновения функции (например, пропавшая в новом релизе подпись PGP).
  • Исходники должны быть уникальными в srcdir (это может потребовать переименования их при загрузке, например, "${pkgname}-${pkgver}.tar.gz::https://${pkgname}.tld/download/${pkgver}.tar.gz")
  • Избегайте использования определённых зеркал (например, на sourceforge) для загрузки, так как они могут стать недоступными.

Работа с upstream

Считается лучшей практикой тесно сотрудничать с upstream, когда это возможно. Это подразумевает сообщение о проблемах, связанных со сборкой и тестированием пакета.

  • Сразу же сообщайте о проблемах в upstream.
  • По возможности добавляйте исправления.
  • Добавляйте комментарии со ссылками на соответствующие баг-трекеры апстрима в PKGBUILD (это особенно важно, так как позволяет другим людям, работающим с пакетом, понять смысл внесённых вами изменений).

Рекомендуется отслеживать upstream с помощью инструментов вроде nvchecker или urlwatch, чтобы узнавать о выходе новых версий.

Каталоги

  • Файлы конфигурации должны размещаться в каталоге /etc. Если существует более одного файла конфигурации, обычно принято использовать подкаталог, чтобы сохранить /etc как можно более чистым. Используйте /etc/pkg, где pkg — имя пакета (или подходящая альтернатива, например, apache использует /etc/httpd/).
  • Файлы пакетов должны следовать этим общим рекомендациям по каталогам:
/etc Системно-значимые файлы конфигурации
/usr/bin Бинарные файлы
/usr/lib Библиотеки
/usr/include Файлы заголовков
/usr/lib/pkg Модули, плагины и тд.
/usr/share/doc/pkg Документация приложений
/usr/share/info Системные файлы GNU Info
/usr/share/licenses/pkg Лицензии приложений
/usr/share/man Страницы man
/usr/share/pkg Данные приложений
/var/lib/pkg Постоянное хранилище приложений
/etc/pkg Файлы конфигураций для pkg
/opt/pkg Крупные автономные пакеты
  • Пакеты не должны содержать ни одного из следующих каталогов:
    • /bin
    • /sbin
    • /dev
    • /home
    • /srv
    • /media
    • /mnt
    • /proc
    • /root
    • /selinux
    • /sys
    • /tmp
    • /var/tmp
    • /run

Функции makepkg

При использовании makepkg для сборки пакета он автоматически делает следующее:

  1. Проверяет, установлены ли пакеты из dependencies и makedepends.
  2. Загружает исходные файлы с серверов
  3. Проверяет целостность исходных файлов
  4. Распаковывает исходные файлы
  5. Применяет все необходимые патчи
  6. Собирает программное обеспечение и устанавливает его в fake root
  7. Удаляет символы из двоичных файлов
  8. Удаляет отладочные символы из библиотек
  9. Сжимает руководства и/или страницы info.
  10. Генерирует мета-файл пакета, включаемый в каждый пакет.
  11. Сжимает fake root в файл пакета
  12. Сохраняет файл пакета в настроенном каталоге назначения (по умолчанию в текущем рабочем каталоге)

Архитектуры

Массив arch должен содержать 'x86_64', если скомпилированный пакет зависит от архитектуры. В противном случае используйте 'any' для независимых от архитектуры пакетов.

Лицензии

Смотри PKGBUILD (Русский)#license.

Воспроизводимые сборки

Arch работает над тем, чтобы сделать все пакеты воспроизводимыми. Создатель пакета может проверить, является ли пакет воспроизводимым, с помощью makerepropkg из devtools или repro из archlinux-repro.

$ makerepropkg $pkgname-1-1-any.pkg.tar.zst

или

$ repro -f $pkgname-1-1-any.pkg.tar.zst

Если во время сборки требуется временная метка, используйте переменную окружения SOURCE_DATE_EPOCH. Формат описан в документации.

Дополнительные рекомендации

Сперва обязательно прочитайте приведённые выше рекомендации — там перечислены важные моменты, которые не будут повторяться на приведённых ниже страницах с рекомендациями. Эти конкретные рекомендации предназначены в качестве дополнения к стандартам, перечисленным на этой странице.

Указания по созданию пакетов

32-bitCLRCMakeCrossDKMSEclipseElectronFontFree PascalGNOMEGoHaskellJavaKDEKernelLispMesonMinGWNode.jsNonfreeOCamlPerlPHPPythonRRubyRustShellVCSWebWine

Пакеты, представленные в AUR, должны дополнительно соответствовать правилам публикации пакетов в AUR.