AppCreation.md

Арго Фреймворк Википедия

Содержание

Введение
Установка Фреймворка
Приложения Фреймворка
Создание Приложений *
- Создание Каркаса Приложения
- Регистрация Системного Приложения
- Делаем Статическое Приложение
Примеры Приложений
Структура Приложений
Структура Управляющих Элементов
Утилиты Фреймворка

Создание Каркаса Приложения

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

Каркас можно написать руками или скопировать нужные файлы из существующих приложений и долго их править. Есть более простой путь с использованием скрипта appmake.sh (configs/bin/appmake.sh - разумеется, что мы находимся в корне рабочего пространства, рабочей директории). Это интерактивный скрипт, который коллекционирует параметры приложения и создает каркас автоматически. Если окружение выставлено, то скрипт можно найти используя команду which:

WS$ which appmake.sh
/home/andrey/share/FRM/FRM-V4/argo-v4-03-04-22/WS/configs/bin/appmake.sh

На первый раз можно запустить справку по этому скрипту:

WS$ appmake.sh --help

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

Скрипт создает все необходимые файлы с контентом для создания пользовательского приложения, для регистрации системного приложения необходимо воспользоваться инструкцией из топика ниже.
Скрипт принимает только один параметр - базовое имя приложения, это основной параметр, который определяет очень многое (его можно еще переопределить на первом шаге). Например:
$ appmake.sh firstapp
Дальнейшие шаги и предлагаемые значения по умолчанию также зависят от этого параметра, но их можно поменять.

Ниже приведен лог запуска скрипта для создания приложения firstapp. Также продемонстрирую смену имени приложения на первом шаге:

$ appmake.sh hello
Application Make Script v1.0.0
Copyright (C) 2026 Andrey Dedukhin (adedukhin@gmail.com)

Enter main application name (Current hello): firstapp                 << Сменили имя на правильное
Application Name: firstapp

Enter application path (Current applets/firstapp):                    << Путь до приложения в дереве, берем по умолчанию (и не советую менять)
Application Path: applets/firstapp

Select application language (from: c c++ python) [c]):                << Выбираем язык для приложения, в данном случае Си, по умолчанию. Можно также выбрать C++ или python.
Application Language: c

Enter application file name (Current firstapp.c(h)):                  << Задаем имена исходных файлов без расширения, берем по умолчанию (также не советую менять)
File Names: firstapp.c firstapp.h

Enter application title (Current firstapp_title): FirstApp            << Имя приложения в системе, также влияет на параметры регистрации приложения (вот тут имя надо поменять)
Application Title: FirstApp

Enter brief application description/title (Current 'Hello World!!!' for example): Framework firstapp application    << Заголовок, отображаемый в окне, и краткое описание
Application Description: Framework firstapp application

Enter application author (Current andrey): Andrey Dedukhin            << Имя автора поменяем, по умолчанию берется логин в системе
Author: Andrey Dedukhin

Processing applets/firstapp/src/firstapp.c ...                        << Основной исходный файл приложения
Processing applets/firstapp/inc/firstapp.h ...                        << Основной заголовок приложения
Processing applets/firstapp/component.mk ...                          << Основной мейкфайл
Processing applets/firstapp/Makefile ...                              << Дополнительный мейкфайл приложения для простройки пользовательских приложений
Processing applets/firstapp/resources/firstapp_root.fml ...           << Основной файл описания графического окна
Processing applets/firstapp/resources/firstapp_resource.fml ...       << Основной файл описания ресурсов приложения
Processing applets/firstapp/install.sh ...                            << Скрипт для установки пользовательского приложения
Processing applets/firstapp/firstapp_install.bgs ...                  << Скрипт для генерации бинарных ресурсных файлов
Processing applets/firstapp/firstapp.install ...                      << Файл параметров для установки пользовательского приложения
Processing applets/firstapp/build.sh ...                              << Скрипт для простройки пользовательского приложения

	Hints:
	1. In order to build and install new application run the applets/firstapp/build.sh script. Also read appropriate install hint at first time.
	2. After successful installation you can see application icon in framework window: Apps -> Common and launch  application.
	3. You can edit the applets/firstapp/firstapp.install file to modify application parameters.
	4. After any appication modifications you have to run applets/firstapp/build.sh script to apply changes.
	   Don't run appmake.sh script if you don't want to re-create application!
	5. If changes are performed in FML files only then run applets/firstapp/install.sh script. It will update all non-binary files (FML descriptions).
	6. Application can be permanently installed as system application using instuctions from Wiki.    << Используйте шаги из топика ниже

Если выбирается язык C++, то выводится дополнительный вопрос на тему стандарта:

...

Select application language (from: c c++) [c]): c++
Application Language: c++

Select language standard (c++17 c++2a c++20 c++23) [c++17]:
Language Standard: c++17

Enter application file name (Current firstapp.cpp(h)):
File Names: firstapp.cpp firstapp.h

...

Стандарт указывается в файле component.mk приложения и может быть изменен позднее. Расширение для C++ файлов (cpp) не может быть изменено без доработки билдовой процедуры. Файлы с другим расширением собираться не будут.

При выборе языка Python дальнейший вывод также отличается:

...

Select application language (from: c c++ python) [c]): python
Application Language: python

Enter application file name (Current firstapp.py):
File Names: firstapp.py

...

Построим C/C++ приложение (смотрите подсказки выше):

WS$ applets/firstapp/build.sh
Сб 19 июл 2025 11:02:27 MSK
WORKSPACE: /home/andrey/share/FRM/FRM-V4/argo-v4-03-04-22/WS
BUILD VARIANT: linux-x86_64-debug
DEFCOMPILER: (C by default)
TARGET: sdk
PROJECT_LIST: applets/firstapp
СС: Compile /home/andrey/share/FRM/FRM-V4/argo-v4-03-04-22/WS/build/linux/x86_64/sdk/debug/applets/firstapp/obj/so/firstapp.o ...
LD: Linking /home/andrey/share/FRM/FRM-V4/argo-v4-03-04-22/WS/build/linux/x86_64/sdk/debug/applets/firstapp/bin/firstapp.so (linux-debug) ...
СС: Compile /home/andrey/share/FRM/FRM-V4/argo-v4-03-04-22/WS/build/linux/x86_64/sdk/debug/applets/firstapp/obj/o/firstapp.o ...
LD: Linking /home/andrey/share/FRM/FRM-V4/argo-v4-03-04-22/WS/build/linux/x86_64/sdk/debug/applets/firstapp/bin/firstapp (linux-debug) ...
Done!!!
The FirstApp application has been installed into /home/andrey/share/FRM/FRM-V4/argo-v4-03-04-22/WS/rootfs/resources/argo/applets/userapp/FirstApp directory

Hint:
First time you need to install new application into system.
Command line to install into system using debug shell:
dbgshell> install -i install/firstapp.install -p /home/andrey/share/FRM/FRM-V4/argo-v4-03-04-22/WS/rootfs/resources/argo/applets/userapp -n FirstApp -c 0

Для постройки приложения на Python надо использовать скрипт install.sh во всех случаях (если мы его создали как приложение на Python):

WS$ applets/firstapp/install.sh
The FirstApp application has been installed into /home/andrey/share/FRM/FRM-V4/argo-v4-03-04-22/WS/rootfs/resources/argo/applets/userapp/FirstApp directory

Hint:
First time you need to install new application into system.
Command line to install into system using debug shell:
dbgshell> install -i install/firstapp.install -p /home/andrey/share/FRM/FRM-V4/argo-v4-03-04-22/WS/rootfs/resources/argo/applets/userapp -n FirstApp -c 0

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

Вторым вариантом это можно сделать через отладочный терминал (Debug Shell). Запустим его в другой консоли:

WS$ source configs/wssetup.sh
WS$ frmdbgterm
Mon 13 Jan 2025: 18:15:19
-------------------------------------------------------------
Welcome!
Copyright (C) 2026 Andrey Dedukhin (adedukhin@gmail.com)
Framework Debug Terminal v1.0.0
dbgterm>

Из основной консоли запустим фреймворк:

WS$ argo-sdk

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

dbgshell>
Framework Debug Shell Application v1.0.0
Press ENTER to continue

Тут есть баг терминала, курсор перескакивает на неожиданную позицию, он известен :) Нам надо запустить команду установки (она точно указана в скрипте постройки, оттуда и взята):

dbgshell> install -i install/firstapp.install -p /home/andrey/share/FRM/FRM-V4/argo-v4-03-04-22/WS/rootfs/resources/argo/applets/userapp -n FirstApp -c 0
install -i install/firstapp.install -p /home/andrey/share/FRM/FRM-V4/argo-v4-03-04-22/WS/rootfs/resources/argo/applets/userapp -n FirstApp -c 0: Application [FirstApp] successfully installed with 0x1001007 private ID
dbgshell>

Теперь мы можем запустить наше новое приложение из UI: Apps->Common->FirstApp. Результат запуска на картинке ниже:

Screenshot of the new created application.

Мы также можем запустить приложение через отладочный терминал:

dbgshell> pid -i
  Private ID    Flags   Application

  0x1001000     NFCR    applets_1.editor hello.txt
  0x1001001     NBCR    applets_1.CalcApp Calculator Application
  0x1001002     NFCR    applets_2.TestApp
  0x1001003     NFCR    applets_2.TestAppPy python testapp_py
  0x1001004     NFCR    applets_2.TestAppCpp
  0x1001005     RBCR    system.DebugShell
  0x1001006     RFCS    system.SysAlert
  0x1001007     RFCD    system.FileView
  0x1001008     RBCD    system.FSMonitor
  0x1001009     RFCR    system.IdleScreen
  0x100100A     NFCR    system.Settings
  0x100100B     NFCR    system.Installer python installer
  0x100100C     NFUR    applets_1.FirstApp
dbgshell> runapp -p 0x100100C
runapp -p 0x100100C: Application 0x100100C successfully launched with 0x2001005 public ID
dbgshell>

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

ВАЖНО! Если вы сделали изменения в файлах приложения, не запускайте более скрипт appmake.sh с тем же именем, иначе изменения будут утеряны!

Скрипт appmake.sh формирует каркас на основе шаблонов в папке templates/application/[c|c++|python|common]/. Данные шаблоны можно изменять в соответствии с вашими желаниями. Можно изменять как непосредственно в рабочей директории (только позаботьтесь о сохранении обновленных шаблонов), так в папке SDK, на отдельном бранче (argo-sdk/templates/application/[c|c++|python|common]/).

Для приложений Python API фреймворка реализуется подключением (импортом) модулей frmapi.py, frmdef.py и frmstruct.py (и других, которые появятся) которые, лежат в папке argo-sdk/target/python/ SDK. Данные файлы копируются в процессе установки приложения в папку, где приложение установлено (rootfs/resources/argo/applets/userapp/FirstApp/python/). На данный момент не весь API фреймворка реализован для Python.

Регистрация Системного Приложения

ВАЖНО! Инструкции ниже соответствуют варианту, когда каркас приложения сделан скриптом appmake.sh. Если каркас сделан вручную, то указанные шаги могут отличаться.

Удаление ненужных файлов

Если каркас приложения создан скриптом appmake.sh, то надо удалить файлы, ненужные для системного приложения, если вы не планируете потом его вернуть в пользователький режим. Пользовательское приложение не может быть статическим, поэтому, если планируется только отладить приложение в статическом режиме, его все равно придется сделать системным. Для этого нужно перейти в папку приложения (applets/firstapp) и выполнить команду ниже (firstapp.install можно пока оставить, будет полезен позднее, но потом все равно надо удалить):

WS$ rm -rf build.sh install.sh Makefile firstapp.install

Если приложение установлено по инструкции выше, то его надо удалить используя приложение-установщик или через отладочный терминал:

dbgshell> uninstall -p 0x100100C

Включение в билдовую процедуру

Включение в билдовую процедуру требуется только для C/C++ приложений. Для приложений на Python данные шаги не требуются.

Зарегистрировать приложение в configs/projects.mk файле. Например, надо добавить строку подобную этой:
PROJECT_LIST-y += applets/firstapp
Если суффикс переменной PROJECT_LIST не ‘y’, то приложение в билд включено не будет.
Почистить прежние билдовые артефакты:
WS$ make clean
Запустить билд и убедиться, что приложение построено (можно увидеть в логе билда). Можно также найти бинарные файлы в билдовой папке, например в build/linux/x86_64/sdk/debug/install/applets/firstapp/. Если каркас приложения сделан скриптом appmake.sh, то приложение собирается только в remote и dynamic вариантах. Чтобы сделать static приложение, надо поправить component.mk файл и, кроме того, добавить его в component.mk системы. Как это сделать будет рассказано в другом топике.

Перенос построенных файлов на файловую систему таргета

Файлы приложения надо перенести на файловую систему таргета. Для пользовательского приложения это делают скрипты build.sh и install.sh. Для системного приложения надо поправить скрипт configs/install.bgs для переноса файлов прямо в процессе билда. В корне нашего приложения находится файл firstapp_install.bgs, по сути скрипт для генерации бинарных файлов и установки нашего приложения. Вызов этого файла надо добавить в корневой скрипт:

# Install first application
printmsg "Install first application ..."
shell frmbingen $WORKSPACE/applets/firstapp/firstapp_install.bgs

Для системного приложения скрипт, возможно, потребуется поправить для размещения в правильной директории (иначе оно так и будет установлено в папку resources/argo/applets/userapp/FirstApp). Для приложений на языке Python надо сделать то же самое, но содержимое файла несколько другое. Подробнее об этом скрипте рассказано в разделе Структура Приложений.

Файл надо править аккуратно, пути зависят от конфигурации системного FML файла (в данном случае resources/argo/system/argo_system.fml). Если пути для установки в component.mk файле приложения другие (INSTALL_PATH), то их тоже надо приводить в соответствие. После успешного запуска билда можно будет увидеть скопировнные файлы на таргете в папке по пути в переменной FIRSTAPP скрипта (на таргете! - rootfs/resources/argo/applets/system/FirstApp/). Если пути не верны, то билд закончится ошибкой.

Пользуясь случаем, хочу дать краткое пояснение, как фреймворк работает с приложениями на Python. Фреймворку для запуска приложения всегда нужен исполняемый файл. В случае приложения на Python такого файла нет, поэтому данный скрипт создает линк testapp_py на исполняемый файл $FRMSDK_HOME_DIR/usr/bin/pyrunner. Это специальное приложение, которое выполняет роль интерфейса между фреймворком и модулями Python. Его не надо устанавливать, достаточно того, что оно есть среди исполняемых файлов. Это приложение требует некоторую командную строку, которая задается в install файлах пользовательских приложений или в корневом конфигурационном файле для приложений системных (см. следующий пункт).

Установка приложения в систему

Установка выполняется модификацией файла resources/argo/system/argo_system.fml:

Устанавливать мы будем в секцию system, как у нас указано в переменной FIRSTAPP в пункте выше (секция system определена в файле тегом <appinfo id="system" title="System" icon="$SYSONLY.$SYSTEM_APPS_ID">)
Внутри секции делаем следующую запись (в самый конец секции, порядок влияет на порядок иконок). Параметры взяты из firstapp.install файла:
<applet appname="FirstApp" appmain="FirstApp" privilege="0x0" src="firstapp_root.fml" exe="firstapp" dll="firstapp.so"/>\
Далее перестраиваем систему и запускаем фреймворк. После запуска идем в приложения: Apps -> System и видим там наше приложение.
Если запущен отладочный терминал (dbgshell), то можно увидеть параметры приложения используя команду pid:

dbgshell> pid
  Public ID     Flags   Application

  0x2001001     AFSS    SysAlert
  0x2001000     ABSR    DebugShell
  0x2001004     AFCR    IdleScreen
  0x2001003     ABCD    USB Mon
  0x2001002     AFSD    FileView
  ...
  0x2001005     AFCR    FirstApp

Видно, что приложение запущено как системное в режиме remote (флаги AFCR). Чтобы запустить в режиме dynamic надо из инсталляционной записи убрать атрибут exe=“firstapp”, тогда приложение запустится в dynamic режиме (флаги AFCD).

Для приложений на языке Python требуется несколько иная строка в конфигурационном файле (на примере приложения applets/testapp_py):

<applet appname="TestAppPy" privilege="0x0" cmd="python testapp_py" src="testapp_py_root.fml" exe="testapp_py"/>

Тут есть два важных момента:

Во-первых, обязательная командная строка - cmd="python testapp_py". Эта строка передает папку, где находятся модули Python приложения (python) и имя модуля приложения (testapp_py). Могут быть и другие параметры для приложения, но эти обязательны (они могут быть взяты из install файла приложения, если оно создано, используя appmake.sh). Есть и другие правила формирования командной строки, но здесь я о них рассказывать не буду.
Во-вторых, надо указывать имя исполняемого файла - exe="testapp_py. Как говорилось выше, это линк на исполняемый файл $FRMSDK_HOME_DIR/usr/bin/pyrunner. Он абсолютно обязателен, иначе фреймворк не сможет запустить оболочку Python.

PS: Имя testapp_py задается при создании приложения в качестве параметра в скрипте appmake.sh.

Заключение

Приложение установлено и готово к дальнейшей работе с ним. Однако данная статья описывает только базовые необходимые шаги.
Для удобства отладки приложение лучше строить и интегрировать его как статическое, это будет описано в следующем параграфе.
Целесообразно изучить команды frmbingen утилиты для лучшего понимания команд bgs скриптов (frmbingen help [setvar|script]).
Также полезно изучить возможности отладочного терминала. В запущенном терминале, соединенном с фреймворком, по кнопке F4 выводится список команд, Далее можно смотреть справку по нужной команде, например справка по команде pid:
dbgshell> pid -h
Детальных инструкций, как использовать параметры FML файлов, пока нет, так что ориентируемся на примеры.

Делаем Статическое Приложение

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

Итак, как это сделать:

Сборка статической библиотеки приложения

В файле applets/firstapp/component.mk присутствует следующий код. Он определяет варианты сборки приложения, в данном случае исполняемый файл (remote вариант) и динамическую библиотеку (dynamic вариант).

# Component type
EXECUTABLE = y
SHARED_LIB = n
STATIC_LIB = n
SHARED_STATIC_LIB = n
SHARED_DLL = y

Для сборки статического варианта надо изменить значение переменной STATIC_LIB: STATIC_LIB = y
После изменений запускаем билд и можем убедиться, что статическая библиотека построена (libfirstapp.a). Ее можно найти в папке build:

WS$ find build -name libfirstapp.a
build/linux/x86_64/sdk/debug/applets/firstapp/bin/libfirstapp.a
build/linux/x86_64/sdk/debug/install/applets/firstapp/libfirstapp.a

Линковка библиотеки приложения с фреймворком

Для этого необходимо изменить мейкфайл системы, чтобы слинковать приложение с фреймворком (system/argo/component.mk). Надо в секцию приложений добавить строчку подключения библиотеки:

# Applications
ARCHIVES += :libsysalert.a
ARCHIVES += :libeditor.a
ARCHIVES += :libfileview.a
ARCHIVES += :libidlescr.a
ARCHIVES += :libsettings.a
ARCHIVES += :libfirstapp.a

Использование переменной STATIC_LIBS тоже возможно, но для этого надо будет править дополнительные файлы, поэтому добавляем через переменную ARCHIVES. Разница в том, что переменная ARCHIVES линкует архив целиком, как есть, в то время как STATIC_LIBS выполняет обычную статическую линковку. В этом случае корневая функция приложения не будет найдена, и надо делать дополнительные изменения, чтобы это исправить.
Но это еще не все. Надо выставить зависимость, чтобы библиотека строилась до того, как будет линковаться система. В мейкфайле есть переменная DEP_LIST с длинной строкой подключенных проектов. В эту строку надо добавить и проект приложения, в нашем случае applets/firstapp, тогда он будет строиться до сборки системы. Строку здесь переносить категорически нельзя!
Запускаем билд, желательно сделать make clean вначале, если все правльно, то билд пройдет без ошибок.

Запуск статического приложения

Приложение готово к запуску в статическом режиме, но, если попробовать запустить через интерфейс, то оно все равно запустится в динамическом или remote режиме, поскольку это прописано в системном FML файле (resources/argo/system/argo_system.fml). Самый простой вариант - это убрать атрибуты exe=“firstapp” и dll=“firstapp.so” из записи, и этот вариант полезен на этапе отладки. После этого приложение запустится в статическом режиме, можно в этом убедиться через отладочный терминал, как говорилось выше (флаги AFCS).
В случае если это не удобно, то можно воспользоваться отладочным терминалом для запуска приложения.

  dbgshell> pid -i                              << Найти приватный идентификатор приложения
  ...
  0x1001005     RFCR    system.IdleScreen
  0x1001006     NFCR    system.Settings
  0x1001007     RFCR    system.FirstApp         << Вот он

  dbgshell> runapp -p 0x1001007 -s              << Запустить приложение
  runapp -p 0x1001007 -s: Application 0x1001007 successfully launched with 0x2001006 public ID
  dbgshell> pid                                 << Убедиться, что приложение запущено в нужном режиме
  Public ID     Flags   Application

  0x2001001     AFSS    SysAlert
  0x2001003     ABCD    USB Mon
  0x2001002     AFSD    FileView
  0x2001000     ABSR    DebugShell
  0x2001004     AFCR    IdleScreen
  0x2001005     AFCR    FirstApp
  0x2001006     AFCS    FirstApp

Тут запущено даже два экземпляра приложения, первый я запустил через интерфейс. Подробнее о режимах запуска можно узнать из справки отладочного терминала:
dbgshell> runapp -h
Закрыть их можно также через интерфейс или через отладочный терминал, используя команду closeapp (см. справку).

Пожалуй на эту тему все.