Требования к spec-файлам

Для корректной установки и работы приложений на устройствах под управлением ОС Аврора .spec-файл должен соответствовать рекомендациям, указанным в данном разделе. Он содержит набор инструкций, которые использует rpmbuild для сборки RPM пакетов. Инструкции разбиты на секции. Секции определены в преамбуле и в основном разделе .spec-файла.

• Преамбула .spec-файла
• Основной раздел .spec-файла
• Пример .spec-файла
• Макросы
  • Встроенные макросы
  • Определение собственных макросов
  • Bash-команды для работы с макросами
• spec-файлы для других типов проектов
  • Проект с несколькими spec-файлами
  • Проект с поддиректориями
• Дополнительная информация

Преамбула .spec-файла

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

Название	Описание
Name	Имя приложения. Базовое имя пакета, которое должно совпадать с именем .spec-файла.
Version	Номер версии приложения. Обычно, если версия начинается с 0 (0.X.Y), то второе число (X) считается major версией, а третье (Y) — minor. Если первое число становится больше 0, например X.Y.Z, то первое число (X) считается major версией, второе (Y) — minor, а третье (Z) — fix version. Рекомендуется использовать правила семантического версионирования SemVer. В целом Semver не подразумевает обновления версии на каждый коммит в системе контроля версий разработчика.
Release	Номер релиза. Значение может быть задано, например, как 1%{?dist}, в этом случае значение будет увеличиваться автоматически системой сборки. %{?dist} — это тег, который означает, какой дистрибутив используется для сборки.
Summary	Краткое описание приложения.
License	Тип лицензии. Например, GPLv3+ или OGL. Примеры доступных значений указаны в таблице в столбце Identifier на сайте.
URL	Полный URL-адрес для получения подробной информации о приложении. Как правило, ссылка на сайт вендора. Например, https://example.com/%{name}
Source0	Имя файла с архивом приложения. Используется для объявления источников, используемых для сборки пакета. Все исходные файлы будут упакованы в rpm-пакеты. При необходимости могут быть указаны несколько имён файлов: Source0, Source1, Source2 и т. д. Обычно имя файла содержит название приложения и его версию, например, mysoft-1.0.tar.gz
Patch0	Имя первого патча, который нужно применить к исходному коду, если это необходимо. При необходимости можно добавить больше параметров PatchX, каждый раз увеличивая число, например: Patch1, Patch2, Patch3 и т. д. Например, application-first-patch.patch
BuildArch	Если пакет не зависит от архитектуры, например, если он полностью написан на интерпретируемом языке программирования, значение BuildArch должно быть равным noarch. Если не установлено, пакет автоматически наследует архитектуру машины, на которой он собран, например x86_64.
BuildRequires	Список пакетов, разделённый запятыми или пробелами. Может быть несколько записей BuildRequires, каждая на отдельной строке. Пакеты в списке могут быть расположены в любом порядке. В данной секции указываются требования к сборке, т.е. названия зависимых пакетов. Эти зависимости будут скачиваться и устанавливаться в таргете в процессе сборки. Например, bash, gcc, make, python. Может иметь пустое значение, если таких пакетов нет. Если используется конфигурационное имя пакета, а не точное, необходимо применять синтаксис pkgconfig(<конфигурационное_имя_пакета>). Например, у Аврора-библиотеки есть точное имя libauroraapp и более короткое конфигурационное auroraapp. Её можно подключить двумя способами: BuildRequires: libauroraapp или BuildRequires: pkgconfig(auroraapp)
Requires	Список пакетов, разделенных запятыми или пробелами, которые программа должна запускать после установки. Может быть несколько записей Requires, каждая на отдельной строке. Пакеты в списке могут быть расположены в любом порядке. В данной секции перечисляются требования к зависимостям, названия зависимых пакетов. Пакеты, указанные в данной секции будут проверены валидатором. Например, bash, python. Может иметь пустое значение, если таких пакетов нет. Сводный перечень доступных библиотек и зависимостей указан в разделе Публичные API.
ExcludeArch	Исключения архитектуры. Если приложение не может работать с определенной архитектурой процессоров, то её следует указать здесь.
Description	Подробное описание приложения. Поле должно заканчиваться точкой. Допускается продублировать информацию из поля с помощью переменной ${summary}, если нет более подробного описания.

Названия данных секций являются именами переменных, по которым можно обратиться к их содержимому в других частях spec-файла. Например, в выражении Source0: %{name}-%{version}.tar.bz2 %{name} позволяет использовать значение Name, а %{version} — значение Version для формирования имени файла с архивом.

Секция Epoch, которая используется для указания временного изменения порядка версий пакетов, игнорируется при формировании rpm-пакета. Поэтому не следует включать её в .spec-файл Аврора-приложения.

Основной раздел .spec-файла

В таблице перечислены секции, используемые в основном разделе .spec-файла.

Название	Описание
%description	Подробное описание приложения, упакованного в RPM. Это описание может занимать несколько строк и может быть разбито на абзацы.
%prep	Команда или последовательность команд для подготовки программного обеспечения к сборке, например, распаковка архива в Source0. Эта директива может содержать сценарий оболочки. Например, %setup -q.
%build	Команда или серия команд для фактического встраивания программного обеспечения в машинный код (для скомпилированных языков) или байт-код (для некоторых интерпретируемых языков).
%install	Команда или последовательность команд для копирования нужных артефактов сборки из каталога %builddir (где происходит сборка) в каталог %buildroot (который содержит структуру каталогов с файлами для упаковки). Обычно это означает копирование файлов из ~/rpmbuild/BUILD в ~/rpmbuild/BUILDROOT и создание необходимых каталогов в ~/rpmbuild/BUILDROOT. Это запускается только при создании пакета, а не при установке пакета конечным пользователем.
%check	Команда или последовательность команд для тестирования программного обеспечения. Обычно это unit-тесты.
%files	Список файлов, которые будут установлены в системе конечного пользователя. Например, для /usr/bin/ можно использовать макрос %{_bindir}/%{name}.
%changelog	Запись об изменениях, произошедших с пакетом между различными версиями.

Пример %changelog:

%changelog
* 2022-12-26 Разработчик <developer@example.com> - 0.1-1
- Релиз первой версии приложения
- Второй релиз, содержащий изменения между версиями 0.1-1

Пример .spec-файла

Пример .spec-файла, который Аврора IDE создаёт для проекта по умолчанию:

Name:       ru.template.MyApp
Summary:    Моё приложение для ОС Аврора
Version:    0.1
Release:    1
License:    BSD-3-Clause
URL:        https://auroraos.ru
Source0:    %{name}-%{version}.tar.bz2

Requires:   sailfishsilica-qt5 >= 0.10.9
BuildRequires:  pkgconfig(auroraapp)
BuildRequires:  pkgconfig(Qt5Core)
BuildRequires:  pkgconfig(Qt5Qml)
BuildRequires:  pkgconfig(Qt5Quick)

%description
Короткое описание моего приложения для ОС Аврора

%prep
%autosetup

%build
%qmake5
%make_build

%install
%make_install

%files
%defattr(-,root,root,-)
%{_bindir}/%{name}
%defattr(644,root,root,-)
%{_datadir}/%{name}
%{_datadir}/applications/%{name}.desktop
%{_datadir}/icons/hicolor/*/apps/%{name}.png

Макросы

Встроенные макросы

Макрос представляет собой простую текстовую замену. Подсистема RPM имеет встроенные макросы. Кроме этого, пользователь может создавать собственные макросы.

Например, можно один раз определить значение макроса %{version} в секции Version и затем использовать его во всём .spec-файле. Каждое упоминание будет заменено на определенное ранее значение. Аналогично можно определить имя приложения в секции Name, а затем использовать его с помощью макроса %{name}.

Таблица с макросами, которые используются в секции %files:

Макрос	Описание
%license	Помечает указанный файл, как файл лицензии. Он будет установлен и помечен RPM как таковой. Пример: %license LICENSE.
%doc	Помечает указанный файл, как файл документации. Пример: %doc README.
%dir	Помечает указанный путь, как принадлежащий RPM. Будет использоваться для очистки каталогов при удалении приложения. Пример: %dir %{_libdir}/%{name}.
%config(noreplace)	Указывает, что следующий файл является файлом конфигурации и поэтому не должен перезаписываться (или заменяться) при установке или при обновлении пакета, если файл был изменен по сравнению с исходной контрольной суммой установки. В случае изменения файл будет создан с добавлением .rpmnew в конец имени файла при обновлении или установке, чтобы ранее существовавший или изменённый файл в таргете не изменился. Пример: %config(noreplace) %{_sysconfdir}/%{name}/%{name}.conf.

Макрос %{?dist} — это тег дистрибутива. Он сигнализирует, какой дистрибутив используется для сборки. Например:

# Для дистрибутива RHEL 7.x
$ rpm --eval %{?dist}
.el7

# Для дистрибутива Fedora 23
$ rpm --eval %{?dist}
.fc23

Макрос %defattr позволяет устанавливать атрибуты доступа по умолчанию для файлов и каталогов. Формат макроса:

%defattr(<file_mode>, <user>, <group>, <dir_mode>)

• <file_mode> — разрешения по умолчанию или «режим» для файлов;
• <user> — идентификатор пользователя по умолчанию;
• <group> — идентификатор группы по умолчанию;
• <dir_mode> — разрешения по умолчанию или «режим» для каталогов.

Если конкретный атрибут не нужно указывать (обычно потому, что файл установлен с правильным атрибутом), его можно заменить дефисом.

Примеры:

%defattr(-,root,root,-)
%defattr(644,root,root,-)

Если проект для ОС Аврора собирается на Linux, то макрос %defattr можно не использовать, так как права для файлов приложения будут определены корректно. Если же проект собирается на macOS или Windows, то права для файлов обязательно нужно определить с помощью %defattr, иначе возникнет ошибка при валидации. Пример правильного размещения файлов и выдачи им прав:

%files
%defattr(-,root,root,-)
%{_bindir}/%{name}
%defattr(644,root,root,-)
%{_datadir}/%{name}
%{_datadir}/applications/%{name}.desktop
%{_datadir}/icons/hicolor/*/apps/%{name}.png

Таблица с макросами, которые используются для сборки:

Макрос	Описание
%setup	Макрос используется для сборки пакета с архивами исходного кода. Он гарантирует, что работа ведётся в правильном каталоге, удаляет остатки предыдущих сборок, распаковывает исходный архив и устанавливает некоторые привилегии по умолчанию. Макросу можно задавать опции, в частности, -q ограничивает детализацию вывода и должна быть указана в первую очередь.
%autosetup	Макрос для автоматизации применения патчей с опциональной интеграцией с распредёленной системой контроля версий.
%make_build	Макрос вызывает make с параметром, обеспечивающим оптимальную параллельную сборку в данной среде. По умолчанию поддерживает при сборке использование нескольких процессоров/ядер.
%make_install	Макрос используется для упрощения установки софта, в конфигурации которого можно настроить параметр DESTDIR
%qmake5	Макрос вызывает qmake для сборки проекта
%qmake5_install	Макрос используется для упрощения установки софта с помощью qmake
%cmake	Макрос вызывает cmake для сборки проекта

Определение собственных макросов

Можно определять собственные макросы. Синтаксис определения макроса:

%global <name>[(opts)] <body>

Все пробелы вокруг \ удаляются. Имя может состоять из буквенно-цифровых символов и символа _ и должно быть не менее 3 символов в длину. Макрос без поля (opts) является «простым» в том смысле, что выполняется только рекурсивное раскрытие макроса. Параметризованный макрос содержит поле (opts). opts (строка в круглых скобках) передаётся в команду getopt(3) для обработки argc/argv в начале вызова макроса.

Также в .spec-файлах может использоваться шаблон макроса %define <name> <body>. Различия между макросами %define и %global заключаются в следующем:

• %define имеет локальную область действия, что означает, что он применяется только к указанной части .spec-файла. Кроме того, тело макроса %define расширяется при использовании — он вычисляется лениво.
• %global имеет глобальную область действия, что означает, что он применяется ко всему .spec-файлу. Кроме того, тело макроса %global расширяется во время определения.

Bash-команды для работы с макросами

Для вывода полного списка макросов используется следующая команда:

rpm --showrc

Для вывода списка файлов пакета, в том числе файлов с макросами RPM, используется команда:

rpm -ql rpm

Для того чтобы узнать значение макроса, можно воспользоваться командой:

rpm --eval %{_MACRO}

Где _MACRO — имя макроса.

Пример:

$ rpm --eval %{_bindir}
/usr/bin

$ rpm --eval %{_libexecdir}
/usr/libexec

spec-файлы для других типов проектов

Проект с несколькими spec-файлами

По умолчанию среда сборки использует единственный .spec-файл, который находится в директории rpm/. Если в проекте имеется несколько .spec-файлов, среда сборки не сможет автоматически определить, какой из них использовать при сборке и выдаст ошибку при сборке Multiple spec files found — please select one. В таком случае нужно явным образом указать, какой именно .spec-файл использовать для сборки проекта. Для этого в интерфейсе Аврора IDE нужно перейти в Проекты → Сборка и запуск → Аврора SDK настройки, в поле RPM spec file указать путь к одному из имеющихся .spec-файлов.

Проект с поддиректориями

Пример spec-файла для subdirs-проекта взят из проекта OFVPN Plugin:

%define __provides_exclude_from ^%{_libdir}/.*$

Name: aurora-connman-vpn-plugin-ofvpn
Version: 0.1
Release: 3
Summary: Aurora Connman external VPN plugin openfortivpn
License: BSD-3-Clause
URL: http://omprussia.ru/
Source: %{name}-%{version}.tar.bz2
BuildRequires: pkgconfig(connman)
BuildRequires: pkgconfig(glib-2.0)
BuildRequires: pkgconfig(dbus-1)

%description
This package contains a openfortivpn of Aurora Connman external VPN plugin with a settings menu GUI.

%prep
%autosetup

%build

%qmake5
%make_build

%install
%make_install

%files
%{_bindir}/*

%defattr(644,root,root,-)
%{_libdir}/connman/plugins-vpn/*.so
%{_libdir}/qt5/qml/ru/omprussia/ofvpn/*
%{_sysconfdir}/connman/vpn-plugin/*.conf
%{_datadir}/sailfish-vpn/*

Следует обратить внимание на секцию %files, где прописываются пути для установки подпроектов.

Дополнительная информация

Путь из макроса %{_bindir} не должен добавляться целиком, стоит указывать только конкретный исполняемый файл, например: %{_bindir}/%{name}.

В .spec-файле можно вызывать утилиту desktop-file-install, которая может устанавливать desktop-файл в заданный каталог и, опционально, изменять данный файл. По умолчанию нет необходмости её вызывать, потому что desktop-файл устанавливается при использовании.

Для сборки пакета в ОС Windows необходимо указывать права доступа к устанавливаемым файлам.

%files
%defattr(-,root,root,-)
%{_bindir}/%{name}
%defattr(644,root,root,-)
%{_datadir}/%{name}
%{_datadir}/applications/%{name}.desktop
%{_datadir}/icons/hicolor/*/apps/%{name}.png

При использовании других систем сборки в секциях %build и %install следует указывать следующие значения:

Для cmake:

BuildRequires: cmake
# ...
%build
%cmake
%make_build

%install
%make_install

Для qmake:

BuildRequires:  pkgconfig(auroraapp)
BuildRequires:  pkgconfig(Qt5Core)
BuildRequires:  pkgconfig(Qt5Qml)
BuildRequires:  pkgconfig(Qt5Quick)
BuildRequires:  desktop-file-utils
# ...
%build
%qmake5
%make_build

%install
rm -rf %{buildroot}
%qmake5_install

Среди примеров приложений доступны различные варианты .spec-файлов.