C++ CMake | "빌드 시스템" 초보자 가이드

다른 생태계와 비교

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

기본 CMakeLists.txt

cmake_minimum_required(VERSION 3.10)
project(MyProject)

set(CMAKE_CXX_STANDARD 17)

add_executable(myapp main.cpp)

빌드:

mkdir build
cd build
cmake ..
make
./myapp

여러 소스 파일

cmake_minimum_required(VERSION 3.10)
project(MyProject)

set(CMAKE_CXX_STANDARD 17)

add_executable(myapp 
    main.cpp
    utils.cpp
    math.cpp
)

라이브러리 만들기

# 정적 라이브러리
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)

헤더 파일 경로

# 프로젝트 구조
# 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: 기본 프로젝트 구조

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

CMakeLists.txt:

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
)

빌드:

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

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

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: 서브디렉토리 구조

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

루트 CMakeLists.txt:

cmake_minimum_required(VERSION 3.10)
project(MyProject)

set(CMAKE_CXX_STANDARD 17)

add_subdirectory(lib)
add_subdirectory(app)

lib/CMakeLists.txt:

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)

고급 기능

조건부 컴파일

option(BUILD_TESTS "Build tests" ON)

if(BUILD_TESTS)
    add_subdirectory(tests)
endif()

# 사용
cmake -DBUILD_TESTS=OFF ..

플랫폼별 설정

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

빌드 타입

# Debug, Release, RelWithDebInfo, MinSizeRel
set(CMAKE_BUILD_TYPE Release)

# 사용
cmake -DCMAKE_BUILD_TYPE=Debug ..

설치 규칙

# 실행 파일 설치
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 경로 미설정

해결법:

# ❌ 경로 없음
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

원인: 라이브러리 링크 누락

해결법:

# ❌ 링크 안됨
add_executable(myapp main.cpp)

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

문제 3: CMake 캐시 문제

증상: 설정 변경이 반영 안됨

원인: 캐시된 설정

해결법:

# 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}")

파일 목록 자동 생성

file(GLOB SOURCES "src/*.cpp")
add_executable(myapp ${SOURCES})

# 재귀적으로
file(GLOB_RECURSE SOURCES "src/*.cpp")

컴파일러 체크

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: 소스 디렉토리와 빌드 디렉토리를 분리하는 것입니다. 권장됩니다.

# 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: 빌드 디렉토리를 여러 개 만드세요.

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

---

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

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

• C++ CMake 고급 | 멀티 타겟·외부 라이브러리 관리 (대규모 프로젝트 빌드)
• C++ Compilation Process | “컴파일 과정” 가이드
• C++ Makefile | “Make 빌드” 가이드

관련 글

• C++ CMake find_package 완벽 가이드 | 외부 라이브러리 통합
• C++ CMake Targets 완벽 가이드 | 타겟 기반 빌드 시스템
• CMake 에러 |
• C++ CMake 고급 | 멀티 타겟·외부 라이브러리 관리 (대규모 프로젝트 빌드)
• C++ vcpkg 고급 활용 | Manifest·Triplet·오버레이·바이너리 캐시 가이드