Profound.js Debugging with VS Code

VS Code: The What and Why

VS Code is a cross-platform, multi-language code editor. With inline IntelliSense, debugging support for multiple languages, inline git support and an extensible API for plugins, it's the editor that has no boundaries.

It's inline debugging support is perfect for Profound.js as it provides the functionality to start and stop Profound.js locally, set breakpoints, and see the values of variables at runtime, all through a friendly user interface.

To download and read more about VS Code, check out the following links:

• https://code.visualstudio.com/
• https://code.visualstudio.com/docs/editor/whyvscode
• https://code.visualstudio.com/docs/nodejs/nodejs-tutorial
• https://code.visualstudio.com/docs/nodejs/nodejs-debugging
• https://code.visualstudio.com/docs/editor/debugging

There are several methods to debug your Profound.js program in VSCode.

• Launch config - serves as the conventional method for configuring debugging. It offers a comprehensive range of options to effectively run intricate applications.
• Attach to a process – this allows you to connect the debugger to an already running process or application. This is useful when you want to debug a program that’s already running.

Written Tutorial

Using Launch config method:

1. In your VSCode, open your Profound.js installation directory in the Explorer.

1.1 File > Open Folder…

1.2 Select the directory where you installed Profound.js

2. Navigate to the ‘Run and Debug’ tab.

3. Click on the ‘create a launch.json file’. This will open a new launch.json file with no configurations just yet on your directory.

Your new launch.json file may look similar to this:

4. The next step is to add your configurations on your launch.json file, which would look like this:

To break this down:

a. "version": "0.2.0" - this is the Visual Studio Code debugger version

b. "configurations" - this is your array of configurations

c. "type": "node" - this tells us that we are debugging a Node.js application

d. "request": "launch" - this signals that VSCode should start a new instance of the Node.js runtime for debugging

e. "name": "Launch PJS Debugger" - this is just a name for the debug configuration. It’s what you’ll see in the dropdown menu in the Debug view.

f. "skipFiles" - this is optional. Here you specify which files the debugger should skip during debugging. The <node_internals>/** notation means that it’s going to skip all Node.js internal files.

g. "program": "${workspaceFolder}\\start.js" - this points VSCode to the entry point of your application which is start.js.

h. "args": ["--no-worker"] - this is also optional. These are command-line arguments passed to your application when it starts. Here, --no-worker prevents Profound.js from using worker threads.

*For more Launch configuration attributes: https://code.visualstudio.com/docs/nodejs/nodejs-debugging#_launch-configuration-attributes

5. To test this, press the Play button.

6. When your debugger starts running, you should see the following in your ‘DEBUG CONSOLE’:

7. Once you have your Profound.js server running from VS Code, that means you are now able to debug.

Debugging a Profound.js module:

For this example, we will be debugging a module called connect4.js, which is included in Profound.js.

1. In the VS Code explorer, open 'modules/pjssamples/connect4.js'

*Note: make sure your Profound.js Module has been set correctly in the config.js file of Profound.js. Here is an example: 

2. Once the file is open, place a breakpoint at the desired location where you want the program to pause.

    You can place a breakpoint by clicking just to the left of the line number where you intend to pause the program.

3. After this, start debugging within VS Code and launch the application in your browser using the URL displayed in the debug console.

4. When the program pauses, VS Code will become the active window, and the current debugged line of code will be highlighted in yellow.

5. From this point forward, you can proceed to step through your module and debug the application.

Using Attach to a process:

1. To do this, open your remote ssh terminal. You need to start the server in debug mode. The command to that will look similar to this:

You can also add the -brk and --no-worker flag for this command. -brk adds a breakpoint at the beginning of your script to wait for the debugger to attach before proceeding.

2. Then create a launch.json file, refer to the Launch config method for steps on how to do this.

{
  "version": "0.2.0",
  "configurations": [
    
      {
        "request": "attach",
        "name": "Debug PJS",
        "address": "21.1.88.92",
        "port": 40399,
        "remoteRoot": "/nmas_pjs",
        "localRoot": "C:\\Documents\\nmas_pjs",
        "type": "node",
        "skipFiles": [
          "<node_internals>/**"
        ]
      }
  ]
}

a. "request": "attach" - this tells VSCode you’re attaching to an already running process.

b. "name": "Launch PJS Debugger" - this is just a name for the debug configuration. It’s what you’ll see in the dropdown menu in the Debug view.

c. "address” & "port" - the address and port of the remote system (or your local machine) where the node.js process you want to debug is running.

d. “remoteRoot” & “localRoot” – are used to help VSCode map your local source code to the remote source code.

e. “type”: “node” – is the debug type.

f. “skipFiles” – optional but is handy when you don’t want to sift through certain files during debugging.

3. To run the launch file, click on the play button

4. Once you have the ‘Debugger attached’ message on your terminal, you can start debugging.

Video Tutorial