CLion으로 C++ 개발하기: CMake 프로젝트 설정, 툴체인, 디버깅, 리팩토링 단축키

들어가며: “C++ IDE 뭘 쓰지?”

VSCode vs CLion vs Visual Studio

VSCode는 가볍고 확장이 많지만, C++ 전용 기능은 제한적입니다. Visual Studio는 Windows에서 강력하지만 크로스 플랫폼이 아닙니다. CLion은 JetBrains의 C++ 전용 IDE로, Linux/macOS/Windows에서 동일한 경험을 제공하며 CMake·디버깅·리팩토링이 통합되어 있습니다.

실제 겪는 문제 시나리오:

- CMake 프로젝트를 열었는데 "툴체인을 찾을 수 없음" 에러 → GCC/Clang 경로 설정 필요
- 디버거로 실행했는데 브레이크포인트가 안 걸림 → Debug 빌드·심볼 확인 필요
- 10만 줄 코드베이스에서 함수 정의 찾기가 너무 느림 → CLion의 인덱싱·심볼 검색 활용
- 리팩토링할 때 변수명 바꾸면 수동으로 다 찾아서 고쳐야 함 → Rename Refactoring 사용
- 팀원마다 다른 OS(Linux/macOS/Windows) → CLion으로 동일한 워크플로 공유
- Docker 컨테이너 안에서 빌드·실행해야 함 → CLion 원격/도커 툴체인
- vcpkg/Conan 설치한 라이브러리 경로를 못 찾음 → 툴체인·CMake 옵션 연동
- 인덱싱 중 CPU 100%로 다른 작업이 불가 → 제외 경로 설정 필요
- "undefined reference" 에러가 나는데 헤더는 잘 찾음 → 링크 대상·소스 파일 누락

시나리오별 상세:

시나리오	증상	CLion에서 해결
신규 프로젝트	CMake 없이 시작	New Project → C++ Executable으로 자동 CMake 생성
레거시 Makefile	Makefile만 있음	CMake로 변환하거나, Compilation Database 생성 후 열기
멀티 플랫폼	Win/Mac/Linux 각각 빌드	CMake Presets로 프로파일 분리, 툴체인 전환
대규모	인덱싱이 오래 걸림	build, third_party 제외, 메모리 증가

CLion으로 해결:

문제	CLion 기능
툴체인 설정	Settings > Toolchains에서 GCC/Clang/MSVC 선택
디버깅	GDB/LLDB 통합, 조건부 브레이크포인트, Watches
코드 탐색	Go to Definition, Find Usages, Call Hierarchy
리팩토링	Rename, Extract, Change Signature
크로스 플랫폼	동일 UI, CMake Presets 지원
원격 개발	SSH, Docker, WSL 툴체인

요구 환경: CLion 2023.x 이상, C++17 이상, CMake 3.16+

CLion 설치와 툴체인·CMake 설정부터 조건부 브레이크포인트 같은 디버깅 기능, 리팩토링과 단축키, 팀 프로젝트에서 설정을 공유하는 방법까지 다룹니다.

---

CLion이 맞는 경우와 다른 IDE 비교

언제 CLion을 쓰면 좋을까?

flowchart TD
    A[C++ 프로젝트] --> B{주요 환경은?}
    B -->|Windows 전용| C[Visual Studio]
    B -->|Linux/macOS/크로스플랫폼| D[CLion]
    B -->|가벼운 편집만| E[VSCode]
    D --> D1[CMake 기반]
    D --> D2[디버깅·리팩토링 중요]
    D --> D3[원격/Docker 개발]

CLion vs 다른 IDE 비교

항목	CLion	Visual Studio	VSCode
플랫폼	Win/Mac/Linux	Windows	모두
빌드 시스템	CMake 중심	MSBuild, CMake	CMake 등 확장
디버깅	GDB/LLDB	MSVC 디버거	확장 의존
리팩토링	내장 강력	내장	제한적
인덱싱	전체 코드베이스	빠름	확장 의존
가격	상업적 사용은 유료, 비상업적 사용·학생은 무료	Community 무료(조건 있음)	무료

---

설치·툴체인·CMake 프로파일 설정

설치

macOS:

# Homebrew로 설치
brew install --cask clion

Linux (Ubuntu/Debian):

# JetBrains Toolbox 또는 직접 다운로드
# https://www.jetbrains.com/clion/download/
sudo snap install clion --classic

Windows:

- https://www.jetbrains.com/clion/download/ 에서 설치 프로그램 다운로드
- MinGW-w64 또는 Visual Studio Build Tools 사전 설치 권장

툴체인(Toolchain) 설정

CLion은 툴체인으로 컴파일러·디버거·CMake를 묶어 관리합니다. 설정 경로: Settings (macOS: Cmd+,) → Build, Execution, Deployment → Toolchains

flowchart LR
    subgraph Toolchain[툴체인 구성]
        T1[CMake]
        T2[C/C++ 컴파일러]
        T3[디버거 GDB/LLDB]
        T4[빌드 도구 make/ninja]
    end

macOS - System 툴체인:

1. Toolchains → + → System
2. Name: macOS (Clang)
3. C Compiler: /usr/bin/clang (또는 Xcode 경로)
4. C++ Compiler: /usr/bin/clang++
5. Debugger: LLDB (기본)
6. Environment: 기본 또는 Custom

Linux - GCC 툴체인:

# GCC 설치 확인
gcc --version
g++ --version
# Ubuntu/Debian
sudo apt install build-essential cmake gdb

1. Toolchains → + → System
2. C Compiler: /usr/bin/gcc
3. C++ Compiler: /usr/bin/g++
4. Debugger: GDB

Windows - MinGW:

1. MinGW-w64 또는 MSYS2 설치
2. Toolchains → + → MinGW
3. Environment: MinGW 설치 경로 지정 (예: C:\msys64\mingw64)
4. 또는 Visual Studio 툴체인 선택

CMake 옵션 예시 (툴체인별):

// CMakePresets.json - 툴체인 자동 감지
{
  "version": 3,
  "configurePresets": [
    {
      "name": "linux-debug",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/debug",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug",
        "CMAKE_CXX_COMPILER": "/usr/bin/g++"
      }
    }
  ]
}

CMake 프로파일 설정

설정 경로: Settings → Build, Execution, Deployment → CMake

항목	설명	권장값
Build type	Debug / Release / RelWithDebInfo	개발: Debug
Toolchain	사용할 툴체인	시스템에 맞게
CMake options	추가 옵션	-DCMAKE_EXPORT_COMPILE_COMMANDS=ON
Build directory	빌드 출력 경로	cmake-build-debug 등

디버그·릴리즈 프로파일 분리:

1. CMake → Profiles → + 로 새 프로파일 추가
2. Debug: Build type = Debug, 이름 = Debug
3. Release: Build type = Release, 이름 = Release
4. 실행 시 상단 드롭다운에서 프로파일 선택

코드 스타일·Clang-Tidy

Clang-Tidy 연동 (정적 분석):

# .clang-tidy - 프로젝트 루트에 생성
Checks: >
  -*,
  bugprone-*,
  performance-*,
  modernize-*,
  readability-*
WarningsAsErrors: 'bugprone-*,performance-*'   # CI에서 막을 규칙만 에러로
HeaderFilterRegex: '^.*/(src|include)/.*'       # 내 코드의 헤더만 검사

설정: Settings → Editor → Inspections → C/C++ → Clang-Tidy 체크 → “Prefer .clang-tidy files over IDE settings”를 켜 두면 CLion과 CI(run-clang-tidy)가 같은 규칙을 씁니다.

예제에서 자주 보이는 WarningsAsErrors: '처럼 따옴표가 닫히지 않은 줄은 YAML 문법 오류라 clang-tidy가 설정 파일 전체를 읽지 못하고, CLion은 조용히 기본 규칙으로 돌아갑니다. 규칙을 바꿨는데 경고가 그대로라면 먼저 이 파일이 제대로 파싱되는지(clang-tidy --dump-config) 확인합니다. HeaderFilterRegex: '.*'도 흔한 함정입니다. vcpkg나 시스템 헤더까지 전부 검사해 경고가 수천 개 쏟아지고 분석이 느려지므로, 프로젝트 경로로 좁히는 편이 실용적입니다.

원격·Docker 툴체인 (선택)

SSH 원격 개발:

1. Toolchains → + → Remote Host
2. SSH Configuration: 호스트, 사용자, 키 경로
3. 원격 머신에 CMake, GCC/Clang, GDB 설치 필요
4. 빌드·실행이 원격에서 수행됨

Docker 툴체인:

1. Toolchains → + → Docker
2. Docker 이미지 선택 (예: ubuntu:22.04)
3. 이미지 내부에 build-essential, cmake, gdb 설치된 Dockerfile 사용 권장

Dockerfile 예시:

# Dockerfile.dev
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y \
    build-essential cmake gdb git \
    && rm -rf /var/lib/apt/lists/*

---

CMake 프로젝트 구성

새 프로젝트 생성

File → New Project → C++ Executable (또는 Library) 생성되는 기본 구조:

# CMakeLists.txt
cmake_minimum_required(VERSION 3.16)
project(my_project CXX)
set(CMAKE_CXX_STANDARD 17)
add_executable(my_project main.cpp)

기존 CMake 프로젝트 열기

File → Open → 프로젝트 루트의 CMakeLists.txt 또는 폴더 선택 CLion이 자동으로:

• CMake 설정 실행
• 컴파일 데이터베이스 생성
• 코드 인덱싱 시작

vcpkg·Conan 연동

vcpkg:

# CMakeLists.txt
set(CMAKE_TOOLCHAIN_FILE "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
    CACHE STRING "Vcpkg toolchain file")
find_package(nlohmann_json CONFIG REQUIRED)
target_link_libraries(my_project PRIVATE nlohmann_json::nlohmann_json)

위처럼 CMakeLists.txt 안에서 CMAKE_TOOLCHAIN_FILE을 지정할 때는 반드시 첫 project() 호출보다 앞에 있어야 합니다. 툴체인 파일은 project()가 컴파일러를 검사하는 시점에 읽히기 때문에, project() 뒤에 쓰면 아무 효과가 없고 find_package(nlohmann_json CONFIG REQUIRED)가 “Could not find a package configuration file”로 실패합니다. 인터넷 예제에도 이 순서가 틀린 경우가 많아 “vcpkg로 설치했는데 못 찾는다”의 가장 흔한 원인입니다. 더 깔끔한 방법은 CMakeLists.txt에 경로를 박지 않고 CLion 쪽에서 넘기는 것입니다.

Settings → Build, Execution, Deployment → CMake → (프로파일) → CMake options
-DCMAKE_TOOLCHAIN_FILE=C:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake

또는 아래 “CMake Presets 활용”처럼 Presets에 "toolchainFile": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"를 두면 CLion·명령줄·CI가 같은 설정을 씁니다. 이때 VCPKG_ROOT는 CLion 프로세스가 보는 환경 변수여야 하므로, macOS·Linux에서 셸 설정 파일(~/.zshrc)에만 넣었다면 Dock에서 실행한 CLion은 그 값을 모릅니다. 툴체인 설정의 Environment 항목에 넣거나 터미널에서 CLion을 실행해 확인합니다.

의존성 목록은 vcpkg install nlohmann-json spdlog처럼 전역에 설치하는 클래식 모드보다, 프로젝트 루트의 vcpkg.json에 적는 매니페스트 모드가 팀 작업에 맞습니다. 툴체인 파일이 연결돼 있으면 CMake 구성 단계에서 vcpkg.json의 패키지를 자동으로 설치하므로, 새로 합류한 사람도 CLion에서 프로젝트를 열기만 하면 됩니다.

{
  "dependencies": ["nlohmann-json", "spdlog"]
}

Conan:

# conanfile.txt
[requires]
nlohmann_json/3.11.2
[generators]
CMakeDeps
CMakeToolchain

# CMakeLists.txt
find_package(nlohmann_json REQUIRED)
target_link_libraries(my_project PRIVATE nlohmann_json::nlohmann_json)

CMake Presets 활용

// CMakePresets.json
{
  "version": 3,
  "configurePresets": [
    {
      "name": "default",
      "hidden": true,
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/${presetName}",
      "cacheVariables": {
        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
      }
    },
    {
      "name": "debug",
      "inherits": "default",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug"
      }
    },
    {
      "name": "release",
      "inherits": "default",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Release"
      }
    }
  ]
}

CLion은 CMakePresets.json을 자동 감지해 프로파일로 가져옵니다.

---

조건부·데이터 브레이크포인트와 역디버깅

기본 디버깅

실행: Shift+F10 (Run), Shift+F9 (Debug) — macOS는 Ctrl+R, Ctrl+D 브레이크포인트: 줄 번호 왼쪽 클릭 또는 Ctrl+F8 (Win/Linux) / Cmd+F8 (Mac) 디버깅 예제 코드:

// debug_demo.cpp
#include <iostream>
#include <vector>
int computeSum(const std::vector<int>& data) {
    int sum = 0;
    for (size_t i = 0; i < data.size(); ++i) {
        sum += data[i];  // 브레이크포인트: i, sum 관찰
    }
    return sum;
}
int main() {
    std::vector<int> vec = {1, 2, 3, 4, 5};
    int result = computeSum(vec);
    std::cout << "Sum: " << result << "\n";
    return 0;
}

조건부 브레이크포인트

사용법: 브레이크포인트 우클릭 → Edit Breakpoint → Condition 입력

예: i == 3          → i가 3일 때만 멈춤
예: ptr == nullptr  → 널 포인터일 때만
예: data.size() > 1000  → 큰 입력에서만

Watches·Evaluate Expression

Watches: 디버깅 중 변수 추가 관찰

Watches 창에 입력:
- vec.size()
- vec.data()
- *ptr (포인터 역참조)

Evaluate Expression (Alt+F8, macOS Opt+F8): 실행 중 임의 식 계산

// 디버깅 중 Evaluate에서 실행 가능
vec.size()
std::accumulate(vec.begin(), vec.end(), 0)

역디버깅 (Reverse Debugging)

역디버깅은 이미 지나간 실행을 거꾸로 되짚는 기능으로, 리눅스에서는 GDB의 record 기능이나 Mozilla의 rr 같은 기록·재생 디버거로 가능합니다. LLDB에는 같은 기능이 없습니다. CLion에서는 GDB 툴체인을 쓰는 경우 디버거 콘솔에서 record를 켠 뒤 reverse-step, reverse-continue 같은 GDB 명령을 직접 입력하는 방식으로 쓸 수 있고, rr로 기록한 실행을 원격 GDB 서버처럼 붙여 디버깅하는 방법도 있습니다. 기록 중에는 실행이 크게 느려지므로 문제 구간을 좁힌 뒤에 씁니다. 버전에 따라 지원 방식이 달라질 수 있으니 CLion 문서를 함께 확인하세요.

디버깅 워크플로

flowchart TD
    A[버그 재현] --> B[재현 가능한 최소 코드 작성]
    B --> C[의심 구간에 브레이크포인트]
    C --> D[Debug 실행]
    D --> E[Step Over/Into로 흐름 추적]
    E --> F[Watches로 변수 확인]
    F --> G{원인 파악?}
    G -->|아니오| C
    G -->|예| H[수정 후 재검증]

데이터 브레이크포인트

특정 메모리 위치의 값이 바뀌는 순간 멈추는 브레이크포인트(워치포인트)입니다. 디버깅 중 Variables 창에서 변수를 우클릭해 데이터 브레이크포인트를 추가하는 방식이 일반적이며, 내부적으로는 GDB/LLDB의 하드웨어 워치포인트를 씁니다. x86에서는 하드웨어 디버그 레지스터가 4개뿐이라 동시에 걸 수 있는 개수와 감시할 수 있는 크기(최대 8바이트 단위)가 제한됩니다.

“누가 이 값을 덮어썼는가”를 찾을 때, 즉 버퍼 오버플로가 옆 변수를 망가뜨리거나 해제된 포인터로 값이 바뀌는 상황에서 특히 유용합니다.

로그포인트 (Logpoint)

멈추지 않고 메시지나 식의 값만 콘솔에 남기는 브레이크포인트입니다. 브레이크포인트 설정에서 Suspend를 끄고, 메시지 기록이나 “Evaluate and log”에 sum 같은 식을 넣으면 해당 줄을 지날 때마다 값이 출력됩니다. 코드를 고쳐 다시 빌드하지 않고 printf 디버깅을 하는 셈입니다. 다만 디버거가 매번 프로그램을 잠시 멈춰 식을 평가하고 재개하므로, 자주 실행되는 루프 안에 걸면 실행이 눈에 띄게 느려집니다.

---

리팩토링 도구

Rename (이름 변경)

단축키: Shift+F6 변수·함수·클래스·파일 이름을 바꾸면 모든 참조가 자동으로 변경됩니다.

// Before: computeSum → computeTotal 로 변경
int computeSum(const std::vector<int>& data) {
    // ...
}
// Refactor → Rename (Shift+F6) → computeTotal
// 모든 호출부가 computeTotal로 변경됨

Extract (추출)

Extract Function: Ctrl+Alt+M (Win/Linux) / Cmd+Alt+M (Mac) 선택한 코드 블록을 새 함수로 추출합니다.

// Before
void process() {
    std::vector<int> data = loadData();
    int sum = 0;
    for (int x : data) sum += x;
    std::cout << "Sum: " << sum << "\n";
}
// 블록 선택 후 Extract Function → 이름: printSum
// After
void printSum(const std::vector<int>& data) {
    int sum = 0;
    for (int x : data) sum += x;
    std::cout << "Sum: " << sum << "\n";
}
void process() {
    std::vector<int> data = loadData();
    printSum(data);
}

Extract Variable: Ctrl+Alt+V / Cmd+Alt+V Extract Parameter: Ctrl+Alt+P / Cmd+Alt+P

Change Signature

함수 시그니처 변경 시 호출부를 자동 업데이트합니다. Refactor → Change Signature (Ctrl+F6 / Cmd+F6)

• 매개변수 추가·삭제·순서 변경
• 기본값 설정
• 반환 타입 변경

Inline

함수 본문을 호출부에 인라인하고 함수 정의를 제거합니다. Refactor → Inline (Ctrl+Alt+N / Cmd+Alt+N)

---

생산성 단축키·팁

필수 단축키 (macOS: Cmd → Ctrl)

동작	Win/Linux	macOS
검색 전체	Shift+Shift	Shift+Shift
파일 검색	Ctrl+Shift+N	Cmd+Shift+O
심볼 검색	Ctrl+Alt+Shift+N	Cmd+Alt+O
정의로 이동	Ctrl+B	Cmd+B
구현으로 이동	Ctrl+Alt+B	Cmd+Alt+B
사용처 찾기	Alt+F7	Alt+F7
호출 계층	Ctrl+Alt+H	Ctrl+Alt+H
리팩토링 메뉴	Ctrl+Shift+Alt+T	Ctrl+T
최근 파일	Ctrl+E	Cmd+E

코드 생성

Live Template:

1. Settings → Editor → Live Templates
2. C++ → + → Live Template
3. Abbreviation: fori (for loop with index)
4. Template text:
   for (size_t $INDEX$ = 0; $INDEX$ < $CONTAINER$.size(); ++$INDEX$) {
       $END$
   }
5. Variables: INDEX=index, CONTAINER=container

기본 제공: main → int main() 생성, for → 범위 for 루프 등

다중 커서·선택

• 다중 선택: Alt+J(macOS Ctrl+G)로 다음 일치 항목 추가, Ctrl+Alt+Shift+J(macOS Ctrl+Cmd+G)로 모든 일치 항목 선택
• 컬럼 선택: Alt+Shift+드래그 (블록 선택)
• 라인 복제: Ctrl+D / Cmd+D

구조 보기

• File Structure: Ctrl+F12 / Cmd+F12 — 현재 파일의 함수·클래스 목록
• Structure 창: 사이드바에서 클래스·함수 트리
• Hierarchy: Ctrl+H — 클래스 상속 계층

TODO·FIXME

// TODO: 최적화 필요
// FIXME: 경계 조건 확인

View → Tool Windows → TODO — 프로젝트 전체 TODO/FIXME 목록

로컬 히스토리

VCS 없이 파일 변경 이력을 로컬에 저장합니다. File → Local History → Show History — 이전 버전 복원 가능

북마크·핀

• 북마크: F11(macOS F3)로 현재 위치 북마크, Ctrl+F11(macOS Alt+F3)로 니모닉 북마크
• 핀: 에디터 탭 우클릭 → Pin Tab — 자주 쓰는 파일 고정

스크래치 파일

임시 코드를 프로젝트 외부에 저장. File → New → Scratch File → C++ 선택 — *.cpp 임시 파일 생성, 프로젝트 빌드에 포함되지 않음.

Compare with Clipboard / Branch

• Clipboard와 비교: 에디터 우클릭 → Compare with Clipboard로 클립보드 내용과 현재 선택 영역 diff (Ctrl+Shift+V는 클립보드 기록에서 붙여넣기)
• Git Branch 비교: Git → Compare with Branch — 다른 브랜치와 diff

Postfix 완성

코드 입력 후 점(.)과 키워드로 변환.

// 예: vec.for → 범위 for 루프로 변환
std::vector<int> vec = {1, 2, 3};
vec.for  // Tab → for (auto&& x : vec) { }

자주 쓰는 것: .for, .if, .null, .not, .cast

---

툴체인 인식 실패, 회색 브레이크포인트, undefined reference: 문제 해결

”No toolchain found” / “툴체인을 찾을 수 없음”

원인: 시스템에 C++ 컴파일러가 없거나, CLion이 경로를 찾지 못함. 해결:

# macOS: Xcode Command Line Tools 설치
xcode-select --install
# Ubuntu/Debian
sudo apt install build-essential cmake gdb
# 경로 확인
which g++
which clang++

CLion: Settings → Toolchains → + → System → 컴파일러 경로 수동 지정

---

”CMake project is not loaded” / CMake 설정 실패

원인: CMakeLists.txt 문법 오류, 의존성 누락, 툴체인 불일치. 해결:

1. CMakeLists.txt 문법 확인:

# 흔한 실수: 괄호 불일치
add_executable(my_app
    main.cpp
    # 닫는 괄호 누락

2. CMake 로그 확인: View → Tool Windows → CMake — 에러 메시지 확인
3. 캐시 삭제 후 재설정:

rm -rf cmake-build-* build
# CLion에서 File → Reload CMake Project

---

디버거에서 브레이크포인트가 안 걸림 (회색)

원인: Release 빌드로 실행 중이거나, 최적화로 인해 라인이 생략됩니다. 해결:

1. Debug 프로파일로 빌드·실행 확인
2. CMake의 Debug 빌드 타입은 GCC·Clang에서 기본으로 -g를 붙이고 최적화를 켜지 않으므로, 따로 플래그를 넣기 전에 다른 곳에서 CMAKE_CXX_FLAGS에 -O2 같은 최적화를 강제로 넣고 있지 않은지 확인합니다. CMake 도구 창의 로그나 compile_commands.json에서 실제 컴파일 명령을 보면 바로 알 수 있습니다.
3. RelWithDebInfo처럼 최적화와 디버그 정보를 함께 쓰는 빌드에서는 일부 줄이 합쳐지거나 사라져 브레이크포인트가 다른 줄에서 멈추는 것이 정상입니다.

---

”Cannot find -lxxx” (링커 에러)

원인: 라이브러리 경로 또는 링크 대상이 잘못됩니다. 해결:

# 올바른 find_package 및 target_link_libraries
find_package(OpenSSL REQUIRED)
target_link_libraries(my_app PRIVATE OpenSSL::SSL OpenSSL::Crypto)
# vcpkg 사용 시: 툴체인 파일은 project() 이전에 지정하거나 CMake 옵션으로 넘긴다
find_package(OpenSSL REQUIRED)

---

인덱싱이 너무 느림 / CPU 100%

원인: 대규모 프로젝트, 외부 라이브러리 포함, 빌드 디렉터리 인덱싱. 해결:

1. 인덱싱 제외: Project 창에서 build, third_party 같은 폴더를 우클릭 → Mark Directory as → Excluded로 지정합니다.
2. 생성된 대용량 파일(자동 생성 코드, 거대한 단일 헤더)이 소스 트리에 섞여 있다면 별도 디렉터리로 옮겨 제외합니다.
3. 메모리 할당 증가: Help → Change Memory Settings(또는 Edit Custom VM Options의 -Xmx)로 IDE 힙 크기를 늘립니다.

---

”undefined reference” — 헤더만 있고 구현 없음

원인: 선언만 있고 정의가 없거나, 링크 대상에 소스 파일 미포함. 해결:

# 모든 소스 파일 포함
add_executable(my_app
    main.cpp
    utils.cpp
    parser.cpp
)
# utils.cpp에 Utils::parse() 구현이 있어야 함

---

Docker/원격 툴체인 연결 실패

원인: SSH 키, 경로, 권한 문제. 해결:

1. SSH 연결 테스트: 터미널에서 ssh user@host 수동 확인
2. 원격 컴파일러 경로: /usr/bin/g++ 등 표준 경로 사용
3. 디버거: 원격에 GDB/LLDB 설치 확인

---

한글 경로·파일명에서 빌드 실패

원인: 일부 툴체인·CMake가 비ASCII 경로를 제대로 처리하지 못함. 해결: 프로젝트 경로를 영문만 사용 (예: C:\dev\my_project)

---

“Symbol not found” / 헤더는 있는데 정의 못 찾음

원인: compile_commands.json 미생성, 인덱싱 미완료, 잘못된 include 경로. 해결:

# CMakeLists.txt
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
# 빌드 후 compile_commands.json 생성됨

# 수동 생성 (CLion 외부에서)
cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
# build/compile_commands.json 확인

---

vcpkg 패키지를 CLion이 못 찾음

원인: CMAKE_TOOLCHAIN_FILE이 CLion의 CMake 실행에 전달되지 않았거나, CMakeLists.txt에서 project() 뒤에 지정됨. 해결: 위 “vcpkg·Conan 연동”처럼 CMake options나 Presets로 툴체인 파일을 넘기고, Tools → CMake → Reset Cache and Reload Project로 캐시를 지운 뒤 다시 로드합니다. CMake는 한 번 구성된 캐시의 CMAKE_TOOLCHAIN_FILE을 바꿔도 반영하지 않기 때문에, 캐시를 지우지 않으면 설정을 고쳐도 계속 실패합니다.

Run Configuration이 저장 안 됨

원인: 실행 구성은 기본적으로 개인 작업 공간 파일(.idea/workspace.xml)에 저장되어 저장소에 올라가지 않습니다. 해결: Edit Configurations → 해당 설정 → “Store as project file”을 체크하면 .idea/runConfigurations/에 XML로 저장되어 팀과 공유할 수 있습니다.

---

팀 공통 설정·CI 동일 빌드·품질 게이트

팀 공통 설정

EditorConfig로 포맷 통일:

# .editorconfig
root = true
[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
[*.{cpp,h,hpp}]
indent_size = 4

공유 Run Configuration:

1. Run → Edit Configurations
2. + → CMake Application
3. 타겟, 실행 인자, 환경 변수 설정
4. "Store as project file" 체크 → .idea/runConfigurations/ 에 저장
5. 팀원이 동일 설정 사용

CI와 동일한 빌드

CLion에서 사용하는 CMake 옵션을 CI 스크립트와 맞춥니다.

# .github/workflows/build.yml 예시
- name: Configure
  run: |
    cmake -B build -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_CXX_COMPILER=g++-12
- name: Build
  run: cmake --build build

CLion CMake options에 동일한 -D 옵션 추가

프로파일별 설정

프로파일	용도	CMAKE_BUILD_TYPE
Debug	개발·디버깅	Debug
Release	성능 측정·배포	Release
RelWithDebInfo	프로파일링·최적화 디버깅	RelWithDebInfo

대규모 프로젝트

flowchart TD
    A[대규모 코드베이스] --> B[CMake Presets로 프로파일 분리]
    B --> C[제외 경로 설정]
    C --> D[인덱싱 최적화]
    D --> E[모듈별 Run Configuration]

• Compilation Database: -DCMAKE_EXPORT_COMPILE_COMMANDS=ON — Clangd 등과 공유
• 모듈화: 서브디렉터리별 add_subdirectory, 필요한 타겟만 빌드

코드 품질 게이트

# .clang-tidy - CI와 동일 규칙
Checks: >
  bugprone-*,
  performance-*,
  modernize-*,
  readability-*
WarningsAsErrors: 'bugprone-*,performance-*'

CLion에서 저장 시 또는 커밋 전에 Clang-Tidy 경고를 0으로 유지하는 습관.

---

참고 자료

• CLion 공식 문서
• CLion 툴체인 설정
• CMake Presets in CLion
• CMake 공식 문서
• C++ Core Guidelines
• cppreference

---

같이 보면 좋은 글

• CLion으로 C++ 디버깅·리팩토링 빠르게 하기
• VS Code C++ 설정 | IntelliSense·빌드·디버깅
• printf 디버깅에서 벗어나기
• CMake 입문 | 수십 개 파일 컴파일할 때 필요한 빌드 자동화 (CMakeLists.txt 기초)
• Visual Studio로 C++ 프로파일링·메모리 진단하기

---