Development Process

This guide covers how to set up a development environment, build, and debug the MATLAB extension for VS Code and the associated MATLAB language server.

Setup the Development Environment

Install Required Software

The MATLAB extension for VS Code and associated language server are TypeScript applications developed with Node.js.

The following software is needed for development:

• Visual Studio Code - The recommended IDE for VS Code extension development.
• Node.js - A cross-platform JavaScript runtime.
  • Includes npm, used for dependency management, building, and testing.
• Git - The version control system used by GitHub, and needed to contribute to GitHub.
• MATLAB - Needed to run MATLAB code as part of the language server.
  • This is optional if not leveraging advanced language server functionality.

Clone and Install Repository

Clone the extension repository with submodules (the language server is a Git submodule):

git clone --recursive https://github.com/mathworks/MATLAB-extension-for-vscode.git
cd MATLAB-extension-for-vscode

Next, install all project dependencies:

npm run project-install

Setup the IDE

VS Code is the recommended IDE for developing VS Code extensions, as it includes integrated tooling for building, running, and debugging extensions.

To get started, simply open the root directory of the cloned repository within VS Code.

Build the Extension

The extension's TypeScript code is compiled into JavaScript before running. There are a few ways to do this:

• Auto-rebuild on save:
  

  npm run watch
  

• One-time build:

  npm run compile
  

• Create a distributable VSIX (for local install/testing):

  npm run package
  

  This produces a language-matlab-<version>.vsix file.

Run and Debug the Extension

A set of VS Code run configurations are provided alongside the extension source code.

To locally run the extension for debugging:

1. Ensure the extension repo is open in VS Code
2. Open the "Run and Debug" panel
3. Choose the "Run & Debug" run configuration from the drop down
4. Select the "Play" button (or press F5)

VS Code launches an Extension Development Host window with the MATLAB extension enabled. Open a .m file to activate the extension.

Debug the Extension using TypeScript

• Set breakpoints in the extension source (your main VS Code window).
• Perform actions in the Extension Development Host window to hit breakpoints.

Debug the Language Server using TypeScript

• There may be a slight delay before the debugger attaches to the language server process.
• If breakpoints appear "unbound", stop and re-run the debugger with the "Run & Debug" configuration (not "Run Extension").

Debug MATLAB Code

If a workflow runs MATLAB code, you can use the MATLAB Desktop to set MATLAB breakpoints as usual and step through M-code behavior triggered by actions in the Extension Development Host window.

To run the MATLAB Desktop:

1. In the Extension Development Host window, run the MATLAB: Open Command Window VS Code command.
2. Run the desktop command in the resulting MATLAB terminal

Tip: For silent exceptions in MATLAB, temporarily wrap suspect code in try/catch and disp the caught error for visibility during debugging.

Testing

The extension includes integration tests and language server unit tests.

Extension Integration Tests

• Location: src/test/
• Framework: Mocha

To run these tests, use the following command:

npm run test

Language Server Unit Tests

• Location: server/tests/
• Types of tests:
  • TypeScript-based (Mocha)
  • MATLAB-based

To run the TypeScript unit tests, use the following commands:

cd server
npm run test

To run the MATLAB unit tests, it is recommended to use the MATLAB test features within MATLAB:

1. Launch MATLAB (outside VS Code)
2. Open the test file in the MATLAB editor
3. Run the tests using one of the following:
   1. "Run Tests" toolstrip button
   2. Test Browser side panel
   3. runtests command

Additional Resources

VS Code Extension Development

• Extension API - Microsoft's resource for VS Code extension development
• Your First Extension - A quick-start guide on creating an extension for VS Code
• Extension Capabilities - Describes the various capabilities which can be leveraged by extensions
• UX Guidelines - A set of guidelines which cover the best practices for creating extensions that seamlessly integrate with VS Code's native interface and patterns.
• Language Extensions - A guide specifically focused on creating extensions which add support for programming languages.
• Contribution Points - A reference for the various contribution points which are available to extensions.
• VS Code API Reference - A reference page for VS Code's extension APIs

Language Server Protocol (LSP)

• LSP Overview & Specification - Microsoft's resource for language servers
  • Language features (e.g. completion, diagnostics, etc.) are detailed within the spec.