Visual Studio에서 CMake 사전 설정으로 구성 및 빌드

아티클
06/09/2023

CMake는 사용자가 일반적인 구성, 빌드, 테스트 옵션을 지정하고 다른 사용자와 공유할 수 있도록 하는 CMakePresets.json 및 CMakeUserPresets.json의 두 파일을 지원합니다. 이러한 파일을 사용하여 Visual Studio, Visual Studio Code, CI(연속 통합) 파이프라인, 명령줄에서 CMake를 구동합니다.

CMakePresets.json은 프로젝트 차원의 빌드를 저장하는 데 사용할 수 있습니다. CMakeUserPresets.json은 개발자가 자체 로컬 빌드를 저장하기 위한 것입니다. 두 파일은 모두 Visual Studio 2019 버전 16.10 이상에서 지원됩니다.

이 문서에는 Visual Studio와의 CMakePresets.json 통합에 대한 정보가 포함되어 있습니다. 다음은 유용한 링크입니다.

CMakePresets.json의 형식에 대한 자세한 내용은 공식 CMake 설명서를 참조하세요.
Microsoft 공급업체 맵 및 매크로 확장에 대한 자세한 내용은 CMakePresets.json 및 CMakeUserPresets.json Microsoft 공급업체 맵을 참조하세요.
Visual Studio Code에서 CMakePresets.json을 사용하는 방법에 대한 자세한 내용은 Configure and build with CMake Presets(CMake 사전 설정으로 빌드 및 구성)를 참조하세요.

CMakeSettings.json의 대체로 CMakePresets.json이 권장됩니다. Visual Studio는 둘 다 CMakePresets.jsonCMakeSettings.json 에서 동시에 읽지 않습니다. Visual Studio에서 CMakePresets.json 통합을 사용하거나 사용하지 않도록 설정하려면 Visual Studio 2019에서 CMakePresets.json 사용을 참조하세요.

지원되는 CMake 및 `CMakePresets.json` 버전

지원되는 CMakePresets.json 스키 CMakeUserPresets.json 마 버전은 Visual Studio 버전에 따라 달라집니다.

Visual Studio 2019 버전 16.10 이상은 스키마 버전 2 및 3을 지원합니다.
Visual Studio 2022 버전 17.4 미리 보기 1은 스키마 버전 4에 대한 지원을 추가합니다.
Visual Studio 2022 버전 17.5 미리 보기 1은 스키마 버전 5에 대한 지원을 추가합니다.

루트 개체의 필드를 변경 "version" 하여 버전을 업데이트할 수 있습니다. 예제 및 자세한 내용은 CMakePresets.json 형식을 참조하세요.

명령줄에서 CMake를 호출하는 경우 CMake CMakePresets.json 버전 3.20 이상이 필요합니다. 그러나 Visual Studio는 CMakePresets.json 및 CMakeUserPresets.json 자체를 읽고 평가하며, --preset 옵션을 사용하여 CMake를 직접 호출하지는 않습니다. 즉, Visual Studio 내에서 CMakePresets.json으로 빌드할 때 CMake 버전 3.20 이상이 반드시 필요하지는 않습니다.

CMake 버전 3.14 이상을 사용하는 것이 좋습니다.

Visual Studio에서 통합 사용 `CMakePresets.json`

CMakePresets.json 통합은 Visual Studio에서 기본적으로 사용하도록 설정되지 않습니다. 도구>옵션>CMake>일반에서 사용하도록 설정할 수 있습니다.

Screenshot showing 'Always use CMakePresets.json' selected.

Important

Visual Studio에서 폴더를 닫았다가 다시 열어 통합을 활성화합니다.

일부 이전 버전의 Visual Studio에서 도구>옵션>CMake>General에는 통합을 사용하도록 설정하는 CMakePresets.json 단일 옵션만 있습니다.

Screenshot of an older version of Visual Studio. There is a checkbox labeled 'Use C Make Presets .json to drive CMake configure, build, and test.'

다음 표에서는 CMake 구성을 구동하고 Visual Studio 2022 및 Visual Studio 2019 버전 16.10 이상에서 빌드하는 대신 CMakeSettings.json 사용되는 시기를 CMakePresets.json 나타냅니다. 구성 파일이 없는 경우 기본 구성 사전 설정이 사용됩니다.

표에서 ‘도구>옵션 사용’은 도구>옵션>CMake>일반에서 Use CMakePresets.json to drive CMake configure, build, and test(CMakePresets.json을 사용하여 CMake 구성, 빌드, 테스트 구동)가 선택되어 있음을 의미합니다.

구성 파일	도구 > 옵션 사용 안 함	도구 > 옵션 사용
구성 파일 없음	`CMakeSettings.json`	`CMakePresets.json`
`CMakeSettings.json` 있음	`CMakeSettings.json`	`CMakePresets.json`
`CMakePresets.json` 있음	`CMakePresets.json`	`CMakePresets.json`
구성 파일 둘 다 있음	`CMakePresets.json`	`CMakePresets.json`

자동 구성 및 캐시 알림 수정

기본적으로 Visual Studio는 활성 대상 시스템이나 구성 사전 설정이 변경될 때마다 자동으로 configure를 호출합니다. 이 동작은 도구>옵션>CMake>일반에서 구성 단계를 자동으로 실행 안 함을 선택하여 수정할 수 있습니다. CMake 캐시 알림 표시를 선택 취소하여 모든 CMake 캐시 알림(금색 막대)을 사용하지 않도록 설정할 수도 있습니다.

기본 구성 사전 설정

파일이 없거나 CMakePresets.jsonCMakeUserPresets.json 파일이 없거나 잘못된 경우 CMakePresets.jsonCMakeUserPresets.json Visual Studio는 다음 기본 구성 사전 설정으로 대체됩니다.

Windows 예제

{
  "name": "windows-default",
  "displayName": "Windows x64 Debug",
  "description": "Sets Ninja generator, compilers, x64 architecture, build and install directory, debug build type",
  "generator": "Ninja",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "architecture": {
    "value": "x64",
    "strategy": "external"
  },
  "cacheVariables": {
    "CMAKE_BUILD_TYPE": "Debug",
    "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
  },
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": [ "Windows" ]
    }
  }
},

Linux 예제

{
  "name": "linux-default",
  "displayName": "Linux Debug",
  "description": "Sets Ninja generator, compilers, build and install directory, debug build type",
  "generator": "Ninja",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "cacheVariables": {
    "CMAKE_BUILD_TYPE": "Debug",
    "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
  },
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": [ "Linux" ]
    },
    "microsoft.com/VisualStudioRemoteSettings/CMake/1.0": {
      "sourceDir": "$env{HOME}/.vs/$ms{projectDirName}"
   }
  }
}

존재하지 않는 CMakePresets.json 파일을 열거나 수정하려고 하면 기본 구성 사전 설정을 사용하는 CMakePresets.json 파일이 Visual Studio에서 프로젝트의 루트에 자동으로 생성됩니다.

구성 및 빌드

Visual Studio 도구 모음에는 통합이 사용하도록 설정된 경우 CMakePresets.json 대상 시스템, 사전 설정 구성 및 빌드 사전 설정에 대한 드롭다운이 있습니다.

Screenshot showing the dropdowns for target system set to Local Machine, configuration set to windows-arm64, and build preset set to default.

대상 시스템 선택

왼쪽의 드롭다운 목록은 활성 대상 시스템을 나타냅니다. 이 시스템은 프로젝트를 구성하고 빌드하기 위해 CMake가 호출되는 시스템입니다. 이 드롭다운 목록에는 로컬 머신, 연결 관리자의 모든 SSH 연결(호스트 이름순), Visual Studio에서 찾을 수 있는 모든 WSL(Linux용 Windows 하위 시스템) 설치가 나열됩니다.

Screenshot of the Target System dropdown list

앞의 예에서:

192.168.0.5는 연결 관리자에 추가된 원격 Linux 시스템입니다.
ubuntu2004 및 debian은 WSL 설치입니다.

연결 관리를 선택하여 연결 관리자를 엽니다.

구성 사전 설정 선택

가운데의 드롭다운 목록은 활성 구성 사전 설정을 나타냅니다. 이 사전 설정은 프로젝트 빌드 시스템을 생성하기 위해 CMake가 호출될 때 사용되는 configurePreset 값입니다. 이 드롭다운 목록에는 CMakePresets.json 및 CMakeUserPresets.json에 정의된 숨겨지지 않은 구성 사전 설정이 나열됩니다.

Visual Studio는 Microsoft Visual Studio 설정 공급업체 맵의 hostOS 값을 사용하여 활성 대상 시스템에 적용되지 않는 사전 설정 구성을 숨깁니다. 자세한 내용은 Visual Studio 설정 공급업체 맵의 표에서 hostOS에 대한 항목을 참조하세요.

구성 관리를 선택하여 프로젝트의 루트에 있는 CMakePresets.json 파일을 엽니다. CMakePresets.json이 아직 없는 경우 새로 만들어집니다.

빌드 사전 설정 선택

오른쪽의 드롭다운 목록은 활성 빌드 사전 설정을 나타냅니다. 이 사전 설정은 프로젝트를 빌드하기 위해 CMake가 호출될 때 사용되는 buildPreset 값입니다. 이 드롭다운 목록에는 CMakePresets.json 및 CMakeUserPresets.json에 정의된 숨겨지지 않은 빌드 사전 설정이 나열됩니다.

연결된 configurePreset 값을 지정하려면 모든 빌드 사전 설정이 필요합니다. Visual Studio는 활성 구성 사전 설정에 적용되지 않는 빌드 사전 설정을 숨깁니다. 자세한 내용은 빌드 사전 설정 목록을 참조하세요.

활성 구성 사전 설정과 연결된 빌드 사전 설정이 없으면 Visual Studio에서 기본 빌드 사전 설정을 나열합니다. 기본 빌드 사전 설정은 명령줄에서 다른 인수 없이 cmake --build를 전달하는 것과 동일합니다.

구성

Visual Studio는 CMake 캐시가 만료된 것을 감지하면 자동으로 프로젝트를 구성하려고 합니다. 구성을 수동으로 호출하려면 기본 메뉴에서 프로젝트>구성 <프로젝트 이름을> 선택합니다. 이 동작은 명령줄에서 cmake --preset <configurePreset>을 실행하는 것과 동일합니다. 여기서 <configurePreset>은 활성 구성 사전 설정의 이름입니다.

자동 캐시 생성을 사용하지 않도록 설정하려면 자동 구성 및 캐시 알림을 참조하세요.

빌드

전체 프로젝트를 빌드하려면 주 메뉴에서 빌드>모두 빌드를 선택합니다. 이 동작은 명령줄에서 cmake --build --preset <buildPreset>을 실행하는 것과 동일합니다. 여기서 <buildPreset>은 활성 빌드 사전 설정의 이름입니다.

단일 대상을 빌드하려면 솔루션 탐색기에서 CMake 대상 뷰로 전환합니다. 그런 다음 대상을 마우스 오른쪽 단추로 클릭하고 바로 가기 메뉴에서 빌드를 선택합니다.

참고 항목

Visual Studio 2019는 CMakePresets.json에 지정된 대상의 하위 집합을 빌드하는 buildPresets.targets 옵션을 지원하지 않습니다.

CTest 실행

CMakePresets.json은 Visual Studio 2019에서 다음 두 가지 메뉴 옵션을 지원합니다.

프로젝트 이름>에 대한 <테스트>실행 CTest는 CTest를 호출하고 활성 구성 사전 설정 및 빌드 사전 설정과 연결된 모든 테스트를 실행하며 다른 인수는 CTest에 전달되지 않습니다.
configurePreset에 대한 <테스트>실행 테스트 사전 설정>이 확장되어 활성 구성 사전 설정과 연결된 모든 테스트 사전 설정이 표시됩니다. 단일 테스트 사전 설정 선택은 명령줄에서 ctest --preset <testPreset>을 실행하는 것과 동일합니다. 여기서 <testPreset>은 선택한 테스트 사전 설정의 이름입니다. 활성 구성 사전 설정에 대해 정의된 테스트 사전 설정이 없는 경우 이 옵션을 사용할 수 없습니다.

Visual Studio 2019에서는 테스트 탐색기가 CMakePresets.json과 통합되지 않습니다.

새 사전 설정 추가

Visual Studio 2019에서는 모든 명령 및 사전 설정 템플릿이 CMakePresets.json을 수정합니다. CMakeUserPresets.json을 직접 편집하여 새 사용자 수준 사전 설정을 추가할 수 있습니다.

CMakePresets.json 및 CMakeUserPresets.json의 경로에 슬래시(/)를 사용합니다.

새 구성 사전 설정 추가

CMakePresets.json에 새 구성 사전 설정을 추가하려면 솔루션 탐색기의 폴더 보기에서 CMakePresets.json을 마우스 오른쪽 단추로 클릭하고 바로 가기 메뉴에서 구성 추가를 선택합니다. 구성 사전 설정 템플릿을 선택하는 대화 상자가 나타납니다.

Screenshot of the Add Configure Preset to the JSON file dialog. It contains entries such as Linux Debug, macOS Debug, x64 Debug, and so on.

Windows 시스템에 구성하려면 Windows x64 Debug(Windows x64 디버그) 템플릿을 선택합니다. WSL 및 원격 Linux 시스템에 구성하려면 Linux Debug(Linux 디버그) 템플릿을 선택합니다. CMakePresets.json 편집에 대한 자세한 내용은 사전 설정 편집을 참조하세요.

선택한 템플릿이 있으면 CMakePresets.json에 추가됩니다. 그러지 않으면 템플릿이 새 CMakePresets.json 파일에 복사됩니다.

새 빌드 사전 설정 및 테스트 사전 설정 추가

Visual Studio 2019는 새 빌드 사전 설정 및 테스트 사전 설정에 대한 템플릿을 제공하지 않습니다. CMakePresets.json을 직접 편집하여 빌드 사전 설정 및 테스트 사전 설정을 추가할 수 있습니다. 자세한 내용은 빌드 사전 설정 목록, 테스트 사전 설정 목록 또는 예제 CMakePresets.json 파일을 참조하세요.

사전 설정 편집

공식 CMake 설명서는 구성 사전 설정, 빌드 사전 설정, 테스트 사전 설정 편집에 가장 적합한 리소스입니다. 다음 정보는 Visual Studio 개발자와 특별히 관련된 CMake 설명서의 일부입니다.

컴파일러 선택

구성 사전 설정의 cacheVariables.CMAKE_C_COMPILER 및 cacheVariables.CMAKE_CXX_COMPILER를 사용하여 C 및 C++ 컴파일러를 설정할 수 있습니다. 이 동작은 명령줄에서 CMake에 -D CMAKE_C_COMPILER=<value> 및 -D CMAKE_CXX_COMPILER=<value>를 전달하는 것과 동일합니다. 자세한 내용은 CMAKE_<LANG>_COMPILER를 참조하세요.

다음 예제를 사용하여 Visual Studio에서 cl.exe 및 clang-cl.exe를 사용하여 빌드합니다. clang-cl을 사용하여 빌드하려면 Windows용 C++ Clang 도구 구성 요소를 설치해야 합니다.

cl.exe를 사용하여 빌드

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "cl",
  "CMAKE_CXX_COMPILER": "cl"
},

clang를 사용하여 빌드

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "clang-cl",
  "CMAKE_CXX_COMPILER": "clang-cl"
},

"vendor": {
  "microsoft.com/VisualStudioSettings/CMake/1.0": {
    "intelliSenseMode": "windows-clang-x64"
  }
}

생성기 중 하나 Visual Studio 16 2019 또는 Visual Studio 17 2022 생성기를 사용하는 경우 구성 사전 설정을 사용하여 toolset 도구 집합을 ClangCL 지정할 수 있습니다.

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
},

"toolset": "ClangCL",

"vendor": {
  "microsoft.com/VisualStudioSettings/CMake/1.0": {
    "intelliSenseMode": "windows-clang-x64"
  }
}

사양을 지원하는 toolset 생성기에 대한 자세한 내용은 CMake 설명서를 참조 CMAKE_GENERATOR_TOOLSET 하세요.

Important

Visual Studio 2019에서는 clang 또는 clang-cl을 사용하여 빌드할 때 Clang IntelliSense 모드를 명시적으로 지정해야 합니다.

Visual Studio 외부에서 이러한 빌드를 재현하려면 명령줄 또는 CI 파이프라인에서 CMake 실행을 참조하세요.

Linux에서 빌드하거나 Visual C++ 도구 집합을 사용하지 않고 빌드하려면 PATH 또는 컴파일러의 전체 경로로 평가되는 환경 변수에 컴파일러의 이름을 지정합니다. 파일을 공유 가능한 상태로 유지할 수 있도록 전체 경로는 권장되지 않습니다. GCC 버전 8로 빌드되는 사전 설정은 다음과 같이 표시될 수 있습니다.

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "gcc-8",
  "CMAKE_CXX_COMPILER": "g++-8"
},

CMake 도구 체인 파일을 사용하여 컴파일러를 설정할 수도 있습니다. 도구 체인 파일은 cacheVariables.CMAKE_TOOLCHAIN_FILE로 설정할 수 있으며 명령줄에서 CMake에 -D CMAKE_TOOLCHAIN_FILE=<value>를 전달하는 것과 동일합니다. CMake 도구 체인 파일은 크로스 컴파일에 주로 사용됩니다. CMake 도구 체인 파일 작성에 대한 자세한 내용은 CMake toolchains(CMake 도구 체인)를 참조하세요.

생성기 선택

Windows 및 Linux 구성 사전 설정 템플릿은 모두 Ninja를 기본 생성기로 지정합니다. 다른 일반적인 생성기는 Windows의 Visual Studio Generators(Visual Studio 생성기)와 Linux 및 macOS의 Unix Makefiles입니다. 구성 사전 설정에서 generator 옵션을 사용하여 새 생성기를 지정할 수 있습니다. 이 동작은 명령줄에서 CMake에 -G를 전달하는 것과 동일합니다.

Visual Studio 생성기로 빌드하는 경우 architecture.strategy 및 toolset.strategy를 set으로 설정합니다. 자세한 내용은 CMake generators(CMake 생성기)를 참조하세요.

구성 형식 선택

cacheVariables.CMAKE_BUILD_TYPE을 사용하여 단일 구성 생성기에 대한 구성 형식(Debug 또는 Release)을 설정할 수 있습니다. 이 동작은 명령줄에서 CMake에 -D CMAKE_BUILD_TYPE=<value>를 전달하는 것과 동일합니다. 자세한 내용은 CMAKE_BUILD_TYPE를 참조하세요.

Visual C++ 도구 집합으로 빌드하는 경우 대상 및 호스트 아키텍처 선택

대상 아키텍처(x64, Win32, ARM64 또는 ARM)는 architecture.value를 사용하여 설정할 수 있습니다. 이 동작은 명령줄에서 CMake에 -A를 전달하는 것과 동일합니다. 자세한 내용은 Platform Selection(플랫폼 선택)을 참조하세요.

참고 항목

현재 x86용으로 빌드할 때 Visual Studio 생성기에는 Win32 구문이 필요하고 명령줄 생성기(예: Ninja)에는 x86 구문이 필요합니다.

toolset.value를 사용하여 호스트 아키텍처(x64 또는 x86) 및 도구 집합을 설정할 수 있습니다. 이 동작은 명령줄에서 CMake에 -T를 전달하는 것과 동일합니다. 자세한 내용은 Toolset Selection(도구 집합 선택)을 참조하세요.

architecture.strategy 및 toolset.strategy 값은 아키텍처 및 도구 집합 필드를 처리하는 방법을 CMake에 알려 줍니다. set 는 CMake가 해당 값을 설정하고 CMake external 가 해당 값을 설정하지 않음을 의미합니다.

Visual Studio 생성기와 같은 IDE 생성기를 사용하는 set 것이 좋습니다. external은 Ninja와 같은 명령줄 생성기에서 사용합니다. 이러한 값을 사용하여 Visual Studio 같은 공급업체에서 CMake를 호출하기 전에 필요한 환경을 제공할 수 있습니다. 아키텍처 및 도구 집합 필드에 대한 자세한 내용은 구성 사전 설정 목록을 참조하세요.

환경을 제공하지 않으려는 경우 architecture.strategy를 external로 설정하고 architecture.value를 unspecified로 설정할 수 있습니다. 다음과 같은 이유 중 하나로 환경을 제공하지 않는 것이 유용할 수 있습니다.

MSVC 이외의 도구 집합을 사용합니다.
포함된 시나리오에서와 같이 사용자 지정 도구 체인을 사용합니다.
빌드할 특정 환경이 필요하지 않습니다.

아키텍처 필드를 지원하는 IDE 생성기 전체 목록은 CMAKE_GENERATOR_PLATFORM을 참조하세요. 도구 집합 필드를 지원하는 IDE 생성기 전체 목록은 CMAKE_GENERATOR_TOOLSET를 참조하세요.

다음 예제를 사용하여 Ninja 생성기를 사용하는 ARM64 또는 Visual Studio 16 2019 생성기를 사용하는 Win32(x86)를 대상으로 합니다.

"generator": "Ninja",
"architecture": {
    "strategy": "external",
    "value": "arm64"
},

"generator": "Visual Studio 16 2019",
"architecture": {
    "strategy": "set",
     "value": "Win32"
},

환경 변수 설정 및 참조

환경 맵을 사용하여 환경 변수를 설정할 수 있습니다. 환경 변수는 inherits 필드를 통해 상속되지만 원하는 대로 재정의할 수 있습니다.

사전 설정의 환경은 자체 환경 및 모든 부모 환경을 합한 환경입니다. 여러 inherits 사전 설정에서 동일한 변수에 대해 충돌하는 값을 제공하는 경우 inherits 목록의 이전 사전 설정이 우선 적용됩니다. null로 설정하여 다른 사전 설정에서 상속된 변수를 설정 해제할 수 있습니다.

inheritConfigureEnvironment를 false로 설정하지 않으면 구성 사전 설정에 설정된 환경 변수는 연결된 빌드 사전 설정 및 테스트 사전 설정으로 자동으로 흐릅니다. 자세한 내용은 구성 사전 설정 목록을 참조하세요.

$env{<variable-name>} 및 $penv{<variable-name>} 구문을 사용하여 환경 변수를 참조할 수 있습니다. 자세한 내용은 Macro Expansion(매크로 확장)을 참조하세요.

크로스 컴파일러에 대해 IntelliSense 구성

기본적으로 Visual Studio는 지정한 도구 집합 및 대상 아키텍처와 일치하는 IntelliSense 모드를 사용합니다. 교차 컴파일을 수행하는 경우 Visual Studio 설정 공급업체 맵에서 intelliSenseMode 옵션을 사용하여 올바른 IntelliSense 모드를 수동으로 지정해야 할 수 있습니다. 자세한 내용은 Visual Studio 설정 공급업체 맵의 표에서 intelliSenseMode에 대한 항목을 참조하세요.

원격 시스템 또는 Linux용 Windows 하위 시스템에서 구성 및 빌드

Visual Studio의 CMakePresets.json 지원을 통해 Windows, WSL, 원격 시스템에서 프로젝트를 쉽게 구성하고 빌드할 수 있습니다. Windows, 원격 시스템 또는 WSL에서 프로젝트를 구성 및 빌드하는 단계는 동일합니다. 그러나 몇 가지 동작은 원격 개발과 관련이 있습니다.

원격 복사 시나리오의 `${sourceDir}` 동작

로컬 시나리오(WSL1 포함)에서 ${sourceDir}은 Visual Studio에 열려 있는 프로젝트 소스 디렉터리의 경로로 평가됩니다. 원격 복사 시나리오에서 ${sourceDir}은 로컬 머신의 프로젝트 소스 디렉터리가 아닌 대상 시스템의 프로젝트 소스 디렉터리 경로로 평가됩니다.

대상 시스템의 프로젝트 소스 디렉터리는 Visual Studio 원격 설정 공급업체 맵의 sourceDir 값에 따라 결정됩니다. 기본적으로 $env{HOME}/.vs/$ms{projectDirName}으로 설정됩니다. 자세한 내용은 Visual Studio 설정 공급업체 맵의 표에서 sourceDir에 대한 항목을 참조하세요.

원격 출력을 위한 로컬 폴더

Visual Studio 원격 설정 공급업체 맵의 copyBuildOutput이 true로 설정된 경우 원격 복사 시나리오에는 CMake File-API 응답 파일이나 빌드 파일과 같은 일부 원격 파일을 복사할 로컬 디렉터리가 필요합니다. 이러한 파일은 <local-source-directory>/out/<remote-connection-ID>/build/${presetName}으로 자동으로 복사됩니다.

Windows 및 WSL1에서 동일한 구성 사전 설정 호출

Windows 및 WSL1에서 동일한 구성 사전 설정을 사용하려고 하면 오류가 표시됩니다. Windows와 WSL1 모두 Windows 파일 시스템을 사용하므로 CMake는 Windows 및 WSL1 빌드 트리에 동일한 출력 디렉터리(binaryDir)를 사용하려고 합니다.

Windows와 WSL1 도구 집합에서 동일한 구성 사전 설정을 사용하려면 원래 사전 설정에서 상속되고 새 binaryDir 값을 지정하는 두 번째 구성 사전 설정을 만듭니다. 다음 예제에서는 windows-preset은 Windows에서 사용하고 base-preset은 WSL1에서 사용할 수 있습니다.

{
  "name": "windows-preset",
  "inherits": "base-preset",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": "Windows"
    }
  }
}

참고 항목

Visual Studio 2019에서는 WSL1 도구 집합만 지원됩니다. Windows 및 WSL 모두에서 configure를 호출할 때마다 이 동작이 표시됩니다.

vcpkg 통합 사용

vcpkg는 Windows, Linux, macOS에서 C 및 C++ 라이브러리를 관리하는 데 도움이 됩니다. vcpkg 통합을 사용하도록 설정하려면 vcpkg 도구 체인 파일(vcpkg.cmake)을 CMake에 전달해야 합니다. 자세한 내용은 vcpkg 설명서를 참조하세요.

CMakePresets.json 통합을 사용하도록 설정할 때 Visual Studio는 더 이상 vcpkg 도구 체인 파일을 CMake에 자동으로 전달하지 않습니다. 이렇게 변경하면 Visual Studio 관련 동작이 제거되며 명령줄에서 빌드를 재현할 수 있습니다.

대신 CMakePresets.json에서 VCPKG_ROOT 환경 변수를 사용하여 경로를 vcpkg.cmake로 설정합니다.

"cacheVariables": {
   "CMAKE_TOOLCHAIN_FILE": {
      "value": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
       "type": "FILEPATH"
    }
 },

VCPKG_ROOT는 vcpkg 설치의 루트로 설정해야 합니다. 자세한 내용은 vcpkg environment variables(vcpkg 환경 변수)를 참조하세요.

CMake 도구 체인 파일을 이미 사용하고 있고 vcpkg 통합을 사용하도록 설정하려는 경우 Using multiple toolchain files(여러 도구 체인 파일 사용)를 참조하세요. 해당 지침에 따라 vcpkg를 사용하여 프로젝트에서 외부 도구 체인 파일을 사용합니다.

`launch.vs.json` 및 `tasks.vs.json`의 변수 대체

CMakePresets.json은 launch.vs.json 및 tasks.vs.json의 변수 대체를 지원합니다. 다음은 몇 가지 고려 사항입니다.

활성 구성 사전 설정에 설정된 환경 변수는 launch.vs.json 및 tasks.vs.json 구성으로 자동으로 흐릅니다. launch.vs.json 및 tasks.vs.json에서 개별 환경 변수를 null로 설정하여 해당 변수를 설정 해제할 수 있습니다. 다음 예제에서는 launch.vs.json에서 DEBUG_LOGGING_LEVEL 변수를 null로 설정합니다("env": { "DEBUG_LOGGING_LEVEL": null }).
활성 구성 사전 설정에 설정된 키-값은 ${cmake.<KEY-NAME>} 구문을 사용하는 launch.vs.json 및 tasks.vs.json에서 사용할 수 있습니다. 예를 들어 ${cmake.binaryDir}을 사용하여 활성 구성 사전 설정의 출력 디렉터리를 참조합니다.
활성 구성 사전 설정의 환경 맵에 설정된 개별 환경 변수는 ${env.<VARIABLE-NAME>} 구문을 통해 launch.vs.json 및 tasks.vs.json에서 사용할 수 있습니다.

launch.vs.json 및 task.vs.json 파일을 업데이트하여 CMakeSettings.json 구문 대신 CMakePresets.json 구문을 참조합니다. CMakePresets.json이 활성 구성 파일일 때 이전 CMakeSettings.json 구문을 참조하는 매크로는 이후 릴리스에서 사용되지 않습니다. 예를 들어 CMakePresets.json은 binaryDir 구문을 사용하므로 ${cmake.buildRoot} 대신 ${cmake.binaryDir}로 활성 구성 사전 설정의 출력 디렉터리를 참조합니다.

문제 해결

작업이 예상대로 수행되지 않는 경우 몇 가지 문제 해결 단계를 수행해 볼 수 있습니다.

CMakePresets.json 또는 CMakeUserPresets.json이 잘못된 경우 Visual Studio는 기본 동작으로 대체되고 기본 구성 사전 설정만 표시합니다. Visual Studio IntelliSense를 사용하면 이러한 JSON 오류 대부분을 catch할 수 있지만 inherits 또는 configurePreset을 사용하는 사전 설정을 잘못된 이름으로 참조하고 있는지 알 수 없습니다.

사전 설정 파일이 유효한지 확인하려면 프로젝트 디렉터리 루트의 명령줄에서 cmake --list-presets을 실행합니다. (CMake 3.20 이상 필요) 두 파일 중 하나가 잘못된 경우 다음 오류가 표시됩니다.

CMake Error: Could not read presets from
C:/Users/<user>/source/repos/<project-name>: JSON parse error

다른 문제 해결 단계는 다음과 같습니다.

캐시를 삭제하고 프로젝트를 다시 구성합니다(CMake: 캐시 삭제 및 프로젝트>구성 <프로젝트 이름>).
Visual Studio에서 폴더를 닫았다가 다시 엽니다(파일>폴더 닫기).
프로젝트 루트에서 .vs 폴더를 삭제합니다.

문제를 파악한 경우 Visual Studio의 오른쪽 모서리 상단에서 피드백 보내기 단추를 선택하여 문제를 신고하는 것이 가장 좋습니다.

원격 연결에 대한 로깅 사용

원격 시스템에 파일을 연결하거나 복사하는 데 문제가 있는 경우 원격 연결에 대한 로깅을 사용하도록 설정할 수 있습니다. 자세한 내용은 원격 연결에 대한 로깅을 참조하세요.

Windows 및 Linux에 AddressSanitizer 사용

Visual Studio는 Windows 및 Linux 개발 모두에서 C 및 C++ 런타임 메모리 오류 감지기인 ASAN(AddressSanitizer)을 지원합니다. 이 addressSanitizerEnabled 옵션은 CMakeSettings.json AddressSanitizer를 사용하도록 설정합니다. CMakePresets.json에서는 이 동작을 지원하지 않습니다.

대신 필요한 컴파일러 및 링커 플래그를 직접 설정하여 AddressSanitizer를 사용하거나 사용하지 않도록 설정합니다. 이렇게 설정하면 Visual Studio 관련 동작이 제거되며 동일한 CMakePresets.json 파일이 명령줄에서 빌드를 재현할 수 있습니다.

다음 샘플을 CMakeLists.txt에 추가하여 대상에 대해 AddressSanitizer를 사용하거나 사용하지 않도록 설정할 수 있습니다.

option(ASAN_ENABLED "Build this target with AddressSanitizer" ON)

if(ASAN_ENABLED)
  if(MSVC)
    target_compile_options(<target> PUBLIC /fsanitize=address)
  else()
    target_compile_options(<target> PUBLIC -fsanitize=address <additional-options>)
    target_link_options(<target> PUBLIC -fsanitize=address)
  endif()
endif()

<additional-options> 파트는 "-fno-omit-frame-pointer"와 같은 다른 컴파일 플래그를 나열합니다. Linux용 AddressSanitizer에 대한 자세한 내용은 Using AddressSanitizer(AddressSanitizer 사용)를 참조하세요. MSVC에서 AddressSanitizer를 사용하는 방법에 대한 자세한 내용은 개발자 명령 프롬프트에서 AddressSanitizer 사용을 참조 하세요.

launch.vs.json의 ASAN_OPTIONS 필드를 사용하여 AddressSanitizer에 런타임 플래그를 전달합니다. LeakSanitizer는 Visual Studio에서 지원되지 않으므로 다른 런타임 옵션이 지정되지 않은 경우 ASAN_OPTIONS는 기본적으로 detect_leaks=0으로 설정됩니다.

명령줄 또는 CI 파이프라인에서 CMake 실행

동일한 CMakePresets.json 및 CMakeUserPresets.json 파일을 사용하여 Visual Studio 및 명령줄에서 CMake를 호출할 수 있습니다. CMake 및 CTest 설명서는 --preset을 사용하여 CMake 및 CTest를 호출하는 데 가장 적합한 리소스입니다. CMake 버전 3.20 이상이 필요합니다.

Windows에서 명령줄 생성기를 사용하여 빌드할 때 환경 소싱

명령줄 생성기를 사용하여 빌드하는 경우 CMake가 호출되기 전에 사용자가 환경을 구성해야 합니다. Windows에서 Ninja 및 Visual C++ 도구 집합을 사용하여 빌드하는 경우에는 빌드 시스템을 생성하기 위해 CMake가 호출되기 전에 환경을 설정합니다. 이 작업은 architecture 인수로 vcvarsall.bat를 호출하여 수행할 수 있습니다. architecture 인수는 사용할 호스트 및 대상 아키텍처를 지정합니다. 자세한 내용은 vcvarsall 구문을 참조하세요. Visual Studio 생성기를 사용하여 Linux 또는 Windows에서 빌드하는 경우에는 이 단계를 수행할 필요가 없습니다.

이 단계는 IDE에서 CMake를 호출할 때 Visual Studio에서 수행되는 단계와 동일합니다. Visual Studio는 toolset 및 architecture로 지정된 호스트 및 대상 아키텍처에 대한 활성 구성 사전 설정을 구문 분석합니다. 그런 다음, Visual Studio는 vcvarsall.bat에서 지정된 환경을 소싱합니다. Ninja를 사용하여 Windows 명령줄에서 빌드하는 경우 이 단계를 직접 수행해야 합니다.

vcvarsall.bat는 Visual Studio용 빌드 도구와 함께 설치됩니다. 기본적으로 vcvarsall.bat는 C:\Program Files (x86)\Microsoft Visual Studio\2019\<edition>\VC\Auxiliary\Build에 설치됩니다. 명령줄 워크플로를 자주 사용하는 경우 PATH에 vcvarsall.bat를 추가할 수 있습니다.

예제 명령줄 워크플로

다음 명령을 사용하면 Ninja를 사용하여 x64 빌드 도구와 함께 ARM64를 대상으로 하는 CMake 프로젝트를 구성하고 빌드할 수 있습니다. CMake 버전 3.20 이상이 필요합니다. CMakePresets.json 파일이 있는 디렉터리에서 이러한 명령을 실행합니다.

/path/to/vcvarsall.bat x64_arm64 
cmake --list-presets=all .
cmake --preset <configurePreset-name>
cmake --build --preset <buildPreset-name>

예제 `CMakePresets.json` 파일

box2d-lite의 CMakePresets.json 파일에는 구성 사전 설정, 빌드 사전 설정, 테스트 사전 설정의 예제가 포함되어 있습니다. 이 예제에 대한 자세한 내용은 CMakePresets.json 소개 프레젠테이션 을 참조하세요. DirectXTK 프로젝트의 또 다른 예제를 볼 수 있습니다. 이 예제는 해당 configurePresets 섹션의 여러 빌드 대상을 보여 줍니다.

다음 단계

Visual Studio에서 CMake 프로젝트를 구성하고 디버깅하는 방법을 자세히 알아봅니다.

Visual Studio의 CMake 프로젝트
CMake 빌드 설정 사용자 지정
CMake 디버깅 세션 구성
CMake 미리 정의된 구성 참조

Visual Studio에서 CMake 사전 설정으로 구성 및 빌드

지원되는 CMake 및 CMakePresets.json 버전

Visual Studio에서 통합 사용 CMakePresets.json

자동 구성 및 캐시 알림 수정

기본 구성 사전 설정

Windows 예제

Linux 예제

구성 및 빌드

대상 시스템 선택

구성 사전 설정 선택

빌드 사전 설정 선택

구성

빌드

CTest 실행

새 사전 설정 추가

새 구성 사전 설정 추가

새 빌드 사전 설정 및 테스트 사전 설정 추가

사전 설정 편집

컴파일러 선택

생성기 선택

구성 형식 선택

Visual C++ 도구 집합으로 빌드하는 경우 대상 및 호스트 아키텍처 선택

환경 변수 설정 및 참조

크로스 컴파일러에 대해 IntelliSense 구성

원격 시스템 또는 Linux용 Windows 하위 시스템에서 구성 및 빌드

원격 복사 시나리오의 ${sourceDir} 동작

원격 출력을 위한 로컬 폴더

Windows 및 WSL1에서 동일한 구성 사전 설정 호출

vcpkg 통합 사용

launch.vs.json 및 tasks.vs.json의 변수 대체

문제 해결

원격 연결에 대한 로깅 사용

Windows 및 Linux에 AddressSanitizer 사용

명령줄 또는 CI 파이프라인에서 CMake 실행

Windows에서 명령줄 생성기를 사용하여 빌드할 때 환경 소싱

예제 명령줄 워크플로

예제 CMakePresets.json 파일

다음 단계

피드백

피드백

추가 리소스

지원되는 CMake 및 `CMakePresets.json` 버전

Visual Studio에서 통합 사용 `CMakePresets.json`

원격 복사 시나리오의 `${sourceDir}` 동작

`launch.vs.json` 및 `tasks.vs.json`의 변수 대체

예제 `CMakePresets.json` 파일