This is the reference for the scripting APIs available from the debugger.
To begin, your scripts should call initScripting which will provide you with the debugger's main scripting interface.
You can find example scripts in ccs/scripting/examples/debugger. They give an overview
of how a script can be structured.
The simplest way to run a script is using the run.bat and run.sh scripts in ccs/scripting.
For example
run.bat examples/debugger/breakpoints.js
Note that to actually run the example script, you will require the hardware target it expects.
It should be possible to use any Node.js debugger as long as it is compatible with the version of Node.js being used. We will focus on debugging in CCS Theia or VS Code. For other debuggers refer to your debugger's documentation and the official Node.js debugging documentation.
If you using CCS Theia ensure you have the JavaScript Debugger extension installed (this is a Microsoft extension, check that the extension you are installing is published by ms-vscode).
Next open your launch.json file (Ctrl+Shift+P > 'Debug: Open Configurations') and add a launch configuration. Here is a basic example:
{
"name": "Debug my script",
"type": "node",
"request": "launch",
"program": "<ccs root>/scripting/launcher.mjs",
"args": ["<path to your script>"],
}
See the documentation for Node.js debugger in VS Code for more details.
Finally, in the debug side-view (Ctrl+Shift+D), select your new debug configuration in the dropdown selector at the top of the view, then start debugging.
Scripts are run in a standard Node.js environment. For some advanced use cases it may be beneficial to invoke Node.js directly. Refer to the run.bat and run.sh scripts for how to invoke Node.js. You may notice that we make use of a small launcher script to import our scripting module. This is done as a convenience so that your script does not need determine from where it needs to import the scripting module.
If you wish, the scripting module can be imported by your script and used like any normal node module. If you copy the module out of its location in a CCS installation, you can specify the location of the CCS installation as an option to initScripting.
In Javascript, all standard numbers are floating point numbers, and can only represent up to 53-bit integers without loss of precision. To support 64-bit addressable targets and 64-bit values in general, our APIs that need to be able to accept or return such values will accept and return BigInts. This is javascript type that can represent arbitrary-sized integers.
For convenience, APIs that accept BigInts, will also accept regular Javascript numbers and strings. If using regular Javascript numbers, but we recommend using BigInts.