jcs.org
Serenity Operating System
1# Visual Studio Code Project Configuration
2
3Visual Studio Code requires some configuration files, and a tailored ``settings.json`` file to understand serenity.
4
5The WSL Remote extension allows you to use VS Code in Windows while using the normal WSL workflow. This works well, but for code comprehension speed you should put the Serenity directory on your WSL root partition.
6
7The recommended extensions for VS Code include:
8
9- [clangd](https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd)
10- [clang-format](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format)
11- [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)
12
13## Code comprehension
14
15Clangd has the best support for cross-compiling workflows, especially if configured as noted below. The Microsoft C/C++ tools can work, but require a lot more configuration and may not understand the sysroot in use.
16
17### clangd
18
19The official clangd extension can be used for C++ comprehension. It is recommended in general, as it is most likely to work on all platforms.
20
21clangd uses ``compile_commands.json`` files to understand the project. CMake will generate these in either Build/x86_64, Build/x86_64clang, and Build/lagom.
22Depending on which configuration you use most, set the CompilationDatabase configuration item in the below ``.clangd`` file accordingly. It goes at the root of your checkout (``serenity/.clangd``):
23
24```yaml
25CompileFlags:
26 Add: [-D__serenity__]
27 CompilationDatabase: Build/x86_64
28```
29
30Run ``./Meta/serenity.sh run`` at least once to generate the ``compile_commands.json`` file.
31
32In addition to the ``.clangd`` file, the ``settings.json`` file below has a required ``clangd.arguments`` entry for ``--query-driver`` that allows clangd to find the cross-compiler's built-in include paths.
33
34#### Known issues
35
36- Some distribution clangd packages still have issues identifying paths to the serenity cross-compilers' builtin include paths after supplying the ``--query-driver`` option from ``settings.json``. This has been seen on at least Debian. If the inlay hints suggest that ``<new>`` cannot be found, first triple check your configuration matches the ``.clangd`` file from this section, verify that you've run the OS via ``Meta/serenity.sh run``, and quadruple check your ``clangd.arguments`` section in the project-local ``settings.json`` file. If all of the above are correct, building ``clangd`` from the serenity clang toolchain is known to work. See [AdvancedBuildInstructions](AdvancedBuildInstructions.md#serenity-aware-clang-tools) for steps on how to build it from source. After building from source, be sure to set ``clangd.path`` in your ``settings.json`` to ``${workspaceFolder}/Toolchain/Local/clang/bin/clangd``.
37
38- clangd has a tendency to crash when stressing bleeding edge compiler features. You can usually just restart it via the command palette. If that doesn't help, close currently open C++ files and/or switch branches before restarting, which helps sometimes.
39
40### DSL syntax highlighting
41
42There's a syntax highlighter extension for SerenityOS DSLs called "SerenityOS DSL Syntax Highlight", available [here](https://marketplace.visualstudio.com/items?itemName=kleinesfilmroellchen.serenity-dsl-syntaxhighlight) or [here](https://open-vsx.org/extension/kleinesfilmroellchen/serenity-dsl-syntaxhighlight).
43The extension provides syntax highlighting for LibIPC's IPC files, LibGUI's GUI Markup Language (GML), [Web IDL](https://webidl.spec.whatwg.org/), and LibJS's
44serialization format (no extension) as output by js with the -d option.
45
46### Microsoft C/C++ tools
47
48This extension can be used as-is, but you need to point it to the custom Serenity compilers. Note that enabling the extension in the same workspace as the
49clangd and clang-format extensions will cause conflicts. If you choose to use Microsoft C/C++ Tools rather than clangd and clang-format, use the
50following ``c_cpp_properties.json`` to circumvent some errors. Even with the configuration in place, the extension will likely still report errors related to types and methods not being found.
51
52<details>
53<summary>.vscode/c_cpp_properties.json</summary>
54
55```json
56{
57 "configurations": [
58 {
59 "name": "userland-x86_64-gcc",
60 "includePath": [
61 "${workspaceFolder}",
62 "${workspaceFolder}/Build/x86_64/",
63 "${workspaceFolder}/Build/x86_64/Userland",
64 "${workspaceFolder}/Build/x86_64/Userland/Applications",
65 "${workspaceFolder}/Build/x86_64/Userland/Libraries",
66 "${workspaceFolder}/Build/x86_64/Userland/Services",
67 "${workspaceFolder}/Build/x86_64/Root/usr/include/**",
68 "${workspaceFolder}/Userland",
69 "${workspaceFolder}/Userland/Libraries",
70 "${workspaceFolder}/Userland/Libraries/LibC",
71 "${workspaceFolder}/Userland/Services",
72 "${workspaceFolder}/Toolchain/Local/x86_64/x86_64-pc-serenity/include/c++/**"
73 ],
74 "defines": [
75 "DEBUG",
76 "__serenity__"
77 ],
78 "compilerPath": "${workspaceFolder}/Toolchain/Local/x86_64/bin/x86_64-pc-serenity-g++",
79 "cStandard": "c17",
80 "cppStandard": "c++20",
81 "intelliSenseMode": "linux-gcc-x86",
82 "compileCommands": "Build/x86_64/compile_commands.json",
83 "compilerArgs": [
84 "-Wall",
85 "-Wextra",
86 "-Werror"
87 ],
88 "browse": {
89 "path": [
90 "${workspaceFolder}",
91 "${workspaceFolder}/Build/x86_64/",
92 "${workspaceFolder}/Build/x86_64/Userland",
93 "${workspaceFolder}/Build/x86_64/Userland/Applications",
94 "${workspaceFolder}/Build/x86_64/Userland/Libraries",
95 "${workspaceFolder}/Build/x86_64/Userland/Services",
96 "${workspaceFolder}/Build/x86_64/Root/usr/include/**",
97 "${workspaceFolder}/Userland",
98 "${workspaceFolder}/Userland/Libraries",
99 "${workspaceFolder}/Userland/Libraries/LibC",
100 "${workspaceFolder}/Userland/Services",
101 "${workspaceFolder}/Toolchain/Local/x86_64/x86_64-pc-serenity/include/c++/**"
102 ],
103 "limitSymbolsToIncludedHeaders": true,
104 "databaseFilename": "${workspaceFolder}/Build/x86_64/"
105 }
106 }
107 ],
108 "version": 4
109}
110```
111</details>
112
113## Formatting
114
115The [clang-format extension](https://marketplace.visualstudio.com/items?itemName=xaver.clang-format) works out of the box. ``clang-format`` support is also included with the Microsoft C/C++ tools (see above). The settings below include a key that makes the Microsoft extension use the proper style.
116
117## Settings
118
119These belong in the `.vscode/settings.json` of Serenity.
120
121```json
122{
123 // Excluding the generated directories keeps your file view clean and speeds up search.
124 "files.exclude": {
125 "**/.git": true,
126 "Toolchain/Local/**": true,
127 "Toolchain/Tarballs/**": true,
128 "Toolchain/Build/**": true,
129 "Build/**": true,
130 "build/**": true,
131 },
132 "search.exclude": {
133 "**/.git": true,
134 "Toolchain/Local/**": true,
135 "Toolchain/Tarballs/**": true,
136 "Toolchain/Build/**": true,
137 "Build/**": true,
138 "build/**": true,
139 },
140 // Force clang-format to respect Serenity's .clang-format style file. This is not necessary if you're not using the Microsoft C++ extension.
141 "C_Cpp.clang_format_style": "file",
142 // Tab settings
143 "editor.tabSize": 4,
144 "editor.useTabStops": false,
145 // format trailing new lines
146 "files.trimFinalNewlines": true,
147 "files.insertFinalNewline": true,
148 // git commit message length
149 "git.inputValidationLength": 72,
150 "git.inputValidationSubjectLength": 72,
151 // Tell clangd to ask the cross-compilers for their builtin include paths
152 "clangd.arguments": [
153 "--query-driver=${workspaceFolder}/Toolchain/Local/**/*",
154 "--header-insertion=never" // See https://github.com/clangd/clangd/issues/1247
155 ]
156}
157```
158
159## Customization
160
161### Custom Tasks
162
163You can create custom tasks (`.vscode/tasks.json`) to quickly compile Serenity.
164The following three example tasks should suffice in most situations, and allow you to specify the build system to use, as well as give you error highlighting.
165
166Note: The Assertion und KUBSan Problem matchers will only run after you have closed qemu.
167
168<details>
169<summary>.vscode/tasks.json</summary>
170
171```json
172{
173 "version": "2.0.0",
174 "tasks": [
175 {
176 "label": "build lagom",
177 "type": "shell",
178 "problemMatcher": [
179 {
180 "base": "$gcc",
181 "fileLocation": [
182 "relative",
183 "${workspaceFolder}/Build/lagom"
184 ]
185 }
186 ],
187 "command": [
188 "bash"
189 ],
190 "args": [
191 "-c",
192 "\"Meta/serenity.sh build lagom\""
193 ],
194 "presentation": {
195 "echo": true,
196 "reveal": "always",
197 "focus": false,
198 "group": "build",
199 "panel": "shared",
200 "showReuseMessage": true,
201 "clear": true
202 }
203 },
204 {
205 "label": "build",
206 "type": "shell",
207 "command": "bash",
208 "args": [
209 "-c",
210 "Meta/serenity.sh build ${input:arch} ${input:compiler}"
211 ],
212 "problemMatcher": [
213 {
214 "base": "$gcc",
215 "fileLocation": [
216 "relative",
217 // FIXME: Clang uses ${input:arch}clang
218 "${workspaceFolder}/Build/${input:arch}"
219 ]
220 },
221 {
222 "source": "gcc",
223 "fileLocation": [
224 "relative",
225 // FIXME: Clang uses ${input:arch}clang
226 "${workspaceFolder}/Build/${input:arch}"
227 ],
228 "pattern": [
229 {
230 "regexp": "^([^\\s]*\\.S):(\\d*): (.*)$",
231 "file": 1,
232 "location": 2,
233 "message": 3
234 }
235 ]
236 }
237 ],
238 "group": {
239 "kind": "build",
240 "isDefault": true
241 }
242 },
243 {
244 "label": "launch",
245 "type": "shell",
246 "command": "bash",
247 "args": [
248 "-c",
249 "Meta/serenity.sh run ${input:arch} ${input:compiler}"
250 ],
251 "options": {
252 "env": {
253 // Put your custom run configuration here, e.g. SERENITY_RAM_SIZE
254 }
255 },
256 "problemMatcher": [
257 {
258 "base": "$gcc",
259 "fileLocation": [
260 "relative",
261 // FIXME: Clang uses ${input:arch}clang
262 "${workspaceFolder}/Build/${input:arch}"
263 ]
264 },
265 {
266 "source": "gcc",
267 "fileLocation": [
268 "relative",
269 // FIXME: Clang uses ${input:arch}clang
270 "${workspaceFolder}/Build/${input:arch}"
271 ],
272 "pattern": [
273 {
274 "regexp": "^([^\\s]*\\.S):(\\d*): (.*)$",
275 "file": 1,
276 "location": 2,
277 "message": 3
278 }
279 ]
280 },
281 {
282 "source": "KUBSan",
283 "owner": "cpp",
284 "fileLocation": [
285 "relative",
286 "${workspaceFolder}"
287 ],
288 "pattern": [
289 {
290 "regexp": "KUBSAN: (.*)",
291 "message": 0
292 },
293 {
294 "regexp": "KUBSAN: at ../(.*), line (\\d*), column: (\\d*)",
295 "file": 1,
296 "line": 2,
297 "column": 3
298 }
299 ]
300 },
301 {
302 "source": "Assertion Failed",
303 "owner": "cpp",
304 "pattern": [
305 {
306 "regexp": "ASSERTION FAILED: (.*)$",
307 "message": 1
308 },
309 {
310 "regexp": "^((?:.*)\\.(h|cpp|c|S)):(\\d*)$",
311 "file": 1,
312 "location": 3
313 }
314 ],
315 "fileLocation": [
316 "relative",
317 // FIXME: Clang uses ${input:arch}clang
318 "${workspaceFolder}/Build/${input:arch}"
319 ]
320 }
321 ]
322 }
323 ],
324 "inputs": [
325 {
326 "id": "compiler",
327 "description": "Compiler to use",
328 "type": "pickString",
329 "default": "GNU",
330 "options": [
331 "GNU",
332 "Clang"
333 ]
334 },
335 {
336 "id": "arch",
337 "description": "Architecture to compile for",
338 "type": "pickString",
339 "default": "x86_64",
340 "options": [
341 "x86_64",
342 "aarch64"
343 ]
344 }
345 ]
346}
347```
348
349</details>
350
351### License snippet
352
353The following snippet may be useful if you want to quickly generate a license header, put it in `.vscode/serenity.code-snippets`:
354```json
355{
356 "License": {
357 "scope": "cpp,c",
358 "prefix": "license",
359 "body": [
360 "/*",
361 " * Copyright (c) $CURRENT_YEAR, ${1:Your Name} <${2:YourName@Email.com}>.",
362 " *",
363 " * SPDX-License-Identifier: BSD-2-Clause",
364 " */"
365 ],
366 "description": "License header"
367 }
368}
369```