Proposed changes to `<context>.cbuild.yml` files

[ReinhardKeil]

The Problems To Be Solved

1. Problem: Clangd based Intellisense needs the location of compiler include files. Solution: add information about the compiler toolchain path used.

   NOTE: Problem 1. can be solved differently; no action in CMSIS-Toolbox

2. Problem: <context>.cbuild.yml files contain information about the build process on the local compiler, all other files of this category are in the out directory. Solution: locate <context>.cbuild.yml files in the releated out directory. Make paths absolute (see next item).

3. Problem: paths are relative, hence files are harder to locate as the base directory is somewhat dynamic in solutions that contain multiple projects. Solution: initally the plan was to use these files to achieve reproducible builds, however this is now achieved by *.cbuild-pack.yml. Therefore these files need no longer to be part of a repo commit. The need for relative paths is therefore diminished.

[brondani]

Some observations:

The <context>.cbuild.yml file together with *.cbuild-idx.yml and *.cbuild-set.yml contain input information for the build stage, where the outdir directory as the name suggests is intended for storing the build output files such as build artifacts. Storing the <context>.cbuild.yml in the outdir would mix the scopes, for example making it harder to clean build files.

The location of generated files is well defined taking as entry point the *.cbuild-idx.yml. I strongly advise against absolute paths in <context>.cbuild.yml because it spoils portability and separation of concerns between project and build stages. In addition portable <context>.cbuild.yml files are much easier to compare for debug purposes and are largely used as golden references in test cases.

---

Analyzing the fundamental clangd problem

It seems that for header files outside the file tree in VS Code, for instance files in packs, the clangd server is not able to find the configuration file .clangd and/or compile_commands.json. From https://clangd.llvm.org/config#files:

project configuration: a file named .clangd in the source tree. (clangd searches in all parent directories of the active file).

This is the VS Code clangd's OUTPUT window when for example the cmsis_os2.h is opened:

Failed to find compilation database for [...]\ARM\CMSIS\6.0.0\CMSIS\RTOS2\Include\cmsis_os2.h

---

Possible solution: when adding the --compile-commands-dir argument with the path to compile_commands.json in the clangd VS Code extension settings, intellisense works as expected.

Example of clangd settings in .vscode/settings.json:

{
    "clangd.arguments": [
        "--compile-commands-dir=c:/csolution-examples/Hello/out/Hello/AVH/Debug"
    ]
}

VS Code clangd's OUTPUT window:

Loaded compilation database from c:/csolution-examples/Hello/out/Hello/AVH/Debug\compile_commands.json
ASTWorker building file [...]\ARM\CMSIS\6.0.0\CMSIS\RTOS2\Include\cmsis_os2.h version 1 with command inferred from [...]\ARM\CMSIS\6.0.0\CMSIS\RTOS2\Source\os_systick.c

[brondani]

As I have explained in my previous comment I strongly advise against item 3 and I also disagree on item 2. If the goal of moving generated *.yml files is to keep the user workspace clean, in my opinion a better approach is to follow the behavior of the --output command line option where almost all generated files can be stored elsewhere, similarly to out-of-tree CMake builds that keeps source (-S) and build (-B) directories separately.

[ReinhardKeil]

1. is tracked in MCUTO-317

Leave this ticket open for now.