|
| 1 | +# How to Setup Development Environment |
| 2 | + |
| 3 | +This document will guide you through the process of setting up typical development environment on Linux and Windows. |
| 4 | + |
| 5 | +## On Windows |
| 6 | + |
| 7 | +Install WSL: |
| 8 | +```PowerShell |
| 9 | +wsl --install |
| 10 | +``` |
| 11 | + |
| 12 | +## On Linux (including WSL) |
| 13 | + |
| 14 | +Install development tools: |
| 15 | +```bash |
| 16 | +sudo apt update |
| 17 | +sudo apt install build-essential gdb make cmake |
| 18 | +``` |
| 19 | + |
| 20 | +## Visual Studio Code |
| 21 | + |
| 22 | +1. [Install VS Code](https://code.visualstudio.com/Download) |
| 23 | + |
| 24 | +2. Launch VS Code and install the following extensions: |
| 25 | + - [C/C++ Extension Pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools-extension-pack) |
| 26 | + - [Remote Development](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) |
| 27 | + |
| 28 | +### Build Command in VS Code |
| 29 | + |
| 30 | +#### WSL |
| 31 | + |
| 32 | +In VS Code you can setup build commands and run them directly from VS Code GUI via menu `Terminal > Run Build Task...` or `Terminal > Run Task...`. |
| 33 | +In order to do that you need to create `.vscode/tasks.json` file inside your workspace. |
| 34 | +To create a single build task that runs our build script `make.sh` from WSL on Windows you can create the following `.vscode/tasks.json` file: |
| 35 | +```json |
| 36 | +{ |
| 37 | + "version": "2.0.0", |
| 38 | + "tasks": [ |
| 39 | + { |
| 40 | + "label": "(WSL) build debug version", |
| 41 | + "type": "process", |
| 42 | + "command": "wsl", |
| 43 | + "args": [ |
| 44 | + "bash", "-c", |
| 45 | + "cd \"$(wslpath '${workspaceFolder}')\" && ./make.sh -B DEBUG=yes" |
| 46 | + ], |
| 47 | + "group": { |
| 48 | + "kind": "build", |
| 49 | + "isDefault": false |
| 50 | + }, |
| 51 | + "problemMatcher": [] |
| 52 | + } |
| 53 | + ] |
| 54 | +} |
| 55 | +``` |
| 56 | +Note that this task works under Windows only. Here's a detailed explanation of each line in the above file: |
| 57 | + |
| 58 | +- `"label": "(WSL) build debug version"` |
| 59 | + - A user-friendly name for the task. |
| 60 | + - This label is shown in the Run Task menu and can be used in launch.json (as a preLaunchTask). |
| 61 | + - You can choose any string, but it must be unique within the file. |
| 62 | + |
| 63 | +- `"type": "process"` |
| 64 | + - Indicates the task runs a process directly, without going through the integrated shell. |
| 65 | + - This means that command refers to a system executable (like wsl, make, python, etc.). |
| 66 | + |
| 67 | +- `"command": "wsl"` |
| 68 | + - Specifies the executable to run. |
| 69 | + - In this case, it's the `wsl` command, which launches a process inside Windows Subsystem for Linux. |
| 70 | + - So, everything after this is interpreted inside the WSL environment. |
| 71 | + |
| 72 | +- `"args": [...]` |
| 73 | +- An array of arguments to pass to the command. |
| 74 | +- In this case: |
| 75 | + - `"bash"`: runs the Bash shell inside WSL |
| 76 | + - `"-c"`: tells Bash to execute the following command string |
| 77 | + - `"cd \"$(wslpath '${workspaceFolder}')\" && ./make.sh -B DEBUG=yes"`: this is the actual shell command being run inside WSL: |
| 78 | + - `$(wslpath ...)` converts the Windows path of `${workspaceFolder}` to a Linux-style path (`/mnt/...`) |
| 79 | + - `cd` into that path |
| 80 | + - then run the script `make.sh` with flags `-B DEBUG=yes` |
| 81 | + |
| 82 | +- `"group": { "kind": "build", "isDefault": false }` |
| 83 | + - Organizes the task for VS Code’s UI: |
| 84 | + - `"kind": "build"` marks this task as a build task (shown in the Build Task menu). |
| 85 | + - `"isDefault": false` means this is not the default build task (i.e., not run automatically when you press `Ctrl+Shift+B`). |
| 86 | + |
| 87 | +- `"problemMatcher": []` |
| 88 | + - Defines how VS Code should parse output from the task to detect errors/warnings. |
| 89 | + - An empty array [] means no error parsing - output will just go to the terminal, but VS Code won't try to detect errors or navigate to files. |
| 90 | + - You could attach a matcher like `$gcc` if you want VS Code to recognize compiler errors. |
| 91 | + |
| 92 | +### Debugging Command in VS Code |
| 93 | + |
| 94 | +#### WSL |
| 95 | + |
| 96 | +1. Install [WSL workspaceFolder](https://marketplace.visualstudio.com/items?itemName=lfurzewaddock.vscode-wsl-workspacefolder) extension in VS Code to be able to convert `"${workspaceFolder}"` to Linux style path. |
| 97 | + |
| 98 | +2. Create `.vscode/launch.json` file inside your workspace with the following content: |
| 99 | + ```json |
| 100 | + { |
| 101 | + "version": "0.2.0", |
| 102 | + "configurations": [ |
| 103 | + { |
| 104 | + "name": "WSL Debug", |
| 105 | + "type": "cppdbg", |
| 106 | + "request": "launch", |
| 107 | + "program": "${command:extension.vscode-wsl-workspaceFolder}/build/GNUMake/bin/test.exe", |
| 108 | + "args": [], |
| 109 | + "stopAtEntry": false, |
| 110 | + "cwd": "${command:extension.vscode-wsl-workspaceFolder}", |
| 111 | + "environment": [], |
| 112 | + "externalConsole": false, |
| 113 | + "MIMode": "gdb", |
| 114 | + "miDebuggerPath": "/usr/bin/gdb", |
| 115 | + "pipeTransport": { |
| 116 | + "pipeProgram": "C:\\Windows\\Sysnative\\bash.exe", |
| 117 | + "pipeArgs": ["-c"], |
| 118 | + "debuggerPath": "/usr/bin/gdb" |
| 119 | + }, |
| 120 | + "setupCommands": [ |
| 121 | + { |
| 122 | + "description": "Enable pretty-printing for gdb", |
| 123 | + "text": "-enable-pretty-printing", |
| 124 | + "ignoreFailures": true |
| 125 | + } |
| 126 | + ], |
| 127 | + "sourceFileMap": { |
| 128 | + "/mnt/d": "d:\\" |
| 129 | + } |
| 130 | + } |
| 131 | + ] |
| 132 | + } |
| 133 | + ``` |
| 134 | +Note that this task works under Windows only. Here's a detailed explanation of each line in the above file: |
| 135 | + |
| 136 | +- `"name": "WSL Debug"` |
| 137 | + Name shown in the Run and Debug panel in VS Code when selecting which debug configuration to run. |
| 138 | + |
| 139 | +- `"type": "cppdbg"` |
| 140 | + Debugger type (debugger backend to use), where `cppdbg` is for C++ using the Microsoft C/C++ debugger extension (ms-vscode.cpptools) which supports **gdb**, **lldb** and **Microsoft's C++ debugger**. |
| 141 | + |
| 142 | +- `"request": "launch"` |
| 143 | + This is a "launch" request (i.e., start the program), as opposed to an "attach" request (attach to a running process). |
| 144 | + |
| 145 | +- `"program": "${command:extension.vscode-wsl-workspaceFolder}/build/GNUMake/bin/test.exe"` |
| 146 | + Path to the executable you want to debug, here using: `${command:extension.vscode-wsl-workspaceFolder}` which resolves to the WSL-style path of your workspace folder (e.g., `/mnt/d/Projects/...`), even if VS Code is running in Windows mode. This avoids issues with backslashes in `${workspaceFolder}` when used across Windows/WSL boundaries. |
| 147 | + |
| 148 | +- `"args": []` |
| 149 | + An array of command-line arguments passed to the program being debugged. |
| 150 | + |
| 151 | +- `"stopAtEntry": false` |
| 152 | + If `true`, the debugger pauses at the program entry point (`main()`); if `false`, it runs until the first breakpoint or program termination. |
| 153 | + |
| 154 | +- `"cwd": "${command:extension.vscode-wsl-workspaceFolder}/test"` |
| 155 | + The current working directory of the launched program. Again, using the WSL path of the workspace. |
| 156 | + |
| 157 | +- `"environment": []` |
| 158 | + Set any environment variables to use during the debugging session. Empty means use the default environment. |
| 159 | + |
| 160 | +- `"externalConsole": false` |
| 161 | + If `true`, launches a new terminal window for input/output; false uses VS Code's built-in terminal. |
| 162 | + |
| 163 | +- `"MIMode": "gdb"` |
| 164 | + - Specifies the debugger engine, `gdb` in this case. |
| 165 | + - Enables the machine interface protocol (MI) that VS Code uses to communicate with GDB (i.e., structured messages, not plain CLI). |
| 166 | + - Used with GDB in Linux/WSL environments. |
| 167 | + |
| 168 | +- `"miDebuggerPath": "/usr/bin/gdb"` |
| 169 | + Absolute path to GDB inside WSL. |
| 170 | + |
| 171 | +- ```json |
| 172 | + "pipeTransport": { |
| 173 | + "pipeProgram": "C:\\Windows\\Sysnative\\bash.exe", |
| 174 | + "pipeArgs": ["-c"], |
| 175 | + "debuggerPath": "/usr/bin/gdb" |
| 176 | + } |
| 177 | + ``` |
| 178 | + - This section tells VS Code to run GDB inside WSL, even if VS Code is running on Windows: |
| 179 | + - `"pipeProgram": "C:\\Windows\\Sysnative\\bash.exe"`: This launches the WSL environment from Windows in a low-level way that works even from 32-bit VS Code. |
| 180 | + - `"pipeArgs": ["-c"]`: Tells bash to treat the next string as a shell command. |
| 181 | + - `"debuggerPath": "/usr/bin/gdb"`: The command `bash -c "/usr/bin/gdb"` gets executed in WSL to start the debugger. |
| 182 | + |
| 183 | +- ```json |
| 184 | + "setupCommands": [ |
| 185 | + { |
| 186 | + "description": "Enable pretty-printing for gdb", |
| 187 | + "text": "-enable-pretty-printing", |
| 188 | + "ignoreFailures": true |
| 189 | + } |
| 190 | + ] |
| 191 | + ``` |
| 192 | + This sends a GDB command at startup to enable pretty-printing of STL containers, useful for C++ debugging. |
| 193 | + |
| 194 | +- ```json |
| 195 | + "sourceFileMap": { |
| 196 | + "/mnt/c": "c:\\", |
| 197 | + "/mnt/d": "d:\\" |
| 198 | + } |
| 199 | + ``` |
| 200 | + Tells VS Code how to map paths between WSL (Linux) and Windows. For example, when GDB says `"breakpoint at /mnt/d/Project/file.cpp"`, VS Code can find and open `d:\Project\file.cpp`. |
0 commit comments