From ba6531e7bebd9ff9d6a2b4a7f745421fa505c74e Mon Sep 17 00:00:00 2001
From: Orion Hodson <orion@cloudflare.com>
Date: Fri, 28 Apr 2023 15:03:41 +0100
Subject: [PATCH] Update README.md and docs/vscode.md

Adds notes on using bazelisk, that build can be done with VSCode, etc.
---
 README.md      |  7 +++++--
 docs/vscode.md | 24 +++++++++++++-----------
 2 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 6bf1cc9f25a..7d41b4a5bfa 100644
--- a/README.md
+++ b/README.md
@@ -73,6 +73,7 @@ On other platforms, you may have to do tinkering to make things work.
 To build `workerd`, you need:
 
 * [Bazel](https://bazel.build/)
+  * If you use [Bazelisk](https://github.com/bazelbuild/bazelisk) (recommended), it will automatically download and use the right version of Bazel for building workerd.
 * On Linux:
   * Clang 11+ (e.g. package `clang` on Debian Bullseye)
   * libc++ 11+ (e.g. packages `libc++-dev` and `libc++abi-dev` on Debian Bullseye)
@@ -89,12 +90,14 @@ To build `workerd`, you need:
   * When developing at the command-line, run [bazel-env.bat](tools/windows/bazel-env.bat) in your shell first
     to select tools and Windows SDK versions before running bazel.
 
-You may then build using:
+You may then build `workerd` at the command-line with:
 
 ```
-bazel build -c opt //src/workerd/server:workerd
+bazel build //src/workerd/server:workerd
 ```
 
+You can also build from within Visual Studio Code using the instructions in [docs/vscode.md](docs/vscode.md).
+
 The compiled binary will be located at `bazel-bin/src/workerd/server/workerd`.
 
 If you run a Bazel build before you've installed some dependencies (like clang or libc++), and then you install the dependencies, you must resync locally cached toolchains, or clean Bazel's cache, otherwise you might get strange errors:
diff --git a/docs/vscode.md b/docs/vscode.md
index bb8f7c67848..0be204e9093 100644
--- a/docs/vscode.md
+++ b/docs/vscode.md
@@ -7,12 +7,13 @@ A few helpful tips for developing workerd with Visual Studio Code.
 We use [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd)
 for code completion and diagnostics.
 
-For debugging, you will need the [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools).
+For debugging, you will need the [Microsoft C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) installed.
 
-The Microsoft C/C++ Intellisense plugin is not compatible with the clangd extension. We recommend disabling the
-Microsoft Intellisense extension for this project.
+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`).
 
-## Generate a compile_commands.json file
+For clangd to work well, you need to generate a `compile_commands.json` file. This can be done from within VSCode using
+`Run Task -> Generate compile_commands.json` or at the command-line:
 
 ```sh
 # Build workerd to ensure all generated sources are present.
@@ -32,23 +33,24 @@ https://github.com/cloudflare/workerd/issues/506).
 
 ## VSCode Tasks
 
-The [.vscode/tasks.json](../.vscode/tasks.json) file included provides a few useful tasks for use within VSCode:
+The [.vscode/tasks.json](../.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 run all tests
+* Generate compile_commands.json
+* Generate rust-project.json
 
 ## Debugging
 
-There are workerd debugging targets within Visual Studio Code. These
-are supported on Linux (x64) and OS X (arm64).
+There are workerd debugging targets within Visual Studio Code which are supported on Linux (x64), OS X (arm64), and Windows (x64).
 
-The file [.vscode/launch.json](../.vscode/launch.json) has launch targets to that can be debugged within VSCode.
+The [.vscode/launch.json](../.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...`, then `Run -> Start Debugging (F5)`.
+`File -> Save Workspace As...`, then `Run -> Start Debugging (F5)`. For more information about workspaces, see https://code.visualstudio.com/docs/editor/workspaces.
 
 The main targets of interest are:
 
@@ -56,8 +58,8 @@ The main targets of interest are:
 * `workerd debug with inspector enabled`
 * `workerd test case`
 
-Launching either `workerd debug` or `workerd debug with inspector enabled` will prompt for a workerd configuration to launch
-workerd with, the default is `${workspaceFolder}/samples/helloworld/config.capnp`.
+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`.