Skip to content

Latest commit

 

History

History
89 lines (58 loc) · 4.9 KB

vscode.md

File metadata and controls

89 lines (58 loc) · 4.9 KB
Raw

Developing workerd with Visual Studio Code

Visual Studio Code is a commonly used editor by workerd developers (other editors are great too!). These notes present some getting started tips. If you have tricks and tips that would improve the developer experience, please let us know!

Recommended extensions for developing workerd

The recommended extensions to install are:

  • LLVM clangd extension for code completion and navigation.

    For clangd to work well, you need to generate a compile_commands.json file. This is described below in Generating compile_commands.json.

  • Microsoft C/C++ extension for debugging, syntax highlighting, etc.

    The Microsoft C/C++ extension has IntelliSense support that is not compatible with the clangd extension. We recommend disabling the Microsoft IntelliSense Engine for this project ("Settings → C_Cpp.intelliSenseEngine → disabled").

  • Capnproto-syntax extension for syntax highlighting if you are editing .capnp files.

  • GitLens extension for super charged git functionality within Visual Studio Code.

You can install all of these extensions with the Extensions: Configure Recommended Extensions (Workspace Folder) command. You can find this through the Visual Studio Code Command Palette (shift+ctrl+p on Linux / Windows, shift+cmd+p on OS X) and typing "Configure Recommended Extensions". The recommendations that will be installed can be found in the .vscode/extensions.json file.

VSCode Tasks for workerd

The .vscode/tasks.json file provides a few useful tasks for use within VSCode:

  • Bazel build workerd (dbg)
  • Bazel build workerd (fastbuild)
  • Bazel build workerd (opt)
  • Bazel build all (dbg)
  • Bazel clean
  • Bazel clean --expunge
  • Bazel run all tests
  • Generate compile_commands.json
  • Generate rust-project.json

The keyboard shortcut for Run Build Task is shift+ctrl+b on Linux and Windows, shift+cmd+b on OS X.

Running and debugging workerd in Visual Studio Code

There are workerd debugging targets within Visual Studio Code which are supported on Linux, OS X, and Windows.

The .vscode/launch.json file has launch targets to that can be debugged within VSCode.

Before you start debugging, ensure that you have saved a vscode workspace for workerd, "File → Save Workspace As...". For more information about workspaces, see https://code.visualstudio.com/docs/editor/workspaces.

The Run and Debug view in VSCode (accessible via shift+ctrl+d on Linux and Windows, shift+cmd+d on OS X) has a drop-down that allows you to choose which target to run and debug. After selecting a target, hitting F5 will launch the target with the debugger attached.

The main targets of interest are:

  • workerd debug
  • workerd debug with inspector enabled
  • workerd test case

Launching either "workerd debug" or "workerd debug with inspector enabled" will prompt for a workerd configuration for workerd to serve, the default is ${workspaceFolder}/samples/helloworld/config.capnp.

Launching "workerd test case" will prompt for a test to debug, the default is bazel-bin/src/workerd/jsg/jsg-test.

Generating compile_commands.json

We use clangd for code completion and navigation with the editor. Clangd requires a compile_commands.json file to find and process the project source code. This can be generated from within VSCode using the Run Build Task command and choosing "Generate compile_commands.json" (or via shift+ctrl+b on Linux / Windows, shift_cmd+b on OS X).

Alternatively, you can generate compile_commands.json at the command-line directly:

bazel run //:refresh_compile_commands

There is an issue between workerd's bazel setup and Hedron's compile_commands.json generator (tracked in cloudflare#506).

If you hit any problems, you may find this helps (though it takes a long time!):

bazel clean --expunge
bazel test //...
bazel run //:refresh_compile_commands

Miscellaneous tips