Template debugging

Overview

Yellicode runs each template in a separate (Node.js) child process. In order to debug a template, you will need to tell Yellicode to start the child process in debug mode. When started, you can attach your IDE's debugger to this process. You can debug only one template at a time.

This sample uses the free Visual Studio Code IDE. However, the process should be similar for other environments.

Preparing Visual Studio Code

In this step, we will create a new launch configuration. VS Code adds launch configurations to a file named launch.json, which will be automatically created if it doesn't exist yet.

  1. In VS Code, open the Debug view (CTRL-SHIFT-D).
  2. Pull down the configurations dropdown and choose Add Configuration.
  3. VS Code prompts you so select an environment. Choose Node.js.
  4. Then, pick the configuration named Node.js: Attach.
  5. VS Code inserts a new launch configuration in the launch.json file. Change the port to 9230 and change the name to Attach to Yellicode Template Process. The final configuration should look like the following:
    {
        "version": "0.2.0",
        "configurations": [
            {
                "type": "node",
                "request": "attach",
                "name": "Attach to Yellicode Template Process",
                "port": 9230
            }
        ]
    }

For Node.js versions prior to 6.14.2, you should set the port number to 5859 because with these versions only the original V8 Debugger Protocol is supported, while newer versions support the new V8 Inspector Protocol.

Preparing the template

Let's use our Quick start example (be sure to include the codegenconfig.json file) and insert a breakpoint, for example using the debugger statement:

import { Generator, TextWriter } from '@yellicode/templating';

Generator.generate({outputFile: './quickstart-output.txt'}, (writer: TextWriter) => {
    debugger;
    writer.writeLine('File generated by Yellicode at '+new Date().toISOString());
});   

Attaching the debugger

Start Yellicode, tell it to start the child process in debug mode...

yellicode --debug-template

... and wait until you see the following message:

Info: Waiting for debugger to attach on port 5859...
Debugger listening on [::]:5859

Finally, in the VS Code Debug view, start using configuration Attach to Yellicode Template Process that we prepared in the first step. You should soon see the debugger hit our breakpoint.

Please note that the --debug-template and --watch arguments cannot be used together.

Choosing the target template

As stated earlier, you can only attach to a single template process at a time. So what if you have multiple templates configured in your codegenconfig.json? There are 2 ways to do this:

  1. By default, Yellicode chooses the first template configured as the target for debugging. If you have more than one template, you can use the debug field to indicate that you want to debug that template instead:
  2. {
        "templates": [
            {
                "templateFile": "./first.template.ts"
            },
            {
                "templateFile": "./second.template.ts",
                "debug":true
            }
        ]
    }
    
  3. Alternatively, you can use the --template argument when you start Yellicode. This argument must contain the full path to the template file. Also, the template file must have a valid configuration in the codegenconfig.json file.
    yellicode --debug-template --template "[full-path-to-template-file]"