CMake 'Could NOT find' 에러

Q: find_package가 성공했는데 링크 에러가 나요.

: find_package는 성공했지만, target_link_libraries를 안 했거나, 컴포넌트를 잘못 지정했을 수 있습니다. Boost::system 대신 Boost::boost만 링크하면 헤더는 보이지만 라이브러리는 링크 안 됩니다.

Q: vcpkg로 설치했는데 find_package가 실패합니다.

: toolchain 파일을 지정하지 않았을 가능성이 큽니다. 반드시 -DCMAKE_TOOLCHAIN_FILE=.../vcpkg.cmake를 써야 합니다.

Q: Config 파일 경로를 어떻게 찾나요?

: bash # Linux/macOS find /usr -name "*Config.cmake" 2>/dev/null | grep -i boost # Windows (PowerShell) Get-ChildItem -Recurse -Filter "*Config.cmake" C:\

Q: FetchContent vs find_package, 언제 뭘 쓰나요?

: - find_package: 시스템에 이미 설치된 라이브러리 사용 (빠름) - FetchContent: 소스에서 자동 다운로드·빌드 (재현성 좋음, 느림) CI/CD 환경에서는 FetchContent가 유리하고, 로컬 개발에서는 find_package + vcpkg가 빠릅니다. ---

2026년 3월 12일 · 17분 읽기 · 수정 2026년 3월 12일

이 글의 핵심

C++ Could NOT find (missing:...) 에러 해결. find_package 실패 원인(경로, 버전, Config vs Module), CMAKE_PREFIX_PATH 설정, vcpkg·Conan 활용법.

들어가며: “Could NOT find Boost (missing: …)”

CMake로 외부 라이브러리를 쓰려고 find_package(Boost REQUIRED)를 호출했는데, Could NOT find Boost (missing: Boost_INCLUDE_DIR Boost_LIBRARY_DIRS) 같은 에러가 나는 경우가 많습니다. “find_package 실패”, “Could NOT find”, “CMAKE_PREFIX_PATH”로 검색해 오셨다면 이 글이 도움이 됩니다. 라이브러리는 분명 설치했는데 CMake가 찾지 못하는 상황입니다. 이 글은 find_package 실패의 주요 원인 5가지와 환경별 해결법을 정리합니다.

이 글에서 다루는 것:

find_package가 어떻게 라이브러리를 찾는지 (Config vs Module 모드)
5가지 주요 원인: 경로 문제, 버전 불일치, Config 파일 없음, 대소문자, 컴포넌트 누락
CMAKE_PREFIX_PATH 설정으로 경로 지정하기
패키지 매니저(vcpkg, Conan) 활용법

find_package 실패 시 점검 순서를 요약하면 아래와 같습니다.

flowchart TD
  A[find_package 실패] --> B[라이브러리 설치 여부]
  B --> C[Config/Module 경로]
  C --> D[CMAKE_PREFIX_PATH]
  D --> E[버전·컴포넌트]
  E --> F[vcpkg/Conan 사용]

실전 경험에서 배운 교훈

이 기술을 실무 프로젝트에 처음 도입했을 때, 공식 문서만으로는 알 수 없었던 많은 함정들이 있었습니다. 특히 프로덕션 환경에서 발생하는 엣지 케이스들은 로컬 개발 환경에서는 재현조차 되지 않았죠.

가장 어려웠던 점은 성능 최적화였습니다. 처음엔 “동작만 하면 되겠지”라고 생각했지만, 실제 사용자 트래픽이 몰리면서 병목 지점들이 하나씩 드러났습니다. 특히 데이터베이스 쿼리 최적화, 캐싱 전략, 에러 핸들링 구조 등은 여러 번의 장애를 겪으면서 개선해 나갔습니다.

이 글에서는 그런 시행착오를 통해 얻은 실전 노하우와, “이렇게 하면 안 된다”는 교훈들을 함께 정리했습니다. 특히 트러블슈팅 섹션은 실제 장애 대응 경험을 바탕으로 작성했으니, 비슷한 문제를 마주했을 때 참고하시면 도움이 될 것입니다.

1. find_package는 어떻게 찾나요?

Config 모드 vs Module 모드

find_package(PackageName)는 두 가지 모드로 작동합니다.

Config 모드 (우선):

라이브러리가 제공하는 PackageNameConfig.cmake 또는 packagename-config.cmake 파일을 찾습니다.
이 파일은 보통 라이브러리 설치 시 /usr/local/lib/cmake/PackageName/ 같은 곳에 생성됩니다.
최신 라이브러리는 대부분 Config 파일을 제공합니다.

Config 파일의 역할:
Config 파일은 라이브러리가 직접 제공하는 “사용 설명서”입니다. 헤더 경로, 라이브러리 파일 경로, 컴파일 옵션 등을 정의합니다. CMake는 이 파일을 읽어서 자동으로 Boost::system 같은 타겟(Target)을 생성하고, target_link_libraries만 하면 모든 설정이 자동으로 적용됩니다.

Module 모드 (Config 실패 시):

CMake가 제공하는 FindPackageName.cmake 모듈을 찾습니다.
CMake 설치 경로의 Modules/ 디렉터리에 있습니다 (예: FindBoost.cmake).
오래된 라이브러리나 CMake가 직접 지원하는 패키지만 해당됩니다.

Module 모드의 한계:
Module 파일은 CMake 개발자가 작성한 것이므로, 라이브러리 버전이 바뀌면 업데이트가 늦을 수 있습니다. 또한 라이브러리 설치 경로를 추측해서 찾으므로, 비표준 경로에 설치하면 실패할 가능성이 높습니다. 최신 라이브러리는 대부분 Config 모드를 권장합니다.

검색 경로

CMake는 다음 경로에서 Config/Module 파일을 찾습니다.

CMAKE_PREFIX_PATH 환경 변수 또는 CMake 변수
시스템 기본 경로: /usr/local/, /usr/, C:/Program Files/ 등
PackageName_DIR 변수 (직접 지정 가능)

2. 원인 1: 라이브러리가 설치 안 됨 또는 경로 문제

문제 상황

find_package(Boost REQUIRED)

에러:

CMake Error at CMakeLists.txt:5 (find_package):
  Could NOT find Boost (missing: Boost_INCLUDE_DIR Boost_LIBRARY_DIRS)

원인: Boost가 설치되지 않았거나, CMake가 찾는 경로에 없습니다.

가장 흔한 케이스:
라이브러리를 설치했다고 생각했는데, 실제로는 헤더만 설치되고 라이브러리 파일(.so, .lib)은 없는 경우입니다. 또는 개발 패키지(dev package)를 설치하지 않은 경우입니다.

Linux 예시:

sudo apt install boost → ❌ 런타임 라이브러리만 설치
sudo apt install libboost-all-dev → ✅ 헤더 + 라이브러리 + Config 파일

확인 방법:

# 헤더 파일 확인
ls /usr/include/boost/

# 라이브러리 파일 확인
ls /usr/lib/x86_64-linux-gnu/libboost_system*

헤더는 있는데 라이브러리가 없으면, dev 패키지를 설치해야 합니다.

해결법 1: 라이브러리 설치

Ubuntu/Debian:

sudo apt install libboost-all-dev

macOS (Homebrew):

brew install boost

Windows: Boost 공식 사이트에서 다운로드하거나, vcpkg 사용 (아래 섹션 참고).

해결법 2: CMAKE_PREFIX_PATH 설정

라이브러리를 비표준 경로에 설치했다면, CMake에 경로를 알려 줘야 합니다.

CMakeLists.txt:

set(CMAKE_PREFIX_PATH "/opt/mylibs;${CMAKE_PREFIX_PATH}")
find_package(Boost REQUIRED)

명령줄:

cmake -DCMAKE_PREFIX_PATH=/opt/mylibs ..

환경 변수:

export CMAKE_PREFIX_PATH=/opt/mylibs:$CMAKE_PREFIX_PATH
cmake ..

3. 원인 2: 버전 불일치

문제 상황

find_package(Boost 1.75 REQUIRED)

에러:

Could NOT find Boost (missing: Boost_INCLUDE_DIR) (found suitable version "1.71.0", minimum required is "1.75")

원인: 설치된 Boost 버전(1.71)이 요구 버전(1.75)보다 낮습니다.

해결법

1. 버전 요구사항 낮추기:

find_package(Boost 1.71 REQUIRED)  # ✅ 설치된 버전에 맞춤

2. 최신 버전 설치:

# Ubuntu
sudo apt install libboost-all-dev

# macOS
brew upgrade boost

3. 버전 지정 제거 (최소 버전만 요구):

find_package(Boost REQUIRED)  # 버전 제약 없음

4. 원인 3: Config 파일이 없음 (Module 모드 실패)

문제 상황

최신 라이브러리인데 CMake가 FindXXX.cmake 모듈을 제공하지 않고, 라이브러리도 Config 파일을 생성하지 않은 경우입니다.

find_package(MyLib REQUIRED)

에러:

Could NOT find MyLib (missing: MyLib_DIR)

해결법 1: Config 파일 경로 직접 지정

라이브러리를 빌드·설치할 때 MyLibConfig.cmake가 생성되었다면, 그 경로를 지정합니다.

set(MyLib_DIR "/path/to/mylib/lib/cmake/MyLib")
find_package(MyLib REQUIRED)

또는 명령줄:

cmake -DMyLib_DIR=/path/to/mylib/lib/cmake/MyLib ..

해결법 2: find_library로 직접 찾기

find_package를 포기하고, find_library로 .a/.so/.lib 파일을 직접 찾습니다.

find_library(MYLIB_LIBRARY NAMES mylib PATHS /usr/local/lib)
find_path(MYLIB_INCLUDE_DIR NAMES mylib/api.h PATHS /usr/local/include)

if(NOT MYLIB_LIBRARY OR NOT MYLIB_INCLUDE_DIR)
    message(FATAL_ERROR "MyLib not found")
endif()

add_executable(myapp main.cpp)
target_include_directories(myapp PRIVATE ${MYLIB_INCLUDE_DIR})
target_link_libraries(myapp PRIVATE ${MYLIB_LIBRARY})

5. 원인 4: 패키지 이름 대소문자 불일치

문제 상황

find_package(boost REQUIRED)  # ❌ 소문자

에러:

Could NOT find boost

원인: Config 파일 이름이 BoostConfig.cmake인데, find_package(boost)로 소문자로 찾으면 실패할 수 있습니다. Linux/macOS는 대소문자를 구분합니다.

해결법

정확한 대소문자 사용:

find_package(Boost REQUIRED)  # ✅ 대문자 B

라이브러리 문서에서 정확한 패키지 이름을 확인하세요.

6. 원인 5: 필요한 컴포넌트 누락

문제 상황

find_package(Boost REQUIRED)

에러:

Could NOT find Boost (missing: system filesystem)

원인: Boost는 여러 컴포넌트로 나뉘어 있습니다. COMPONENTS를 지정하지 않으면 헤더만 찾고, 필요한 라이브러리(.so/.lib)를 찾지 못합니다.

Boost의 구조:
Boost는 100개 이상의 라이브러리로 구성되어 있습니다. 일부는 헤더 온리(Header-only)라서 링크가 필요 없지만(예: Boost.Algorithm), 일부는 컴파일된 라이브러리가 필요합니다(예: Boost.System, Boost.Filesystem).

헤더 온리 vs 컴파일 필요:

헤더 온리: #include만 하면 됨 (예: <boost/algorithm/string.hpp>)
컴파일 필요: 별도 .lib/.so 파일 링크 필요 (예: boost_system.lib)

COMPONENTS를 지정하지 않으면, CMake는 헤더만 찾고 끝입니다. 컴파일된 라이브러리가 필요한 함수를 쓰면 LNK2019 에러가 발생합니다.

해결법

필요한 컴포넌트 명시:

find_package(Boost REQUIRED COMPONENTS system filesystem)
target_link_libraries(myapp PRIVATE Boost::system Boost::filesystem)

주의: 컴포넌트 이름은 라이브러리마다 다릅니다. 문서를 확인하세요.

7. CMAKE_PREFIX_PATH로 경로 지정

여러 경로 추가

list(APPEND CMAKE_PREFIX_PATH 
    "/opt/mylibs"
    "/usr/local/custom"
)
find_package(MyLib REQUIRED)

환경 변수로 설정

export CMAKE_PREFIX_PATH=/opt/mylibs:/usr/local/custom
cmake ..

Windows에서

set CMAKE_PREFIX_PATH=C:\libs;C:\custom
cmake ..

또는 CMake GUI에서 CMAKE_PREFIX_PATH 변수를 추가합니다.

8. 패키지 매니저 활용 (vcpkg, Conan)

vcpkg (Microsoft)

vcpkg는 C++ 라이브러리를 자동으로 다운로드·빌드·설치하고, CMake에서 바로 쓸 수 있게 해 줍니다.

vcpkg의 장점:

크로스 플랫폼: Windows, Linux, macOS 모두 지원
자동 빌드: 소스에서 자동으로 빌드해서 설치
CMake 통합: toolchain 파일 하나로 모든 라이브러리 자동 인식
버전 관리: vcpkg.json으로 프로젝트별 의존성 관리

언제 쓰나요?
특히 Windows 환경에서 C++ 라이브러리 관리가 어려운데, vcpkg는 이를 npm/pip처럼 쉽게 만들어 줍니다. Linux/macOS는 시스템 패키지 매니저(apt, brew)가 있지만, Windows는 vcpkg가 사실상 표준입니다.

설치:

# 실행 예제
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh  # Linux/macOS
# 또는 bootstrap-vcpkg.bat (Windows)

라이브러리 설치:

./vcpkg install boost
./vcpkg install fmt
./vcpkg install nlohmann-json

CMake에서 사용:

cmake -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake ..

이후 find_package(Boost REQUIRED)가 자동으로 작동합니다.

CMakeLists.txt:

// 실행 예제
find_package(Boost REQUIRED COMPONENTS system)
find_package(fmt REQUIRED)
find_package(nlohmann_json REQUIRED)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE 
    Boost::system 
    fmt::fmt 
    nlohmann_json::nlohmann_json
)

Conan

Conan도 비슷하게 작동합니다.

conanfile.txt:

// 실행 예제
[requires]
boost/1.80.0
fmt/9.1.0

[generators]
CMakeDeps
CMakeToolchain

빌드:

conan install . --build=missing
cmake --preset conan-default
cmake --build --preset conan-release

해결 체크리스트

원인	확인 사항	해결법
라이브러리 미설치	`apt search`, `brew search`	패키지 매니저로 설치
경로 문제	Config 파일 위치 확인	`CMAKE_PREFIX_PATH` 설정
버전 불일치	설치된 버전 vs 요구 버전	버전 낮추거나 업그레이드
Config 파일 없음	`XXXConfig.cmake` 존재 여부	`find_library`로 직접 찾기
대소문자 오류	패키지 이름 확인	정확한 이름 사용
컴포넌트 누락	`COMPONENTS` 지정	필요한 컴포넌트 명시

실전 디버깅 프로세스

1단계: 에러 메시지 확인

Could NOT find Boost (missing: Boost_INCLUDE_DIR)

→ Boost_INCLUDE_DIR를 찾지 못했다는 뜻. 헤더 경로 문제입니다.

2단계: 라이브러리 설치 확인

# Ubuntu/Debian
dpkg -l | grep boost

# macOS
brew list | grep boost

# Windows
vcpkg list | findstr boost

3단계: Config 파일 찾기

find /usr -name "BoostConfig.cmake" 2>/dev/null
find /usr/local -name "boost-config.cmake" 2>/dev/null

4단계: CMAKE_PREFIX_PATH 설정

Config 파일이 /opt/boost/lib/cmake/Boost/에 있다면:

cmake -DCMAKE_PREFIX_PATH=/opt/boost ..

5단계: 디버그 모드로 재실행

cmake --debug-find ..

--debug-find를 쓰면 CMake가 어디를 검색했는지 자세히 출력합니다.

환경별 자주 하는 실수

Linux

문제: sudo apt install boost로 설치했는데 못 찾음.
원인: 패키지 이름이 libboost-all-dev입니다.
해결: sudo apt install libboost-all-dev

macOS (Homebrew)

문제: brew install boost 후에도 못 찾음.
원인: Homebrew는 /usr/local/ 또는 /opt/homebrew/에 설치하는데, CMake가 못 찾을 수 있습니다.
해결:

export CMAKE_PREFIX_PATH=/opt/homebrew
cmake ..

또는:

brew --prefix boost
# 출력: /opt/homebrew/opt/boost
cmake -DCMAKE_PREFIX_PATH=/opt/homebrew/opt/boost ..

Windows (수동 설치)

문제: Boost를 C:\boost에 압축 풀었는데 못 찾음.
원인: Config 파일이 없거나, 경로를 지정하지 않음.
해결:

cmake -DBOOST_ROOT=C:\boost -DBoost_INCLUDE_DIR=C:\boost\include ..

또는 vcpkg 사용:

vcpkg install boost
cmake -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake ..

vcpkg 실전 예시

설치 및 설정

# vcpkg 설치
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh

# 라이브러리 설치
./vcpkg install boost-system boost-filesystem
./vcpkg install fmt

CMakeLists.txt

cmake_minimum_required(VERSION 3.15)
project(MyApp LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

# vcpkg toolchain을 쓰면 find_package가 자동으로 작동
find_package(Boost REQUIRED COMPONENTS system filesystem)
find_package(fmt REQUIRED)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE 
    Boost::system 
    Boost::filesystem 
    fmt::fmt
)

빌드

cmake -DCMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake ..
cmake --build .

팁: vcpkg toolchain 파일을 환경 변수로 설정해 두면 매번 지정하지 않아도 됩니다.

export CMAKE_TOOLCHAIN_FILE=/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake

Conan 실전 예시

conanfile.txt 작성

[requires]
boost/1.80.0
fmt/9.1.0

[generators]
CMakeDeps
CMakeToolchain

[options]
boost:shared=False

설치 및 빌드

# 의존성 설치
conan install . --build=missing

# CMake 빌드 (Conan이 생성한 preset 사용)
cmake --preset conan-default
cmake --build --preset conan-release

CMakeLists.txt:

cmake_minimum_required(VERSION 3.15)
project(MyApp LANGUAGES CXX)

find_package(Boost REQUIRED)
find_package(fmt REQUIRED)

add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE Boost::Boost fmt::fmt)

정리: find_package 실패 시 순서대로 체크

라이브러리 설치 확인 → apt search, brew list, vcpkg list
Config 파일 위치 찾기 → find / -name "XXXConfig.cmake"
CMAKE_PREFIX_PATH 설정 → Config 파일이 있는 상위 디렉터리 지정
버전 확인 → 요구 버전과 설치된 버전 비교
컴포넌트 확인 → COMPONENTS 필요 여부
디버그 모드 → cmake --debug-find로 검색 경로 확인
패키지 매니저 사용 → vcpkg/Conan으로 자동화

한 줄 요약: Could NOT find은 CMake가 라이브러리 경로를 모를 때 나오므로, CMAKE_PREFIX_PATH·버전·컴포넌트를 점검하고 vcpkg/Conan을 쓰면 대부분 해결됩니다. 다음으로 CMake 입문이나 LNK2019 해결을 읽어보면 좋습니다.

자주 묻는 질문 (FAQ)

Q. find_package가 성공했는데 링크 에러가 나요.

A: find_package는 성공했지만, target_link_libraries를 안 했거나, 컴포넌트를 잘못 지정했을 수 있습니다. Boost::system 대신 Boost::boost만 링크하면 헤더는 보이지만 라이브러리는 링크 안 됩니다.

Q. vcpkg로 설치했는데 find_package가 실패합니다.

A: toolchain 파일을 지정하지 않았을 가능성이 큽니다. 반드시 -DCMAKE_TOOLCHAIN_FILE=.../vcpkg.cmake를 써야 합니다.

Q. Config 파일 경로를 어떻게 찾나요?

# Linux/macOS
find /usr -name "*Config.cmake" 2>/dev/null | grep -i boost

# Windows (PowerShell)
Get-ChildItem -Recurse -Filter "*Config.cmake" C:\

Q. FetchContent vs find_package, 언제 뭘 쓰나요?

find_package: 시스템에 이미 설치된 라이브러리 사용 (빠름)
FetchContent: 소스에서 자동 다운로드·빌드 (재현성 좋음, 느림)

CI/CD 환경에서는 FetchContent가 유리하고, 로컬 개발에서는 find_package + vcpkg가 빠릅니다.

CMake 입문: CMake 기본 개념과 외부 라이브러리 연동
CMake 치트시트: FetchContent로 라이브러리 가져오기
C++ 패키지 매니저 (vcpkg, Conan): 패키지 매니저 비교와 활용법

Could NOT find 에러는 대부분 경로 문제입니다. 라이브러리가 설치되어 있어도 CMake가 어디를 봐야 하는지 모르면 찾지 못합니다. CMAKE_PREFIX_PATH로 경로를 알려 주거나, vcpkg/Conan 같은 패키지 매니저를 쓰면 이런 문제를 대부분 피할 수 있습니다. 특히 vcpkg는 Windows 환경에서 C++ 라이브러리 관리를 획기적으로 쉽게 만들어 줍니다.

검색 시 참고 키워드: CMake Could NOT find, find_package 실패, CMAKE_PREFIX_PATH, vcpkg toolchain, Boost Config.cmake

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

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

C++ 패키지 매니저 | vcpkg·Conan으로 “라이브러리 설치 지옥” 탈출하기
C++ LNK2019 | “unresolved external symbol” 링커 에러 원인 5가지와 해결법
CMake 입문 | 수십 개 파일 컴파일할 때 필요한 빌드 자동화 (CMakeLists.txt 기초)

심화 부록: 구현·운영 관점

이 부록은 앞선 본문에서 다룬 주제(「CMake ‘Could NOT find’ 에러」)를 구현·런타임·운영 관점에서 다시 압축합니다. 도메인별 세부 구현은 글마다 다르지만, 입력 검증 → 핵심 연산 → 부작용(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·동시성을 프로덕션에 가깝게 맞출수록 재현율이 올라갑니다.

확장 예시: 엔드투엔드 미니 시나리오

앞선 본문 주제(「CMake ‘Could NOT find’ 에러」)를 배포·운영 흐름에 맞춰 옮긴 체크리스트입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.

입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드를 경계에 둔다.
핵심 경로 계측: 요청 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 순서를 권장합니다.

이 글에서 다루는 키워드 (관련 검색어)

CMake, find_package, Could NOT find, 빌드에러, vcpkg, Conan, CMAKE_PREFIX_PATH 등으로 검색하시면 이 글이 도움이 됩니다.

이 글이 도움이 되셨나요?

여러분의 피드백은 더 나은 콘텐츠를 만드는 데 도움이 됩니다

문제가 있거나 개선 제안이 있으시면 연락처로 알려주세요.

Keyboard Shortcuts

이 글의 핵심

들어가며: “Could NOT find Boost (missing: …)”

실전 경험에서 배운 교훈

1. find_package는 어떻게 찾나요?

Config 모드 vs Module 모드

검색 경로

2. 원인 1: 라이브러리가 설치 안 됨 또는 경로 문제

문제 상황

해결법 1: 라이브러리 설치

해결법 2: CMAKE_PREFIX_PATH 설정

3. 원인 2: 버전 불일치

문제 상황

해결법

4. 원인 3: Config 파일이 없음 (Module 모드 실패)

문제 상황

해결법 1: Config 파일 경로 직접 지정

해결법 2: find_library로 직접 찾기

5. 원인 4: 패키지 이름 대소문자 불일치

문제 상황

해결법

6. 원인 5: 필요한 컴포넌트 누락

문제 상황

해결법

7. CMAKE_PREFIX_PATH로 경로 지정

여러 경로 추가

환경 변수로 설정

Windows에서

8. 패키지 매니저 활용 (vcpkg, Conan)

vcpkg (Microsoft)

Conan

해결 체크리스트

실전 디버깅 프로세스

환경별 자주 하는 실수

Linux

macOS (Homebrew)

Windows (수동 설치)

vcpkg 실전 예시

설치 및 설정

CMakeLists.txt

빌드

Conan 실전 예시

conanfile.txt 작성

설치 및 빌드

정리: find_package 실패 시 순서대로 체크

자주 묻는 질문 (FAQ)

Q. find_package가 성공했는데 링크 에러가 나요.

Q. vcpkg로 설치했는데 find_package가 실패합니다.

Q. Config 파일 경로를 어떻게 찾나요?

Q. FetchContent vs find_package, 언제 뭘 쓰나요?

관련 글

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

심화 부록: 구현·운영 관점

내부 동작과 핵심 메커니즘

프로덕션 운영 패턴

확장 예시: 엔드투엔드 미니 시나리오

문제 해결(Troubleshooting)

이 글에서 다루는 키워드 (관련 검색어)

이 글이 도움이 되셨나요?