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 옵션을 사용해 특정 캐시 변수를 업데이트할 수 있다.

관련 자료: