Требования к установочным пакетам

Для корректной установки на устройство под управлением ОС Аврора RPM-пакет приложения должен соответствовать требованиям, указанным в данном разделе. Также установочные пакеты приложений проверяются на соответствие указанным требованиям при размещении в Платформе управления Аврора и Аврора Маркете. Самостоятельно проверить установочный пакет можно с помощью инструмента RPM Validator.

Общие требования

  • Файлы установочного пакета должны быть размещены в определённых директориях (см. Пути к файлам). В том числе, при установке приложения файлы не должны создаваться в домашней директории пользователя. Про размещение данных, конфигурации и кэша приложения см. Данные, конфигурация и кэш приложения.
  • Файлы не должны содержать абсолютные пути импорта модулей QML.
  • Установочный пакет не должен содержать файлы систем управления версиями.
  • Файлы и директории в установочном пакете должны оставаться под контролем менеджера пакетов RPM, им нельзя присвоить права доступа chmod 666 или chmod 777. Изменение или удаление файлов извне не имеет смысла, данные восстановятся после обновления или переустановки пакета.
  • В исполняемых файлах запрещено использовать флаги доступа Set User/Group ID Upon Execution (suid/sgid), поскольку не допускается запуск приложения от пользователя root.
  • Размер файла установочного пакета не должен превышать 200 мегабайт.

Наименование установочного пакета

Установочный пакет следует именовать следующим образом —
<название_пакета>-<версия>-<релиз>.<архитектура>.rpm, где:

  • <название_пакета> — имя пакета, которое является основным именем для остальных файлов в установочном пакете.
  • <версия> указывается в .spec/.yaml файле для сборки приложения в строке Version (см. Версия).
  • <релиз> указывается в .spec/.yaml файле для сборки приложения в строке Release (см. Релиз).
  • <архитектура> может быть armv7hl или i486.

Пути к файлам

Файлы должны быть размещены в следующих директориях RPM-пакета:

  • /usr/bin/<название_пакета> — исполняемый файл;
  • /usr/share/applications/<название_пакета>.desktop — файл в формате .desktop;
  • /usr/share/icons/hicolor/<размер>/apps/<название_пакета>.png — файлы значка приложения;
  • /usr/share/<название_пакета>/* — прочие файлы (данные приложения, собственные разделяемые библиотеки, импорт собственных QML-файлов и т. д.).

Файл .desktop

В .desktop-файле следует придерживаться следующей структуры:

Type=Application
X-Nemo-Application-Type=silica-qt5
Icon=<название_пакета>
Exec=<название_пакета>
Name=<название_приложения_на_английском_языке>
Name[ru]=<название_приложения_на_русском_языке>

X-Nemo-Application-Type

Использование значения строки X-Nemo-Application-Type=silica-qt5 позволяет проверить, что приложение использует модуль Sailfish.Silica, который позволяет ускорить запуск приложения.

Icon

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

Exec

Строка Exec должна иметь следующий вид:

  • Exec=<название_пакета> — если приложение использует С++ и QML;
  • Exec=sailfish-qml <название_пакета> — если приложение использует только QML.

Name

Значение строки Name определяет название приложения на экране приложений ОС Аврора. Значение не обязательно должно совпадать с названием пакета в установочном пакете и быть уникальным. Таким образом, на экране приложений ОС Аврора может быть более одного приложения c одним названием.

Для локализации названия приложения используется конструкция Name[<двухбуквенный_код_языка>]. Например, Name[ru] позволяет задать название приложения для русскоязычного интерфейса.

Отключение запуска одного экземпляра приложения

Для приложений рекомендуется использовать запуск только одного экземпляра (повторное нажатие значка на экране приложений откроет окно уже запущенного приложения). Если по какой-либо причине требуется отключить запуск одного экземпляра приложения, то в файл .desktop следует добавить строку X‑Nemo‑Single‑Instance = no.

Файлы .spec/.yaml

Версия

Версия установочного пакета указывается в строке Version в .spec/.yaml-файле. Для указания версии следует придерживаться принципов семантического версионирования в формате X.Y или X.Y.Z.

Примечание — версия приложения для Аврора Маркет может состоять только из цифр, разделенных точками. Длина строки версии — от 1 до 20 символов. Во время загрузки приложения в Аврора Маркет версия нового релиза должна быть выше ранее загруженного релиза. Увеличить номер версии можно с сохранением предыдущего формата релиза или с добавлением минорной версии.

Правильно Неправильно
Версия 1;
0.1;
0.0.1;
1.23.777600.0
01.5.15, 0.01.1 (01 — не допускается, следует использовать 1 );
0.1a (используется буквенный символ)
Увеличение версии с 1 до 2;
c 1 до 1.1
c 1.1.0 до 1.0.1 (ошибка версионирования);
с 1.0 до 1.0+1 (используется недопустимый символ)

Релиз

Релиз установочного пакета указывается в строке Release в .spec/.yaml-файле. В строке релиза допускается использовать только числа, символ точки и подчеркивания.

Зависимости

Зависимости для приложения указываются в строке Requires в .spec/.yaml-файле. Разрешенные для использования в приложении зависимости приведены в разделе Допустимые зависимости приложений ОС Аврора. Следует обратить внимание на зависимости с пометкой (deprecated), в текущих версиях ОС Аврора их использование допускается, но соответствующие компоненты более не развиваются и станут недоступными в одной из ближайших версий ОС.

Код приложения

Код приложения является уникальным идентификатором для приложений, которые размещаются в Аврора Маркете, и объединяет разные версии приложения. Код для приложения указываются в строке appCode в .spec/.yaml-файле.

Длина строки кода приложения — от 3 до 100 символов. Код приложения может содержать только латинские буквы, цифры, символы точки, дефиса и нижнего подчеркивания. В значении кода приложения подряд не могут идти символы точки, дефиса, точки и дефиса. Значение кода приложения не должно начинаться или заканчиваться символом точки и дефиса.

Правильно Неправильно
vpn2020;
auroraos-io.edin_.projects.sailsync-owncloud;
auroraos_vpn2020
$$$ (использование недопустимых символов);
-vpn2020 (не может начинаться с символа дефиса);
vpn.-2020 (подряд не могут идти символы точки и дефиса)

Запрещённые спецификации

В .spec/.yaml-файле запрещено использовать следующие спецификации:

  • Vendor — приложения в ОС Аврора не поддерживают обновления пакетов от вендоров;
  • Obsoletes;
  • скрипты RPM %pre, %post, %preun, %postun и %verifyscript — выполнение дополнительных действий с правами пользователя root не допускается.

Данные, конфигурация и кэш приложения

Файлы с данными можно устанавливать в /usr/share/<название_пакета>. Если пользователю требуется отключить системные данные, то можно использовать флаг в $XDG_*_HOME/<название_пакета>. Отключение системных данных не освободит место, но в случае сокрытия или ошибки при загрузке данных уменьшится время запуска и отзывчивость приложений.

Большой объем предустановленных данных

Большой объем данных не рекомендуется размещать в RPM-пакете для установки в /usr/share/<название_пакета> из-за ограниченных ресурсов целевых устройств. RPM-пакет будет конкурировать за свободное дисковое пространство с другими приложениями и может потерять возможность установиться или обновиться из-за нехватки свободного места.

В установочном пакете рекомендуется размещать только скомпилированный код приложения, QML-файлы интерфейса пользовтеля, файлы значков, файлы переводов и сопутствующие системные файлы. Если приложению требуется большой объем данных, то их можно загружать из сети при первом запуске приложения или поставлять на microSD-карте.

Хранение данных, конфигурации и кэша приложения

В зависимости от цели файлы должны устанавливаться в соответствии со спецификацией XDG Base Directory с добавлением директории <название_пакета> в каталог. Не следует жестко задавать пути домашней директории пользователя или $HOME/.config/ и т. д. Для определения путей следует использовать модули QStandardPaths, Silica.StandardPaths, методы GLib или библиотеку xdg‑helper. Это позволит убедиться, что приложение продолжит работать в изолированных вариантах использования, многопользовательских случаях использования, а также в многопрофильных однопользовательских случаях использования.

В приложениях для ОС Аврора данные должны быть организованы следующим образом:

  • $XDG_CACHE_HOME — директория кэша приложения ($XDG_CACHE_HOME/<название_пакета>) согласно спецификации XDG Base Directory, которая используется для хранения кэшированных данных (веб-кэширования, полученные и сгенерированные данные и т. д.). Очистка директории кэша не должна влиять на пользовательские данные или конфигурацию. Система может очищать кэш, когда заканчивается пространство, но приложение должно продолжать нормально функционировать, данные пользователя также не должны быть потеряны. Если переменная окружения $XDG_CACHE_HOME не задана или пуста, то следует использовать значение по умолчанию $HOME/.cache.

  • $XDG_CONFIG_HOME — директория конфигурации приложения ($XDG_CONFIG_HOME/<название_пакета>) согласно спецификации XDG Base Directory, которая используется для хранения пользовательских настроек (режим работы, необязательные функции переключения, настройки темы, конфигурация поведения и т. д.). Очистка директории конфигурации должна сбросить настройки приложения, но сохранить данные пользователя. Если переменная окружения $XDG_CONFIG_HOME не задана или пуста, то следует использовать значение по умолчанию $HOME/.config.

  • $XDG_DATA_HOME — директория данных приложения ($XDG_DATA_HOME/<название_пакета>) согласно спецификации XDG Base Directory, которая используется для хранения данных, генерируемых пользователем или приложением, и остальных данных, которые не относятся к конфигурации приложения. Очистка директории данных должна удалять пользовательские данные. Если переменная окружения $XDG_DATA_HOME не задана или пуста, то следует использовать значение по умолчанию $HOME/.local/share.

QML

Разрешенные для использования в приложении модули QML API приведены в разделе Допустимые зависимости приложений ОС Аврора. Следует обратить внимание на модули с пометкой (deprecated), в текущих версиях ОС Аврора их использование допускается, но соответствующие компоненты более не развиваются и станут недоступными в одной из ближайших версий ОС.

Модули QML

Поставляемые в пакете модули QML рекомендуется называть с префиксом, соответствующим названию пакета — например, MyAppName или MyAppName.ModuleName. Имена модулей не должны совпадать со следующими шаблонами имен:

  • Bluetooth.*;
  • Meego.*;
  • Mer.*;
  • Nemo.*;
  • NemoMobile.*;
  • Sailfish.*;
  • Qt*;
  • org.nemomobile.*;
  • org.sailfishos.*;
  • com.jolla.*;
  • com.nokia.*;
  • com.meego.*;
  • org.kde.bluezqt.

Собственные и сторонние модули QML, поставляемые в установочном пакете, следует размещать в директории /usr/share/<название_пакета>/qml.

Значок приложения

Изображения значка приложения должны быть в формате .png и называться в соответствии с установочным пакетом (строка Icon в .desktop-файле).

С приложением должны поставляться изображения значка следующих размеров:

  • 86 × 86;
  • 108 × 108;
  • 128 × 128;
  • 172 × 172.

Изображения именно этих размеров требуются для отображения на различных устройствах с разными размерами и разрешениями экрана. Другие размеры не поддерживаются.

Рекомендуемая структура размещения файлов значка имеет следующий вид:

/usr/share/icons/hicolor/
├── 86x86/apps/<название_пакета>.png
├── 108x108/apps/<название_пакета>.png
├── 128x128/apps/<название_пакета>.png
└── 172x172/apps/<название_пакета>.png

Разделяемые библиотеки

Разрешенные для использования в приложении разделяемые библиотеки приведены в разделе Допустимые зависимости приложений ОС Аврора. Следует обратить внимание на библиотеки с пометкой (deprecated), в текущих версиях ОС Аврора их использование допускается, но соответствующие компоненты более не развиваются и станут недоступными в одной из ближайших версий ОС.

Собственные разделяемые библиотеки

Собственные и сторонние разделяемые библиотеки, поставляемые в установочном пакете, следует размещать в директории /usr/share/<название_пакета>/lib.

Если приложение не использует библиотеку SailfishApp, то следует убедиться, что в исполняемом файле приложения строка rpath правильно указывает на директорию /usr/share/<название_пакета>/lib. В qmake можно использовать QMAKE_RPATHDIR для установки значения rpath.

Способы проверить корректность rpath в среде сборки:

  • c помощью команды readelf;

    bash $ readelf -d | grep RPATH 0x0000000f (RPATH) Library rpath: [/usr/share/example_app/lib]

  • с помощью инструмента RPM Validator, валидатор выведет значение rpath.

    bash RPATH ===== OK [rpath in binary seems to be ok: '/usr/share/example_app/lib'] PASSED

Запрет использования модуля QtWidgets

Модуль QtWidgets запрещен для использования, так как не оптимизирован для интерфейса пользователя ОС Аврора (выполнение программного кода будет намного медленнее, чем рендеринг с использованием Qt Quick и OpenGL ES).

Альтернатива использованию модуля QtOpenGL

Модуль QtOpenGL также запрещен для использования (из-за обширных зависимостей от модуля QtWidgets), вместо него рекомендуется использовать ряд классов допустимого модуля Qt GUI. В большинстве случаев использование Qt GUI означает переименование классов из QGL* → QOpenGL* и удаление ссылки на QtOpenGL. В некоторых случаях требуются изменения API, но они не должны быть слишком сложными.

D-Bus

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

Запрещено поставлять в RPM-пакете файлы в формате .service, активирующие шину D-Bus.