Include error for Homebrew packages (possibly due to symlinks)

[NemoYuan2008]

Environment

• OS and Version: macOS Sequoia 15.3 (Apple M3 chip)
• VS Code Version: 1.96.4 (Universal)
• C/C++ Extension Version: 1.23.5
• If using SSH remote, specify OS of remote machine: N/A

Bug Summary and Steps to Reproduce

Bug Summary:
Note: This issue is closely related to #13214. That issue is for Windows, while this is for macOS, but both are related to symlinks. I'd like to open this issue to provide some more info.

The extension cannot find the header files of Homebrew installed packages, even if /opt/homebrew/include is added to includePath.
By default, on Apple silicon machines, Homebrew installs the packages in /opt/homebrew/Cellar, and creates symlinks of the header files in /opt/homebrew/include. Hence, in general, it suffices to add /opt/homebrew/include to includePath. However, the extension is not able to find the symlinked directories, while it is able to find the symlinked files.

Steps to reproduce:

1. Use brew to install gmp and fmt (just for demonstration, can be any other package like boost, see below)

brew install gmp fmt

2. Ensure that /opt/homebrew/include contains the header files of gmp and fmt:

> ls -l /opt/homebrew/include | grep gmp
lrwxr-xr-x@ 1 yuan  admin  33  2  4 21:56 gmp.h -> ../Cellar/gmp/6.3.0/include/gmp.h
lrwxr-xr-x@ 1 yuan  admin  35  2  4 21:56 gmpxx.h -> ../Cellar/gmp/6.3.0/include/gmpxx.h

and

ls -l /opt/homebrew/include/fmt
lrwxr-xr-x@ 1 yuan  admin  32  2  4 21:59 /opt/homebrew/include/fmt -> ../Cellar/fmt/11.1.3/include/fmt

Note that /opt/homebrew/include/gmpxx.h is a symlink to a file, and /opt/homebrew/include/fmt is a symlink to a directory. (important)

3. create and open a new directory in VS Code, and create a file main.cpp with the following content

#include <iostream>
#include <gmpxx.h>      // OK
#include <fmt/format.h> // Error

int main() {
    fmt::print("Hello, World!\n");

    mpz_class a = 1;
    std::cout << a << std::endl;

    return 0;
}

4. Create .vscode/c_cpp_properties.json and add /opt/homebrew/include to includePath (see below for the full config file)
5. Observe that an #include error is reported for the line #include <fmt/format.h> (with red squiggly lines). However, no error for the line #include <gmpxx.h>. Note that both have symlinks in /opt/homebrew/include, but the former is a directory and the latter is a single file. (see Additional Context for screenshot).
6. However, if I Cmd+Click the line #include <fmt/format.h>, the editor is able to jump to the corresponding file.
7. To solve the problem, I have to manually add the actual path /opt/homebrew/Cellar/fmt/11.1.3/include to includePath.
   Note that the same error exists for libraries that have header files inside a directory, e.g., #include <boost/asio.hpp>, and can be reproduced with the same steps.

Configuration and Logs

Configurations in c_cpp_properties.json

{
    "configurations": [
        {
            "name": "Mac",
            "includePath": [
                "${workspaceFolder}/**",
                "/opt/homebrew/include"
            ],
            "defines": [],
            "macFrameworkPath": [
                "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/System/Library/Frameworks"
            ],
            "compilerPath": "/usr/bin/clang",
            "cStandard": "c17",
            "cppStandard": "c++17",
            "intelliSenseMode": "macos-clang-arm64"
        }
    ],
    "version": 4
}





Logs from running C/C++: Log Diagnostics from the VS Code command palette

-------- Diagnostics - 2025/2/4 22:55:33
Version: 1.23.5
Current Configuration:
{
    "name": "Mac",
    "includePath": [
        "/Users/yuan/projects/test/**",
        "/opt/homebrew/include"
    ],
    "defines": [],
    "macFrameworkPath": [
        "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/System/Library/Frameworks"
    ],
    "compilerPath": "/usr/bin/clang",
    "cStandard": "c17",
    "cppStandard": "c++17",
    "intelliSenseMode": "macos-clang-arm64",
    "compilerPathIsExplicit": true,
    "cStandardIsExplicit": true,
    "cppStandardIsExplicit": true,
    "intelliSenseModeIsExplicit": true,
    "compilerPathInCppPropertiesJson": "/usr/bin/clang",
    "mergeConfigurations": false,
    "browse": {
        "path": [
            "/Users/yuan/projects/test/**",
            "/opt/homebrew/include",
            "${workspaceFolder}"
        ],
        "limitSymbolsToIncludedHeaders": true
    }
}
Modified Settings:
{
    "C_Cpp.loggingLevel": "Debug"
}
Additional Tracked Settings:
{
    "editorTabSize": 4,
    "editorInsertSpaces": true,
    "editorAutoClosingBrackets": "languageDefined",
    "filesEncoding": "utf8",
    "filesAssociations": {},
    "filesExclude": {
        "**/.git": true,
        "**/.svn": true,
        "**/.hg": true,
        "**/CVS": true,
        "**/.DS_Store": true,
        "**/Thumbs.db": true
    },
    "filesAutoSaveAfterDelay": false,
    "editorInlayHintsEnabled": true,
    "editorParameterHintsEnabled": true,
    "searchExclude": {
        "**/node_modules": true,
        "**/bower_components": true,
        "**/*.code-search": true
    },
    "workbenchSettingsEditor": "ui"
}
cpptools version (native): 1.23.5.0
Current database path: /Users/yuan/Library/Caches/vscode-cpptools/c03c8c2de41af61c5fe2b81e358ac6f6/.browse.VC.db
Translation Unit Mappings:
[ /Users/yuan/projects/test/main.cpp - source TU]:
Translation Unit Configurations:
[ /Users/yuan/projects/test/main.cpp ]
    Process ID: 29721
    Memory Usage: 7 MB
    Compiler Path: /usr/bin/clang
    Includes:
        /opt/homebrew/include
    System Includes:
        /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include/c++/v1
        /Library/Developer/CommandLineTools/usr/lib/clang/16/include
        /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/usr/include
        /Library/Developer/CommandLineTools/usr/include
    Frameworks:
        /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/System/Library/Frameworks
    Standard Version: c++17
    IntelliSense Mode: macos-clang-arm64
    Other Flags:
        --clang
        --clang_version=170006
Total Memory Usage: 7 MB

------- Workspace parsing diagnostics -------
Number of files discovered (not excluded): 26017





Logs from the language server logging: it exceeds the space limit here, so I have attached it in `Other Extensions` field.

Other Extensions

Logs from the language server logging: language_server_logging.txt

Additional context

The screenshot of the error:

The screenshot of my /opt/homebrew/include directory

[Colengms]

Hi @NemoYuan2008 . Thanks for the detailed repro info. This looks to be the same issue as #13214 . I'm closing this as a duplicate.

[Colengms]

Re-opening. #13214 is Windows specific (and not yet something we've been able to repro). Using this to track the fix we have for Linux and macOS.