Sanitizers · 5/5

Sanitizer를 CMake와 CI에 통합 — Multi-config 빌드 전략

2026년 5월 29일 · Hawk · 6분 읽기

Sanitizer CMake CI GitHub Actions GitLab Debugging

Twitter LinkedIn

#이 장의 목표

Ch 1~Ch 4에서 Sanitizer를 손으로 켜는 방법을 봤습니다. 실무에서는 이걸 프로젝트에 자연스럽게 통합해 PR마다 자동으로 돌게 만들어야 합니다.

이 장은 두 가지 통합 시나리오를 다룹니다.

CMake 프로젝트 — cmake -DENABLE_SANITIZERS=ON으로 한 줄에 켜기.
CI 파이프라인 — GitHub Actions와 GitLab CI에 sanitizer job 추가.

마지막에 예시 템플릿을 한 자리에 모읍니다.

#CMake 통합 — 기본 패턴

가장 단순한 통합부터.

1
option(ENABLE_ASAN "Enable AddressSanitizer + UBSan" OFF)
2
option(ENABLE_TSAN "Enable ThreadSanitizer" OFF)
3

4
if(ENABLE_ASAN AND ENABLE_TSAN)
5
    message(FATAL_ERROR "ASan and TSan cannot be enabled at the same time")
6
endif()
7

8
if(ENABLE_ASAN)
9
    add_compile_options(
10
        -fsanitize=address,undefined
11
        -fno-omit-frame-pointer
12
        -g -O1
13
    )
14
    add_link_options(-fsanitize=address,undefined)
15
endif()
16

17
if(ENABLE_TSAN)
18
    add_compile_options(
19
        -fsanitize=thread
20
        -fno-omit-frame-pointer
21
        -g -O1
22
    )
23
    add_link_options(-fsanitize=thread)
24
endif()

사용:

1
# ASan 빌드
2
cmake -B build-asan -DENABLE_ASAN=ON
3
cmake --build build-asan
4

5
# TSan 빌드 — 별도 디렉터리
6
cmake -B build-tsan -DENABLE_TSAN=ON
7
cmake --build build-tsan

이 패턴이 작은 프로젝트에 충분합니다. ASan/TSan/UBSan을 옵션 한 줄로 켜고 끌 수 있고, 둘 동시 활성화를 방지합니다.

#CMake 통합 — 함수로 추상화

큰 프로젝트에서는 함수로 묶어 재사용합니다. 여러 타겟에 sanitizer 옵션을 일관되게 적용할 때 깔끔합니다.

1
function(enable_sanitizers target)
2
    if(NOT CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
3
        return()
4
    endif()
5

6
    set(sanitizers "")
7

8
    if(ENABLE_ASAN)
9
        list(APPEND sanitizers "address")
10
        list(APPEND sanitizers "undefined")
11
    endif()
12

13
    if(ENABLE_TSAN)
14
        if(sanitizers)
15
            message(FATAL_ERROR "ASan + TSan cannot coexist")
16
        endif()
17
        list(APPEND sanitizers "thread")
18
        list(APPEND sanitizers "undefined")
19
    endif()
20

21
    if(ENABLE_MSAN)
22
        if(sanitizers)
23
            message(FATAL_ERROR "MSan incompatible with other sanitizers")
24
        endif()
25
        if(NOT CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
26
            message(WARNING "MSan requires Clang — disabling")
27
            return()
28
        endif()
29
        list(APPEND sanitizers "memory")
30
    endif()
31

32
    if(sanitizers)
33
        list(JOIN sanitizers "," sanitizers_str)
34
        target_compile_options(${target} PRIVATE
35
            -fsanitize=${sanitizers_str}
36
            -fno-omit-frame-pointer
37
            -g -O1
38
        )
39
        target_link_options(${target} PRIVATE
40
            -fsanitize=${sanitizers_str}
41
        )
42
    endif()
43
endfunction()

1
# 메인 CMakeLists.txt
2
include(cmake/Sanitizers.cmake)
3

4
option(ENABLE_ASAN "Enable ASan + UBSan" OFF)
5
option(ENABLE_TSAN "Enable ThreadSanitizer" OFF)
6
option(ENABLE_MSAN "Enable MemorySanitizer (Clang)" OFF)
7

8
add_executable(myapp ${SRCS})
9
enable_sanitizers(myapp)
10

11
add_executable(test_runner ${TEST_SRCS})
12
enable_sanitizers(test_runner)

이 함수의 좋은 점:

컴파일러 검사 — MSVC에서는 자동 skip.
MSan은 Clang 전용 자동 검사.
모순된 조합 사전 차단.
타겟 단위 적용 — 어떤 타겟에 sanitizer를 적용할지 명시적.

#CMakePresets로 더 깔끔하게

CMake 3.19+에서는 프리셋으로 빌드 모드를 묶을 수 있습니다(Ch 9).

1
{
2
  "version": 6,
3
  "configurePresets": [
4
    {
5
      "name": "asan",
6
      "displayName": "ASan + UBSan Build",
7
      "binaryDir": "${sourceDir}/build/${presetName}",
8
      "generator": "Ninja",
9
      "cacheVariables": {
10
        "CMAKE_BUILD_TYPE": "Debug",
11
        "ENABLE_ASAN": "ON"
12
      },
13
      "environment": {
14
        "ASAN_OPTIONS": "halt_on_error=1:abort_on_error=1:detect_leaks=1:symbolize=1",
15
        "UBSAN_OPTIONS": "halt_on_error=1:print_stacktrace=1:symbolize=1"
16
      }
17
    },
18
    {
19
      "name": "tsan",
20
      "displayName": "TSan Build",
21
      "binaryDir": "${sourceDir}/build/${presetName}",
22
      "generator": "Ninja",
23
      "cacheVariables": {
24
        "CMAKE_BUILD_TYPE": "Debug",
25
        "ENABLE_TSAN": "ON"
26
      },
27
      "environment": {
28
        "TSAN_OPTIONS": "halt_on_error=1:second_deadlock_stack=1"
29
      }
30
    },
31
    {
32
      "name": "release",
33
      "binaryDir": "${sourceDir}/build/${presetName}",
34
      "generator": "Ninja",
35
      "cacheVariables": {
36
        "CMAKE_BUILD_TYPE": "Release"
37
      }
38
    }
39
  ],
40
  "buildPresets": [
41
    { "name": "asan", "configurePreset": "asan" },
42
    { "name": "tsan", "configurePreset": "tsan" },
43
    { "name": "release", "configurePreset": "release" }
44
  ],
45
  "testPresets": [
46
    {
47
      "name": "asan",
48
      "configurePreset": "asan",
49
      "output": { "outputOnFailure": true }
50
    },
51
    {
52
      "name": "tsan",
53
      "configurePreset": "tsan",
54
      "output": { "outputOnFailure": true }
55
    }
56
  ]
57
}

1
# 한 명령에 한 빌드
2
cmake --preset asan
3
cmake --build --preset asan
4
ctest --preset asan

environment 섹션에 sanitizer 환경 변수까지 박아 두기 때문에, 매번 export할 필요가 없습니다. 팀이 같은 설정으로 작업하는 것이 자동 보장됩니다.

#GitHub Actions — 실전 워크플로

가장 기본적인 패턴부터 보겠습니다.

1
name: Sanitizers
2

3
on:
4
  pull_request:
5
  push:
6
    branches: [main]
7

8
jobs:
9
  asan-ubsan:
10
    name: ASan + UBSan
11
    runs-on: ubuntu-22.04
12
    steps:
13
      - uses: actions/checkout@v4
14

15
      - name: Install dependencies
16
        run: |
17
          sudo apt-get update
18
          sudo apt-get install -y cmake ninja-build llvm
19

20
      - name: Configure
21
        run: cmake --preset asan
22

23
      - name: Build
24
        run: cmake --build --preset asan
25

26
      - name: Test
27
        env:
28
          ASAN_OPTIONS: halt_on_error=1:abort_on_error=1:detect_leaks=1
29
          UBSAN_OPTIONS: halt_on_error=1:print_stacktrace=1
30
          ASAN_SYMBOLIZER_PATH: /usr/bin/llvm-symbolizer
31
        run: ctest --preset asan
32

33
  tsan:
34
    name: ThreadSanitizer
35
    runs-on: ubuntu-22.04
36
    steps:
37
      - uses: actions/checkout@v4
38

39
      - name: Install dependencies
40
        run: |
41
          sudo apt-get update
42
          sudo apt-get install -y cmake ninja-build llvm
43

44
      - name: Configure
45
        run: cmake --preset tsan
46

47
      - name: Build
48
        run: cmake --build --preset tsan
49

50
      - name: Test
51
        env:
52
          TSAN_OPTIONS: halt_on_error=1:second_deadlock_stack=1
53
          TSAN_SYMBOLIZER_PATH: /usr/bin/llvm-symbolizer
54
        run: ctest --preset tsan

핵심 포인트:

두 job 병렬 실행 — ASan과 TSan은 별도 워크플로 job. 호환되지 않아 한 빌드에 못 합침.
환경 변수 명시 — halt_on_error=1로 첫 에러에서 종료, 반드시 비-0 종료 코드로 CI 실패 트리거.
심볼라이저 경로 — Ubuntu의 /usr/bin/llvm-symbolizer. 없으면 주소만 보임.
llvm 패키지 설치 — llvm-symbolizer가 여기 들어 있음.

#추가 최적화 — 캐시

1
- name: Cache CMake build
2
  uses: actions/cache@v4
3
  with:
4
    path: build/asan
5
    key: ${{ runner.os }}-asan-${{ hashFiles('**/CMakeLists.txt') }}
6
    restore-keys: |
7
      ${{ runner.os }}-asan-

Sanitizer 빌드는 컴파일이 1.5배 정도 느려서 캐시 효과가 큽니다. CMakeLists.txt 변경 없는 PR은 캐시를 그대로 재사용해 빌드 시간을 절약.

#TSan 반복 실행

Ch 4에서 본 반복 실행으로 커버리지 확보 패턴.

1
- name: TSan stress (10x)
2
  env:
3
    TSAN_OPTIONS: halt_on_error=1
4
  run: |
5
    for i in {1..10}; do
6
      echo "===== Iteration $i ====="
7
      ctest --preset tsan || exit 1
8
    done

10번 중 한 번이라도 실패하면 CI 전체가 실패. 데이터 레이스의 비결정적 본성을 극복합니다.

#GitLab CI — 동일 패턴

GitLab은 YAML 구조가 GitHub Actions와 약간 다릅니다.

1
stages:
2
  - test
3

4
.sanitizer_template: &sanitizer_template
5
  stage: test
6
  image: ubuntu:22.04
7
  before_script:
8
    - apt-get update
9
    - apt-get install -y cmake ninja-build llvm
10
  cache:
11
    key: "$CI_JOB_NAME"
12
    paths:
13
      - build/
14

15
asan-ubsan:
16
  <<: *sanitizer_template
17
  variables:
18
    ASAN_OPTIONS: "halt_on_error=1:abort_on_error=1:detect_leaks=1"
19
    UBSAN_OPTIONS: "halt_on_error=1:print_stacktrace=1"
20
    ASAN_SYMBOLIZER_PATH: "/usr/bin/llvm-symbolizer"
21
  script:
22
    - cmake --preset asan
23
    - cmake --build --preset asan
24
    - ctest --preset asan
25

26
tsan:
27
  <<: *sanitizer_template
28
  variables:
29
    TSAN_OPTIONS: "halt_on_error=1:second_deadlock_stack=1"
30
    TSAN_SYMBOLIZER_PATH: "/usr/bin/llvm-symbolizer"
31
  script:
32
    - cmake --preset tsan
33
    - cmake --build --preset tsan
34
    - ctest --preset tsan

YAML 앵커(&template, <<: *template)로 공통 설정을 한 자리에 둡니다.

#Compiler / OS 매트릭스

여러 컴파일러와 OS에서 모두 sanitizer가 통과해야 안전합니다. GitHub Actions에서는 매트릭스로 한 줄.

1
asan-ubsan:
2
  strategy:
3
    fail-fast: false
4
    matrix:
5
      os: [ubuntu-22.04, macos-14]
6
      compiler: [gcc, clang]
7
  runs-on: ${{ matrix.os }}
8
  steps:
9
    - uses: actions/checkout@v4
10
    - name: Set up compiler
11
      run: |
12
        if [ "${{ matrix.compiler }}" = "gcc" ]; then
13
          echo "CC=gcc" >> $GITHUB_ENV
14
          echo "CXX=g++" >> $GITHUB_ENV
15
        else
16
          echo "CC=clang" >> $GITHUB_ENV
17
          echo "CXX=clang++" >> $GITHUB_ENV
18
        fi
19
    - name: Configure
20
      run: cmake --preset asan
21
    - name: Build
22
      run: cmake --build --preset asan
23
    - name: Test
24
      env:
25
        ASAN_OPTIONS: halt_on_error=1:abort_on_error=1
26
      run: ctest --preset asan

fail-fast: false로 한 조합이 실패해도 나머지가 끝까지 돌아 어디서 깨지는지 한눈에 봅니다.

#실패 진단 — Sanitizer가 깼을 때

CI에서 sanitizer가 깨지면 보통 다음 단계로 진단합니다.

출력 확인 — CI 로그의 sanitizer 보고서. SUMMARY: 줄과 스택 트레이스.

로컬 재현 — 같은 프리셋으로 로컬에서 동일 빌드.

1
cmake --preset asan && cmake --build --preset asan && ctest --preset asan

단일 테스트 격리 — 실패한 테스트만 따로.
Terminal window
```
1
ctest --preset asan -R FailingTestName -V
```

gdb/lldb로 디버깅 — Sanitizer 빌드는 -g가 켜져 있어 디버거 사용 가능.

1
ASAN_OPTIONS=abort_on_error=1 gdb ./build/asan/test
2
(gdb) run
3
# 에러 발생 시 abort → 스택 검사
4
(gdb) bt

abort_on_error=1이 디버거에서 잡기 핵심입니다. exit()는 디버거가 못 잡고, abort()는 잡습니다.

#자주 만나는 CI 문제들

#”Sanitizer가 동작하는데 줄 번호가 안 나옴”

1
#0 0x4012a3 in main
2
#1 0x401aef in __libc_start_main

원인: llvm-symbolizer 또는 addr2line이 PATH에 없음.

해결: 패키지 설치 + 환경 변수.

1
- name: Install symbolizer
2
  run: sudo apt-get install -y llvm
3

4
env:
5
  ASAN_SYMBOLIZER_PATH: /usr/bin/llvm-symbolizer

#”ASan + UBSan 빌드가 너무 느려”

원인: 큰 코드베이스에서 sanitizer 빌드는 1.5~2배 컴파일 시간이 걸립니다.

해결:

Ninja 사용 — Make보다 빠른 빌드.
빌드 캐시 — actions/cache로 incremental.
테스트 범위 축소 — ctest -L unit으로 단위 테스트만 빠르게.

#”TSan이 false positive 너무 많아”

원인: 외부 라이브러리 / 사용자 모드 동기화 / lock-free 알고리즘.

해결:

Suppression 파일 작성 — 외부 라이브러리 무시.
TSan annotation — __tsan_acquire(), __tsan_release()로 직접 happens-before 알려 주기.
PR 빌드 제외 — TSan은 야간 빌드로 이동.

#”macOS에서 detect_leaks가 안 됨”

원인: macOS는 LSan 기본 OFF.

해결: 환경 변수 명시.

1
env:
2
  ASAN_OPTIONS: detect_leaks=1:halt_on_error=1

#권장 운영 모델

규모별 권장 설정.

#소규모 프로젝트 (소스 < 50KLoC)

PR 빌드: ASan + UBSan 한 작업.
메인 브랜치: TSan 한 번 더 (멀티스레드면).
매트릭스: GCC + Clang × Ubuntu 한 OS.
전체 CI 시간: 510분.

#중규모 (50~500KLoC)

PR 빌드: ASan + UBSan + 빠른 단위 테스트만.
메인 브랜치: ASan + UBSan 전체 + TSan 작은 시나리오.
야간: TSan 전체 + MSan (Clang 가능 시).
매트릭스: GCC + Clang × Ubuntu + macOS.
전체 CI 시간: PR ~15분, 야간 ~1시간.

#대규모 (500KLoC+)

PR 빌드: ASan + UBSan 작은 변경분 영향 테스트만.
메인 브랜치: 일부 추출된 대표 테스트.
야간: 전체 매트릭스 (ASan / TSan / MSan / 다양한 컴파일러).
별도 fuzzer + sanitizer 워크플로 — OSS-Fuzz 같은 외부 서비스.

큰 프로젝트일수록 sanitizer를 빌드 인프라의 일부로 다루게 됩니다. 단순한 옵션이 아니라 별도 빌드 파이프라인.

#정리

CMake 통합: option()으로 sanitizer 빌드 모드, 함수로 추상화.
CMakePresets.json으로 설정·환경 변수까지 외부화.
GitHub Actions / GitLab CI 모두 별도 job으로 ASan과 TSan 분리.
환경 변수: halt_on_error=1, abort_on_error=1, SYMBOLIZER_PATH 명시.
매트릭스 (OS × 컴파일러) + fail-fast: false로 어디서 깨지는지 한눈에.
진단 — CI 출력 → 로컬 재현 → 단일 테스트 → 디버거.
운영 모델은 프로젝트 규모에 맞춰 단순 → 복잡으로 진화.

#시리즈 마무리

Sanitizer 시리즈 다섯 챕터를 마칩니다.

장	주제
Ch 1	개요 — ASan / UBSan / LSan / TSan / MSan
Ch 2	ASan + UBSan 실전 설정
Ch 3	LSan과 누수 분석
Ch 4	TSan과 데이터 레이스
Ch 5	CMake / CI 통합

Sanitizer는 컴파일러 한 옵션으로 수많은 런타임 버그를 잡는 강력한 도구입니다. 도입 비용은 거의 0(-fsanitize=address,undefined 한 줄), 효과는 수년 동안 잠재된 버그를 즉시 드러내는 수준.

도입 순서:

로컬 개발 빌드에 ASan + UBSan — 오늘 추가.
단위 테스트에 ASan — 이번 주 안에.
PR CI에 ASan + UBSan — 다음 PR 사이클부터.
멀티스레드면 TSan — 동시성 코드 추가 시.

Valgrind 시리즈는 sanitizer가 닿지 못하는 자리 — 재컴파일 불가 바이너리, 시스템 호출 추적 — 를 보완합니다.

#참고 자료

Google Sanitizers Wiki
Clang Sanitizer Manuals — 각 sanitizer 공식 문서
GitHub Actions: actions/checkout, actions/cache
GitLab CI/CD Reference
CMakePresets v6 Spec

#관련 시리즈

Valgrind — sanitizer 보완
CMake — 빌드 통합 기초
GNU Make — 더 단순한 빌드

Sanitizers · 5 of 5

LSan 누수 분석 — Stop-the-world Leak Detection 메커니즘

LeakSanitizer로 메모리 누수 추적 — 보고서 해석, suppression, 일회성·반복 분석 패턴.

2026년 5월 29일·Sanitizer

ASan과 UBSan 실전 설정 — 컴파일 옵션과 런타임 동작

황금 조합 -fsanitize=address,undefined를 실제로 켜고 운영하는 자세한 방법 — 옵션, 환경 변수, suppression, 흔한 오탐.

2026년 5월 29일·Sanitizer

Sanitizer 종류 비교 — ASan·UBSan·LSan·TSan·MSan

C/C++ 런타임 검사 도구 Sanitizer 계열의 역할, 종류별 선택, 실무 도입 순서.

2026년 5월 29일·Sanitizer

Sanitizer를 CMake와 CI에 통합 — Multi-config 빌드 전략

#이 장의 목표

#CMake 통합 — 기본 패턴

#CMake 통합 — 함수로 추상화

#CMakePresets로 더 깔끔하게

#GitHub Actions — 실전 워크플로

#추가 최적화 — 캐시

#TSan 반복 실행

#GitLab CI — 동일 패턴

#Compiler / OS 매트릭스

#실패 진단 — Sanitizer가 깼을 때

#자주 만나는 CI 문제들

#”Sanitizer가 동작하는데 줄 번호가 안 나옴”

#”ASan + UBSan 빌드가 너무 느려”

#”TSan이 false positive 너무 많아”

#”macOS에서 detect_leaks가 안 됨”

#권장 운영 모델

#소규모 프로젝트 (소스 < 50KLoC)

#중규모 (50~500KLoC)

#대규모 (500KLoC+)

#정리

#시리즈 마무리

#참고 자료

#관련 시리즈

Sanitizers · 5 of 5

관련 글

LSan 누수 분석 — Stop-the-world Leak Detection 메커니즘

ASan과 UBSan 실전 설정 — 컴파일 옵션과 런타임 동작

Sanitizer 종류 비교 — ASan·UBSan·LSan·TSan·MSan

이 글을 참조하는 글 (3)