Skip to content

Latest commit

 

History

History
262 lines (178 loc) · 8.37 KB

README-DEVELOPER.md

File metadata and controls

262 lines (178 loc) · 8.37 KB
Raw

Visual Studio Marketplace Version license TS-Standard - Typescript Standard Style Guide Visual Studio Marketplace Installs Visual Studio Marketplace Downloads GitHub issues GitHub pulls Codacy Badge

Developer info

This page documents the prerequisites and procedures used during the development of the VS Code xPack C/C++ Managed Build extension.

This project is written in TypeScript, as recommended for VS Code extensions.

Prerequisites

Briefly, the prerequisites are:

  • npm
  • a recent xpm, which is a portable Node.js command line application
  • an instance of Visual Studio Code with a specific set of extensions
  • a marketplace publisher access token; vsce login ilg-vscode

Install xpm

npm install --global xpm@latest

Prepare a separate instance of VS Code

To avoid interferences with other extensions in the regular VS Code configuration, it is recommended to use a custom folder and a separate set of extensions:

mkdir ${HOME}/Work/vscode-extensions/code-portable-data-develop
cd ${HOME}/Work/vscode-extensions

code \
--extensions-dir ${HOME}/Work/vscode-extensions/code-portable-data-develop \
--install-extension ms-vscode.cpptools  \
--install-extension ms-vscode.cmake-tools \
--install-extension twxs.cmake \
--install-extension mhutchie.git-graph \
--install-extension github.vscode-pull-request-github \
--install-extension DavidAnson.vscode-markdownlint \
--install-extension christian-kohler.npm-intellisense \
--install-extension ban.spellright \
--install-extension standard.vscode-standard \

code \
--extensions-dir ${HOME}/Work/vscode-extensions/code-portable-data-develop \
--list-extensions --show-versions

ms-vscode.makefile-tools may also be useful.

On Windows, use the Git console, which is more or less a regular shell.

Clone the project repository

The project is hosted on GitHub:

To clone the master branch, use:

mkdir ${HOME}/Work/vscode-extensions
cd ${HOME}/Work/vscode-extensions
git clone \
  https://github.com/xpack/vscode-xpack-extension-ts.git vscode-xpack-extension-ts.git

For development, to clone the develop branch, use:

git clone \
  --branch develop \
  https://github.com/xpack/vscode-xpack-extension-ts.git vscode-xpack-extension-ts.git

Start VS Code

code \
  --extensions-dir ${HOME}/Work/vscode-extensions/code-portable-data-develop \
  ${HOME}/Work/vscode-extensions/vscode-xpack-extension-ts.git

Update VS Code settings

TBD

Satisfy dependencies

npm install

Start the webpack-dev background task

The xPack extension uses webpack to make the distribution more compact.

To automate the workflow, webpack can be started as a background task to convert the out folder into the dist folder:

npm run webpack-dev-watch

Start debug sessions

Use the existing launchers.

Note: the dist folder content is processed by webpack and the relationship to the original TS files is lost. Temporarily adjust package.json to point to the out folder.

Language standard compliance

The current version is TypeScript 4:

VS Code extension API

The API used to implement VS Code extensions:

package.json contributions

The VS Code extensions require some definitions stored in the contributes property of package.json.

contributes.commands

All commands are listed here, but not all commands are equal, those that must be shown in Command Palette better have the category defined, while those that go in menus probably better have the icons.

contributes.menus.commandPalette

The Command Palette is the way extensions contribute commands that can be invoked manually.

The picker prefixes commands with their category, allowing for easy grouping.

contributes.menus.view/title

These are the commands associated with the view title.

The navigation group is special as it will always be sorted to the top/beginning of a menu.

contributes.menus.view/item/context

These are the commands associated with the items in the view tree.

  • inline groups are shown in the item line
  • navigation groups are shown as right click.

Node: the when expressions do not accept parenthesis, so to enable commands for multiple items, repeat the command with all different viewItem.

contributes.configuration

Scope:

  • application (all instances of VS Code and can only be configured in user settings)
  • machine (user or remote settings, like installation path which shouldn't be shared across machines)
  • machine-overridable (can be overridden by workspace or folder)
  • window (user, workspace, or remote settings; default)
  • resource (files and folders, and can be configured in all settings levels, even folder settings)
  • language-overridable

Documentation

Read configuration values

vscode.workspace.getConfiguration('xpack').get<number>('maxSearchDepthLevel', 3)

Write configuration values

const inspectedValue = npm.inspect('exclude')
const isGlobal = inspectedValue !== undefined &&
  inspectedValue.workspaceValue === undefined

await npm.update('exclude', newArray, isGlobal)

Implementation details

Data model

The extension recursively searches for package.json files, down to a given depth and possibly excluding some folders, in order to prepare a data model which is a tree of packages. For easier access, the configurations, commands actions are also identified and listed in separate arrays.

TBD

Standard style

As style, the project uses the TypeScript variant of Standard Style, automatically checked at each commit via CI.

Generally, to fit two editor windows side by side in a screen, all files should limit the line length to 80.

/* eslint max-len: [ "error", 80, { "ignoreUrls": true } ] */
// eslint-disable-next-line @typescript-eslint/no-dynamic-delete

Known and accepted exceptions:

  • none

To manually fix compliance with the style guide (where possible):

$ npm run fix

> xpack@0.0.1 fix
> ts-standard --fix src

TSDoc (TypeScript documentation)

Bundling extensions