// ============================================================================
// devcontainer.json - VS Code Dev Containers configuration
// ----------------------------------------------------------------------------
// Tells the VS Code "Dev Containers" extension how to launch this project
// inside the Docker container defined by our docker-compose.yml. When you
// run "Dev Containers: Reopen in Container" from the command palette, VS
// Code uses this file to:
//   1. Reuse the existing docker-compose.yml / Dockerfile (no duplication)
//   2. Attach to the `pico-build` service and open /project as the workspace
//   3. Install clangd + CMake Tools INSIDE the container (so language servers
//      can see the real Pico SDK at /opt/pico-sdk)
//   4. Run CMake once after creation to generate compile_commands.json so
//      intellisense works from the moment the first file is opened
//
// NOTE: this file is JSONC (JSON with Comments + trailing commas allowed),
// which is why these // comments are legal.
// ============================================================================
{
    // Display name shown in the VS Code status bar / window title
    "name": "Color Switcher PICO",

    // Path to the docker-compose file, relative to THIS file.
    // .devcontainer/ is one level below the project root, so ../ reaches it.
    "dockerComposeFile": "../docker-compose.yml",

    // Which service in docker-compose.yml to attach to. We only have one.
    "service": "pico-build",

    // Folder inside the container to open as the VS Code workspace.
    // Must match the WORKDIR set in the Dockerfile.
    "workspaceFolder": "/project",

    // Runs exactly once, the first time the container is created. We invoke
    // CMake to configure the build so that compile_commands.json is written
    // to build/ before clangd tries to parse the first source file.
    "postCreateCommand": "cmake -S cmake -B build",

    "customizations": {
        "vscode": {
            // VS Code extensions installed INSIDE the container (not on the
            // host Mac). These run with access to /opt/pico-sdk and can
            // resolve all Pico SDK headers correctly.
            "extensions": [
                "llvm-vs-code-extensions.vscode-clangd",
                "ms-vscode.cmake-tools"
            ],

            // Arguments forwarded to clangd when it starts.
            //   --compile-commands-dir tells clangd where CMake wrote the
            //     compile_commands.json (inside build/, not the project root)
            //   --header-insertion=never stops clangd from auto-adding
            //     #include lines as you type, which tends to be noisy
            //   --background-index builds a project-wide symbol index in
            //     the background for fast go-to-definition / find-references
            "settings": {
                "clangd.arguments": [
                    "--compile-commands-dir=${workspaceFolder}/build",
                    "--header-insertion=never",
                    "--background-index"
                ]
            }
        }
    }
}