# CMake: 트러블슈팅 및 문제 해결

CMake를 사용하면서 발생할 수 있는 다양한 문제와 이를 해결하기 위한 트러블슈팅 방법을 이해하는 것은 매우 중요하다. 이 섹션에서는 CMake를 사용할 때 흔히 발생하는 문제와 이에 대한 해결책을 다룬다.

#### CMake 설정 문제

**CMakeLists.txt 파일에서의 구문 오류**

CMakeLists.txt 파일에 구문 오류가 있을 경우, CMake는 파일을 해석하지 못하고 오류를 발생시킨다. 예를 들어, 잘못된 명령어 사용이나 변수 이름의 오타 등이 구문 오류를 유발할 수 있다. 이런 경우, CMake는 오류 메시지를 출력하며, 문제의 위치를 명확히 지적할 수 있다. 이를 해결하기 위해서는 해당 메시지를 참고하여 CMakeLists.txt 파일을 수정해야 한다.

**빌드 디렉토리의 문제**

때때로 CMake 설정 파일이나 빌드 디렉토리가 손상되어 예상치 못한 오류가 발생할 수 있다. 이 문제는 특히 빌드 디렉토리와 소스 디렉토리가 혼합될 때 자주 발생한다. 이 문제를 해결하려면 빌드 디렉토리를 깨끗하게 삭제한 후, 새로운 빌드 디렉토리를 생성하고 다시 설정을 실행하는 것이 좋다.

```bash
rm -rf build/
mkdir build
cd build
cmake ..
```

위의 명령어를 사용하여 빌드 디렉토리를 초기화하고, 문제를 해결할 수 있다.

#### 외부 패키지 및 라이브러리 관련 문제

**`find_package` 오류**

`find_package` 명령을 사용하여 외부 라이브러리나 패키지를 찾을 때 문제가 발생할 수 있다. CMake는 지정된 패키지를 찾지 못할 경우, 다음과 같은 오류 메시지를 출력할 수 있다:

```
CMake Error at CMakeLists.txt:10 (find_package):
  Could not find a package configuration file provided by "PackageName" with
  any of the following names:
    PackageNameConfig.cmake
    packagename-config.cmake
```

이 문제는 패키지가 설치되지 않았거나, 패키지 경로가 CMake에 올바르게 제공되지 않았을 때 발생한다. 이를 해결하기 위해서는 패키지가 설치되어 있는지 확인하고, 필요한 경우 `CMAKE_PREFIX_PATH` 변수에 해당 경로를 추가해야 한다.

```bash
cmake -DCMAKE_PREFIX_PATH=/path/to/package ..
```

또한, `find_package` 명령어에 `REQUIRED` 옵션을 제거하면, 해당 패키지를 필수로 요구하지 않도록 설정할 수 있다.

**링크 오류**

외부 라이브러리를 사용할 때, 링크 오류가 발생할 수 있다. 이 경우, CMake는 다음과 같은 링크 에러 메시지를 출력할 수 있다:

```
undefined reference to 'function_name'
```

이 문제는 라이브러리가 올바르게 링크되지 않았기 때문에 발생한다. 이를 해결하기 위해서는 `target_link_libraries` 명령어를 사용해 해당 라이브러리를 정확하게 링크해야 한다.

```cmake
target_link_libraries(my_executable PRIVATE my_library)
```

또한, 라이브러리가 올바른 경로에 있는지, 또는 경로가 CMake에 정확히 지정되었는지 확인하는 것이 중요하다.

#### 컴파일러 및 빌드 관련 문제

**컴파일러 오류**

CMake는 다양한 컴파일러를 지원하지만, 프로젝트 설정이 특정 컴파일러에 의존하는 경우가 있다. 컴파일러 오류는 종종 잘못된 컴파일러 선택이나 컴파일러 플래그 설정으로 인해 발생할 수 있다. 이 문제를 해결하기 위해서는 CMakeLists.txt 파일에서 명시적으로 컴파일러를 설정하거나, 컴파일러 관련 플래그를 수정해야 한다.

```cmake
set(CMAKE_CXX_COMPILER "/usr/bin/g++")
set(CMAKE_CXX_FLAGS "-Wall -Wextra")
```

또한, CMake 실행 시 `-DCMAKE_CXX_COMPILER` 옵션을 사용해 원하는 컴파일러를 지정할 수 있다.

**빌드 실패**

빌드 실패는 여러 가지 이유로 발생할 수 있다. 가장 흔한 원인 중 하나는 종속성 문제로, 필요로 하는 라이브러리나 헤더 파일이 누락되었거나 올바르게 포함되지 않았을 때 발생한다. 이러한 문제를 해결하기 위해서는 종속성이 올바르게 설정되었는지 확인하고, 필요한 파일들이 모두 포함되었는지 점검해야 한다.

또한, 컴파일러 버전 불일치, 컴파일러 설정 문제, 또는 플랫폼 간 차이로 인해 빌드가 실패할 수 있다. 이 경우, 빌드 로그를 분석하고 문제가 발생한 부분을 추적하여 해결 방안을 모색해야 한다.

#### 디버깅 및 로그 확인

**CMake 디버깅 모드**

복잡한 CMake 설정을 디버깅할 때는 CMake의 디버깅 모드를 활용할 수 있다. `--trace` 옵션을 사용하면 CMake가 처리하는 모든 명령어를 출력할 수 있으며, 이를 통해 문제의 원인을 보다 쉽게 파악할 수 있다.

```bash
cmake --trace .
```

이 명령어는 CMakeLists.txt 파일이 실행되는 동안 발생하는 모든 명령어를 터미널에 출력한다. 이를 통해 구문 오류나 논리적 오류를 추적할 수 있다.

**빌드 로그 확인**

빌드 과정에서 발생하는 오류를 이해하기 위해서는 빌드 로그를 확인하는 것이 중요하다. 특히, 컴파일러가 출력하는 경고나 오류 메시지를 통해 문제의 원인을 추적할 수 있다. 빌드 로그는 일반적으로 터미널에 출력되며, 필요 시 파일로 저장해 분석할 수 있다.

```bash
make 2>&1 | tee build.log
```

이 명령어는 빌드 로그를 `build.log` 파일에 저장하고, 터미널에도 출력한다. 이를 통해 문제를 분석하고 적절한 조치를 취할 수 있다.

***

관련 자료:

* Kitware Inc., CMake Documentation, <https://cmake.org/cmake/help/latest/>
* Martin, R., Mastering CMake, Kitware, Inc., 2010.
* Saxer, A., Professional CMake: A Practical Guide, Leanpub, 2020.