C++ CMake Targets 완벽 가이드 | 타겟 기반 빌드 시스템
이 글의 핵심
C++ CMake Targets : 타겟 기반 빌드 시스템. CMake Targets란?. 왜 타겟 기반인가·타겟 생성.
다른 빌드 모델과 비교
CMake 타겟은 의존성 그래프의 노드에 가깝습니다. Rust Cargo의 크레이트·타겟이나 npm 패키지 트리와 완전히 같지는 않지만, “무엇이 무엇에 링크되는가”를 명시한다는 점에서 비교하면 팀 온보딩에 도움이 됩니다. Make 기반은 C++ Makefile·빌드 시스템 비교와 연결해 보세요.
CMake Targets란? 왜 타겟 기반인가
문제 시나리오: 전역 설정의 혼란
문제: 예전 CMake 스타일에서는 include_directories(), link_libraries() 같은 전역 명령을 썼습니다. 프로젝트가 커지면 어떤 타겟이 어떤 헤더를 쓰는지 추적하기 어렵고, 의존성이 꼬입니다.
# ❌ 구식: 전역 설정
include_directories(/usr/local/include)
link_libraries(boost_system)
add_executable(app1 main1.cpp)
add_executable(app2 main2.cpp)
# app1, app2 모두 boost_system에 링크됨 (의도하지 않았을 수도)해결: 타겟 기반 명령(target_*)을 쓰면 각 타겟의 의존성이 명확해지고, 불필요한 링크가 없어집니다.
# ✅ 모던: 타겟별 설정
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_* 명령으로 각 타겟의 속성(헤더 경로, 링크 라이브러리, 컴파일 옵션)을 설정합니다.
// 실행 예제
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(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})정적 라이브러리
add_library(mylib STATIC
src/lib.cpp
src/helper.cpp
)동적 라이브러리
add_library(mylib SHARED
src/lib.cpp
src/helper.cpp
)헤더 전용 라이브러리
add_library(mylib INTERFACE)
target_include_directories(mylib INTERFACE include)OBJECT 라이브러리
# 오브젝트 파일만 생성 (링크 안 함)
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
add_library(mylib src/lib.cpp)
target_include_directories(mylib
PUBLIC include # 외부에 노출
PRIVATE src/internal # 내부 전용
)target_link_libraries
add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE
mylib
Boost::filesystem
pthread
)target_compile_options
target_compile_options(myapp PRIVATE
-Wall
-Wextra
-Werror
$<$<CONFIG:Debug>:-O0 -g>
$<$<CONFIG:Release>:-O3>
)target_compile_definitions
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
개념
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 | 사용 안 함 | 사용 |
실전 예시
# 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 사용 사례
헤더 전용 라이브러리에서 사용합니다.
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. 의존성 전파
전이적 의존성
# 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 전파)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로 전파 차단
# 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() 같은 전역 명령은 이후 모든 타겟에 영향을 줍니다.
# ❌ 잘못된 사용
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 혼동
증상: 헤더를 찾지 못하거나, 불필요한 헤더가 노출됨.
# ❌ 잘못된 사용: 내부 헤더를 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를 링크함.
# ❌ 잘못된 사용
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 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: 인터페이스 라이브러리로 공통 설정
# 프로젝트 전역 컴파일 옵션을 인터페이스 라이브러리로
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: 별칭 타겟
add_library(mylib src/lib.cpp)
add_library(MyProject::mylib ALIAS mylib)
# 다른 곳에서 네임스페이스로 참조
target_link_libraries(myapp PRIVATE MyProject::mylib)패턴 3: 조건부 타겟
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: 타겟 속성 조회
# 타겟 속성 가져오기
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. 완전한 예제: 멀티 라이브러리 프로젝트
프로젝트 구조
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_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
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
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
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:
- CMake 공식 문서 - cmake-buildsystem
- “Professional CMake: A Practical Guide”
- Effective Modern CMake 한 줄 요약: CMake 타겟 기반 접근으로 의존성을 명확히 관리할 수 있습니다. 다음으로 CMake find_package를 읽어보면 좋습니다.
같이 보면 좋은 글 (내부 링크)
이 주제와 연결되는 다른 글입니다.
- C++ CMake 완벽 가이드 | 크로스 플랫폼 빌드·최신 CMake 3.28+ 기능·프리셋·모듈
- C++ CMake find_package 완벽 가이드 | 외부 라이브러리 통합
- C++ Conan 완벽 가이드 | 현대적인 C++ 패키지 관리
관련 글
- C++ CMake find_package 완벽 가이드 | 외부 라이브러리 통합
- C++ CMake |
- C++ CMake 완벽 가이드 | 크로스 플랫폼 빌드·최신 CMake 3.28+ 기능·프리셋·모듈
- C++ Conan 완벽 가이드 | 현대적인 C++ 패키지 관리
- CMake 에러 |
심화 부록: 구현·운영 관점
이 부록은 앞선 본문에서 다룬 주제(「C++ CMake Targets 완벽 가이드 | 타겟 기반 빌드 시스템」)를 구현·런타임·운영 관점에서 다시 압축합니다. 도메인별 세부 구현은 글마다 다르지만, 입력 검증 → 핵심 연산 → 부작용(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·동시성을 프로덕션에 가깝게 맞출수록 재현율이 올라갑니다.
확장 예시: 엔드투엔드 미니 시나리오
앞선 본문 주제(「C++ CMake Targets 완벽 가이드 | 타겟 기반 빌드 시스템」)를 배포·운영 흐름에 맞춰 옮긴 체크리스트입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.
- 입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드를 경계에 둔다.
- 핵심 경로 계측: 요청 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 순서를 권장합니다.
이 글에서 다루는 키워드 (관련 검색어)
C++, cmake, targets, library, build, dependency 등으로 검색하시면 이 글이 도움이 됩니다.