Style Template Building

To add a style template to Renga, you will need to build it using the RstBuilder.exe console utility included in the Style Template Developer Kit. When running RstBuilder.exe with the necessary options, the utility verifies the input files and generates an RST file that can be imported into the Categories window in Renga Professional.

Command Line Format

To run the utility from the command line, you need to specify the startup options, a parameter and port file, and a script file in the following form:

RstBuilder.exe [configuration] [executable_lua] [options]

Option	Description
-h, --help	Display the utility help.
-v, --version	Display the utility version information.
--configuration path_to_configuration_file	Specify the location of the file in JSON format.
--executable_lua path_to_executable_lua_file	Specify the location of the Lua-script file.
-s stdl_version, --stdlVersion stdl_version	Set the STDL version.
-o path_to_output_file, --output path_to_output_file	Specify the location of the created category file in RST format.
-i path_to_include_lua_file, --include path_to_include_lua_file	Specify the location of additional Lua scripts and modules.

Examples:

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

Using RstBuilder

When using different options with RstBuilder, various results will be obtained. To build an RST file, set in the options:

• Configuration of parameters and ports in JSON file.
• Executable Lua-script file.
• STDL version.
• Additional Lua-script files.
• Resulting file.

Example:

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

The -s stdl_version or –stdlVersion stdl_version parameter is required to set the STDL version. Defines the validation rules and STDL version for the style template. Whenever possible, use the older version of STDL to maintain forward compatibility with older versions of Renga.

Upon starting up, RstBuilder verifies input files. If the check fails, the utility will not create the resulting file and will display a message about the failed check. If the check is successful, you will receive a style template file in RST format that can be used for further testing and added to your Renga project.

If the -o file or –output file option is not specified, you will only receive the check result. For instance, if the format of the version is incorrect, the following error message will be displayed:

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

If you use the require function to include third-party modules, you should add them using the -i file or –include file option. It is important to ensure that module names must be unique.

If you add modules in the script as shown below, for example:

require("mod1")
require("mod2")

the line to call RstBuilder to get a file in RST format looks like this:

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

Please note that when using the require function in a script, the module path should not be specified, whereas for template building, specifying the path is required.

Checking Input Files

When starting RstBuilder:

• Checks that the encoding of all input files is UTF-8.
• Checks the JSON configuration file for compliance, required fields, and correct values.
• Checks if the Lua script can be compiled.

When RstBuilder is complete, it returns the following values:

• 0 — if there are no errors;
• 1 — in case of an error. In this case, an error message will also be displayed on the standard error output stream.

Please note that checking with RstBuilder does not detect errors of using the Renga Template API. To debug a style template, refer to Testing and Debugging.

Integration in Visual Studio Code

To add a building integration from VS Code, include the tasks.json file in the .vscode folder of the current project.

{
    "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
            }
        }
    ]
}

To build a style template, run Terminal - Run Build Task (Ctrl+Shift+B).