Could not find CMAKE_CXX_COMPILER(또는 C 컴파일러)는 어떻게 해결하나요?

IDE 터미널이 아닌, 컴파일러가 PATH에 잡힌 개발자 명령 프롬프트(예: Visual Studio의 x64 Native Tools)에서 cmake를 실행하거나, CMAKE_C_COMPILER·CMAKE_CXX_COMPILER에 컴파일러 전체 경로를 지정합니다. WSL/리눅스에서는 build-essential 등 툴체인 설치 여부를 먼저 확인합니다.

find_package가 패키지를 못 찾는데 뭘 점검해야 하나요?

CMAKE_PREFIX_PATH에 설치 루트(또는 vcpkg toolchain 경로)를 넣고, xxx_DIR(예: OpenCV_DIR, Ceres_DIR)로 CMake config가 있는 폴더를 직접 지정할 수 있습니다. 동일한 이름의 FindXXX.cmake와 패키지가 제공하는 XXXConfig.cmake 중 어느 쪽이 기대에 맞는지도 구분해 보세요.

옵션을 바꿨는데도 이전 설정이 남는 것 같습니다. 캐시는 어떻게 지우나요?

빌드 디렉터리의 CMakeCache.txt를 삭제하거나, 빈 폴더에 새로 cmake -B build로 구성하는 것이 가장 확실합니다. IDE가 고정한 빌드 폴더를 쓰는 경우, 해당 경로의 캐시를 지우는지 함께 확인합니다.

윈도우에선 되는데 리눅스/CI에서만 실패합니다. 원인을 좁히려면?

동일한 CMakeLists.txt라도 CMAKE_TOOLCHAIN_FILE, 패키지 매니저(vcpkg/conan) 환경, 대소문자 구분(파일·경로), 기본 C++ 표준/컴파일러가 다르면 실패가 납니다. CI 로그에 찍힌 CMAKE_COMMAND·generator·컴파일러 버전을 로컬과 비교하고, cmake --trace-expand로 변수 전개를 추적해 차이를 찾는 것이 좋습니다.

CMake 에러 완벽 해결 가이드 | 빌드 실패·의존성·링커 에러 트러블슈팅

2026년 4월 7일 · 16분 읽기 · 수정 2026년 4월 7일 중급

이 글의 핵심

CMake 에러 완벽 해결 가이드에 대해 정리한 개발 블로그 글입니다. > TL;DR: CMake 빌드 에러를 체계적으로 해결하는 방법을 배웁니다. 컴파일러 찾기 실패부터 링커 에러까지, 실무에서 자주 마주치는 모든 문제의 해결책을 제공합니다. 이 글을 읽으면: - ✅ CMake 에러 메시지… 개념과 예제 코드를 단계적으로 다루며, 실무·학습에 참고할 수 있도록 구성했습니다. 관련…

🎯 이 글을 읽으면 (읽는 시간: 50분)

TL;DR: CMake 빌드 에러를 체계적으로 해결하는 방법을 배웁니다. 컴파일러 찾기 실패부터 링커 에러까지, 실무에서 자주 마주치는 모든 문제의 해결책을 제공합니다. 이 글을 읽으면:

✅ CMake 에러 메시지 읽는 방법과 디버깅 전략 마스터
✅ 컴파일러/라이브러리 찾기 실패 해결 능력 습득
✅ 링커 에러와 의존성 문제 해결 패턴 이해
✅ 크로스 플랫폼 빌드 이슈 대응 능력 향상 실무 활용:
🔥 C++ 프로젝트 빌드 시스템 구축
🔥 외부 라이브러리 통합 (Boost, OpenCV 등)
🔥 CI/CD 파이프라인 빌드 안정화
🔥 크로스 플랫폼 빌드 설정 난이도: 중급 | 실습 예제: 20개 | 프로덕션 레벨

이 글의 핵심

CMake 빌드 에러의 근본 원인을 이해하고 체계적으로 해결하는 완벽 가이드입니다. 실무에서 자주 마주치는 에러 패턴과 검증된 해결책을 제공합니다.

실무 경험 공유: 수십 개의 프로젝트에서 CMake 빌드 이슈를 해결하면서 축적한 노하우와 디버깅 기법을 공유합니다.

들어가며: “CMake가 왜 실패하죠?”

흔한 에러 시나리오

시나리오 1: 컴파일러를 찾지 못함

CMake Error: Could not find CMAKE_CXX_COMPILER

시나리오 2: 라이브러리 링킹 실패

undefined reference to `boost::system::error_category::~error_category()'

시나리오 3: 의존성 버전 충돌

CMake Error: Could NOT find OpenSSL (missing: OPENSSL_CRYPTO_LIBRARY)

시나리오 4: 크로스 플랫폼 빌드 실패

Windows에서는 빌드되는데 Linux에서 실패합니다.

1. CMake 에러 분류 체계

에러 단계별 분류

flowchart TD
    A[CMake 실행] --> B{Configure 단계}
    B -->|실패| C[Configure Error]
    B -->|성공| D{Generate 단계}
    D -->|실패| E[Generate Error]
    D -->|성공| F{Build 단계}
    F -->|실패| G[Build Error]
    F -->|성공| H[성공]
    
    C --> C1[컴파일러 찾기 실패]
    C --> C2[find_package 실패]
    C --> C3[CMakeLists.txt 문법 에러]
    
    E --> E1[Generator 에러]
    E --> E2[Toolchain 에러]
    
    G --> G1[컴파일 에러]
    G --> G2[링커 에러]
    G --> G3[의존성 에러]

에러 심각도

심각도	유형	예시	해결 난이도
FATAL_ERROR	즉시 중단	`CMake Error`	높음
SEND_ERROR	계속 진행 후 실패	`CMake Warning (dev)`	중간
WARNING	경고만 표시	`Policy CMP0xxx`	낮음
STATUS	정보 메시지	`-- Found OpenSSL`	-

2. 컴파일러 관련 에러

에러 1: 컴파일러를 찾을 수 없음

증상:

CMake Error: Could not find CMAKE_C_COMPILER
CMake Error: Could not find CMAKE_CXX_COMPILER

원인:

컴파일러가 설치되지 않음
PATH 환경 변수에 없음
CMake가 잘못된 경로 참조 해결책:

Linux/macOS

# GCC 설치 확인
which gcc g++
# 없으면 설치
# Ubuntu/Debian
sudo apt-get install build-essential
# macOS
xcode-select --install
# CMake에 명시적 지정
cmake -DCMAKE_C_COMPILER=/usr/bin/gcc \
      -DCMAKE_CXX_COMPILER=/usr/bin/g++ \
      ..

Windows

# Visual Studio 설치 확인
where cl.exe
# Visual Studio Developer Command Prompt에서 실행
# 또는 CMake에 명시적 지정
cmake -G "Visual Studio 17 2022" -A x64 ..
# MinGW 사용 시
cmake -G "MinGW Makefiles" \
      -DCMAKE_C_COMPILER=C:/mingw64/bin/gcc.exe \
      -DCMAKE_CXX_COMPILER=C:/mingw64/bin/g++.exe \
      ..

에러 2: 컴파일러 버전 불일치

증상:

CMake Error: The C++ compiler does not support C++17

해결책:

# CMakeLists.txt
cmake_minimum_required(VERSION 3.15)
project(MyProject)
# C++ 표준 명시
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)
# 컴파일러 버전 확인
if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
    if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS "7.0")
        message(FATAL_ERROR "GCC 7.0 이상 필요 (현재: ${CMAKE_CXX_COMPILER_VERSION})")
    endif()
elseif(CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
    if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS "19.14")
        message(FATAL_ERROR "MSVC 2017 15.7 이상 필요")
    endif()
endif()

에러 3: 크로스 컴파일 설정 오류

증상:

CMake Error: TRY_RUN() invoked in cross-compiling mode

해결책:

# toolchain.cmake
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR arm)
set(CMAKE_C_COMPILER arm-linux-gnueabihf-gcc)
set(CMAKE_CXX_COMPILER arm-linux-gnueabihf-g++)
# 크로스 컴파일 시 TRY_RUN 결과 미리 설정
set(HAVE_SOME_FEATURE 1 CACHE BOOL "Feature check result")
# 사용
cmake -DCMAKE_TOOLCHAIN_FILE=toolchain.cmake ..

3. 라이브러리 찾기 에러

에러 4: find_package 실패

증상:

CMake Error at CMakeLists.txt:10 (find_package):
  Could NOT find Boost (missing: Boost_INCLUDE_DIR)

원인:

라이브러리가 설치되지 않음
CMake가 찾을 수 없는 경로에 설치됨
버전 불일치 해결책:

방법 1: 설치 경로 명시

# Boost 예시
cmake -DBoost_ROOT=/usr/local/boost_1_75_0 \
      -DBoost_INCLUDE_DIR=/usr/local/boost_1_75_0/include \
      -DBoost_LIBRARY_DIR=/usr/local/boost_1_75_0/lib \
      ..

방법 2: CMAKE_PREFIX_PATH 사용

cmake -DCMAKE_PREFIX_PATH="/usr/local;/opt/local" ..

방법 3: CMakeLists.txt 수정

# 디버그 정보 출력
set(Boost_DEBUG ON)
# 필수가 아닌 선택적으로 변경
find_package(Boost 1.70 COMPONENTS system filesystem)
if(NOT Boost_FOUND)
    message(WARNING "Boost not found, some features disabled")
    set(ENABLE_BOOST_FEATURES OFF)
else()
    message(STATUS "Boost version: ${Boost_VERSION}")
    message(STATUS "Boost include: ${Boost_INCLUDE_DIRS}")
    message(STATUS "Boost libraries: ${Boost_LIBRARIES}")
endif()
# 대체 방법: pkg-config 사용
find_package(PkgConfig)
if(PKG_CONFIG_FOUND)
    pkg_check_modules(BOOST QUIET boost)
    if(BOOST_FOUND)
        include_directories(${BOOST_INCLUDE_DIRS})
        link_directories(${BOOST_LIBRARY_DIRS})
    endif()
endif()

에러 5: 라이브러리 버전 충돌

증상:

CMake Error: Could NOT find OpenSSL: Found unsuitable version "1.0.2", 
but required is at least "1.1.0"

해결책:

# 버전 범위 지정
find_package(OpenSSL 1.1.0 REQUIRED)
# 또는 여러 버전 시도
find_package(OpenSSL 3.0)
if(NOT OpenSSL_FOUND)
    find_package(OpenSSL 1.1 REQUIRED)
endif()
# 버전 정보 출력
message(STATUS "OpenSSL version: ${OPENSSL_VERSION}")
message(STATUS "OpenSSL include: ${OPENSSL_INCLUDE_DIR}")
message(STATUS "OpenSSL libraries: ${OPENSSL_LIBRARIES}")

에러 6: Config vs Module 모드 혼동

증상:

CMake Warning: Could not find a package configuration file provided by "MyLib"

이해:

Config 모드: MyLibConfig.cmake 파일 찾기 (라이브러리 제공)
Module 모드: FindMyLib.cmake 파일 찾기 (CMake 제공) 해결책:

# Config 모드 강제
find_package(MyLib CONFIG REQUIRED)
# Module 모드 강제
find_package(MyLib MODULE REQUIRED)
# 커스텀 Find 모듈 경로 추가
list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake/modules")
# 수동으로 찾기
find_path(MYLIB_INCLUDE_DIR mylib.h
    PATHS /usr/local/include /opt/local/include
)
find_library(MYLIB_LIBRARY mylib
    PATHS /usr/local/lib /opt/local/lib
)
if(MYLIB_INCLUDE_DIR AND MYLIB_LIBRARY)
    set(MYLIB_FOUND TRUE)
    add_library(MyLib::MyLib UNKNOWN IMPORTED)
    set_target_properties(MyLib::MyLib PROPERTIES
        IMPORTED_LOCATION "${MYLIB_LIBRARY}"
        INTERFACE_INCLUDE_DIRECTORIES "${MYLIB_INCLUDE_DIR}"
    )
endif()

4. 링커 에러

에러 7: undefined reference

증상:

undefined reference to `boost::system::error_category::~error_category()'
undefined reference to `pthread_create'

원인:

라이브러리가 링크되지 않음
링크 순서 오류
정적/동적 라이브러리 혼용 해결책:

방법 1: 명시적 링크

# 라이브러리 링크
target_link_libraries(myapp PRIVATE
    Boost::system
    Boost::filesystem
    pthread
)
# 또는 직접 지정
target_link_libraries(myapp PRIVATE
    ${Boost_LIBRARIES}
    pthread
)

방법 2: 링크 순서 조정

# ❌ 잘못된 순서
target_link_libraries(myapp
    lib_a
    lib_b  # lib_b가 lib_a에 의존
)
# ✅ 올바른 순서 (의존성이 나중에)
target_link_libraries(myapp
    lib_b
    lib_a
)

방법 3: 전체 아카이브 링크

# 정적 라이브러리의 모든 심볼 포함
if(UNIX)
    target_link_libraries(myapp PRIVATE
        -Wl,--whole-archive
        mystaticlib
        -Wl,--no-whole-archive
    )
elseif(APPLE)
    target_link_libraries(myapp PRIVATE
        -Wl,-force_load
        mystaticlib
    )
elseif(MSVC)
    target_link_libraries(myapp PRIVATE
        /WHOLEARCHIVE:mystaticlib
    )
endif()

에러 8: 중복 심볼 (duplicate symbol)

증상:

duplicate symbol '_myFunction' in:
    obj1.o
    obj2.o

원인:

헤더에 함수 정의 (inline 없이)
같은 소스 파일이 여러 번 컴파일됨
라이브러리 중복 링크 해결책:

// ❌ 잘못된 헤더 (mylib.h)
void myFunction() {  // 여러 번 정의됨
    // ...
}
// ✅ 올바른 헤더
inline void myFunction() {  // inline 추가
    // ...
}
// 또는 선언만
void myFunction();  // 정의는 .cpp에

# 중복 링크 제거
target_link_libraries(myapp PRIVATE
    mylib
    # mylib  # 중복 제거
)
# 또는 INTERFACE로 전파
add_library(mylib INTERFACE)
target_link_libraries(mylib INTERFACE
    dependency
)
target_link_libraries(myapp PRIVATE
    mylib  # dependency는 자동 포함
)

에러 9: 라이브러리 찾을 수 없음 (runtime)

증상:

./myapp: error while loading shared libraries: libmylib.so.1: 
cannot open shared object file: No such file or directory

해결책:

Linux

# 방법 1: LD_LIBRARY_PATH 설정
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
./myapp
# 방법 2: ldconfig 업데이트
sudo echo "/usr/local/lib" > /etc/ld.so.conf.d/mylib.conf
sudo ldconfig
# 방법 3: RPATH 설정 (CMake)

# CMakeLists.txt
set(CMAKE_INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/lib")
set(CMAKE_INSTALL_RPATH_USE_LINK_PATH TRUE)
# 또는 $ORIGIN 사용 (실행 파일 기준)
set_target_properties(myapp PROPERTIES
    INSTALL_RPATH "$ORIGIN/../lib"
)

macOS

# DYLD_LIBRARY_PATH 설정
export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH
# 또는 install_name_tool 사용
install_name_tool -change \
    libmylib.dylib \
    @rpath/libmylib.dylib \
    myapp

Windows

# DLL을 실행 파일과 같은 디렉토리에 복사
add_custom_command(TARGET myapp POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
        $<TARGET_FILE:mylib>
        $<TARGET_FILE_DIR:myapp>
)

5. 의존성 관리 에러

에러 10: FetchContent 실패

증상:

CMake Error: Failed to download https://github.com/user/repo/archive/v1.0.tar.gz

해결책:

include(FetchContent)
# 타임아웃 증가
set(FETCHCONTENT_QUIET OFF)
FetchContent_Declare(
    mylib
    GIT_REPOSITORY https://github.com/user/mylib.git
    GIT_TAG v1.0.0
    GIT_SHALLOW TRUE  # 히스토리 없이 빠르게
    TIMEOUT 60  # 타임아웃 60초
)
# 에러 처리
FetchContent_MakeAvailable(mylib)
if(NOT mylib_POPULATED)
    message(FATAL_ERROR "Failed to fetch mylib")
endif()
# 또는 수동으로
FetchContent_GetProperties(mylib)
if(NOT mylib_POPULATED)
    FetchContent_Populate(mylib)
    add_subdirectory(${mylib_SOURCE_DIR} ${mylib_BINARY_DIR})
endif()

에러 11: ExternalProject 빌드 실패

증상:

CMake Error: External project failed to build

해결책:

include(ExternalProject)
ExternalProject_Add(
    mylib_external
    URL https://example.com/mylib-1.0.tar.gz
    URL_HASH SHA256=abc123...
    
    # 빌드 설정
    CMAKE_ARGS
        -DCMAKE_BUILD_TYPE=${CMAKE_BUILD_TYPE}
        -DCMAKE_INSTALL_PREFIX=${CMAKE_BINARY_DIR}/external
        -DCMAKE_C_COMPILER=${CMAKE_C_COMPILER}
        -DCMAKE_CXX_COMPILER=${CMAKE_CXX_COMPILER}
    
    # 로그 활성화
    LOG_DOWNLOAD ON
    LOG_CONFIGURE ON
    LOG_BUILD ON
    LOG_INSTALL ON
    
    # 병렬 빌드
    BUILD_COMMAND ${CMAKE_COMMAND} --build . --parallel
)
# 의존성 추가
add_dependencies(myapp mylib_external)
# 라이브러리 링크
target_link_libraries(myapp PRIVATE
    ${CMAKE_BINARY_DIR}/external/lib/libmylib.a
)
target_include_directories(myapp PRIVATE
    ${CMAKE_BINARY_DIR}/external/include
)

에러 12: vcpkg/Conan 통합 실패

증상:

CMake Error: Could not find vcpkg toolchain file

해결책:

vcpkg

# vcpkg 설치
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh  # Linux/macOS
# .\bootstrap-vcpkg.bat  # Windows
# 패키지 설치
./vcpkg install boost openssl
# CMake 통합
cmake -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake ..

# CMakeLists.txt
if(DEFINED ENV{VCPKG_ROOT} AND NOT DEFINED CMAKE_TOOLCHAIN_FILE)
    set(CMAKE_TOOLCHAIN_FILE "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
        CACHE STRING "")
endif()
project(MyProject)
find_package(Boost REQUIRED)
find_package(OpenSSL REQUIRED)

Conan

# conanfile.txt
[requires]
boost/1.75.0
openssl/1.1.1k
[generators]
cmake_find_package
# 설치
conan install . --build=missing
# CMake
cmake -DCMAKE_PREFIX_PATH=$(pwd) ..

6. 크로스 플랫폼 에러

에러 13: 경로 구분자 문제

증상:

CMake Error: File not found: C:\path\to\file (Windows)
CMake Error: File not found: /path/to/file (Linux)

해결책:

# ❌ 하드코딩된 경로
set(MY_PATH "C:/Users/me/project")
# ✅ 플랫폼 독립적
set(MY_PATH "${CMAKE_SOURCE_DIR}/subdir")
# ✅ 경로 결합
file(TO_CMAKE_PATH "${MY_PATH}" MY_PATH)
# ✅ 네이티브 경로로 변환
file(TO_NATIVE_PATH "${MY_PATH}" MY_NATIVE_PATH)
# ✅ 파일 복사 (자동 경로 변환)
configure_file(
    "${CMAKE_SOURCE_DIR}/config.h.in"
    "${CMAKE_BINARY_DIR}/config.h"
)

에러 14: 플랫폼별 컴파일 옵션 충돌

증상:

cl.exe: error: unknown argument: '-Wall'
gcc: error: unrecognized command line option '/W4'

해결책:

# 플랫폼별 옵션
if(MSVC)
    target_compile_options(myapp PRIVATE
        /W4  # 경고 레벨 4
        /WX  # 경고를 에러로
        /permissive-  # 표준 준수
    )
else()
    target_compile_options(myapp PRIVATE
        -Wall
        -Wextra
        -Werror
        -pedantic
    )
endif()
# 또는 generator expression 사용
target_compile_options(myapp PRIVATE
    $<$<CXX_COMPILER_ID:MSVC>:/W4>
    $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:-Wall>
)
# 플랫폼별 정의
if(WIN32)
    target_compile_definitions(myapp PRIVATE
        _WIN32_WINNT=0x0601  # Windows 7
        NOMINMAX  # min/max 매크로 비활성화
    )
elseif(UNIX)
    target_compile_definitions(myapp PRIVATE
        _GNU_SOURCE
    )
endif()

에러 15: 라이브러리 확장자 차이

증상:

CMake Error: Cannot find libmylib.so (Linux)
CMake Error: Cannot find mylib.dll (Windows)

해결책:

# ❌ 확장자 하드코딩
find_library(MYLIB_LIBRARY mylib.so)
# ✅ 확장자 없이
find_library(MYLIB_LIBRARY mylib)
# ✅ 플랫폼별 처리
if(WIN32)
    set(LIB_SUFFIX ".dll")
elseif(APPLE)
    set(LIB_SUFFIX ".dylib")
else()
    set(LIB_SUFFIX ".so")
endif()
# ✅ CMake 변수 사용
set(CMAKE_FIND_LIBRARY_PREFIXES "lib" "")
set(CMAKE_FIND_LIBRARY_SUFFIXES ".so" ".a" ".dll" ".lib")

7. 캐시 및 설정 에러

에러 16: 캐시된 설정으로 인한 문제

증상:

CMake Error: Variable was cached but is now different

해결책:

# 방법 1: 캐시 삭제
rm CMakeCache.txt
rm -rf CMakeFiles/
# 방법 2: 완전히 새로 빌드
rm -rf build/
mkdir build && cd build
cmake ..
# 방법 3: CMake GUI에서 캐시 삭제
cmake-gui .
# File -> Delete Cache

# 캐시 변수 강제 업데이트
set(MY_VAR "new_value" CACHE STRING "Description" FORCE)
# 캐시 변수 초기화
unset(MY_VAR CACHE)
# 조건부 캐시 설정
if(NOT DEFINED MY_VAR)
    set(MY_VAR "default" CACHE STRING "Description")
endif()

에러 17: Generator 불일치

증상:

CMake Error: Error: generator : Ninja
Does not match the generator used previously: Unix Makefiles

해결책:

# 빌드 디렉토리 삭제 후 재생성
rm -rf build/
mkdir build && cd build
# Generator 명시
cmake -G "Ninja" ..
# 또는
cmake -G "Unix Makefiles" ..
# 또는
cmake -G "Visual Studio 17 2022" ..
# 사용 가능한 Generator 목록
cmake --help

에러 18: Policy 경고

증상:

CMake Warning (dev): Policy CMP0054 is not set

해결책:

# 최소 버전 명시 (자동으로 policy 설정)
cmake_minimum_required(VERSION 3.15)
# 명시적 policy 설정
cmake_policy(SET CMP0054 NEW)
# 여러 policy 설정
if(POLICY CMP0054)
    cmake_policy(SET CMP0054 NEW)
endif()
# Policy 범위 설정
cmake_policy(PUSH)
cmake_policy(SET CMP0054 OLD)
# ....코드 ...
cmake_policy(POP)

8. 고급 디버깅 기법

디버깅 옵션 활성화

# 상세 출력
cmake --debug-output ..
# 변수 추적
cmake --trace ..
# 특정 변수만 추적
cmake --trace-expand --trace-source=CMakeLists.txt ..
# 로그 레벨 설정
cmake --log-level=DEBUG ..

CMakeLists.txt 디버깅

# 변수 출력
message(STATUS "CMAKE_SOURCE_DIR: ${CMAKE_SOURCE_DIR}")
message(STATUS "CMAKE_BINARY_DIR: ${CMAKE_BINARY_DIR}")
message(STATUS "CMAKE_CXX_COMPILER: ${CMAKE_CXX_COMPILER}")
# 모든 변수 출력
get_cmake_property(_variableNames VARIABLES)
foreach(_variableName ${_variableNames})
    message(STATUS "${_variableName}=${${_variableName}}")
endforeach()
# 타겟 속성 출력
get_target_property(MYAPP_SOURCES myapp SOURCES)
message(STATUS "myapp sources: ${MYAPP_SOURCES}")
get_target_property(MYAPP_LINK_LIBS myapp LINK_LIBRARIES)
message(STATUS "myapp link libraries: ${MYAPP_LINK_LIBS}")
# 조건부 디버깅
option(CMAKE_DEBUG "Enable CMake debugging" OFF)
if(CMAKE_DEBUG)
    message(STATUS "=== Debug Info ===")
    message(STATUS "Build type: ${CMAKE_BUILD_TYPE}")
    message(STATUS "C++ flags: ${CMAKE_CXX_FLAGS}")
    message(STATUS "Link flags: ${CMAKE_EXE_LINKER_FLAGS}")
endif()

빌드 로그 분석

# 상세 빌드 로그
cmake --build . --verbose
# 또는 make 사용 시
make VERBOSE=1
# Ninja 사용 시
ninja -v
# 로그 파일로 저장
cmake --build . --verbose > build.log 2>&1
# 특정 타겟만 빌드
cmake --build . --target myapp --verbose

링커 명령 확인

# 링커 명령 출력
set(CMAKE_VERBOSE_MAKEFILE ON)
# 또는
set_target_properties(myapp PROPERTIES
    LINK_WHAT_YOU_USE TRUE
)
# 링커 맵 파일 생성
if(UNIX)
    target_link_options(myapp PRIVATE
        -Wl,-Map=myapp.map
    )
elseif(MSVC)
    target_link_options(myapp PRIVATE
        /MAP:myapp.map
    )
endif()

9. 예방 및 베스트 프랙티스

1) 견고한 CMakeLists.txt 작성

# 최소 버전 명시 (최신 버전 권장)
cmake_minimum_required(VERSION 3.15)
# 프로젝트 정보
project(MyProject
    VERSION 1.0.0
    DESCRIPTION "My awesome project"
    LANGUAGES CXX
)
# C++ 표준 설정
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)
# 빌드 타입 기본값
if(NOT CMAKE_BUILD_TYPE)
    set(CMAKE_BUILD_TYPE Release CACHE STRING "Build type" FORCE)
endif()
# 출력 디렉토리 통일
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin)
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/lib)
# 옵션 제공
option(BUILD_SHARED_LIBS "Build shared libraries" OFF)
option(BUILD_TESTS "Build tests" ON)
option(ENABLE_WARNINGS "Enable compiler warnings" ON)
# 의존성 찾기 (에러 처리 포함)
find_package(Boost 1.70 COMPONENTS system filesystem)
if(NOT Boost_FOUND)
    message(FATAL_ERROR "Boost not found. Install: sudo apt-get install libboost-all-dev")
endif()
# 타겟 정의
add_executable(myapp src/main.cpp)
# 타겟 속성 설정
target_include_directories(myapp PRIVATE
    ${CMAKE_SOURCE_DIR}/include
    ${Boost_INCLUDE_DIRS}
)
target_link_libraries(myapp PRIVATE
    Boost::system
    Boost::filesystem
)
# 컴파일 옵션
if(ENABLE_WARNINGS)
    if(MSVC)
        target_compile_options(myapp PRIVATE /W4)
    else()
        target_compile_options(myapp PRIVATE -Wall -Wextra)
    endif()
endif()
# 설치 규칙
install(TARGETS myapp
    RUNTIME DESTINATION bin
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
)

2) 의존성 관리 전략

# 방법 1: FetchContent (간단, 빠름)
include(FetchContent)
FetchContent_Declare(
    googletest
    GIT_REPOSITORY https://github.com/google/googletest.git
    GIT_TAG release-1.11.0
)
FetchContent_MakeAvailable(googletest)
# 방법 2: find_package + Fallback
find_package(fmt 8.0)
if(NOT fmt_FOUND)
    message(STATUS "fmt not found, fetching...")
    FetchContent_Declare(
        fmt
        GIT_REPOSITORY https://github.com/fmtlib/fmt.git
        GIT_TAG 8.1.1
    )
    FetchContent_MakeAvailable(fmt)
endif()
# 방법 3: 조건부 의존성
if(ENABLE_FEATURE_X)
    find_package(LibX REQUIRED)
    target_link_libraries(myapp PRIVATE LibX::LibX)
    target_compile_definitions(myapp PRIVATE FEATURE_X_ENABLED)
endif()

3) 에러 예방 체크리스트

# 1. 변수 존재 확인
if(NOT DEFINED MY_VAR)
    message(FATAL_ERROR "MY_VAR is not defined")
endif()
# 2. 파일 존재 확인
if(NOT EXISTS "${CMAKE_SOURCE_DIR}/config.h.in")
    message(FATAL_ERROR "config.h.in not found")
endif()
# 3. 타겟 존재 확인
if(TARGET mylib)
    target_link_libraries(myapp PRIVATE mylib)
else()
    message(WARNING "mylib target not found")
endif()
# 4. 컴파일러 기능 확인
include(CheckCXXCompilerFlag)
check_cxx_compiler_flag(-std=c++17 HAS_CXX17)
if(NOT HAS_CXX17)
    message(FATAL_ERROR "Compiler does not support C++17")
endif()
# 5. 헤더 파일 확인
include(CheckIncludeFileCXX)
check_include_file_cxx("filesystem" HAS_FILESYSTEM)
if(NOT HAS_FILESYSTEM)
    message(FATAL_ERROR "<filesystem> header not found")
endif()
# 6. 함수 존재 확인
include(CheckFunctionExists)
check_function_exists(pthread_create HAS_PTHREAD)
if(NOT HAS_PTHREAD)
    message(FATAL_ERROR "pthread_create not found")
endif()

4) 빌드 스크립트 자동화

#!/bin/bash
# build.sh
set -e  # 에러 시 중단
# 색상 정의
RED='\033[0;31m'
GREEN='\033[0;32m'
NC='\033[0m'  # No Color
# 함수 정의
error() {
    echo -e "${RED}Error: $1${NC}" >&2
    exit 1
}
success() {
    echo -e "${GREEN}$1${NC}"
}
# 의존성 확인
command -v cmake >/dev/null 2>&1 || error "CMake not found"
command -v ninja >/dev/null 2>&1 || error "Ninja not found"
# 빌드 디렉토리 생성
BUILD_DIR="build"
rm -rf "$BUILD_DIR"
mkdir -p "$BUILD_DIR"
cd "$BUILD_DIR"
# CMake 설정
cmake -G Ninja \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
    ...|| error "CMake configuration failed"
# 빌드
cmake --build . --parallel || error "Build failed"
# 테스트
if [ -f "bin/myapp_test" ]; then
    ./bin/myapp_test || error "Tests failed"
    success "All tests passed!"
fi
success "Build completed successfully!"

정리

핵심 요약

에러 분류
- Configure 에러: 컴파일러, find_package 실패
- Generate 에러: Generator, Toolchain 문제
- Build 에러: 컴파일, 링커 에러
주요 에러 패턴
- 컴파일러 찾기 실패 → PATH 확인, 명시적 지정
- find_package 실패 → 설치 경로 지정, CMAKE_PREFIX_PATH
- 링커 에러 → target_link_libraries, 순서 확인
- 크로스 플랫폼 → 플랫폼별 분기, generator expression
디버깅 기법
- --debug-output, --trace 옵션
- message(STATUS) 활용
- VERBOSE 빌드 로그
예방 전략
- 명확한 에러 메시지
- 의존성 버전 명시
- 플랫폼 독립적 코드
- 자동화된 빌드 스크립트

빠른 참조

# 캐시 삭제
rm CMakeCache.txt
# 상세 출력
cmake --debug-output ..
# 빌드 로그
cmake --build . --verbose
# Generator 변경
cmake -G "Ninja" ..
# 변수 지정
cmake -DCMAKE_PREFIX_PATH=/usr/local ..
# 컴파일러 지정
cmake -DCMAKE_CXX_COMPILER=g++-11 ..

체크리스트

참고 자료

CMake Documentation
CMake Discourse
Professional CMake
Effective CMake 한 줄 요약: CMake 에러는 Configure/Generate/Build 단계로 분류되며, 컴파일러/라이브러리 경로 명시, 캐시 삭제, VERBOSE 로그 확인으로 대부분 해결 가능하고, 플랫폼 독립적 코드와 명확한 에러 메시지로 예방할 수 있습니다.

심화 부록: 구현·운영 관점

이 부록은 앞선 본문에서 다룬 주제(「CMake 에러 완벽 해결 가이드 | 빌드 실패·의존성·링커 에러 트러블슈팅」)를 구현·런타임·운영 관점에서 다시 압축합니다. 도메인별 세부 구현은 글마다 다르지만, 입력 검증 → 핵심 연산 → 부작용(I/O·네트워크·동시성) → 관측의 흐름으로 장애를 나누면 원인 추적이 빨라집니다.

내부 동작과 핵심 메커니즘

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]

sequenceDiagram
  participant C as 클라이언트/호출자
  participant B as 경계(런타임·게이트웨이·프로세스)
  participant D as 의존성(API·DB·큐·파일)
  C->>B: 요청/이벤트
  B->>D: 조회·쓰기·RPC
  D-->>B: 지연·부분 실패·재시도 가능
  B-->>C: 응답 또는 오류(코드·상관 ID)

불변 조건(Invariant): 버퍼 경계, 프로토콜 상태, 트랜잭션 격리, FD 상한 등 단계별로 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
결정성: 순수 층과 시간·네트워크·스케줄에 의존하는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
경계 비용: 직렬화, 인코딩, syscall 횟수, 락 경합, 할당·GC, 캐시 미스를 의심 목록에 둡니다.
백프레셔: 생산자가 소비자보다 빠를 때 버퍼·큐·스트림에서 속도를 줄이는 신호를 어디에 둘지 정의합니다.

프로덕션 운영 패턴

영역	운영 관점 질문
관측성	요청 단위 상관 ID, 에러율·지연 p95/p99, 의존성 타임아웃·재시도가 대시보드에 보이는가
안전성	입력 검증·권한·비밀·감사 로그가 코드 경로마다 일관적인가
신뢰성	재시도는 멱등 연산에만 적용되는가, 서킷 브레이커·백오프·DLQ가 있는가
성능	캐시·배치 크기·커넥션 풀·인덱스·백프레셔가 데이터 규모에 맞는가
배포	롤백 룬북, 카나리/블루그린, 마이그레이션·피처 플래그가 문서화되어 있는가
용량	피크 트래픽·디스크·FD·스레드 풀 상한을 주기적으로 검증하는가

스테이징은 데이터 양·네트워크 RTT·동시성을 프로덕션에 가깝게 맞출수록 재현율이 올라갑니다.

확장 예시: 엔드투엔드 미니 시나리오

앞선 본문 주제(「CMake 에러 완벽 해결 가이드 | 빌드 실패·의존성·링커 에러 트러블슈팅」)를 배포·운영 흐름에 맞춰 옮긴 체크리스트입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.

입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드를 경계에 둔다.
핵심 경로 계측: 요청 ID, 단계별 지연, 외부 호출 결과 코드를 로그·메트릭·트레이스에서 한 흐름으로 본다.
실패 주입: 의존성 타임아웃·5xx·부분 데이터·락 대기를 스테이징에서 재현한다.
호환·롤백: 설정/마이그레이션/클라이언트 버전을 되돌릴 수 있는지 확인한다.
부하 후 검증: 피크 대비 p95/p99, 에러율, 리소스 상한, 알림 임계값을 점검한다.

handle(request):
  ctx = newCorrelationId()
  validated = validateSchema(request)
  authorize(validated, ctx)
  result = domainCore(validated)
  persistOrEmit(result, idempotentKey)
  recordMetrics(ctx, latency, outcome)
  return result

문제 해결(Troubleshooting)

증상	가능 원인	조치
간헐적 실패	레이스, 타임아웃, 외부 의존성, DNS	최소 재현 스크립트, 분산 트레이스·로그 상관관계, 재시도·서킷 설정 점검
성능 저하	N+1, 동기 I/O, 락 경합, 과도한 직렬화, 캐시 미스	프로파일러·APM으로 핫스팟 확인 후 한 가지씩 제거
메모리 증가	캐시 무제한, 구독/리스너 누수, 대용량 버퍼, 커넥션 미반납	상한·TTL·힙/FD 스냅샷 비교
빌드·배포만 실패	환경 변수, 권한, 플랫폼 차이, lockfile	CI 로그와 로컬 diff, 런타임·이미지 버전 핀
설정 불일치	프로필·시크릿·기본값, 리전	스키마 검증된 설정 단일 소스와 배포 매트릭스 표준화
데이터 불일치	비멱등 재시도, 부분 쓰기, 캐시 무효화 누락	멱등 키·아웃박스·트랜잭션 경계 재검토

권장 순서: (1) 최소 재현 (2) 최근 변경 범위 축소 (3) 환경·의존성 차이 (4) 관측으로 가설 검증 (5) 수정 후 회귀·부하 테스트.

배포 전에는 git add → git commit → git push 후 npm run deploy 순서를 권장합니다.

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

A. CMake 빌드 에러의 원인과 해결책을 상세히 분석합니다. 컴파일러 찾기 실패, 라이브러리 링킹 에러, 의존성 문제, 크로스 플랫폼 빌드 이슈까지 실전 트러블슈팅 가이드. Start now. 실무에서는 위 본문의 예제와 선택 가이드를 참고해 적용하면 됩니다.

Q. 선행으로 읽으면 좋은 글은?

A. 각 글 하단의 이전 글 또는 관련 글 링크를 따라가면 순서대로 배울 수 있습니다. C++ 시리즈 목차에서 전체 흐름을 확인할 수 있습니다.

Q. 더 깊이 공부하려면?

A. cppreference와 해당 라이브러리 공식 문서를 참고하세요. 글 말미의 참고 자료 링크도 활용하면 좋습니다.

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

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

이 글에서 다루는 키워드 (관련 검색어)

CMake, Build, Error, Troubleshooting, C++, Debugging 등으로 검색하시면 이 글이 도움이 됩니다.

이 글이 도움이 되셨나요?

여러분의 피드백은 더 나은 콘텐츠를 만드는 데 도움이 됩니다

문제가 있거나 개선 제안이 있으시면 연락처로 알려주세요.

Keyboard Shortcuts

이 글의 핵심

🎯 이 글을 읽으면 (읽는 시간: 50분)

이 글의 핵심

들어가며: “CMake가 왜 실패하죠?”

흔한 에러 시나리오

Windows에서는 빌드되는데 Linux에서 실패합니다.

1. CMake 에러 분류 체계

에러 단계별 분류

에러 심각도

2. 컴파일러 관련 에러

에러 1: 컴파일러를 찾을 수 없음

Linux/macOS

Windows

에러 2: 컴파일러 버전 불일치

에러 3: 크로스 컴파일 설정 오류

3. 라이브러리 찾기 에러

에러 4: find_package 실패

방법 1: 설치 경로 명시

방법 2: CMAKE_PREFIX_PATH 사용

방법 3: CMakeLists.txt 수정

에러 5: 라이브러리 버전 충돌

에러 6: Config vs Module 모드 혼동

4. 링커 에러

에러 7: undefined reference

방법 1: 명시적 링크

방법 2: 링크 순서 조정

방법 3: 전체 아카이브 링크

에러 8: 중복 심볼 (duplicate symbol)

에러 9: 라이브러리 찾을 수 없음 (runtime)

Linux

macOS

Windows

5. 의존성 관리 에러

에러 10: FetchContent 실패

에러 11: ExternalProject 빌드 실패

에러 12: vcpkg/Conan 통합 실패

vcpkg

Conan

6. 크로스 플랫폼 에러

에러 13: 경로 구분자 문제

에러 14: 플랫폼별 컴파일 옵션 충돌

에러 15: 라이브러리 확장자 차이

7. 캐시 및 설정 에러

에러 16: 캐시된 설정으로 인한 문제

에러 17: Generator 불일치

에러 18: Policy 경고

8. 고급 디버깅 기법

디버깅 옵션 활성화

CMakeLists.txt 디버깅

빌드 로그 분석

링커 명령 확인

9. 예방 및 베스트 프랙티스

1) 견고한 CMakeLists.txt 작성

2) 의존성 관리 전략

3) 에러 예방 체크리스트

4) 빌드 스크립트 자동화

정리

핵심 요약

빠른 참조

체크리스트

참고 자료

심화 부록: 구현·운영 관점

내부 동작과 핵심 메커니즘

프로덕션 운영 패턴

확장 예시: 엔드투엔드 미니 시나리오

문제 해결(Troubleshooting)

자주 묻는 질문 (FAQ)

Q. 이 내용을 실무에서 언제 쓰나요?

Q. 선행으로 읽으면 좋은 글은?

Q. 더 깊이 공부하려면?

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

이 글에서 다루는 키워드 (관련 검색어)

이 글이 도움이 되셨나요?