omp-logo
search
Документация
ОС Аврора 5.0.1

Инструмент sfdk для работы с пакетами из командной строки

В комплекте SDK для современной разработки под ОС Аврора поставляется IDE на основе QtCreator, который поддерживает работу только с проектами на основе систем сборки qmake и CMake. Для других систем сборки (Meson, Autotools и другие) предлагается использовать утилиту sfdk, входящую в состав SDK.

sfdk — это утилита интерфейса командной строки SDK. С её помощью можно управлять параметрами SDK, выполнять сборку и тестирование. Она позволяет настроить стороннюю IDE, которая поддерживает выбранную систему сборки, для разработки приложений для ОС Аврора. Также утилита может применяться и в системах CI/CD.

В данной статье описывается использование утилиты на всех этапах разработки: сборка, запуск, работа с зависимостями, управление spec-файлом, управление устройствами. Для примера используются приложение на основе CMake и библиотека на основе GNU Automake. Для других систем сборки алгоритм будет аналогичным.

Подготовка

Для начала работы потребуется Аврора SDK. (См. установку по ссылке). В статье использование команд sfdk демонстрируется на примере проектов:

доступные по ссылкам из публичных репозиториев.

Утилита sfdk располагается в директории <AuroraSDK_DIR>/bin. Далее в статье предполагается, что на ЭВМ разработчика в оболочке настроен псевдоним, с помощью которого будет доступен вызов sfdk без указания полного пути.

Пример настройки псевдонима. Команды в данной инструкции приводятся для Unix-совместимого терминала. В Linux и macOS можно использовать стандартный терминал, в Windows необходимо использовать Git Bash.

alias sfdk=~/AuroraOS/bin/sfdk

Вызов sfdk должен осуществляться из директории рабочего пространства, которая была указана при установке Аврора SDK.

Для получения списка установленных инструментов сборки используется команда sfdk tools list:

$ sfdk tools list
AuroraOS-5.1.2.10-base                          предоставлено SDK,последнее
├── AuroraOS-5.1.2.10-base-aarch64              предоставлено SDK,последнее
│   └── AuroraOS-5.1.2.10-base-aarch64.default  снимок                     
├── AuroraOS-5.1.2.10-base-armv7hl              предоставлено SDK,последнее
│   └── AuroraOS-5.1.2.10-base-armv7hl.default  снимок                     
└── AuroraOS-5.1.2.10-base-x86_64               предоставлено SDK,последнее
    └── AuroraOS-5.1.2.10-base-x86_64.default  снимок

Из вывода команды необходимо выбрать название нужного комплекта для сборки.

Большинство команд утилиты требует задание комплекта и мобильного устройства/эмулятора. Если их не указать, будет выведено соответствующее сообщение об ошибке. Чтобы не указывать их каждый раз при работе с утилитой, существует команда sfdk config. Она позволяет сохранять параметры, необходимые для других команд sfdk.

В следующем разделе будет продемонстрирована сборка приложения ApplicationTemplate для эмулятора. Для этого потребуется соответствующий комплект.

Общий формат команды:

sfdk config target=AuroraOS-<номер_релиза>-base-<архитектура>

Комплекты armv7hl и aarch64 используются для мобильных устройств, x86_64 — для эмулятора.

Пример:

sfdk config target=AuroraOS-5.1.2.10-base-x86_64

Сборка qmake-приложения

На этапе подготовки был получен проект приложения. Его сборку можно выполнить в формате теневой сборки, когда каталог сборки находится на одном уровне файловой системы с каталогом исходных файлов, аналогично тому, как это делается автоматически при работе с IDE. Для этого нужно выполнить команду sfdk build:

mkdir ApplicationTemplate.build.x86_64 && cd ApplicationTemplate.build.x86_64
sfdk build ../ApplicationTemplate

Примечание. В рамках статьи предполагается, что если в проекте имеются зависимости для сборки, которые отсутствуют по умолчанию в поставке Аврора SDK, то они объявлены в spec-файле RPM для автоматической установки во время сборки пакета. Если необходимо установить дополнительные зависимости вручную, это можно можно сделать с помощью команды sfdk tools package-install.

После успешного завершения сборки RPM-пакеты будут находиться в каталоге RPMS. Для повторной фазы сборки можно отдельно использовать команды следующего вида:

sfdk qmake ../ApplicationTemplate [qmake-options...]
sfdk make [make-options...]
sfdk build-shell <arbitrary-build-command> [options...]
sfdk make-install
sfdk package

Подобно команде sfdk qmake, команда sfdk cmake существует для проектов на основе CMake. Вместе с sfdk make эти команды позволяют запускать rpmbuild таким образом, что выполняется только соответствующая часть раздела %build spec-файла.

После сборки пакет следует подписать:

sfdk engine exec rpmsign-external sign -k path/to/.auroraos-regular-keys/regular_key.pem  -c path/to/.auroraos-regular-keys/regular_cert.pem RPMS/*

Запуск приложения на эмуляторе

Развёртывание приложения допускается только в виде RPM-пакетов. Следующие инструкции относятся только к указанному случаю.

Для определения имени устройства, соответствующего эмулятору, следует перечислить доступные устройства:

$ sfdk device list
#0 "Aurora OS эмулятор 5.1.2.10-base"
    эмулятор               автоопределённое      defaultuser@127.0.0.1:2223
    закрытый ключ: ~/AuroraOS/vmshare/ssh/private_keys/sdk

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

sfdk config device="Aurora OS эмулятор <номер_релиза>-base"

Пример:

sfdk config device="Aurora OS эмулятор 5.1.2.10-base"

Для развёртывания приложений используется команда sfdk deploy.

sfdk deploy --sdk

После успешного развёртывания значок приложения появится в меню. Таким образом, Аврора-приложение было успешно собрано и установлено вручную.

Запуск приложения из командной строки:

sfdk device exec /usr/bin/ru.auroraos.ApplicationTemplate

Запуск отладчика выполняется командой:

sfdk debug /usr/bin/ru.auroraos.ApplicationTemplate

Следует отметить, что обе команды выше запускают приложение вне песочницы.

Развёртывание вручную

Если автоматическое развёртывание не соответствуют конкретным потребностям пакета, то для передачи RPM-пакетов на устройство или эмулятор используется опция команды --manual:

sfdk deploy --manual RPMS/ru.auroraos.ApplicationTemplate-1.0-1.x86_64.rpm

В этом случае RPM копируются в каталог ~/RPMS на устройстве. Затем с помощью командной строки на устройстве следует развернуть RPM-пакет любым удобным способом.

$ sfdk device exec
(device) $ sdk-deploy-rpm RPMS/ru.auroraos.ApplicationTemplate-1.0-1.x86_64.rpm

Передать RPM-пакеты на устройство можно и с помощью других инструментов. Например, можно использовать scp:

scp -P 2223 -i ~/AuroraOS/vmshare/ssh/private_keys/sdk \
    path/to/package.rpm defaultuser@127.0.0.1:

Запуск приложения на устройстве

По аналогии с запуском на эмуляторе, нужно выбрать устройство из списка зарегистрированных устройств. Если желаемое устройство отсутствует в списке, нужно выполнить его регистрацию. В настоящее время это возможно сделать только в настройках Аврора IDE.

$ sfdk device list
#0 "Aurora OS эмулятор 5.1.2.10-base"
    эмулятор               автоопределённое      defaultuser@127.0.0.1:2223
    закрытый ключ: ~/AuroraOS/vmshare/ssh/private_keys/sdk
#1 "Fplus Pro R570E"
    hardware-device  user-defined  defaultuser@192.168.2.15:22
    private-key: ~/.ssh/id_fplus_r570e
$ sfdk config device="Fplus Pro R570E"

В то время как эмуляторы ОС Аврора имеют архитектуру x86_64, большинство аппаратных устройств ОС Аврора имеют архитектуру ARM. Поэтому необходима другая сборка приложения. Для пересборки под устройство сперва следует выбрать подходящий под архитектуру устройства комплект сборки.

sfdk config target=AuroraOS-<номер_релиза>-base-<архитектура>

Пример:

sfdk config target=AuroraOS-5.1.2.10-base-armv7hl

Нужно создать каталог сборки для этой цели и собрать приложение.

mkdir ApplicationTemplate.build.armv7hl && ApplicationTemplate.build.armv7hl
sfdk build ../ApplicationTemplate

И выполнить команду sfdk deploy в новом каталоге сборки:

sfdk deploy --sdk

В результате приложение появилось в списке установленных приложений и готово к запуску:

sfdk device exec /usr/bin/ru.auroraos.ApplicationTemplate

Развёртывание вручную идентично продемонстрированному ранее для эмулятора.

Примечание. sudo не установлен на аппаратных средствах по умолчанию, права суперпользователя присваиваются с помощью команды devel-su.

Работа с зависимыми пакетами

Если разработка проекта ведётся для нескольких зависимых друг от друга пакетов, то необходимо убедиться, что обновлённые версии требуемых пакетов доступны в комплекте сборки. Для этого необходимо указать параметры конфигурации sfdk: output-prefix и search-output-dir (первая команда на самом деле использует вторую внутри себя). В примере ниже настраивается конфигурация для результирующих RPM-пакетов таким образом, чтобы использовался общий выходной каталог, а sfdk при разрешении зависимостей на этапе сборки будет учитывать существующие в этом каталоге пакеты.

mkdir ~/RPMS
sfdk config --global --push output-prefix ~/RPMS

Справка sfdk --help-building содержит больше информации о том, как объединить эти действия с параметром конфигурации task для получения выходных каталогов для каждой задачи.

Далее в примерах будет использоваться эмулятор, поэтому нужно вернуться к комплекту для архитектуры x86_64, если ранее она была переключена на цель ARM.

sfdk config target=AuroraOS-5.1.2.10-base-x86_64

В качестве зависимости будет использоваться библиотека automakesample (см. {#prepare}). В отличие от проектов на основе qmake или CMake, проекты на основе Automake (Autotools) редко упаковываются таким образом, чтобы можно было выполнять теневую сборку с помощью sfdk. Но конфигурация данной библиотеки позволяет это осуществить. С информацией об ограничениях теневых сборок можно ознакомиться из sfdk --help-building.

git clone https://github.com/sailfishos/automakesample
mkdir automakesample.build.x86_64 && cd automakesample.build.x86_64
sfdk build ../automakesample

Далее необходимо изменить приложение, добавив зависимость сборки от библиотеки.

Следует отредактировать main.cpp и добавить следующий код:

#include <automakesample.h>
#include <iostream>
...
std::cout << automakesample::greetings() << std::endl;

Далее необходимо отредактировать CMakeLists.txt, чтобы библиотека automakesample находилась и использовалась с помощью pkg-config (см. в примере, как это делается для sailfishapp), и добавить BuildRequires: pkgconfig(automakesample) в rpm/ru.auroraos.ApplicationTemplate.spec.

Сборка обновлённого приложения:

cd ApplicationTemplate.x86_64
sfdk build ../ApplicationTemplate

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

The following 2 NEW packages are going to be installed:
  automakesample        0.1-1
  automakesample-devel  0.1-1

Нужно развернуть приложение и библиотеку (но не пакет разработки) в эмуляторе и запустить приложение. В выводе консоли после запуска приложения должно появиться приветствие.

$ sfdk deploy --all "-*-devel"
$ sfdk device exec /usr/bin/automakesample
Hello, World!

Изменение кода с помощью Аврора IDE и без неё

Для успешной загрузки проектов для ОС Аврора и включения в них расширенных функций редактирования кода, на стороне среды разработки для конкретного типа проектов должен существовать определённый уровень интеграции с Аврора SDK. Это необходимо, потому что пути к файловой системе, задействованные во время сборки, не всегда существуют в файловой системе хоста — некоторые действительны только в Build Engine. В Аврора IDE такая интеграция существует для проектов на основе qmake и CMake.

Если редактор кода или инструмент не получает необходимую информацию из системы сборки, используемой в конкретном проекте, следует использовать формат Clang JSON для базы данных компиляции, применяемый в качестве взаимозаменяемого описания проекта, подходящего для загрузки с помощью инструментов. Такой же подход может использоваться для любой среды разработки, способной загружать базы данных компиляции, а не только с Аврора IDE.

Для систем сборки, которые могут использовать make, Аврора SDK поддерживает удобное создание баз данных компиляции с помощью команды sfdk compiledb.

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

cd automakesample.build.x86_64
sfdk build ../automakesample # не требуется, если команда уже была запущена ранее
sfdk compiledb
cp compile_commands.json ../automakesample/

Теперь проект на основе Automake можно открыть в Аврора IDE. Чтобы открыть файл базы данных компиляции в исходном каталоге, можно использовать путь Файл → Открыть файл или проект.... При этом не следует открывать оригинал в каталоге сборки. После открытия проекта необходимо:

  • настроить его для использования комплекта, соответствующего цели сборки, применяемой для сборки проекта с помощью sfdk;
  • настроить путь к каталогу сборки в разделе Проекты → Настройки сборки.

Для упрощения навигации по задачам сборки проект с этой конфигурацией может быть построен непосредственно из Аврора IDE. В случае проектов приложений также можно будет обновить настройки запуска и запустить проект на устройстве непосредственно из Аврора IDE.

В качестве примера альтернативной среды редактирования можно рассмотреть использование редактора ViM с установленным плагином YouCompleteMe. С плагином YouCompleteMe ViM ищет файл compile_commands.json выше по иерархии файловой системы, начиная с каталога, где находится редактируемый файл. Предполагается, что на данном этапе произведены необходимые настройки, и после открытия файла lib/automakesample.cpp все функции, предоставляемые плагином YouCompleteMe, должны быть доступны.

Написание удобных для разработчиков spec-файлов RPM

Для сохранения возможности полной сборки на месте (однократно) с помощью команды sfdk build, в spec-файле не следует указывать ничего специфического. Необходимо обеспечить максимально удобные для разработчиков рабочие процессы с инкрементными (и повторными) сборками и задействованными теневыми сборками.

Процедура сборки и установки должна быть полностью реализована с использованием базовой системы сборки (qmake, CMake, GNU Automake, make, …) без дополнительных шагов, реализованных на уровне спецификации RPM. Это также означает, что нельзя использовать макрос %doc. Если используется система сборки, отличная от qmake или CMake, и в процедуру сборки пакета входит шаг, подобный настройке, раздел %build должен быть написан таким образом, чтобы этот шаг был пропущен для повторяющихся инкрементных сборок. Ниже приведены примеры разделов %build и %install.

Для qmake:

%build
%qmake ARGS...
make %{?_smp_mflags}
make %{?_smp_mflags} doc

%install
%qmake_install

Для CMake:

%build
%cmake ARGS...
make %{?_smp_mflags}
make %{?_smp_mflags} doc

%install
%make_install

Для GNU Automake, Autoconf и подобных:

%build
if ! test -f Makefile; then
    %reconfigure
fi
make %{?_smp_mflags}
make %{?_smp_mflags} doc

%install
%make_install

Объявление зависимостей

Если пакет имеет рабочие зависимости от других пакетов, подобные зависимости должны храниться в метаданных пакета, чтобы менеджер пакетов мог при установке пакета также установить зависимости. Управление метаданными происходит в spec-файлах. Оптимальный способ добавить зависимость — добавить поле Requires в spec-файл:

Requires:   sailfishsilica-qt5 >= 0.10.9
Requires:   libsailfishapp-launcher

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

Если автоматизированный процесс добавляет нежелательную зависимость, его следует отключить для одной зависимости с помощью %define __requires_exclude. Например, если автоматическая генерация зависимостей добавила нежелательную зависимость к модулю Python с именем wrongmodule, можно отключить это с помощью следующей команды:

%define __requires_exclude python3dist.wrongmodule

При необходимости полного отключения автоматической генерации зависимостей для модулей Python можно добавить:

%undefine __pythonapp_requires

Валидация пакетов

Приложения для ОС Аврора версии 4.0.1 и выше обязаны соответствовать заданным требованиям и проходить валидацию. Валидатор запускается средствами sfdk:

cd ApplicationTemplate
sfdk build
sfdk check

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

sfdk config target=AuroraOS-<номер_релиза>-base-<архитектура>
sfdk check ...path/to/ru.auroraos.ApplicationTemplate-1.0-1.<архитектура>.rpm

Пример:

sfdk config target=AuroraOS-5.1.2-base-armv7hl
sfdk check ...path/to/ru.auroraos.ApplicationTemplate-1.0-1.armv7hl.rpm

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

Руководство использования утилиты можно получить командой sfdk --help.

Мы используем cookies для персонализации сайта и его более удобного использования. Вы можете запретить cookies в настройках браузера.

Пожалуйста ознакомьтесь с политикой использования cookies.