Debugging

This section contains information about configuring and debugging Melezh-based projects

Enabling Melezh debugging in a container

tip

Works in Melezh starting from version 0.9.0 when using OneScript Debug Adapter >=1.1.0

Melezh Docker images have debug port 1931 configured by default for OneScript Debug Adapter. This port needs to be forwarded to the local machine, after which you should create a launch.json in VS Code with the following content:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Melezh Attach",
            "type": "oscript",
            "request": "attach",
            "debugPort": 1831,
            "pathsMapping": {
                "remotePath": "/app",
                "localPath": "D:/Repos/Melezh"
            }
        },
    ]
}

During debugging, the base for calculating paths to modules with breakpoints is determined using the remotePath and localPath fields. Simply put, the debugger replaces remotePath with localPath in the file path for debugging to find a copy of the file from the container on the local machine. This is necessary because the full file path on the machine and in the container will differ. For example, with the launch.json file from the example, the module /app/my_extension/extension.os can be debugged on the local machine by working with the module D:/Repos/Melezh/my_extension/extension.os in the code editor

The container always has the /app directory - the main Melezh workspace directory where project files and log directory are stored, and from which relative paths in settings and extensions are calculated. It is recommended to mount it as a volume on the local machine when creating the container and create a subdirectory there for extensions that need to be debugged. With this approach, you can specify volume mount paths as remotePath and localPath, and make changes to extensions directly during debugging in VS Code, applying changes without restarting the server by refreshing the cache using the button in the Web UI (see Extensions Panel)

Debugging on a local machine

To start debugging on a local machine, you can either launch Melezh through the adapter in VS Code (the Melezh process will terminate when debugging ends), or, as with Docker containers, allocate a permanent port to connect the debugger to as needed

To launch Melezh debugging through VS Code, you need to open the main Melezh installation directory in the editor and create a launch.json with the following content:

{
    "name": "Debug Melezh UI",
    "type": "oscript",
    "request": "launch",
    "program": "${workspaceRoot}/core/Classes/app.os",
    "args": ["ЗапуститьПроект", "--port", "1921", "--proj", "D:/test_proj.melezh"],
    "cwd": "${workspaceRoot}",
    "env": {},
    "runtimeExecutable": null,
    "runtimeArgs": [],
    "debugPort": 2801
}

• In the program field, you need to specify the path to the core/Classes/app.os file in the Melezh directory
• In the args field, you need to replace port and proj with your launch port and path to the project file being debugged, respectively

important

If Melezh was installed from a Windows installer or Linux package, OneScript may not be present on the target machine as a separate application registered in PATH. In this case, you can install OneScript separately, or specify the path to the embedded OneScript engine inside Melezh in the runtimeExecutable field

On Linux: usr/lib/oint/bin/oscript On Windows: {OInt installation directory}\OInt\share\oint\bin\oscript.exe

After starting debugging in VS Code, you can set breakpoints both in the main Melezh scripts and in custom extension files

To launch Melezh with a permanent debug port, you need to:

• If Melezh was installed from a Windows installer or Linux package, it is sufficient to set the MELEZH_DEBUG environment variable with the preferred port number before launching melezh, through which the debugger will be accessible later

• If Melezh was installed as an OPM package, you need to modify the melezh.bat/melezh.sh file in OneScript/bin, adding -debug -port="Port number" -noWait between oscript and the path to app.os. For example:

oscript -debug -port="1931" -noWait /usr/share/oint/lib/melezh/core/Classes/app.os "$@"

You can connect to the process for debugging after launching Melezh using the Debug Adapter with a launch.json of the following form:

{
   "name": "Melezh Attach",
   "type": "oscript",
   "request": "attach",
   "debugPort": 1931
}