3.1.41. waf_tools.vscode

VS Code workspace generation tool for the Waf build system.

This waf tool automates the generation and configuration of Visual Studio Code workspace files (https://code.visualstudio.com/) for the foxBMS project. It produces IDE configuration files (c_cpp_properties.json, settings.json, tasks.json, launch.json) tailored to the active build variant so that IntelliSense, build tasks, and debugging work out of the box.

The tool supports multiple workspace variants, each targeting a different build configuration:

generic - General-purpose workspace for the foxBMS repository.
cli - Command-line-focused workspace.
app_ti_arm_cgt - Embedded application compiled with TI ARM CGT.
bootloader_ti_arm_cgt - Bootloader compiled with TI ARM CGT.
app_unit_test_gcc - Application unit tests compiled with GCC.
bootloader_unit_test_gcc - Bootloader unit tests compiled with GCC.

For each variant the tool resolves compiler built-in defines, include paths (including dynamic paths derived from the project configuration), and use dependency chains, then merges this information into the corresponding VS Code JSON configuration files. Template JSON files are read from tools/ide/vscode/<target>/ and patched in place.

3.1.41.1. Usage

Load the tool during configure:
```
def configure(ctx):
    ctx.load("vscode", tooldir=TOOLDIR)
```
The configure step locates the code executable, determines the platform-specific shell wrapper (pwsh on Windows, bash on Linux), and finds gcc/gdb for IntelliSense and debugging.
Run the vscode command to generate all workspaces at once:
```
waf vscode
```
Or generate individual workspaces:
```
waf vscode_app_ti_arm_cgt
waf vscode_app_unit_test_gcc
```

Declare a task generator with the vscode feature in a build script:

def build(bld):
    bld(
        features="vscode",
        target=<VS Code workspace variant>,
        vscode_dir=<Path to VS Code entry point as Node>,
        environment=<Waf build environment>,
        use_compiler_defines=<True/False>,
        use_dynamic_includes=<True/False>,
        include_dirs=<include paths>,   # e.g. ["src/app", "src/os"]
        glob_patterns=<include glob patterns>,   # e.g. ["src/app/**/"]
        glob_patterns_excl=<exclude glob patterns>,
        use_compiler_includes=<True/False>,
        pylint=<True/False>,
        python_extra_paths=<True/False>,
        files_exclude={<glob_pattern>: <True/False>}   # e.g. {".vscode/**": True}
        build_tasks=<True/False>,
        defines=<extra defines>,
    )

3.1.41.2. Dependencies

VS Code (code executable, optional)
GCC (used as dummy compilerPath for IntelliSense)
GDB (used for debug configurations in launch.json)
Platform shell: pwsh (Windows) or bash (Linux)
TI ARM CGT or GCC compiler configured in the respective build environment (for compiler built-in defines extraction)

Functions

`build_c_cpp_properties`(bld, vscode_dir, tg)	Patch `c_cpp_properties.json` with project-specific defines and includes.
`build_launch`(bld, vscode_dir)	Patch `launch.json` with debugger paths and program locations.
`build_settings`(bld, vscode_dir, tg)	Patch `settings.json` with project-specific editor settings.
`build_tasks`(bld, vscode_dir)	Patch `tasks.json` with platform-specific shell and wrapper commands.
`build_vscode`(bld)	Entry point that chains all VS Code workspace generation commands.
`build_vscode_app_ti_arm_cgt`(bld)	Generate the embedded app VS Code workspace configuration.
`build_vscode_app_unit_test_gcc`(bld)	Generate the app unit test VS Code workspace configuration.
`build_vscode_bootloader_ti_arm_cgt`(bld)	Generate the embedded bootloader VS Code workspace configuration.
`build_vscode_bootloader_unit_test_gcc`(bld)	Generate the bootloader unit test VS Code workspace configuration.
`build_vscode_cli`(bld)	Generate the CLI VS Code workspace configuration.
`build_vscode_generic`(bld)	Generate the generic VS Code workspace configuration.
`configure`(ctx)	Configure the waf build system for VS Code workspace generation.
`dump_json_to_node`(node, cfg)	Serialize a dictionary as pretty-printed JSON and write it to a node.
`find_vscode`(ctx)	Locate the VS Code `code` executable.
`get_compiler_builtin_defines`(tg)	Extract compiler built-in defines for the active toolchain.
`get_dynamic_include_paths`(bld, tg)	Assemble dynamic include paths based on the project configuration.
`get_fox_py_wrapper_executable`(ctx)	Locate the platform-specific `fox.py` wrapper script.
`get_hcg_includes`(halcogen)	Derive the TI F021 Flash API include path from the HALCoGen installation.
`get_use_includes`(bld, tg)	Recursively resolve include paths from `use` dependencies.
`get_vscode_relevant_defines`(...)	Convert raw `#define` lines into VS Code IntelliSense format.
`process_vscode`(self)	Process the `vscode` feature on a task generator.
`valid_configuration_files`(bld, base_cfg_dir)	Validate that all VS Code configuration files are valid JSON.

Classes

`VSCode`(**kw)	Build context for the `waf vscode` command.
`VSCodeAppTiArmCgt`(**kw)	Build context for `waf vscode_app_ti_arm_cgt`.
`VSCodeAppUnitTestGcc`(**kw)	Build context for `waf vscode_app_unit_test_gcc`.
`VSCodeBootloaderTiArmCgt`(**kw)	Build context for `waf vscode_bootloader_ti_arm_cgt`.
`VSCodeBootloaderUnitTestGcc`(**kw)	Build context for `waf vscode_bootloader_unit_test_gcc`.
`VSCodeCli`(**kw)	Build context for `waf vscode_cli`.
`VSCodeGeneric`(**kw)	Build context for `waf vscode_generic`.