[2026] C++ CMake | 빌드 시스템 초보자 가이드

· 11분 읽기 · 수정 중급 튜토리얼
[2026] C++ CMake | 빌드 시스템 초보자 가이드

이 글의 핵심

cmake_minimum_required(VERSION 3.10) project(MyProject).

다른 생태계와 비교

CMake는 메타 빌드 시스템(실제 빌드는 Make·Ninja·IDE가 담당)입니다. Rust의 Cargo·npm·Go 모듈처럼 언어와 패키지 매니저가 한 축에 있는 구조와 달리, C++는 CMake + Conan 또는 vcpkg 조합으로 맞추는 경우가 많습니다. Python pip·uv·Poetry와 의존성 락·재현 빌드를 비교해 보면 팀 표준을 잡기 쉽습니다. Makefile 직접 작성과의 관계는 C++ Makefile·빌드 시스템 비교를 함께 보세요.

기본 CMakeLists.txt

아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

cmake_minimum_required(VERSION 3.10)
project(MyProject)
set(CMAKE_CXX_STANDARD 17)
add_executable(myapp main.cpp)

빌드: 아래 코드는 bash를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

mkdir build
cd build
cmake ..
make
./myapp

여러 소스 파일

아래 코드는 cmake를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

cmake_minimum_required(VERSION 3.10)
project(MyProject)
set(CMAKE_CXX_STANDARD 17)
add_executable(myapp 
    main.cpp
    utils.cpp
    math.cpp
)

라이브러리 만들기

다음은 cmake를 활용한 상세한 구현 코드입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# 정적 라이브러리
add_library(mylib STATIC
    lib.cpp
    helper.cpp
)
# 동적 라이브러리
add_library(mylib SHARED
    lib.cpp
    helper.cpp
)
# 실행 파일에 링크
add_executable(myapp main.cpp)
target_link_libraries(myapp mylib)

헤더 파일 경로

아래 코드는 cmake를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# 프로젝트 구조
# project/
#   CMakeLists.txt
#   src/
#     main.cpp
#   include/
#     mylib.h
cmake_minimum_required(VERSION 3.10)
project(MyProject)
include_directories(${PROJECT_SOURCE_DIR}/include)
add_executable(myapp src/main.cpp)

실전 예시

예시 1: 기본 프로젝트 구조

아래 코드는 code를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

MyProject/
├── CMakeLists.txt
├── src/
│   ├── main.cpp
│   ├── math.cpp
│   └── utils.cpp
├── include/
│   ├── math.h
│   └── utils.h
└── build/

CMakeLists.txt: 다음은 cmake를 활용한 상세한 구현 코드입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

cmake_minimum_required(VERSION 3.10)
project(MyProject VERSION 1.0)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED True)
# 헤더 파일 경로
include_directories(${PROJECT_SOURCE_DIR}/include)
# 소스 파일 목록
set(SOURCES
    src/main.cpp
    src/math.cpp
    src/utils.cpp
)
# 실행 파일 생성
add_executable(myapp ${SOURCES})
# 컴파일 옵션
target_compile_options(myapp PRIVATE
    -Wall
    -Wextra
    -O2
)

빌드: 다음은 간단한 bash 코드 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

mkdir build && cd build
cmake ..
make
./myapp

예시 2: 외부 라이브러리 사용

아래 코드는 cmake를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

cmake_minimum_required(VERSION 3.10)
project(MyProject)
set(CMAKE_CXX_STANDARD 17)
# pthread 찾기
find_package(Threads REQUIRED)
add_executable(myapp main.cpp)
# pthread 링크
target_link_libraries(myapp Threads::Threads)

예시 3: 서브디렉토리 구조

아래 코드는 code를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

MyProject/
├── CMakeLists.txt
├── app/
│   ├── CMakeLists.txt
│   └── main.cpp
└── lib/
    ├── CMakeLists.txt
    ├── mylib.cpp
    └── mylib.h

루트 CMakeLists.txt: 아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

// 실행 예제
cmake_minimum_required(VERSION 3.10)
project(MyProject)
set(CMAKE_CXX_STANDARD 17)
add_subdirectory(lib)
add_subdirectory(app)

lib/CMakeLists.txt: 아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

// 실행 예제
add_library(mylib STATIC
    mylib.cpp
)
target_include_directories(mylib PUBLIC
    ${CMAKE_CURRENT_SOURCE_DIR}
)

app/CMakeLists.txt:

add_executable(myapp main.cpp)
target_link_libraries(myapp mylib)

고급 기능

조건부 컴파일

아래 코드는 cmake를 사용한 구현 예제입니다. 조건문으로 분기 처리를 수행합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

option(BUILD_TESTS "Build tests" ON)
if(BUILD_TESTS)
    add_subdirectory(tests)
endif()
# 사용
cmake -DBUILD_TESTS=OFF ..

플랫폼별 설정

아래 코드는 cmake를 사용한 구현 예제입니다. 조건문으로 분기 처리를 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

if(WIN32)
    # Windows
    add_definitions(-DWINDOWS)
elseif(APPLE)
    # macOS
    add_definitions(-DMACOS)
elseif(UNIX)
    # Linux
    add_definitions(-DLINUX)
endif()

빌드 타입

아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

# Debug, Release, RelWithDebInfo, MinSizeRel
set(CMAKE_BUILD_TYPE Release)
# 사용
cmake -DCMAKE_BUILD_TYPE=Debug ..

설치 규칙

다음은 cmake를 활용한 상세한 구현 코드입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# 실행 파일 설치
install(TARGETS myapp
    DESTINATION bin
)
# 헤더 파일 설치
install(FILES mylib.h
    DESTINATION include
)
# 라이브러리 설치
install(TARGETS mylib
    DESTINATION lib
)
# 사용
make install

자주 발생하는 문제

문제 1: 헤더 파일을 찾을 수 없음

증상: fatal error: mylib.h: No such file or directory 원인: include 경로 미설정 해결법: 아래 코드는 cmake를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# ❌ 경로 없음
add_executable(myapp main.cpp)
# ✅ 경로 추가
include_directories(${PROJECT_SOURCE_DIR}/include)
add_executable(myapp main.cpp)
# ✅ target 단위로 추가 (더 권장)
target_include_directories(myapp PRIVATE
    ${PROJECT_SOURCE_DIR}/include
)

문제 2: 라이브러리 링크 에러

증상: undefined reference to function 원인: 라이브러리 링크 누락 해결법: 아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

# ❌ 링크 안됨
add_executable(myapp main.cpp)
# ✅ 라이브러리 링크
add_executable(myapp main.cpp)
target_link_libraries(myapp mylib)

문제 3: CMake 캐시 문제

증상: 설정 변경이 반영 안됨 원인: 캐시된 설정 해결법: 아래 코드는 bash를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

# build 디렉토리 삭제
rm -rf build
mkdir build && cd build
cmake ..
# 또는 캐시만 삭제
rm CMakeCache.txt
cmake ..

유용한 명령어

변수 출력

message(STATUS "CMAKE_CXX_COMPILER: ${CMAKE_CXX_COMPILER}")
message(STATUS "PROJECT_SOURCE_DIR: ${PROJECT_SOURCE_DIR}")

파일 목록 자동 생성

아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

file(GLOB SOURCES "src/*.cpp")
add_executable(myapp ${SOURCES})
# 재귀적으로
file(GLOB_RECURSE SOURCES "src/*.cpp")

컴파일러 체크

아래 코드는 cmake를 사용한 구현 예제입니다. 조건문으로 분기 처리를 수행합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
    target_compile_options(myapp PRIVATE -Wall -Wextra)
elseif(MSVC)
    target_compile_options(myapp PRIVATE /W4)
endif()

FAQ

Q1: CMake vs Makefile?

A:

  • CMake: 크로스 플랫폼, 자동 생성
  • Makefile: 플랫폼 종속적, 수동 작성

Q2: out-of-source 빌드란?

A: 소스 디렉토리와 빌드 디렉토리를 분리하는 것입니다. 권장됩니다. 아래 코드는 bash를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

# out-of-source (권장)
mkdir build && cd build
cmake ..
# in-source (비권장)
cmake .

Q3: 어떤 버전의 CMake를 사용해야 하나요?

A: 최소 3.10 이상, 가능하면 최신 버전을 사용하세요.

Q4: find_package는 어떻게 작동하나요?

A: CMake가 시스템에서 라이브러리를 찾아줍니다.

find_package(OpenCV REQUIRED)
target_link_libraries(myapp ${OpenCV_LIBS})

Q5: 여러 빌드 타입을 동시에?

A: 빌드 디렉토리를 여러 개 만드세요. 아래 코드는 bash를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

mkdir build-debug && cd build-debug
cmake -DCMAKE_BUILD_TYPE=Debug ..
mkdir build-release && cd build-release
cmake -DCMAKE_BUILD_TYPE=Release ..

Q6: CMake 학습 리소스는?

A:

  • 공식 문서: cmake.org
  • Modern CMake: cliutils.gitlab.io/modern-cmake
  • 예제: github.com/ttroy50/cmake-examples

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

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

관련 글

... 996 lines not shown ... Token usage: 63706/1000000; 936294 remaining Start-Sleep -Seconds 3