Utilities.md

---

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

Содержание

• Введение
• Установка Фреймворка
• Приложения Фреймворка
• Создание Приложений
• Примеры Приложений
• Структура Приложений
• Структура Управляющих Элементов
• Утилиты Фреймворка *
  • Генератор Бинарных Файлов
  • Отладочный Терминал

Утилиты Фреймворка

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

Генератор Бинарных Файлов

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

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

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

$ frmbingen <environment options> <script name> | <command>

Опции окружения фреймворка (environment options) задают параметры окружения для работы скрипта или команды. Информацию по этим опциям можно получить следующей командой:

$ frmbingen help sysenv

Скрипты бинарного генератора будут подробно рассмотрены позже. Также информацию по скриптам можно получить командой:

$ frmbingen help script

Как говорилось выше, пока есть только три доступные команды:

Первая команда для сборки шрифтов (frmbingen font) предназначена для сборки шрифта из FML описания и (опционально) из подготовленного растра в виде изображения в формате BMP. Это команда была сделана давно и широко использовалась до октября 2025г. С ее помощью создавались все шрифты до этого октябрьского релиза. Подготавливать описания для нее и растровое изображение для символов - весьма долгая и нудная задача, что ограничивало набор шрифтов, и полученные шрифты были, скажем так, не лучшего качества. Но тем не менее эта команда необходима для сборки кастомизованных шрифтов и по прежнему необходима.

Вторая команда (frmbingen ttf) предназначена для сборки шрифтов фреймворка из векторных TrueType шрифтов, которые используются везде (шрифты фреймворка растровые). Это мощная команда, которая парсит TTF шрифт и генерирует из полученных данных шрифт фреймворка с заданными параметрами (высота, набор символов). Также есть некоторые возможности для отладки шрифтов. С октября 2025г все шрифты постепенно переводятся на новые, поскольку они обеспечивают более высокое качество, разнообразие и поддержку языков.

Третья команда (frmbingen resgen) предназначена для сборки бинарных файлов ресурсов, системы, приложений, управляющих элементов из соответствующих FML описаний. Загрузка системы с использованием бинарных файлов в десятки раз быстрее, чем загрузка из FML файлов (от 25 до 40 раз!), и процедура сборки для всех бинарных файлов реализована.

Рассмотрим эти команды подробнее, хотя есть справки по каждой команде и скриптам:

Команда frmbingen font

Как уже говорилось, команда предназначена для сборки растровых шрифтов из FML описаний и растровых изображений. Однако есть ещё дополнительные возможности для экспорта шрифта обратно в FML описание и дампирование шрифта в растровое изображение в BMP формате. Эти опции позволяют поправить дефекты шрифта и визуализировать символы соответственно.

Общая структура команды представлена ниже:

$ frmbingen font [-h] -C|-E <fontname>|-D -i <input file> -o <output file> -b <1|2|4|8> [-n] [-v]

Основную операцию задают ключи -C, -E и -D. Это взаимоисключающие ключи, если используются совместно, то будет выдана ошибка. Опция -C (Create) создает новый шрифт, опция -E (export) формирует описание из существующего шрифта, опция -D (dump) дампирует все символы шрифта в растровое изображение. Опции -C и -D не требуют параметров, в то время как опция -E требует внутреннее имя шрифта для генерированного описания (это любое произвольное имя, оно используется как идентификатор в FML описании).

Опции -i и -o задают пути для входного и выходного файла соответственно (абсолютные или относительные - как удобно). Эти опции обязательны для всех команд, но тип передаваемого файла зависит от команды: для опции -C это должен быть файл описания, а для остальных - бинарный файл шрифта. Формат выходного файла разный для всех команд: бинарный файл шрифта при его создании, текстовый FML файл при экспорте и растровый BMP файл при дампе. Расширения для выходных файлов не учитываются и не меняются генератором, поэтому надо указывать то, которое будет удобно (font, fml или bmp соответственно).

Опция -b определяет сколько битов будет использовано при сохранении одного пиксела растра - 1, 2, 4 или 8 (Bit-per-pixel значение, BPP). Опция обязательна при создании шрифта или его экспорте. При дампировании всегда создается BMP файл с кодировкой 24-бита на пиксель. Данная опция позволяет изменить кодировку уже существующего шрифта, разумеется в сторону уменьшения, увеличение BPP не даст ничего кроме увеличения размеров шрифта. Уменьшение BPP позволяет уменьшить размер шрифта при сохранении качества (например конвертирование 8-и битового шрифта в 4-х битовый формат мало скажется на качестве, а размер шрифта уменьшится вдвое).

Примечание: Значение пиксела определяет его прозрачность - нулевое значение определяет полностью прозрачный пиксел в растре, цвет будет определятся только фоном подложки; максимальное значение для кодировки (1, 3, 63, 255 соответсвенно) определяют полностью непрозрачный пиксел и цвет определяется только цветом шрифта; все промежуточные значения преобразуются в полупрозрачные пиксели и цвет определяется смешением цветов фона и шрифта в соответствии со значением пиксела в шрифте.

Опция -n управляет режимом сборки бинарного файла. Бинарные файлы фреймворка могут быть сериализованными (упакованными) или не сериализованными. Сериализованные бинарные файлы более компактны и могут использоваться равно на системах с разной разрядностью и эндианностью. То есть файл, собранный на системе 64-бита little endian, может быть использован на устройстве 32-бита big endian и наоборот. Не сериализованные бинарные файлы могут быть использованы только на системе с такой-же разрядностью и эндианностью и по размеру всегда чуть (или не чуть) больше. Единственным достоинством таких файлов является более быстрая загрузка, даже может быть существенно более быстрая. Фреймворк, кстати, сам генерирует некоторые собственные бинарные файлы (например, записи инсталлированных приложений) и использует для этого не сериализованный формат. Однако по умолчанию генератор бинарных файлов всегда создает сериализованные файлы. Опция -n отменяет этот режим.

Опция -v определяет уровень подробностей в логе выполнения. В случае её отсутствия никакого вывода выполнятся не будет, если нет ошибок обработки.

Опция -h обеспечивает вывод справочной информации, и на этом команда прекращает работу. Эта опция так же работает и во всех остальных командах. Можно использовать два формата для вывода справки:

$ frmbingen help font

Или

$ frmbingen font -h

Ниже приведены примеры использования команды:

$ frmbingen font -C -i font_description.fml -o font_binary.font -b 8                      << Создание нового шрифта
$ frmbingen font -E four_bit_font -i font_binary.font -o font_description_4bpp.fml -b 4   << Экспорт созданного шрифта в 4-х битовое описание
$ frmbingen font -D -i font_binary.font -o font_dump.bmp                                  << Дамп шрифта в изображение в BMP формате

Примеры описаний шрифтов можно найти в папке resources/argo/system/fs0/sysres/fonts/ (fml файлы).

Команда frmbingen ttf

Команда используется для сборки шрифта из TrueType шрифтов (ttf шрифты, otf пока не поддерживаются). Команда парсит исходный шрифт, создает внутреннюю таблицу символов и выполняет растеризацию каждого символа в соответствии с желаемой высотой шрифта. TTF шрифты обычно содержат ряд вариантов шрифта в отдельных файлах - Regular, Bold, Italic и BoldItalic (есть и другие варианты). Сами TTF шрифты в данный репозиторий выкладыватся не будут, поскольку многие находятся под лицензиями, не допускающими свободного распостранения. В репозитории будут только готовые шрифты и спецификации шрифтов. В дальнейшем планируется выгрузка символьной таблицы в бинарный файлы и вот они могут быть размещены в репозитории.

Общая структура команды представлена ниже:

$ frmbingen ttf [-h] -f <ttf font file> -o <output file> -s <spec file> [-v|-n|-H|-S|-Q|-R|-D|-N|-U <param>]

Параметры -f, -o и -s являются обязательными, а все остальные опциональные. Параметр -f определяет путь до оригинального TrueType шрифта для последующего парсинга. Параметр -o определяет путь до выходного файла шрифта. Параметр -s определяет путь до специального файла спецификации шрифта (fspc файлы). Файл спецификации крайне важен, поскольку он определяет набор символов, которые будут добавлены в шрифт. Также он определяет дополнительные параметры, необходимые для растеризации символов и отладки генерируемых шрифтов. Все дополнительные параметры могут быть переопределены через опции команды. Набор символов в шрифте можно определить только в файле, поэтому он обязателен. Ниже приведен пример файла спецификации (resources/argo/system/fs0/sysres/fonts/arial/arial.fspc):

# Arial fonts family specification file

height   : 14
scale    : 15
quality  : 8

dumppath : resbuild/dump
fontname : Arial

# Latin
range    : "0x20-0xFF"

# Cyrillic (Russian)
range    : "0x0410-0x044F"
range    : "0x0401"  # Russian Ё
range    : "0x0451"  # Russian ё

# Cyrillic (Belorussian)
range    : "0x0406"  # Belorussian І
range    : "0x0456"  # Belorussian і
range    : "0x040E"  # Belorussian Ў
range    : "0x045E"  # Belorussian ў

# Special symbols
range    : "0x2116"  # Numero sign №
range    : "0x2014"  # EM Dash —

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

$ frmbingen help fspc

Символ решетки ‘#’ используется для комментариев, все что добавлено после этого символа не обрабатывается.

ВАЖНО! Кодировка файла спецификации должна быть ASCII/UTF-8. Наличие или отсутствие byte order mark (BOM) не критично. В случае других кодировок будет выдана ошибка.

Для указания символов в шрифте используется ключи ‘range’ и ‘urange’. Ключ ‘range’ задает диапазон символов в unicode, которые будут добавлены в шрифт. Ключ ‘urange’ задает текстовое имя диапазона символов (например urange : Cyrillic). Список имен диапазонов можно найти в файле public/inc/frm_utf16.h. Если имя диапазона содержит пробелы, то его надо заключить в двойные кавычки (это касается всех ключей, если пробелов нет, то кавычки не обязательны). Ключ ‘range’ может содержать и одиночный символ как показано выше. В случае задания диапазона символ ‘-’ (дефис) обязателен, добавляются все символы в указанном диапазоне, если они есть в исходном шрифте. Если символа нет, но он, разумеется, добавлен не будет, и также не будет ни ошибки, ни предупреждения на эту тему. Это правило касается и остальных диапазонных ключей. Диапазоны могут пересекаться между собой, но дублирующие символы будут отброшены. Как минимум, один диапазон должен быть определен в файле спецификации.

Второй очень важный параметр - это высота шрифта в пикселах, задаваемая ключом ‘height’. Он определяет высоту шрифта по умолчанию. Значение по умолчанию уже определено генератором, но высота шрифта в 3 пиксела едва ли понравится. На практике высота шрифта почти всегда задается параметром -H команды, но если параметр не задан, то будет использовано значение по умолчанию. Высоту шрифта нельзя задать меньше 3-х и больше 255 пикселов. В первом случае значение будет увеличено до 3-х, а во втором случае - результат непредсказуем, проверки там нет (это не баг, это сделано “на вырост”). Шрифты фреймворка не поддерживают высоту символа больше 255-и, но на растеризацию есть дополнительные перспективы.

Ключ ‘scale’ определяет коэффициент масштабирования при растеризации. В процессе растеризации символ отрисовывается в специальном битмапе, высота и ширина которого зависят от произведения высоты в пикселах и данного коэффициента. Он задает сетку масштабирования, и чем он больше, тем качественне полутона символа. Однако он сильно влияет на скорость растеризации в сторону увеличения (скорость растеризации увеличивается в квадратичной пропорции), при этом не давая выигрыша в качестве. Слишком маленькие значения приведут к плохому качеству символов и, возможно, сбою растеризатора на некоторых сложных символах. Статистика по значению этого параметра пока не наработана, и текущее значение (15) выглядит близко к оптимальному по скорости и качеству символов для малых шрифтов (8 - 14 пикселов). Для более крупных шрифтов параметр может быть безболезненно уменьшен до 5 - 10. Очень рекомендуется указывать этот параметр всегда, поскольку значение по умолчанию неприемлемо (1). Так же он может быть переопределен параметром команды -S.

Ключ ‘quality’ определяет гладкость контуров символа, но на малых шрифтах значение по умолчанию (8) вполне подходит. Дело в том, что в TrueType шрифтах элементы контура задаются кривыми Безье и содержат обычно 3 точки (две опорные и одна curve точка, точка изгиба). Использование этого параметра позволяет увеличить количество промежуточных точек, но на малых шрифтах это не заметно совсем. На крупных шрифтах (> 20) это может привести к ломаным линиям на сложных символах, поэтому необходимо это значение увеличивать. Это можно сделать либо в спецификации, либо в в команде, используя параметр -Q. Значения этого параметра находятся в диапазоне от 8-и до 128-и. Избыточное значение этого параметра несколько замедляет растеризацию на сложных символах, но не так критично как коэффициент масштабирования.

Остальные ключи менее важные и поэтому будут рассмотрены кратко.

Ключ ‘dumppath’ определяет путь, где будут создаваться изображения символов в случае сбоя растеризатора или символ отмечен для дампирования ключом ‘dump’. Путь должен существовать, иначе изображение будет создано в рабочей директории (файлы symbol_<utf16 code>.bmp) и выведется предупреждение об этом. Рекомендуется этот путь установить и создать, если его нет. Установка этого пути также может быть сделана с помощью опции -D команды.

Ключ ‘fontname’ практически не нужен, это тоже на будущее расширение. Значение может быть переопределено опцией -N. По умолчанию значение будет ‘experimental’.

Важный ключ ‘refsymb’ определяет опорный символ для определения коэффициета высоты шрифта. Коэффициент высоты не совпадает с высотой шрифта в пикселах и определяется как делимое высоты в пикселах (height) на высоту опорного символа (всегда < 1.0). Передача опорного символа обеспечивает точное вычисление коэффициента, который и нужен для вычисления координат символа. По умолчанию всегда берется заглавная латинская ‘A’, но и она может отсутствовать в шрифте, а без опорного символа шрифт не соберется. Опорным символом может служить любая заглавная буква или цифра, которые не содержат дополнительных элементов как буквы Й или Ё и не содержат элементов ниже горизонта как буквы Ц или Щ. Опорный символ может быть определен параметром -U команды. Значение параметра должно быть unicode кодом нужного символа.

Ключ ‘coeff’ определяет коэффициент высоты и переопределяет высоту шрифта в пикселах, если определена. Коэффициент считается как делимое высоты в пикселах на высоту опорного символа. Значение параметра - это число с плавающей точкой. Этот параметр обычно не применяется, но может потребоваться в каких-то исключительных случаях. Коэффициент может быть переопределен параметром -C команды.

Ключ ‘rbsize’ определяет размер внутреннего буфера растеризатора. Менять его строго не рекомендуется. Его значение по умолчанию (1000) может быть оптимизировано в дальнейшем. Размер буфера может быть переопределен параметром -R команды.

Ключ ‘dump’ маркирует символы для дампирования. Это диапазонный ключ, как и ‘range’, поэтому все правила, указанные выше, применимы и к нему. Маркированные этим ключом символы будут дампироваться в изображение. Кроме того, в лог будет выведена информация по символу, независимо от уровня подробностей (verbose level). Этот ключ очень полезен при отладке шрифта в случаях сбоя растеризатора. Символы для дампирования могут быть определены только в файле спецификации.

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

Из параметров команды не рассмотрены остались опции -h, -v и -n. Эти опции работают точно так же, как и для предыдущей команды (-h - справка, -v - уровень подробностей и -n - создание не сериализованного бинарного файла). Маленькое уточнение лишь по опции -v. При ее отсутствии будет выводится прогресс обработки символов в одной строке. Шрифт с большим количеством символов создается относительно долго (от нескольких секунд), и хочется видеть прогресс. Значение 1 позволяет выводить прогресс построчно с указанием кода символа и собственно символа. Значения 2 и 3 позволяют вывести параметры исходного шрифта и заданные в команде параметры. Значение опции больше 3-х не даст уже никакого дополнительного эффекта. Информация по отдельным символам выводится, только если символы промаркированы ключом ‘dump’.

Можно использовать два формата для вывода справки:

$ frmbingen help ttf

Или

$ frmbingen ttf -h

Ниже приведен пример использования команды:

$ frmbingen ttf -f LiberationSerif-Regular.ttf -o experimental.font -s experimental.fspc -H 30     << Создание нового шрифта LiberationSerif-Regular с высотой 30 пикселов

Команда frmbingen resgen

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

Общая структура команды представлена ниже:

$ frmbingen resgen [-h] -R|-C|-S|-A [-e] [-n] -i <input file> [-s <source path>] -o <output path> [-f <output file>] [-t <param>] [-v]

Опции -R, -C, -S и -A предназначены для выбора операционного режима, т.е. какой бинарный файл надо сделать. Опции взаимно исключающие, указание двух и более опций вызовет ошибку. Опция -R определяет сборку бинарных файлов ресурсов, опция -C - сборку бинарных файлов управляющих элементов, опции -A и -S - сборку бинарных файлов корневых описаний приложений и системы соответственно.

Обязательная опция для всех режимов ‘-i’ определяет полный или относительный путь до FML файла описания ресурсов. Описание должно соответствовать операционному режиму сборки. В общем случае допускается как относительный, так и абсолютный путь. Но для опции -S есть исключение - там допускается только имя файла (argo_system.fml, например), указание с путем работать не будет. Также, для опции -A тоже может использоваться только имя файла если определена опция ‘-s’.

Опция ‘-s’ определяет путь до каталога ресурсов, откуда они могут быть взяты по относительному пути в FML описании ресурсов. Обычно путь совпадает с путем, где лежит исходный файл описаний. Опция обязательна для сборки бинарных файлов ресурсов (даже для строковых ресурсов и сборки с опцией -e) и системы. В последнем случае должен быть указан путь до FML описания системы (например resources/argo/system/). Опция обязательна для сборки корневого файла системы (опция -S), поскольку задает путь до этого файла (особенность API). Также опция может использоваться для сборки корневого файла приложения (опция -A). В случае если файл использует ноды ‘instance’, где указыватся относительные пути до вложенных файлов, этот вариант обязателен.

Опция ‘-o’ определяет путь для собранного файла, опция не обязательна, если определен путь до каталога ресурсов заданный опцией ‘-s’.

Имя собранного файла определяется опцией ‘-f’, но это необязательный параметр, поскольку имя файла может быть взято из файла описания. Если его нужно указать, то без расширения, генератор сам подставит необходимое, исходя из типа файлов (для ресурсных файлов это fbin или fbine, для управляющих виджетов - ctrl, ainf и sinf - для корневых описаний приложения и системы соответственно). Расширение файлов практически ничего не значит для фреймворка, он всегда сам определяет тип файлов.

Опция ‘-e’ крайне важна для генерации бинарных файлов ресурсов, для остальных вариантов опция безразлична. По умолчанию генератор создает файлы с content секцией, куда собирается содержимое всех файлов ресурсов кроме строковых и DLL ресурсов. Данные в этой секции располагаются как есть, все прочитанное из файла с путем ‘src’ в описании. Важно то, что при подгрузке ресурсного файла подгружается весь файл, в том числе, и с content секцией (ранее был вариант подгрузки без нее, но в силу бесполезности был убран). В результате, если не управлять подрузкой бинарных файлов извне, то в оперативной памяти будет куча бесполезной информации, которая используется редко и будет лежать мертвым грузом. Например, если собрать window_default.fbin из старой версии без этой опции, то размер ресурсного файла составит около 2.5 мегабайта. Это вообще-то много, поскольку эти ресурсы будут находится в памяти вечно. Львиную долю добавили файлы шрифтов, которые тяжелы, и далеко не все используются. После их выноса в отдельный ресурсный файл (window_default_ext.fml), и сборки его с опцией ‘-e’ получилось следующее: файл window_default.fbin стал 136 килобайт, а файл window_default_ext.fbine - всего около 5 килобайт. Разумеется, необходимые файлы шрифтов тоже подгрузились - но уже не вечно, а пока используются.

Вывод прост: опция ‘-e’ убирает секцию content, и ресурсы подгружаются из оригинальных файлов, в файле остаются только метаданные для ресурсов (пути и типы ресурсов) и строковые ресурсы. Если файл тяжелый и/или используется редко, то его целесообразно поместить в отдельный ресурсный файл, и собирать бинарный файл с этой опцией. Так и сделано сейчас во фреймворке - тяжелые шрифты перенесены в файл window_default_ext.fml, который так и собирается. Шрифты тоже присутствуют на файловой системе, но в оперативной памяти ненужных шрифтов нет. DLL ресурсы никогда не входят в секцию content, независимо от этой опции, в ресурсном файле сохраняются только метаданные. Легкие ресурсы нужно оставлять в бинарном файле, который собирается без этой опции, с секцией content, откуда они могут браться без дополнительных операций с файлами.

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

Опция ‘-n’ действует точно так же, как и в случае сборки шрифтов, делает не сериализованный файл.

Опция ‘-t’ предназначена для самотестирования файла. Значение параметра 0 вызовет загрузку сгенерированного файла и вывод некоторых параметров. Для ресурсных бинарных файлов это будет выглядеть так:

$ frmbingen resgen -R -i build/resources/argo/system/fs0/sysres/window_default.fml -s build/resources/argo/system/fs0/sysres/ -o build/resources/argo/system/fs0/sysres -t 0
INFO: Binary file name: build/resources/argo/system/fs0/sysres/window_default.fbin
INFO: Binary file size: 143920
INFO: Table type: 4
INFO: Items number: 53

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

$ frmbingen resgen -R -i build/resources/argo/system/fs0/sysres/window_default.fml -s build/resources/argo/system/fs0/sysres/ -o resbuild/resources/argo/system/fs0/sysres/ -t 1
INFO: Resource ID:   0
INFO: Resource Type: 4
INFO: Resource Name: WIN_BORDER_BLUE_ID
INFO: Resource Path: BM�) (0x7f8f217c6690)   << Здесь не крякозябры, а начало BMP файла по указанному адресу
INFO: String Value:  (null) ((nil))
INFO: Resource Size: 10704
$ frmbingen resgen -R -i build/resources/argo/system/fs0/sysres/window_default.fml -s build/resources/argo/system/fs0/sysres/ -o resbuild/resources/argo/system/fs0/sysres/ -t 53
INFO: Resource ID:   52
INFO: Resource Type: 3
INFO: Resource Name: TENTRY_DEFTEXT_RU_ID
INFO: Resource Path: (null) ((nil))
INFO: String Value:  Введите текст (0x7fc5ccaff670)
INFO: Resource Size: 0

Для других команд значение параметра безразлично, всегда выведется дамп аналогичный опции ‘-t 0’.

Опции ‘-h’ и ‘-v’ работают также как и для других команд.

Можно использовать два формата для вывода справки:

$ frmbingen help resgen

Или

$ frmbingen resgen -h

Скрипты бинарного генератора

Скрипты бинарного генератора представляют собой последовательный набор инструкций по выполнению заданной операции, какие-либо циклы или ветвления в нем не предусмотрены. Каждая команда предваряется некоторым ключевым словом. Команды генератора, такие как ‘font’ или ‘ttf’, являются такими ключевыми словами. Соответственно команды, рассмотренные выше, могут так же и использоваться (без имени самого генератора).

Скрипты поддерживают следующие операции:

• Все команды бинарного генератора, подобные ‘ttf’, ‘font’ и ‘resgen’, могут быть вызваны в файле скрипта.
• Процессор скриптов создает внутренний список переменных, который сразу содержит некоторые переменные со значением по умолчанию. Пользователь может добавить собственные переменные, используя команду ‘setvar’, и использовать их в последующих командах.
• Процессор скриптов позволяет использовать переменные окружения системы непосредственно в любой команде.
• Команды оболочки подобные ‘cp’, ‘mkdir’, ‘chmod’ и другие могут быть использованы в скрипте с помощью команды ‘shell’. Могут быть вызваны и другие shell скрипты или скрипты бинарного генератора.
• Пользовательские сообщения могут выводится в лог с помощью команды ‘printmsg’.
• Целая строка или часть строки может быть закомментирована, используя символ решетки ‘#’.
• Некоторые дополнительные опции могут быть переданы в скрипт процессор (для увеличения уровня подробностей, например).

ВАЖНО! Кодировка файла скрипта должна быть ASCII/UTF-8. Наличие или отсутствие byte order mark (BOM) не критично. В случае других кодировок будет выдана ошибка.

Ниже приведен пример скрипта:

# Variables declarations
setvar BUILDDIR     $FRMBUILD_HOME_DIR/resbuild
setvar FONTSDIR     @BUILDDIR/resources/argo/system/fs0/sysres/fonts
setvar TTFDIR       $FRMBUILD_HOME_DIR/third_party/fonts
setvar SYSRESDIR    $FRMBUILD_HOME_DIR/resources/argo/system/fs0/sysres

# Create directory structure
printmsg "Create directory structure ..."
shell mkdir -p @BUILDDIR
shell mkdir -p @BUILDDIR/resources
shell mkdir -p @BUILDDIR/resources/argo
shell mkdir -p @BUILDDIR/resources/argo/system
shell mkdir -p @BUILDDIR/resources/argo/system/fs0
shell mkdir -p @BUILDDIR/resources/argo/system/fs0/sysres
shell mkdir -p @BUILDDIR/resources/argo/system/fs0/sysres/fonts
shell mkdir -p @BUILDDIR/dump

# Create Arial family fonts
shell mkdir -p @FONTSDIR/arial
printmsg "The Arial-Regular.ttf 10 font processing ..."
ttf -f @TTFDIR/Arial-Regular.ttf -o @FONTSDIR/arial/arial_r_10.font -s @SYSRESDIR/fonts/arial/arial.fspc -H 10 # -v
printmsg "The Arial-Regular.ttf 12 font processing ..."
ttf -f @TTFDIR/Arial-Regular.ttf -o @FONTSDIR/arial/arial_r_12.font -s @SYSRESDIR/fonts/arial/arial.fspc -H 12 # -v
printmsg "The Arial-Bold.ttf 10 font processing ..."
ttf -f @TTFDIR/Arial-Bold.ttf -o @FONTSDIR/arial/arial_b_10.font -s @SYSRESDIR/fonts/arial/arial.fspc -H 10 # -v
printmsg "The Arial-Bold.ttf 12 font processing ..."
ttf -f @TTFDIR/Arial-Bold.ttf -o @FONTSDIR/arial/arial_b_12.font -s @SYSRESDIR/fonts/arial/arial.fspc -H 12 # -v
printmsg "The Arial-Italic.ttf 10 font processing ..."
ttf -f @TTFDIR/Arial-Italic.ttf -o @FONTSDIR/arial/arial_i_10.font -s @SYSRESDIR/fonts/arial/arial.fspc -H 10 # -v
printmsg "The Arial-Italic.ttf 12 font processing ..."
ttf -f @TTFDIR/Arial-Italic.ttf -o @FONTSDIR/arial/arial_i_12.font -s @SYSRESDIR/fonts/arial/arial.fspc -H 12 # -v

# Copy generated files to target system
printmsg "Copy generated files to target system ..."
shell cp -rf @BUILDDIR/resources/* $FRMSDK_HOME_DIR/resources

printmsg "Done!!!"

На первых строках скрипта выполняется создание необходимых переменных с использованием команды ‘setvar’. Формат команды следующий:

setvar <variable_name> <variable_value>

В значениях переменных используется переменная окружения FRMBUILD_HOME_DIR, отмеченная символом доллара ‘$’. Это формат использования переменных окружения. Значения вновь созданные переменных берутся с использованием символа at ‘@’. Общие правила создания переменных:

• Дополнительные параметры в команде не допускаются (комментарии можно добавить).
• Если переменная используется в объявлении других переменных, она должна быть объявлена раньше.
• Существует некоторый набор предопределенных переменных (для справки см. frmbingen help sysenv). Переопределять их нельзя, но использовать их, как обычно, можно. Некоторые переменные могут отсутствовать и использоваться не могут. Для проверки их наличия и актуальных значений используется справочная команда выше.
• Если переменная окружения или скрипта отсутствует, при обработке дальнейших команд процессор выдаст ошибку.

Далее создается структура папок для хранения собранных файлов. Операции выполняются с помощью команды ‘shell’. Формат команды следующий:

shell <command> [parameters]

Также в данном блоке присутствует пользовательское сообщение, которое будет выведено в лог с переносом строки. Сообщение выводится командой ‘printmsg’. Формат команды:

printmsg [user message]

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

• Кавычки не обязательны, если сообщение не содержит пробелов (это всегда должны быть двойные кавычки).
• Сообщение должно быть в одной строке, символы переноса строки и табуляций допускаются (\n, \r, \t).
• Сообщение может отсутствовать, тогда вставится только перенос строки.
• Процессор игнорирует любую информацию после самого сообщения (поэтому и нужны кавычки). Форматированный вывод не предусмотрен.

В следующем блоке создается набор шрифтов с ипользованием команды ‘ttf’. Ничего нового тут уже нет, как и последнем блоке, где полученные шрифты просто копируются в папку таргета.

Для запуска скрипта никаких ключей не требуется, только имя скрипта (они обычно с расширением bgs, но расширения нигде не проверяются):

$ frmbingen <script_name> [options]

При запуске можно использовать некоторые дополнительные опции после имени скрипта:

• -h - вывод справки по скриптам (эквивалентно команде frmbingen help script). Скрипт при этом не обрабатывается.
• -v - установка уровня подробности в логе. Значение опции передается всем внутренним модулям генератора.
• -m - установка размера строкового буфера процессора. По умолчанию размер 256 байт. Этого обычно достаточно, чтобы считать команду из скрипта. Буфер будет увеличен согласно параметру, если его значение больше текущего размера буфера.

Отладочный терминал

Отладочный терминал (frmdbgterm) - это утилита для коммуникации с приложением-сервером, запущенным в контексте фреймворка (на данный момент - это только debug shell). Утилита отправляет команду, введенную в командной строке серверу, получает от него ответ и выводит полученную информацию в консоли. Также у теминала есть и собственные команды, которые он обрабатывает сам, без обращений к серверу. У терминала есть также некоторый набор параметров, которые управляют запуском терминала, все они опциональные и обычно не используются. Формат команды запуска терминала следующий:

$ frmdbgterm [-h] | [-b|-a|-p|-t|-r param] | [-l]

Вкратце рассмотрим эти опции:

• Опция -h, как и везде, выводит справку по командам терминала и доступным опциям. Запуск терминала при этом не выполняется.

• Опция -b определяет размер приемного буфера, в который поступает информация от сервера. По умолчанию размер буфера 4096 байт. Однако, размер по умолчанию и даже заданный с помощью этой опции может быть увеличен автоматически, если сервер запрашивает больше памяти для буфера (это происходит каждый раз когда терминал подключается к серверу). Реальный размер буфера можно посмотреть командой ‘info’ (горячая клавиша F2) в запущенном и подключенном к серверу терминале.

• Опции -a и -p определяют IP адрес и порт сервера для подключения соответственно. Адрес по умолчанию 127.0.0.1, порт 3001 (также можно посмотреть командой ‘info’).

• Опции -t и -r определяют таймауты соединения с сервером и ответа от сервера в миллисекундах. По умолчанию оба значения 1000 ms.

• Последняя опция -l является отладочной для терминала и в работе с фреймворком не используется. С этой опцией терминал запускается вместе со специальным loop back сервером для контроля пересылки сообщений.

После запуска терминал пытается соединится с сервером используя IP адрес и порт, но пока фреймворк не запущен, сервер не появится, соответственно и соединения не будет. Терминал продолжит пытаться соединится с интервалом равным таймауту соединения, но происходит это в фоновом режиме. Ниже представлен лог запуска и запущенной командой ‘help’ (горячая клавиша F1):

$ /home/andrey/frmsdk-linux/x86_64/usr/bin/frmdbgterm
Wed 22 Oct 2025: 13:18:27
-------------------------------------------------------------
Welcome!
Copyright (C) 2026 Andrey Dedukhin (adedukhin@gmail.com)
Framework Debug Terminal v1.0.0
dbgterm> help
Debug Terminal Usage:

Command line options:
  -h               - Print this message and exit
  -b <bufsize>     - Set receive buffer size in bytes
  -a <addr>        - Set server address (127.0.0.1 default)
  -p <port>        - Set server port (3001 default)
  -t <tout>        - Set connection timeout in ms (1000 ms default)
  -r <tout>        - Set response timeout in ms (1000 ms default)
  -l               - Loopback test server starting

Terminal commands:
  help             - Print this message               [F1]
  info             - Print terminal info              [F2]
  history -[ftc]   - Print command history            [F3]
    Options:
    -f <key>       - Print records where 'key' is found (-f discards the -t option)
    -t <num>       - Print the last 'num' entries (10 - default, 0 - all records)
    -c             - Clear history
  lscmd            - Print list of available commands [F4]
  lbstart          - Loopback server start
  lbstop           - Loopback server stop
  quit             - Terminal exit                    [F10]
dbgterm>

Тут надо обратить внимание на две вещи:

• Я запустил его по прямому пути (/home/andrey/frmsdk-linux/x86_64/usr/bin/frmdbgterm), хотя можно запустить и без абсолютного пути. Все дело в том, что я запускал его из отдельной консоли, в котором окружения фреймворка нет, соответственно запустить без пути не получится. Терминал сделан так, что его можно запускать из любого места, и в динамических библиотеках фреймворка он не нуждается. Кстати, исполняемый файл в SDK лежит по другому пути (там нет папки usr/bin). Команда $ which frmdbgterm в рабочей консоли с окружением даст правильный путь, ну или в другой консоли надо тоже установить окружение.
• Промпт в терминале ‘dbgterm>’ говорит о том, что терминал не соединен с сервером. При соединении промпт изменится на промпт отдаваемый сервером ‘dbgshell>’:

dbgterm>
Copyright (C) 2026 Andrey Dedukhin (adedukhin@gmail.com)
Framework Debug Shell Application v1.0.0
Press ENTER to continue

dbgshell>

После выгрузки сервера терминал снова перейдет в режим ожидания:

dbgshell>
Server Exit. Press ENTER to continue

dbgterm>

Терминал сделан так, что его не надо перегружать каждый раз при перезапуске фреймворка. Загруженный один раз, он будет работать до тех пор, пока не будет закрыта его консоль, пока не будет перегружен хостовый компьютер или пока не будет команды ‘quit’ для завершения работы терминала. У меня он работает месяцами.

dbgterm> quit
Are you sure to quit? [y/N]: y
Done!

Последний вариант предпочтительный, поскольку сохраняет историю команд в терминале. Выход может выполняться по горячей клавише F10, но не везде эта клавиша работает правильно. В стандартном терминале Ubuntu не работает, в xterm будет работать.

Пожалуй, сразу перечислю известные мне недоработки терминала:

• Терминал не сохраняет записи в истории команд при внезапной аварийной выгрузке, поэтому наработанная история теряется. Она сохраняется только при корректном выходе через команду ‘quit’. Надо либо сделать опцию сохранения истории, либо сохранять команду сразу по выполнении.
• При первом запуске в чистой консоли команды перетирают прежний вывод, после ввода первой команды обычно все работает правильно. При дальнейшей работе, когда вся консоль заполнена выводом, проблем нет.
• Возможна пока не подтвержденная проблема в случае изменения размеров консоли.
• Терминал поддерживает автоввод команды по нескольким символам (по клавише TAB), но если уже введены некоторые параметры, то введенные параметры теряются.
• Термнал поддерживает скроллинг команд по истории стрелками вверх/вниз, но при смене направления происходит “залипание” команды, и требуется еще раз нажать стрелки.
• Терминал поддерживает только ASCII символы, при переходе на русский язык, например, ввод не выполняется. В редких случаях это может быть неудобно.

Это все минорные недостатки, и они будут исправляться, когда дойдут руки :)

Пока были рассмотрены следующие команды терминала:

• ‘help’ - вывод справки.
• ‘info’ - вывод информации по терминалу и по сереверу если подключен.
• ‘quit’ - выгрузка терминала и сохранение истории команд.

Рассмотрим оставшиеся команды:

• ‘history’ - вывод истории команд (горячая клавиша F3). По умолчанию выводятся только 10 последних записей. Используя опцию -t можно указать сколько записей выводить, при значении 0 выводятся все записи истории. Опция -f позволяет выполнять поиск по ключу (ключ не должен содержать пробелы), будут выведены все команды, где встретится ключ в строке. Опция -t при этом игнорируется. Опция -c позволяет очистить историю, хотя опция сохранения была бы более желательной.
• ‘lscmd’ - вывод доступных команд терминала (горячая клавиша F4). Без подключения сервера выведутся только команды терминала. Если сервер подключен, выведутся и доступные команды сервера с кратким описанием.
• ‘lbstart’/‘lbstop’ - это отладочные команды для запуска и остановки отладочного loop back сервера, и в работе с фреймворком не используются.

Ниже приведены логи запуска команд:

dbgterm> history
History:
 78   pid -i
 79   uninstall -p 0x1001009
 80   install -i install/imgview.install -p /home/andrey/frmsdk-linux/x86_64/resources/argo/applets/userapp -n ImageView -c 0
 81   install -i install/imgview.install -p /home/andrey/share/FRM/FRM-V4/argo-v4-03-04-22/WS/rootfs/resources/argo/applets/userapp -n ImageView -c 0
 82   variable
 83   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
 84   variable -l 0
 85   help
 86   pid
 87   help
dbgterm> history -f install
History:
 44   install -i install/testapp.install -p qqq -n qqq
 78   uninstall -p 0x1001009
 79   install -i install/imgview.install -p /home/andrey/frmsdk-linux/x86_64/resources/argo/applets/userapp -n ImageView -c 0
 80   install -i install/imgview.install -p /home/andrey/share/FRM/FRM-V4/argo-v4-03-04-22/WS/rootfs/resources/argo/applets/userapp -n ImageView -c 0
 82   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
dbgterm> history -t2
History:
 87   history
 88   history -f install
dbgterm> lscmd
List of Commands:

  quit             - Terminal: Debug terminal exit
  help             - Terminal: Print debug terminal help
  info             - Terminal: Print debug terminal and server info
  history          - Terminal: Print commands history. See help for options
  lbstart          - Terminal: Loopback server start
  lbstop           - Terminal: Loopback server stop
  lscmd            - Terminal: Print list of available commands
dbgterm>
Copyright (C) 2026 Andrey Dedukhin (adedukhin@gmail.com)
Framework Debug Shell Application v1.0.0
Press ENTER to continue

dbgshell> lscmd
List of Commands:

  quit             - Terminal: Debug terminal exit
  help             - Terminal: Print debug terminal help
  info             - Terminal: Print debug terminal and server info
  history          - Terminal: Print commands history. See help for options
  lbstart          - Terminal: Loopback server start
  lbstop           - Terminal: Loopback server stop
  lscmd            - Terminal: Print list of available commands
  dbgshell         - Server:   Get debug shell application info
  pid              - Server:   Get applications PID list
  closeapp         - Server:   Close application by public ID
  runapp           - Server:   Run applications using private ID or install name
  wakeup           - Server:   Wake up application windows using public and/or private IDs
  sysinfo          - Server:   Get system info content
  appinfo          - Server:   Get application info content
  shell            - Server:   Execute shell command
  install          - Server:   Install application
  uninstall        - Server:   Uninstall application
  category         - Server:   Command to list, add and delete install categories
  language         - Server:   Command to list available languages and set one of them
  variable         - Server:   Command to control available databases and variables
  theme            - Server:   Command to control available themes and set one of them
  dispctl          - Server:   Command to view display info and set background
dbgshell>

При просмотре доступных команд, команды терминала отмемены как ‘Terminal’ - это уже рассмотренные команды. Команды отмеченные как ‘Server’ - это команды, которые предоставляет сервер. В данном случае - это команды, предоставленные приложением Debug Shell фреймворка. Я не буду рассматривать эти команды в данном разделе. Все команды (кроме ‘sysinfo’ и ‘appinfo’ - не имплементированы) имеют справку, вызываемую с помощью опции -h. Кроме того, наиболее полезные команды упоминаются в других разделах.