[2026] CMake 에러 | CMake Error 자주 나는 에러 10가지와 해결법
![[2026] CMake 에러 | CMake Error 자주 나는 에러 10가지와 해결법](/og/s/cpp-error-18-cmake-errors.webp)
이 글의 핵심
CMake 에러의 CMake, CMake, Error, 들어가며: CMake 에러가 너무 많아요를 실전 예제와 함께 상세히 설명합니다.
들어가며: “CMake 에러가 너무 많아요"
"CMakeLists.txt를 어떻게 고쳐야 할지 모르겠어요”
CMake는 C++ 프로젝트의 빌드 시스템을 자동화하는 도구이지만, 에러 메시지가 불친절해서 초보자가 어려워합니다. 아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.
# ❌ 에러 코드
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가지
에러 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를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.
# ❌ 높은 버전 요구
cmake_minimum_required(VERSION 3.20)
# ✅ 낮은 버전으로 변경
cmake_minimum_required(VERSION 3.16)해결법 2: CMake 업데이트 아래 코드는 bash를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.
# 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
아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.
# ❌ 에러 코드
target_link_libraries(myapp mylib) # mylib 정의 없음
add_executable(myapp main.cpp)
# CMake Error: Cannot specify link libraries for target "mylib"해결: 타겟을 먼저 정의. 다음은 간단한 cmake 코드 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.
# ✅ 올바른 순서
add_library(mylib mylib.cpp)
add_executable(myapp main.cpp)
target_link_libraries(myapp mylib) # mylib가 이미 정의됨에러 3: syntax error (괄호 불일치)
아래 코드는 cmake를 사용한 구현 예제입니다. 에러 처리를 통해 안정성을 확보합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.
# ❌ 괄호 불일치
add_executable(myapp
main.cpp
utils.cpp
# 닫는 괄호 없음
# CMake Error: Parse error. Expected a newline, got EOF.해결: 아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.
# ✅ 괄호 일치
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를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.
# ✅ CMAKE_PREFIX_PATH 설정
set(CMAKE_PREFIX_PATH "/usr/local" ${CMAKE_PREFIX_PATH})
find_package(Boost REQUIRED)
# 또는 vcpkg 사용에러 5: 파일 경로 오류
아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.
# ❌ 파일 없음
add_executable(myapp
main.cpp
utils.cpp # 파일이 없음
)
# CMake Error: Cannot find source file: utils.cpp해결: 파일 존재 확인. 아래 코드는 bash를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.
# 파일 확인
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: 중복 타겟 정의
아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.
# ❌ 중복 정의
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: 경로 공백 처리
아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.
# ❌ 공백 처리 안 함
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 빌드. 아래 코드는 bash를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.
# ❌ in-source 빌드
cd project/
cmake .
# ✅ out-of-source 빌드
cd project/
mkdir build
cd build
cmake ..2. CMakeLists.txt 문법
기본 구조
다음은 cmake를 활용한 상세한 구현 코드입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.
# 최소 버전
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를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.
# 소스 디렉토리
${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 | 파일 경로 오류 | 경로 확인 |
핵심 규칙
- out-of-source 빌드 사용
- 타겟을 먼저 정의
- 경로는 따옴표로 감싸기
- find_package 실패는 CMAKE_PREFIX_PATH 확인
- vcpkg/Conan 사용 권장
같이 보면 좋은 글 (내부 링크)
이 주제와 연결되는 다른 글입니다.
- CMake 입문 | “처음 배우는” CMake 완벽 가이드
- CMake “Could NOT find” 에러 해결
- CMake 링크 에러 | target_link_libraries 가이드
- CMake 모던 패턴 | target 기반 빌드
마치며
CMake 에러는 문법과 타겟 의존성을 이해하면 쉽게 해결됩니다. 핵심 원칙:
- out-of-source 빌드
- 타겟을 먼저 정의
- find_package 실패는 CMAKE_PREFIX_PATH
- vcpkg/Conan 사용 CMake는 처음에는 어렵지만, 기본 패턴을 익히면 강력한 빌드 시스템입니다. 이 가이드를 참고해 CMake 에러를 빠르게 해결하세요. 다음 단계: CMake를 이해했다면, CMake 모던 패턴에서 더 나은 빌드 스크립트를 작성해 보세요.