[2026] C++ CMake Targets 완벽 가이드 | 타겟 기반 빌드 시스템

· 16분 읽기 · 수정 중급 튜토리얼
[2026] C++ CMake Targets 완벽 가이드 | 타겟 기반 빌드 시스템

이 글의 핵심

C++ CMake Targets : 타겟 기반 빌드 시스템. CMake Targets란?. 왜 타겟 기반인가·타겟 생성.

다른 빌드 모델과 비교

CMake 타겟은 의존성 그래프의 노드에 가깝습니다. Rust Cargo의 크레이트·타겟이나 npm 패키지 트리와 완전히 같지는 않지만, “무엇이 무엇에 링크되는가”를 명시한다는 점에서 비교하면 팀 온보딩에 도움이 됩니다. Make 기반은 C++ Makefile·빌드 시스템 비교와 연결해 보세요.

CMake Targets란? 왜 타겟 기반인가

문제 시나리오: 전역 설정의 혼란

문제: 예전 CMake 스타일에서는 include_directories(), link_libraries() 같은 전역 명령을 썼습니다. 프로젝트가 커지면 어떤 타겟이 어떤 헤더를 쓰는지 추적하기 어렵고, 의존성이 꼬입니다. 아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

# ❌ 구식: 전역 설정
include_directories(/usr/local/include)
link_libraries(boost_system)
add_executable(app1 main1.cpp)
add_executable(app2 main2.cpp)
# app1, app2 모두 boost_system에 링크됨 (의도하지 않았을 수도)

해결: 타겟 기반 명령(target_*)을 쓰면 각 타겟의 의존성이 명확해지고, 불필요한 링크가 없어집니다. 아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

# ✅ 모던: 타겟별 설정
add_executable(app1 main1.cpp)
target_include_directories(app1 PRIVATE /usr/local/include)
target_link_libraries(app1 PRIVATE Boost::system)
add_executable(app2 main2.cpp)
# app2는 boost에 링크되지 않음

타겟이란

타겟은 CMake에서 빌드할 대상(실행 파일, 라이브러리)을 의미합니다. add_executable, add_library로 타겟을 만들고, target_* 명령으로 각 타겟의 속성(헤더 경로, 링크 라이브러리, 컴파일 옵션)을 설정합니다. 다음은 mermaid를 활용한 상세한 구현 코드입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 실행 예제
flowchart TD
    subgraph targets[타겟]
        exe[add_executable(myapp)]
        lib[add_library(mylib)]
    end
    subgraph properties[타겟 속성]
        inc[target_include_directories]
        link[target_link_libraries]
        opt[target_compile_options]
        def[target_compile_definitions]
    end
    exe --> inc
    exe --> link
    lib --> inc
    lib --> opt

목차

  1. 타겟 생성: add_executable, add_library
  2. 타겟 속성: target_* 명령어
  3. 가시성: PUBLIC, PRIVATE, INTERFACE
  4. 의존성 전파
  5. 자주 발생하는 문제와 해결법
  6. 프로덕션 패턴
  7. 완전한 예제: 멀티 라이브러리 프로젝트

1. 타겟 생성

실행 파일

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

# 단일 소스
add_executable(myapp main.cpp)
# 여러 소스
add_executable(myapp
    src/main.cpp
    src/utils.cpp
    src/config.cpp
)
# 변수 사용
set(APP_SOURCES
    src/main.cpp
    src/utils.cpp
)
add_executable(myapp ${APP_SOURCES})

정적 라이브러리

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

add_library(mylib STATIC
    src/lib.cpp
    src/helper.cpp
)

동적 라이브러리

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

add_library(mylib SHARED
    src/lib.cpp
    src/helper.cpp
)

헤더 전용 라이브러리

add_library(mylib INTERFACE)
target_include_directories(mylib INTERFACE include)

OBJECT 라이브러리

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

# 오브젝트 파일만 생성 (링크 안 함)
add_library(myobj OBJECT
    src/common.cpp
)
# 여러 타겟에서 재사용
add_executable(app1 main1.cpp $<TARGET_OBJECTS:myobj>)
add_executable(app2 main2.cpp $<TARGET_OBJECTS:myobj>)

2. 타겟 속성: target_* 명령어

target_include_directories

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

add_library(mylib src/lib.cpp)
target_include_directories(mylib
    PUBLIC include          # 외부에 노출
    PRIVATE src/internal    # 내부 전용
)

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

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE
    mylib
    Boost::filesystem
    pthread
)

target_compile_options

아래 코드는 cmake를 사용한 구현 예제입니다. 에러 처리를 통해 안정성을 확보합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

target_compile_options(myapp PRIVATE
    -Wall
    -Wextra
    -Werror
    $<$<CONFIG:Debug>:-O0 -g>
    $<$<CONFIG:Release>:-O3>
)

target_compile_definitions

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

target_compile_definitions(myapp PRIVATE
    APP_VERSION="1.0"
    $<$<CONFIG:Debug>:DEBUG_MODE>
    $<$<PLATFORM_ID:Windows>:WINDOWS_BUILD>
)

target_compile_features

# C++20 기능 요구
target_compile_features(myapp PRIVATE cxx_std_20)

3. 가시성: PUBLIC, PRIVATE, INTERFACE

개념

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

flowchart LR
    subgraph lib[mylib]
        priv["PRIVATE\n내부 전용"]
        pub["PUBLIC\n외부 노출"]
        iface[INTERFACE\n전파만]
    end
    subgraph app[myapp]
        use[사용]
    end
    pub --> use
    iface --> use
키워드타겟 자신의존 타겟
PRIVATE사용사용 안 함
PUBLIC사용사용
INTERFACE사용 안 함사용

실전 예시

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

# mylib: 라이브러리
add_library(mylib src/lib.cpp)
target_include_directories(mylib
    PUBLIC include              # mylib를 링크하는 타겟도 include/ 사용
    PRIVATE src/internal        # mylib 내부에서만 사용
)
target_compile_definitions(mylib
    PUBLIC MYLIB_VERSION=1      # mylib를 링크하는 타겟도 정의됨
    PRIVATE MYLIB_INTERNAL      # mylib 내부에서만 정의됨
)
# myapp: 실행 파일
add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE mylib)
# myapp은 include/ 사용 가능 (PUBLIC)
# myapp은 src/internal 사용 불가 (PRIVATE)
# myapp에 MYLIB_VERSION 정의됨 (PUBLIC)

INTERFACE 사용 사례

헤더 전용 라이브러리에서 사용합니다. 아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

add_library(header_only INTERFACE)
target_include_directories(header_only INTERFACE include)
target_compile_definitions(header_only INTERFACE HEADER_ONLY_LIB)
add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE header_only)
# myapp은 include/ 사용 가능
# myapp에 HEADER_ONLY_LIB 정의됨

4. 의존성 전파

전이적 의존성

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

# liba: 최하위 라이브러리
add_library(liba STATIC a.cpp)
target_include_directories(liba PUBLIC include/a)
# libb: liba에 의존
add_library(libb STATIC b.cpp)
target_link_libraries(libb PUBLIC liba)
target_include_directories(libb PUBLIC include/b)
# myapp: libb에 의존
add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE libb)
# myapp은 include/a, include/b 모두 사용 가능 (PUBLIC 전파)

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

flowchart TD
    liba["liba\nPUBLIC include/a"]
    libb["libb\nPUBLIC include/b"]
    myapp[myapp]
    
    libb -->|PUBLIC| liba
    myapp -->|PRIVATE| libb
    
    note1["myapp은 include/a, include/b 모두 사용 가능"]

PRIVATE로 전파 차단

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

# libb가 liba를 PRIVATE로 링크
target_link_libraries(libb PRIVATE liba)
# myapp
target_link_libraries(myapp PRIVATE libb)
# myapp은 include/b만 사용 가능 (liba는 전파 안 됨)

5. 자주 발생하는 문제와 해결법

문제 1: 전역 명령 사용

원인: include_directories(), link_libraries() 같은 전역 명령은 이후 모든 타겟에 영향을 줍니다. 아래 코드는 cmake를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# ❌ 잘못된 사용
include_directories(/usr/local/include)
add_executable(app1 main1.cpp)
add_executable(app2 main2.cpp)
# app1, app2 모두 /usr/local/include 사용
# ✅ 올바른 사용: 타겟별 설정
add_executable(app1 main1.cpp)
target_include_directories(app1 PRIVATE /usr/local/include)
add_executable(app2 main2.cpp)
# app2는 영향 없음

문제 2: PUBLIC/PRIVATE 혼동

증상: 헤더를 찾지 못하거나, 불필요한 헤더가 노출됨. 아래 코드는 cmake를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# ❌ 잘못된 사용: 내부 헤더를 PUBLIC으로
add_library(mylib src/lib.cpp)
target_include_directories(mylib PUBLIC src/internal)
# src/internal이 외부에 노출됨
# ✅ 올바른 사용
target_include_directories(mylib
    PUBLIC include          # API 헤더
    PRIVATE src/internal    # 구현 헤더
)

문제 3: 순환 의존성

증상: CMake Error: Circular dependency. 원인: A가 B를 링크하고, B가 A를 링크함. 아래 코드는 cmake를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

# ❌ 잘못된 사용
add_library(liba a.cpp)
add_library(libb b.cpp)
target_link_libraries(liba PRIVATE libb)
target_link_libraries(libb PRIVATE liba)  # 순환!
# ✅ 올바른 사용: 의존성 재설계
# liba, libb가 모두 의존하는 공통 코드를 libcommon으로 분리
add_library(libcommon common.cpp)
add_library(liba a.cpp)
add_library(libb b.cpp)
target_link_libraries(liba PRIVATE libcommon)
target_link_libraries(libb PRIVATE libcommon)

문제 4: OBJECT 라이브러리 링크

원인: OBJECT 라이브러리는 target_link_libraries로 직접 링크할 수 없습니다 (CMake 3.12 이전). 아래 코드는 cmake를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

# CMake 3.12+: OBJECT 라이브러리 링크 가능
add_library(myobj OBJECT common.cpp)
add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE myobj)
# CMake 3.11 이하: $<TARGET_OBJECTS:> 사용
add_executable(myapp main.cpp $<TARGET_OBJECTS:myobj>)

6. 프로덕션 패턴

패턴 1: 인터페이스 라이브러리로 공통 설정

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

# 프로젝트 전역 컴파일 옵션을 인터페이스 라이브러리로
add_library(project_options INTERFACE)
target_compile_features(project_options INTERFACE cxx_std_20)
target_compile_options(project_options INTERFACE
    $<$<CXX_COMPILER_ID:GNU>:-Wall -Wextra -Wpedantic>
    $<$<CXX_COMPILER_ID:MSVC>:/W4>
)
# 모든 타겟에 적용
add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE project_options)
add_library(mylib lib.cpp)
target_link_libraries(mylib PRIVATE project_options)

패턴 2: 별칭 타겟

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

add_library(mylib src/lib.cpp)
add_library(MyProject::mylib ALIAS mylib)
# 다른 곳에서 네임스페이스로 참조
target_link_libraries(myapp PRIVATE MyProject::mylib)

패턴 3: 조건부 타겟

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

option(BUILD_TOOLS "Build command-line tools" ON)
if(BUILD_TOOLS)
    add_executable(tool1 tools/tool1.cpp)
    target_link_libraries(tool1 PRIVATE mylib)
endif()

패턴 4: 타겟 속성 조회

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

# 타겟 속성 가져오기
get_target_property(MYLIB_INCLUDES mylib INCLUDE_DIRECTORIES)
message(STATUS "mylib includes: ${MYLIB_INCLUDES}")
# 타겟 속성 설정
set_target_properties(mylib PROPERTIES
    VERSION 1.0.0
    SOVERSION 1
    OUTPUT_NAME "my_library"
)

7. 완전한 예제: 멀티 라이브러리 프로젝트

프로젝트 구조

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

project/
├── CMakeLists.txt
├── core/
│   ├── CMakeLists.txt
│   ├── core.cpp
│   └── core.h
├── utils/
│   ├── CMakeLists.txt
│   ├── utils.cpp
│   └── utils.h
├── app/
│   ├── CMakeLists.txt
│   └── main.cpp
└── include/
    ├── core/
    │   └── core.h
    └── utils/
        └── utils.h

루트 CMakeLists.txt

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

cmake_minimum_required(VERSION 3.20)
project(MultiLib VERSION 1.0.0 LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
# 공통 설정
add_library(project_options INTERFACE)
target_compile_features(project_options INTERFACE cxx_std_20)
add_subdirectory(core)
add_subdirectory(utils)
add_subdirectory(app)

core/CMakeLists.txt

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

add_library(core STATIC
    core.cpp
    core.h
)
target_include_directories(core
    PUBLIC ${CMAKE_SOURCE_DIR}/include/core
    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}
)
target_link_libraries(core PRIVATE project_options)
add_library(MultiLib::core ALIAS core)

utils/CMakeLists.txt

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

add_library(utils STATIC
    utils.cpp
    utils.h
)
target_include_directories(utils
    PUBLIC ${CMAKE_SOURCE_DIR}/include/utils
)
# utils가 core에 의존
target_link_libraries(utils
    PUBLIC MultiLib::core
    PRIVATE project_options
)
add_library(MultiLib::utils ALIAS utils)

app/CMakeLists.txt

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

add_executable(myapp main.cpp)
# utils를 링크하면 core도 자동으로 링크됨 (PUBLIC 전파)
target_link_libraries(myapp PRIVATE
    MultiLib::utils
    project_options
)

타겟 명령어 요약

명령어설명
add_executable(name sources...)실행 파일 타겟 생성
add_library(name STATIC sources...)정적 라이브러리 생성
add_library(name SHARED sources...)동적 라이브러리 생성
add_library(name INTERFACE)헤더 전용 라이브러리
add_library(name OBJECT sources...)오브젝트 파일만 생성
target_include_directories(target vis dirs...)헤더 경로 추가
target_link_libraries(target vis libs...)라이브러리 링크
target_compile_options(target vis opts...)컴파일 옵션 추가
target_compile_definitions(target vis defs...)전처리 정의 추가
target_compile_features(target vis features...)C++ 기능 요구

정리

개념설명
타겟빌드 대상 (실행 파일, 라이브러리)
target_*타겟별 속성 설정
PUBLIC타겟 + 의존 타겟
PRIVATE타겟만
INTERFACE의존 타겟만 (헤더 전용)
전이적 의존성PUBLIC으로 자동 전파
CMake의 타겟 기반 접근은 의존성을 명확히 하고, 빌드 설정을 타겟별로 격리해 대규모 프로젝트에서도 유지보수가 쉽습니다.

FAQ

Q1: 전역 명령 vs 타겟 명령?

A: 타겟 명령(target_*)을 쓰세요. 전역 명령(include_directories, link_libraries)은 모든 타겟에 영향을 주어 의존성이 꼬입니다.

Q2: PUBLIC vs PRIVATE 언제 쓰나요?

A: 외부에 노출할 헤더는 PUBLIC, 내부 구현 헤더는 PRIVATE입니다. 라이브러리를 만들 때 API 헤더는 PUBLIC, 구현 헤더는 PRIVATE로 두세요.

Q3: INTERFACE는 언제 쓰나요?

A: 헤더 전용 라이브러리에서 사용합니다. 컴파일할 소스가 없고, 헤더만 제공하는 경우 add_library(name INTERFACE)로 만들고, target_include_directories(name INTERFACE ...)로 헤더 경로를 지정합니다.

Q4: OBJECT 라이브러리는 언제 쓰나요?

A: 여러 타겟에서 같은 소스를 재사용할 때 사용합니다. 오브젝트 파일만 생성해 두고, 여러 실행 파일/라이브러리에서 $<TARGET_OBJECTS:myobj>로 포함하면 중복 컴파일을 피할 수 있습니다.

Q5: 별칭 타겟은 왜 쓰나요?

A: add_library(MyProject::mylib ALIAS mylib)로 네임스페이스를 붙이면, 외부 패키지와 내부 타겟을 일관된 방식으로 참조할 수 있습니다. target_link_libraries(myapp PRIVATE MyProject::mylib Boost::filesystem) 처럼 모두 :: 형식으로 통일됩니다.

Q6: CMake Targets 학습 리소스는?

A:

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

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

관련 글

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