CMake 에러 | "CMake Error" 자주 나는 에러 10가지와 해결법

들어가며: “CMake 에러가 너무 많아요"

"CMakeLists.txt를 어떻게 고쳐야 할지 모르겠어요”

CMake는 C++ 프로젝트의 빌드 시스템을 자동화하는 도구이지만, 에러 메시지가 불친절해서 초보자가 어려워합니다.

# ❌ 에러 코드
add_executable(myapp main.cpp)
target_link_libraries(myapp mylib)  # mylib 정의 없음

# CMake Error: Cannot specify link libraries for target "mylib" 
#              which is not built by this project.

이 글에서 다루는 것:

• 자주 나오는 CMake 에러 10가지
• CMakeLists.txt 문법 실수
• find_package 실패
• 타겟 의존성 문제
• 경로 설정 오류

---

목차

1. CMake 에러 10가지
2. CMakeLists.txt 문법
3. find_package 에러
4. 타겟 의존성
5. 정리

---

1. CMake 에러 10가지

에러 1: CMake version too old

CMake Error: CMake 3.20 or higher is required. You are running version 3.16

해결법 1: cmake_minimum_required 낮추기

# ❌ 높은 버전 요구
cmake_minimum_required(VERSION 3.20)

# ✅ 낮은 버전으로 변경
cmake_minimum_required(VERSION 3.16)

해결법 2: CMake 업데이트

# Ubuntu
sudo apt install cmake

# 또는 최신 버전 설치
wget https://github.com/Kitware/CMake/releases/download/v3.28.0/cmake-3.28.0-linux-x86_64.sh
sudo sh cmake-3.28.0-linux-x86_64.sh --prefix=/usr/local --skip-license

에러 2: target not found

# ❌ 에러 코드
target_link_libraries(myapp mylib)  # mylib 정의 없음
add_executable(myapp main.cpp)

# CMake Error: Cannot specify link libraries for target "mylib"

해결: 타겟을 먼저 정의.

# ✅ 올바른 순서
add_library(mylib mylib.cpp)
add_executable(myapp main.cpp)
target_link_libraries(myapp mylib)  # mylib가 이미 정의됨

에러 3: syntax error (괄호 불일치)

# ❌ 괄호 불일치
add_executable(myapp
    main.cpp
    utils.cpp
# 닫는 괄호 없음

# CMake Error: Parse error. Expected a newline, got EOF.

해결:

# ✅ 괄호 일치
add_executable(myapp
    main.cpp
    utils.cpp
)

에러 4: Could NOT find package

# ❌ 라이브러리 없음
find_package(Boost REQUIRED)

# CMake Error: Could NOT find Boost (missing: Boost_INCLUDE_DIR)

해결: CMake “Could NOT find” 에러 해결 참고.

# ✅ CMAKE_PREFIX_PATH 설정
set(CMAKE_PREFIX_PATH "/usr/local" ${CMAKE_PREFIX_PATH})
find_package(Boost REQUIRED)

# 또는 vcpkg 사용

에러 5: 파일 경로 오류

# ❌ 파일 없음
add_executable(myapp
    main.cpp
    utils.cpp  # 파일이 없음
)

# CMake Error: Cannot find source file: utils.cpp

해결: 파일 존재 확인.

# 파일 확인
ls utils.cpp

# 또는 CMake 변수 사용
file(GLOB SOURCES "src/*.cpp")
add_executable(myapp ${SOURCES})

에러 6: 변수 미정의

# ❌ 변수 없음
target_include_directories(myapp PRIVATE ${MY_INCLUDE_DIR})

# CMake Warning: MY_INCLUDE_DIR is not defined

해결:

# ✅ 변수 정의
set(MY_INCLUDE_DIR "${CMAKE_SOURCE_DIR}/include")
target_include_directories(myapp PRIVATE ${MY_INCLUDE_DIR})

에러 7: 중복 타겟 정의

# ❌ 중복 정의
add_executable(myapp main.cpp)
add_executable(myapp other.cpp)  # 같은 이름

# CMake Error: add_executable cannot create target "myapp" because 
#              another target with the same name already exists.

해결: 타겟 이름을 다르게.

# ✅ 다른 이름
add_executable(myapp main.cpp)
add_executable(myapp2 other.cpp)

에러 8: 잘못된 명령어

# ❌ 오타
add_executabel(myapp main.cpp)  # executable 오타

# CMake Error: Unknown CMake command "add_executabel".

해결: 철자 확인.

에러 9: 경로 공백 처리

# ❌ 공백 처리 안 함
set(MY_PATH C:/Program Files/MyLib)
target_include_directories(myapp PRIVATE ${MY_PATH})

# 에러: C:/Program과 Files/MyLib로 분리됨

# ✅ 따옴표 사용
set(MY_PATH "C:/Program Files/MyLib")
target_include_directories(myapp PRIVATE "${MY_PATH}")

에러 10: 빌드 디렉토리 오염

CMake Error: The source directory is the same as the binary directory.
             In-source builds are not allowed.

해결: out-of-source 빌드.

# ❌ in-source 빌드
cd project/
cmake .

# ✅ out-of-source 빌드
cd project/
mkdir build
cd build
cmake ..

---

2. CMakeLists.txt 문법

기본 구조

# 최소 버전
cmake_minimum_required(VERSION 3.16)

# 프로젝트 이름
project(MyProject)

# C++ 표준
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# 실행 파일
add_executable(myapp
    src/main.cpp
    src/utils.cpp
)

# 헤더 경로
target_include_directories(myapp PRIVATE
    ${CMAKE_SOURCE_DIR}/include
)

# 라이브러리 링크
target_link_libraries(myapp
    pthread
)

자주 쓰는 변수

# 소스 디렉토리
${CMAKE_SOURCE_DIR}

# 빌드 디렉토리
${CMAKE_BINARY_DIR}

# 현재 디렉토리
${CMAKE_CURRENT_SOURCE_DIR}

# 프로젝트 이름
${PROJECT_NAME}

# 컴파일러
${CMAKE_CXX_COMPILER}

---

정리

CMake 에러 해결 체크리스트

• cmake_minimum_required가 있는가?
• 타겟을 먼저 정의했는가? (add_executable/add_library)
• 괄호·따옴표가 일치하는가?
• 파일 경로가 올바른가?
• find_package가 성공했는가?
• out-of-source 빌드를 사용하는가?

자주 나오는 에러 요약

에러	원인	해결법
version too old	CMake 버전 낮음	업데이트 또는 버전 낮추기
target not found	타겟 미정의	add_executable 먼저
syntax error	괄호·따옴표 불일치	문법 확인
Could NOT find	라이브러리 없음	CMAKE_PREFIX_PATH 설정
file not found	파일 경로 오류	경로 확인

핵심 규칙

1. out-of-source 빌드 사용
2. 타겟을 먼저 정의
3. 경로는 따옴표로 감싸기
4. find_package 실패는 CMAKE_PREFIX_PATH 확인
5. vcpkg/Conan 사용 권장

---

같이 보면 좋은 글 (내부 링크)

이 주제와 연결되는 다른 글입니다.

• CMake 입문 | “처음 배우는” CMake 완벽 가이드
• CMake “Could NOT find” 에러 해결
• CMake 링크 에러 | target_link_libraries 가이드
• CMake 모던 패턴 | target 기반 빌드

---

마치며

CMake 에러는 문법과 타겟 의존성을 이해하면 쉽게 해결됩니다.

핵심 원칙:

1. out-of-source 빌드
2. 타겟을 먼저 정의
3. find_package 실패는 CMAKE_PREFIX_PATH
4. vcpkg/Conan 사용

CMake는 처음에는 어렵지만, 기본 패턴을 익히면 강력한 빌드 시스템입니다. 이 가이드를 참고해 CMake 에러를 빠르게 해결하세요.

다음 단계: CMake를 이해했다면, CMake 모던 패턴에서 더 나은 빌드 스크립트를 작성해 보세요.

---

관련 글

• C++ 시리즈 전체 보기
• C++ Adapter Pattern 완벽 가이드 | 인터페이스 변환과 호환성
• C++ ADL |
• C++ Aggregate Initialization |