Для добавления шаблона стиля в Renga необходимо собрать его с помощью консольной утилиты RstBuilder.exe, которая входит в Комплект разработчика шаблона стиля. При запуске RstBuilder.exe с необходимыми параметрами происходит проверка входных файлов и создание файла в формате RST, который можно импортировать в окне Категории в Renga Professional.

Формат командной строки

Чтобы запустить утилиту из командной строки, нужно указать параметры запуска, файл описания параметров и портов и файл скрипта в следующем виде:

RstBuilder.exe [configuration] [executable_lua] [параметры]

Параметр	Описание
`-h`, `--help`	Получение справки по использованию утилиты.
`-v`, `--version`	Вывод версии утилиты.
`--configuration path_to_configuration_file`	Задание расположения файла параметров в формате JSON.
`--executable_lua path_to_executable_lua_file`	Задание расположения исполняемого файла Lua-скрипта.
`-s stdl_version`, `--stdlVersion stdl_version`	Задание версии STDL.
`-o path_to_output_file`, `--output path_to_output_file`	Задание расположения создаваемого файла категории в формате RST.
`-i path_to_include_lua_file`, `--include path_to_include_lua_file`	Задание расположения дополнительных lua-скриптов и библиотек.

Примеры:

RstBuilder.exe configuration.json run.lua -s 1.0 -i library.lua

RstBuilder.exe --executable_lua C:\Project\run.lua --configuration C:\Project\configuration.json --stdlVersion 1.0 --output C:\Project\category.rst

Использование RstBuilder

При запуске RstBuilder c разными параметрами вы получите разные результаты. Чтобы создать файл в формате RST, задайте параметры, определяющие:

Файл описания параметров и портов в формате JSON.
Файл исполняемого Lua-скрипта.
Версия STDL.
Файлы дополнительных Lua-скриптов.
Результирующий файл.

Пример:

RstBuilder.exe configuration.json run.lua -s 1.0 -o category.rst

Параметр -s stdl_version или –stdlVersion stdl_version для задания версии STDL обязателен. Определяет правила проверки и версию STDL для шаблона стиля. При возможности используйте наиболее старшую версию STDL, чтобы сохранить прямую совместимость с Renga старших версий.

При запуске будет проведена проверка входных файлов. Если она не пройдёт, то результирующий файл не будет создан и будет показан результат проверки. Если проверка прошла успешно, то вы получите файл шаблона стиля category.rst, который можно добавить в проект Renga для дальнейшего тестирования.

Если параметр -o file или –output file не задан, вы получите только результат проверки. Например, при неправильном формате версии вы получите следующее сообщение об ошибке:

Failed to match regex specified by 'pattern' constraint. <root>\[metadata\]\[version\]

Если при написании Lua-скрипта были подключены сторонние модули с помощью функции require, то для сборки шаблона скрипта с помощью RstBuilder необходимо добавить их c помощью параметра -i file или –include file. Имена модулей должны быть уникальными.

Например, если в скрипте модули добавлены следующим образом:

require("mod1")

require("mod2")

то строка вызова RstBuilder, для получения файла в формате RST будет следующей:

RstBuilder.exe configuration.json run.lua -s 1.0 -o category.rst -i C:\Modules\mod1.lua -i C:\Modules\mod2.lua

Обратите внимание, что при написании скрипта в функции require не надо указывать путь, по которому лежит модуль, а для сборки шаблона путь указать необходимо.

Проверка входных файлов

При запуске RstBuilder:

Проверяет, что кодировка всех входных файлов соответствует UTF-8.
Проверяет файл параметров на соответствие формату JSON, а также на наличие необходимых полей и корректность значений в них.
Проверяет, можно ли скомпилировать Lua-скрипт.

Завершая работу, RstBuilder возвращает следующие значения:

0 — в случае отсутствия ошибок.
1 — в случае ошибки. В этом случае также появится текстовое сообщение об ошибке в стандартном потоке ошибок.

Обратите внимание, что проверка с помощью RstBuilder не выявляет ошибок использования Renga Template API. Об отладке шаблона стиля см. Тестирование и отладка.

Интеграция в Visual Studio Code

Для интеграции сборки из VS Code добавьте в папку .vscode текущего проекта файл tasks.json:

{
    "tasks": [
        {
            "type": "shell",
            "label": "Build rst file",
            "command": "C:\\PathToSTDLSDK\\RstBuilder.exe",
            "args": [                 
                "configuration.json",
                "run.lua",
                "-s",
                "1.0",
                "-o",
                "category.rst"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        }
    ]
}

Чтобы собрать шаблон стиля, вызовите команду Terminal->Run Build Task... (Ctrl+Shift+B).