# CMake: 일반적인 오류와 해결 방법

CMake는 매우 유용한 도구이지만, 복잡한 프로젝트를 설정하거나 빌드할 때 종종 오류가 발생할 수 있다. 이러한 오류는 CMakeLists.txt 파일의 구성, 환경 설정, 또는 외부 종속성 문제 등 다양한 원인에서 비롯될 수 있다. 이 섹션에서는 CMake 사용 시 발생할 수 있는 일반적인 오류와 그 해결 방법을 다룬다.

#### CMake 오류 메시지 이해하기

CMake는 오류가 발생할 경우 구체적인 오류 메시지를 제공한다. 이 메시지에는 오류의 원인, 발생 위치, 관련 파일 및 라인 번호 등이 포함될 수 있다. 오류 메시지를 면밀히 분석하는 것이 문제를 해결하는 첫 번째 단계이다. 오류 메시지를 이해하고 관련 문서를 참조하여 문제를 해결하는 습관을 들이는 것이 중요하다.

#### CMakeLists.txt 파일에서의 일반적인 오류

**명령어 오타 또는 잘못된 구문**

CMakeLists.txt 파일에서 가장 흔히 발생하는 오류 중 하나는 명령어 오타나 잘못된 구문이다. CMake는 엄격한 구문 규칙을 가지고 있으므로, 오타나 잘못된 구문으로 인해 빌드가 실패할 수 있다. 예를 들어, `add_executable()`을 `add_excutable()`로 잘못 입력하면 오류가 발생한다. 이러한 오류는 CMake가 특정 명령을 인식하지 못하거나 예상치 못한 입력을 받았을 때 발생한다.

**해결 방법:** 오류 메시지를 확인하여 어떤 명령에서 오류가 발생했는지 파악하고, CMakeLists.txt 파일을 다시 검토한다. 명령어 오타나 구문 오류를 수정하고, 빌드를 다시 시도한다.

**파일 또는 디렉토리 경로 문제**

CMake는 파일 경로와 디렉토리 구조에 의존한다. 소스 파일이나 헤더 파일의 경로를 잘못 설정하면 파일을 찾을 수 없다는 오류가 발생한다. `add_executable()` 또는 `target_link_libraries()` 명령에서 잘못된 경로를 지정하는 것이 일반적인 원인이다.

**해결 방법:** CMakeLists.txt 파일에서 지정한 경로를 정확하게 확인하고, 해당 파일이 실제로 존재하는지 확인한다. 경로가 상대 경로인지 절대 경로인지 확인하고, 필요에 따라 경로를 수정한다.

**외부 패키지 찾기 실패**

CMake는 종종 외부 라이브러리나 패키지를 찾아서 프로젝트에 포함해야 한다. `find_package()` 명령이 실패하면, 특정 라이브러리를 찾지 못 하였다는 오류가 발생한다. 이는 라이브러리가 설치되지 않았거나, 환경 변수 설정이 잘못되었거나, 올바른 CMake 모듈을 찾지 못했을 때 발생한다.

**해결 방법:** 먼저, 해당 라이브러리가 시스템에 설치되어 있는지 확인한다. 환경 변수(CMAKE\_PREFIX\_PATH 등)를 올바르게 설정하여 CMake가 라이브러리를 찾을 수 있도록 한다. 필요한 경우, CMake 모듈 경로를 추가하거나 라이브러리의 위치를 명시적으로 지정한다.

#### 빌드 프로세스에서의 일반적인 오류

**컴파일러 관련 오류**

CMake는 다양한 컴파일러를 지원하지만, 컴파일러 설정이 잘못되었거나 특정 옵션이 누락된 경우 컴파일러 오류가 발생할 수 있다. 예를 들어, 프로젝트에서 요구하는 C++ 표준을 지원하지 않는 컴파일러를 사용하는 경우 문제가 발생할 수 있다.

**해결 방법:** CMakeLists.txt 파일에서 `set(CMAKE_CXX_STANDARD 11)`와 같은 명령을 사용해 프로젝트에 맞는 컴파일러 표준을 명시적으로 설정한다. 필요에 따라 다른 컴파일러를 지정하거나, 현재 컴파일러의 설정을 조정하여 문제를 해결한다.

**라이브러리 링크 오류**

CMake를 사용해 프로젝트를 빌드할 때, 종종 라이브러리 링크 오류가 발생할 수 있다. 이는 `target_link_libraries()` 명령에서 잘못된 라이브러리를 지정했거나, 라이브러리가 시스템에 설치되지 않았을 때 발생한다. 링크 오류는 컴파일 단계에서는 문제가 없지만, 최종 링크 단계에서 문제가 발생할 수 있다.

**해결 방법:** 링크 오류 메시지를 확인하여 어떤 라이브러리가 문제인지 파악한다. CMakeLists.txt에서 `target_link_libraries()` 명령을 검토하고, 올바른 라이브러리가 지정되었는지 확인한다. 필요한 경우, 시스템에 누락된 라이브러리를 설치하거나 환경 변수를 수정하여 라이브러리 경로를 올바르게 설정한다.

**중복 정의 오류**

다수의 파일에서 동일한 심볼이나 변수를 정의하는 경우, 중복 정의 오류가 발생할 수 있다. 이는 여러 라이브러리를 동시에 링크할 때 특히 발생할 수 있다. 중복 정의 오류는 주로 전역 변수나 함수에서 발생하며, 링크 단계에서 충돌을 일으킨다.

**해결 방법:** 코드에서 전역 변수나 함수의 정의를 확인하고, 중복 정의된 부분을 수정하거나 제거한다. 필요하다면, 네임스페이스를 사용해 심볼 충돌을 방지할 수 있다. 또한, 특정 라이브러리를 링크에서 제외하거나, 정의 충돌을 방지하기 위해 빌드 설정을 조정할 수 있다.

#### 기타 환경 설정 관련 오류

**빌드 디렉토리 정리 필요**

CMake를 사용해 빌드 파일을 생성하는 동안, 기존의 빌드 파일이 새로운 설정과 충돌을 일으킬 수 있다. 이로 인해 빌드가 실패하거나, 예상치 못한 결과가 발생할 수 있다.

**해결 방법:** 빌드 디렉토리를 완전히 삭제한 후, 다시 생성하고 빌드를 시도한다. CMake에서는 `rm -rf build/` 명령을 사용해 빌드 디렉토리를 삭제한 후, `cmake .` 명령으로 다시 빌드 파일을 생성할 수 있다.

**캐시 문제**

CMake는 빌드 설정을 캐시에 저장하여 빌드 속도를 높인다. 그러나 가끔 캐시된 정보가 최신 상태가 아니어서 문제가 발생할 수 있다. 예를 들어, CMakeLists.txt를 수정했지만, 캐시된 이전 설정이 적용되는 경우가 있다.

**해결 방법:** CMake 캐시를 삭제하고, 다시 구성한다. `cmake .` 명령을 실행할 때 `-DCMAKE_CACHE` 옵션을 사용하여 캐시를 초기화할 수 있다. 또는, CMake를 실행할 때 `-U` 옵션을 사용해 특정 캐시 변수를 업데이트할 수 있다.

***

관련 자료:

* 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.