이 출시되었습니다! 11월의 새로운 기능 및 수정 사항을 읽어보세요.

C++ 확장 설정 참조

C++ 확장 설정은 구성 가능성이 높습니다. 이 문서는 c_cpp_properties.json 파일의 스키마를 설명합니다. VS Code의 설정에 대한 일반 정보는 설정 구성, 변수 참조 및 기본 VS Code 설정을 참조하세요.

C++ 프로젝트 구성 시작 방법을 찾고 계신가요? IntelliSense 구성부터 시작하세요.

변수 예제

다음 JSON 스니펫은 c_cpp_properties.json의 구성 예제입니다. JSON 파일에는 관련 변수만 포함하면 되며, 누락된 필드는 C++ 확장에 의해 기본값으로 채워집니다.

{
  "env": {
    "myIncludePath": ["${workspaceFolder}/include", "${workspaceFolder}/src"],
    "myDefines": ["DEBUG", "MY_FEATURE=1"]
  },
  "configurations": [
    {
      "name": "Mac",
      "compilerPath": "/usr/bin/clang++",
      "intelliSenseMode": "macos-clang-x64",
      "includePath": ["${myIncludePath}", "${workspaceFolder}/**"],
      "defines": ["${myDefines}"],
      "cStandard": "c17",
      "cppStandard": "c++20",
      "macFrameworkPath": ["/System/Library/Frameworks", "/Library/Frameworks"],
      "browse": {
        "path": ["${myIncludePath}", "${workspaceFolder}"]
      }
    }
  ],
  "version": 4,
  "enableConfigurationSquiggles": true
}

최상위 속성

  • env: 표준 환경 변수 구문: ${<var>} 또는 ${env:<var>}를 통해 구성에서 대체할 수 있는 사용자 정의 변수의 배열입니다. 문자열 및 문자열 배열이 허용됩니다.

  • configurations: IntelliSense 엔진에 프로젝트 및 기본 설정에 대한 정보를 제공하는 구성 객체의 배열입니다. 기본적으로 확장은 운영 체제를 기반으로 구성을 생성합니다. 더 많은 구성을 추가할 수도 있습니다.

  • version: 이 필드는 수정하지 않는 것이 좋습니다. c_cpp_properties.json 파일의 현재 버전을 추적하므로 확장이 어떤 속성과 설정이 존재해야 하는지, 그리고 이 파일을 최신 버전으로 업그레이드하는 방법을 알 수 있습니다.

  • enableConfigurationSquiggles: c_cpp_properties.json 파일에서 감지된 오류를 C++ 확장으로 보고하려면 true로 설정합니다.

구성 속성

  • name: 구성을 식별하는 사용자 친화적인 이름입니다. Linux, Mac, Win32는 해당 플랫폼에서 자동으로 선택되는 구성을 위한 특별 식별자입니다. VS Code의 상태 표시줄에 활성 구성이 표시됩니다. 상태 표시줄의 레이블을 선택하여 활성 구성을 변경할 수도 있습니다.

  • compilerPath: 프로젝트 빌드에 사용하는 컴파일러의 전체 경로입니다. 예를 들어 /usr/bin/gcc는 더 정확한 IntelliSense를 활성화합니다. 이 확장은 컴파일러를 쿼리하여 IntelliSense에 사용할 시스템 포함 경로 및 기본 정의를 결정합니다.

    "compilerPath": ""(빈 문자열)을 지정하면 컴파일러 쿼리가 건너뜁니다. 선호하는 컴파일러가 쿼리에 사용되는 인수를 지원하지 않는 경우 유용하며, 이 경우 확장은 찾을 수 있는 지원되는 컴파일러(예: MSVC)로 기본 설정됩니다. compilerPath 속성을 생략해도 쿼리가 건너뛰지 않습니다.

  • compilerArgs: 포함 경로 또는 정의에 사용할 컴파일러 인수를 수정합니다. 예를 들어 -nostdinc++, -m32 등입니다. 추가 공백으로 구분되는 인수를 사용하는 인수는 배열에 별도의 인수로 입력해야 합니다. 예를 들어 --sysroot <arg>의 경우 \"--sysroot\", \"<arg>\"를 사용합니다.

  • intelliSenseMode: MSVC, gcc 또는 Clang의 아키텍처별 변형에 매핑되는 IntelliSense 모드입니다. 설정되지 않았거나 ${default}로 설정된 경우 해당 플랫폼의 기본값을 사용합니다.

    플랫폼 기본값

    • Windows: windows-msvc-x64
    • Linux: linux-gcc-x64
    • macOS: macos-clang-x64

    <compiler>-<architecture> 변형만 지정하는 IntelliSense 모드(예: gcc-x64)는 레거시 모드이며 호스트 플랫폼에 따라 <platform>-<compiler>-<architecture> 변형으로 자동 변환됩니다.

  • includePath: 포함 경로는 소스 파일에 포함되는 헤더 파일의 디렉터리입니다. 예를 들어 소스 파일에 #include "myHeaderFile.h" 포함 지시문이 있는 경우 이 헤더 파일의 경로를 includePath에 추가합니다. IntelliSense 엔진이 포함된 헤더 파일을 검색하는 동안 사용할 경로 목록을 지정합니다. 이러한 경로의 검색은 재귀적이지 않습니다. 경로 끝에 /**를 지정하여 재귀적 검색을 나타냅니다. 예를 들어 ${workspaceFolder}/**는 모든 하위 디렉터리를 검색하는 반면 ${workspaceFolder}는 그렇지 않습니다. Visual Studio가 설치된 Windows를 사용하거나 compilerPath 설정에 컴파일러가 지정된 경우 시스템 포함 경로는 여기에 나열되지 않아야 합니다.

  • defines: IntelliSense 엔진이 파일을 구문 분석하는 동안 사용할 전처리기 정의 목록입니다. 선택적으로 =를 사용하여 값을 설정할 수 있습니다. 예를 들어 VERSION=1입니다.

  • cStandard: IntelliSense에 사용할 C 언어 표준 버전입니다. 예를 들어 c17, gnu23 또는 ${default}입니다. 참고: GNU 표준은 설정된 컴파일러를 쿼리하여 GNU 정의를 가져오는 데만 사용되며, IntelliSense는 해당 C 표준 버전을 에뮬레이트합니다.

  • cppStandard: IntelliSense에 사용할 C++ 언어 표준 버전입니다. 예를 들어 c++20, gnu++23 또는 ${default}입니다. 참고: GNU 표준은 설정된 컴파일러를 쿼리하여 GNU 정의를 가져오는 데만 사용되며, IntelliSense는 해당 C++ 표준 버전을 에뮬레이트합니다.

  • configurationProvider: 소스 파일에 대한 IntelliSense 구성 정보를 제공할 수 있는 VS Code 확장 ID입니다. 예를 들어 VS Code 확장 ID ms-vscode.cmake-tools를 사용하여 CMake Tools 확장에서 구성 정보를 제공합니다. configurationProvider를 지정한 경우 제공하는 구성은 c_cpp_properties.json의 다른 설정보다 우선합니다.

    configurationProvider 후보 확장은 vscode-cpptools-api를 구현해야 합니다.

  • mergeConfigurations: 구성 제공자의 포함 경로, 정의 및 강제 포함을 병합하려면 true로 설정합니다.

  • windowsSdkVersion: Windows에서 사용할 Windows SDK 포함 경로의 버전입니다. 예를 들어 10.0.17134.0입니다.

  • macFrameworkPath: Mac 프레임워크의 포함된 헤더를 검색하는 동안 IntelliSense 엔진이 사용할 경로 목록입니다.

  • forcedInclude: 소스 파일의 모든 텍스트가 처리되기 전에 포함되어야 하는 파일 목록입니다. 파일은 나열된 순서대로 포함됩니다.

  • compileCommands: 작업 영역에 대한 compile_commands.json 파일의 전체 경로를 포함하는 경로 배열입니다. 편집기에서 열린 파일에 대해 compile_commands.json에 일치하는 항목이 있는 경우 해당 명령줄이 c_cpp_properties.json의 다른 필드 대신 해당 파일의 IntelliSense를 구성하는 데 사용됩니다. 파일 형식에 대한 자세한 내용은 Clang 설명서를 참조하세요. CMake와 같은 일부 빌드 시스템은 이 파일 생성을 단순화합니다.

  • dotConfig: Kconfig 시스템에서 생성된 .config 파일의 경로입니다. Kconfig 시스템은 프로젝트 빌드에 필요한 모든 정의가 포함된 파일을 생성합니다. Kconfig 시스템을 사용하는 프로젝트의 예로는 Linux 커널 및 NuttX RTOS가 있습니다.

  • customConfigurationVariables: launch.json 또는 tasks.json의 입력 변수에 사용하기 위해 ${cpptools:activeConfigCustomVariable} 명령을 통해 쿼리할 수 있는 사용자 정의 변수입니다.

  • browse: 코드 베이스의 모든 기호를 식별하기 위해 IntelliSense와 함께 사용되는 속성 집합입니다. 이러한 속성은 **정의/선언으로 이동**, 전역 기호 검색 또는 "기본" IntelliSense 엔진이 소스 파일의 #includes를 확인하지 못하는 경우와 같은 기능에 사용됩니다.

  • recursiveIncludes: 재귀적 검색을 지정하는 includePath 항목을 확장이 처리하는 방법을 구성하는 데 사용되는 속성 집합입니다.

탐색 속성

  • path: 전역 기호 검색에 사용하기 위해 구문 분석할 소스 파일의 경로 목록입니다. 생략하면 includePath가 path로 사용됩니다. 이러한 경로의 검색은 기본적으로 재귀적입니다. 경로 끝에 *를 지정하여 비재귀 검색을 나타냅니다. 예를 들어 ${workspaceFolder}는 모든 하위 디렉터리를 검색하는 반면 ${workspaceFolder}/*는 그렇지 않습니다.

  • limitSymbolsToIncludedHeaders: true이면 태그 파서가 ${workspaceFolder}의 소스 파일에 직접 또는 간접적으로 포함된 헤더 파일만 구문 분석합니다. false이면 태그 파서가 browse.path 목록에 지정된 모든 코드 파일을 구문 분석합니다.

  • databaseFilename: 생성된 기호 데이터베이스의 경로입니다. 이 속성은 확장에 작업 영역의 기본 저장 위치가 아닌 다른 위치에 작업 영역 기호 데이터베이스를 저장하도록 지시합니다. 상대 경로가 지정된 경우 작업 영역 폴더 자체가 아니라 작업 영역의 기본 저장 위치에 상대적으로 지정됩니다. ${workspaceFolder} 변수는 작업 영역 폴더에 상대적인 경로를 지정하는 데 사용할 수 있습니다(예: ${workspaceFolder}/.vscode/browse.vc.db).

재귀적 포함 속성

  • reduce: 재귀적 includePath 항목이 확장되면 IntelliSense가 소스 파일의 #include 문을 확인하기 위해 처리해야 하는 포함 경로 집합이 매우 커질 수 있습니다. 많은 포함 경로를 IntelliSense 컴파일러로 보내면 일부 시스템에서 IntelliSense 성능에 영향을 줄 수 있습니다. 기본적으로 이 확장은 먼저 소스 파일을 태그 구문 분석하여 #include 문을 검색하고 필요한 포함 경로를 결정하여 가장 작은 가능한 집합으로 포함 경로 집합을 줄입니다. 이 축소 프로세스는 이 설정의 always 옵션과 동일한 동작입니다. 이 동작은 나중에 IntelliSense가 더 빨라질 수 있도록 초기 오버헤드를 일부 사용합니다. 이 속성을 never로 설정하면 IntelliSense 프로세스에 포함 경로의 전체 재귀적 확장을 제공합니다. 미리 파일을 구문 분석하지 않음으로써 이 동작은 소스 파일이 열릴 때 IntelliSense가 더 빨리 시작될 수 있도록 나중에 잠재적인 성능을 희생합니다. 일반적으로 구성에서 재귀적 포함 경로 수를 줄이면 많은 경로가 관련된 경우 IntelliSense 성능이 향상될 수 있습니다.

  • priority: #include 문을 확인할 때 재귀적 포함 경로 검색의 우선 순위입니다. beforeSystemIncludes로 설정하면 재귀적 포함 경로가 시스템 포함 경로 앞에 검색됩니다. afterSystemIncludes로 설정하면 재귀적 포함 경로가 시스템 포함 경로 뒤에 검색됩니다. beforeSystemIncludes는 컴파일러의 검색 순서를 더 가깝게 반영하여 예측 가능성을 높이는 반면, afterSystemIncludes는 성능 향상으로 이어질 수 있습니다.

  • order: 재귀적 포함의 하위 디렉터리가 breadthFirst 또는 depthFirst로 검색되는지 여부입니다.

지원되는 변수

tasks.json 또는 launch.json에서 c_cpp_properties.json의 현재 활성 구성을 쿼리할 수 있습니다. 이를 위해 tasks.json 또는 launch.json 스크립트의 인수로 변수 ${command:cpptools.activeConfigName}을 사용합니다.

기본 VS Code 설정

C_Cpp.default.includePath와 같은 모든 기본 VS Code 설정은 c_cpp_properties.json에서 지원됩니다. 유일한 예외는

C_Cpp.default.systemIncludePath : string[]

이 설정은 시스템 포함 경로를 포함 경로와 별도로 지정할 수 있도록 합니다. 그러나 C++ 확장이 컴파일러에서 받는 선택된 시스템 포함 경로는 IntelliSense 프로세스로 전달되지 않습니다. 이는 표준 컴파일러 동작을 덮어쓰는 드문 시나리오(예: 컴파일러가 지원되지 않는 경우)에만 사용됩니다. 대신 compilerArgs 설정을 사용하고 -isystem 플래그를 사용하여 시스템 헤더를 지정하는 것이 대부분의 시나리오에서 더 나은 해결책입니다.

4/25/2025
English 한국어 中文(简体)
© . This site is unofficial and not affiliated with Microsoft.