Стили написания PKGBUILD: официальные гайды

20.09.2026 · ~9 минут чтения

Стиль PKGBUILD описан в трёх официальных источниках: страница PKGBUILD на ArchWiki, гайд Arch package guidelines и утилита namcap. Порядок полей фиксированный, функции оформляются с отступами в четыре пробела и комментариями ## begin/## end, а перед публикацией в AUR пакет прогоняется через namcap. Ниже полный разбор этих правил и чек-лист перед сдачей пакета.

Какие официальные гайды по стилю PKGBUILD существуют?

Три источника покрывают всё, что нужно знать о стиле. Каждый отвечает за свою часть.

PKGBUILD на ArchWiki. Главная страница, с которой стоит начинать. Там описан каждый элемент файла: переменные, функции, порядок записи и правила оформления. Отдельно разобраны типовые ошибки и частые вопросы новичков. Если сомневаешься в каком-то поле, ответ ищи здесь, страница обновляется вместе с развитием makepkg.

Arch package guidelines. Общие правила для пакетов в официальных репозиториях и AUR. Тут требования к именованию, лицензиям, зависимостям и структуре пакета. Отдельные страницы есть для Python, Node.js, Go, Rust и других языков, там описаны специфичные для экосистемы нюансы вроде установки зависимостей или путей к файлам данных.

Namcap. Утилита из официального репозитория, которая проверяет PKGBUILD и собранный пакет на типовые ошибки. Документация и список всех правил на странице Namcap на ArchWiki. Утилита не заменяет чтение гайдов, но ловит то, что легко пропустить глазами: пропущенную лицензию, лишнюю зависимость, неверный путь к файлу.

Эти три источника: база. Дальше разберём, что именно они требуют, на конкретных примерах.

Какой порядок полей в PKGBUILD?

Поля записываются в строгом порядке. Нарушение не сломает сборку, но ревьюеры и другие пользователи привыкли к стандартному виду. Вот эталонный порядок:

pkgname=myapp
pkgver=1.0.0
pkgrel=1
pkgdesc="Описание пакета"
arch=('x86_64')
url="https://example.com"
license=('MIT')
groups=()
depends=('glibc')
makedepends=('cmake')
checkdepends=()
optdepends=()
provides=()
conflicts=()
replaces=()
backup=()
options=()
install=myapp.install
source=("$pkgname-$pkgver.tar.gz")
sha256sums=('...')

Сначала идёт идентификация пакета: pkgname, pkgver, pkgrel, pkgdesc. pkgname: имя, pkgver: версия, pkgrel: номер сборки, pkgdesc: короткое описание. Потом метаданные: arch: архитектуры, url: домашняя страница проекта, license: лицензия, groups: группы пакетов.

Затем зависимости: depends: обязательные, makedepends: нужные только для сборки, checkdepends: для тестов, optdepends: опциональные. Дальше конфликты и замены: provides, conflicts, replaces. В конце файлы и контрольные суммы: backup, options, install, source, sha256sums.

После переменных идут функции в таком порядке: prepare(), pkgver(), build(), check(), package(). Функции, которые не нужны, просто пропускаются. Например, для пакета без тестов не пишут check(), а для простого скрипта достаточно одной package().

Есть пара тонкостей. pkgdesc пишется без точки в конце и без имени пакета внутри: описание отвечает на вопрос «что это?», а не повторяет название. В source можно указать несколько файлов, тогда для каждого нужна своя контрольная сумма в sha256sums. Порядок элементов в source и sha256sums должен совпадать, иначе makepkg не сможет сопоставить файл с суммой.

Поле install указывает на файл .install со скриптами pre_install, post_install, pre_upgrade, post_upgrade и pre_remove. Оно нужно только тогда, когда пакет требует действий при установке: создание пользователя, перезапуск службы, обновление базы. Для простых пакетов поле опускают.

Как оформлять функции в PKGBUILD?

Правила оформления функций простые и единые для всех пакетов.

Отступы: четыре пробела. Табы не используются.
Каждая функция обрамляется комментариями ## begin имя() и ## end имя().
Между функциями: пустая строка.
Кавычки: одинарные для строк без переменных, двойные, когда подставляешь переменные.

Пример:

build() {
    cmake -B build -DCMAKE_INSTALL_PREFIX=/usr
    cmake --build build
}

package() {
    cmake --install build --prefix "$pkgdir/usr"
}

Комментарии ## begin/## end помогают быстро находить границы функций в длинном файле. Особенно удобно, когда в PKGBUILD пять-шесть функций и каждая по двадцать строк. В редакторе с подсветкой синтаксиса такие маркеры видны сразу.

Для пакетов, которые патчат исходники, добавляется prepare():

prepare() {
    patch -p1 -i "$srcdir/fix-build.patch"
}

Она тоже обрамляется комментариями ## begin/## end. Функция pkgver() нужна только тогда, когда версия определяется динамически, например из тега git-репозитория. В остальных случаях её не пишут.

Стиль кавычек:

local url='https://example.com'   # без переменных: одинарные
local version="$pkgver"           # с переменной: двойные

Правило простое: если в строке есть подстановка переменной, двойные кавычки, иначе одинарные. Такой стиль принят во всех официальных пакетах Arch, и namcap на него не ругается.

Почему license обязателен?

Поле license: единственное, без которого AUR не примет пакет. Это требование Arch package guidelines. Пакет без лицензии отклонят, потому что непонятно, можно ли его вообще распространять. Лицензия определяет, кто и как может использовать твой пакет.

Как заполнять:

Если лицензия есть в /usr/share/licenses/common, пиши её имя: license=('MIT'), license=('GPL-3.0-or-later').
Если стандартной лицензии нет, ставь license=('custom').
Для нестандартной лицензии с именем: license=('custom:название').

license=('custom'): допустимый вариант, но лучше указывать имя. Например, license=('custom:MyApp'), если проект распространяется под собственным текстом лицензии. Так пользователю сразу понятно, что за лицензия, без открытия файла.

Если лицензия нестандартная, текст обычно кладут в исходники проекта. В package() его копируют в /usr/share/licenses/$pkgname/. Тогда пользователь найдёт лицензию рядом с пакетом, а не будет искать её на сайте проекта.

Список стандартных лицензий лежит в /usr/share/licenses/common/. Там MIT, GPL, BSD, Apache и другие. Если нужной лицензии нет в списке, это повод задуматься: возможно, проект использует нестандартную лицензию, и стоит проверить её условия перед публикацией.

Как проверить PKGBUILD с помощью namcap?

namcap ставится из официального репозитория:

sudo pacman -S namcap

Проверка PKGBUILD:

namcap PKGBUILD

Эту проверку стоит запускать ещё до сборки: она ловит ошибки в полях и функциях, когда исправить их проще всего. Потом собираешь пакет и проверяешь уже результат.

Проверка собранного пакета:

namcap *.pkg.tar.zst

Вывод разбит на три уровня: E: ошибка, W: предупреждение, I: информационное сообщение. Ошибки нужно исправлять обязательно. Предупреждения желательно. Информационные сообщения можно игнорировать.

Каждая строка вывода начинается с уровня и текста правила. Например, E: Missing license: ошибка, правило missinglicense. По имени правила легко найти описание в документации или в выводе namcap -l. Такой формат удобен и для автоматизации: можно грепать вывод по E: и падать на любой ошибке.

Интерактивный режим, когда namcap спрашивает про каждое предупреждение:

namcap -i myapp-1.0.0-1-x86_64.pkg.tar.zst

Рекурсивная проверка зависимостей:

namcap -r PKGBUILD

Флаг -r проверяет не только сам пакет, но и его зависимости. Полезно, когда собираешь пакет для чужой системы и хочешь убедиться, что все зависимости доступны.

Отдельные правила можно включать и выключать. Список всех правил:

namcap -l

Объяснение каждого предупреждения:

namcap -e PKGBUILD

Отключить конкретное правило:

namcap -d missinglicense PKGBUILD

Флаг -e полезен, когда не понимаешь, что именно namcap хочет сказать. Флаг -d пригодится при ложных срабатываниях, когда правило срабатывает, но проблема не настоящая.

Какие ошибки namcap встречаются чаще всего?

Чаще всего namcap находит проблемы с лицензией и зависимостями.

E: Missing license: нет поля license. Исправляется одной строкой.
W: Dependency included and not needed: зависимость в depends, но пакет её не использует. Лишние зависимости раздувают установку и могут тянуть конфликты.
W: Dependency not included and needed: пакет использует библиотеку, которой нет в depends. На чужой системе такой пакет не запустится.
E: ELF file outside of a valid architecture: бинарник собран не для той архитектуры, что указана в arch.
W: File listed in backup but not in package: файл указан в backup, но не попал в пакет.

Ошибки E блокируют публикацию. Предупреждения W стоит разобрать по одному: часть из них реальные проблемы, часть ложные срабатывания на скриптах. Если предупреждение повторяется на каждом пакете одного проекта, загляни в исходники, возможно, там скрипт, который namcap не может проанализировать.

Как автоматизировать проверку namcap?

Запускать namcap вручную после каждой сборки легко забыть. Есть два простых способа автоматизации.

Функция в ~/.bashrc, которая собирает пакет и сразу проверяет:

function mkn() {
    makepkg -f "$@" && namcap *.pkg.tar.zst
}

Теперь вместо makepkg -f пишешь mkn, и проверка выполняется автоматически. Подробнее про флаги makepkg читай в статье «makepkg: всё, что нужно знать».

Второй способ: CI. Например, GitHub Actions с контейнером archlinux: на каждый коммит ставится namcap и прогоняется на PKGBUILD. Если появляется ошибка E, сборка падает, и ты узнаёшь о проблеме до публикации. Такой подход удобен, когда пакет поддерживают несколько человек. В CI проверяют и PKGBUILD, и собранный пакет, если сборка выполняется прямо в пайплайне.

Перед публикацией в AUR прогони обе проверки:

namcap PKGBUILD
namcap *.pkg.tar.zst

Обе должны завершиться без ошибок E. Если namcap нашёл проблему в собранном пакете, а не в PKGBUILD, смотри, что именно он пишет. Часто это лишняя зависимость или файл не в том месте. Разбор ошибок сборки по шагам читай в статье «Divide and conquer: отладка сборки».

Частые вопросы

namcap ругается на лишнюю зависимость: что делать?

W: Dependency included and not needed значит, что зависимость можно убрать из depends. Проверь, реально ли пакет её использует. Иногда namcap ошибается на скриптах и динамически подгружаемых библиотеках. Тогда оставляй зависимость и добавляй комментарий, почему она нужна. Комментарий спасёт от повторного вопроса в ревью.

Нужно ли запускать namcap и на PKGBUILD, и на пакете?

Да, это разные проверки. namcap PKGBUILD смотрит на поля и функции файла. namcap *.pkg.tar.zst на содержимое собранного пакета: бинарники, зависимости, файлы. Ошибка может быть только в одном из них, поэтому обе проверки обязательны.

Что значит license=(‘custom’)?

Проект использует лицензию, которой нет в /usr/share/licenses/common. Например, собственный текст лицензии. В AUR это допустимо, но лучше уточнить: license=('custom:название').

namcap не установлен: откуда его взять?

Из официального репозитория extra:

sudo pacman -S namcap

Можно ли пропустить проверку namcap перед публикацией?

Можно, но не стоит. Модераторы AUR и пользователи часто запускают namcap сами. Пакет с ошибками E скорее всего отклонят или пометят. Пять минут проверки экономят час переписки. Перед публикацией также полезно прочитать чужой PKGBUILD: как это делается, разобрано в статье «Как проверить, что AUR-пакет делает». Чужой код покажет, как выглядят принятые пакеты, и подсветит привычки, которые стоит перенять.

Полезные ресурсы

Свой PKGBUILD: полный гайд: как написать PKGBUILD с нуля, от идеи до готового файла.
Проверка PKGBUILD: 10 вопросов: чек-лист, который стоит пройти перед публикацией.

Заключение

Стиль PKGBUILD это не вкусовщина, а набор правил из официальных гайдов. Порядок полей, отступы в четыре пробела, комментарии ## begin/## end, обязательное поле license: всё это описано на ArchWiki и проверяется утилитой namcap. Прогони namcap PKGBUILD и namcap *.pkg.tar.zst перед публикацией, и пакет пройдёт ревью без лишних вопросов.

Не получилось? Поможем настроить

Задай вопрос в чате — отвечаем быстро, по делу и без воды.

Telegram Max