[CMake] Modules

References

• Professional CMake : A Practical Guide

Contents

• Modules
• include()
• find_package()
• CMakePrintHelpers, TestBigEndian
• CheckCSourceCompiles, CheckCXXSourceCompiles, CheckFortranSourceCompiles
• CheckCSourceRuns, CheckCXXSourceRuns
• CheckCCompilerFlag, CheckCXXCompilerFlag, CheckFortranCompilerFlag
• CheckSymbolExists, CheckCXXSymbolExists
• CheckStructHasMember, CheckPrototypeDefinition, CheckTypeSize 등
• CMakePushCheckState

---

모듈(Module)은 CMake에서 제공되는 코드 덩어리입니다. 프로젝트에서 아주 유용하게 사용될 수 있는 기능들을 제공합니다. 모듈은 CMake가 설치될 때 같이 설치되며, 저의 경우에는 CMake 설치 경로에서 CMake\shared\cmake-3.20\Modules 에서 제공되는 모듈의 코드를 확인할 수 있습니다. 

 

모듈을 사용하는 기본적인 방법은 include() 커맨드로 현재 scope에 모듈을 추가하는 것입니다. include()는 이전 글에서 살짝 다루었는데, 필요하시면 참고 바랍니다 !

2021.10.31 - [CMake] - [CMake] add_subdirectory() 와 변수 Scope

[CMake] add_subdirectory() 와 변수 Scope

 

include() 커맨드에 모듈 이름이 주어지면, 모듈 이름에 '.cmake' 확장자가 붙은 파일을 찾습니다. 이때, 모듈 이름은 대소문자를 구분합니다. 예를 들어, 'include(FooBar)'는 CMake가 'FooBar.cmake'라는 파일을 찾도록 합니다.

 

모듈의 파일을 찾을 때 CMake는 먼저 CMAKE_MODULE_PATH 변수를 참조합니다. 이 변수는 디렉토리를 값으로 갖는 리스트로 간주되며, CMake는 이 디렉토리 리스트에서 순서대로 모듈을 검색합니다. 만약 이 변수에서 모듈을 찾지 못하거나, 이 변수가 비어있거나 정의되지 않은 경우에는 자체 내부 모듈 디렉토리에서 검색합니다. 따라서, 프로젝트에서는 CMAKE_MODULE_PATH에 디렉토리를 추가해서 자신만의 모듈을 추가할 수 있습니다. 

자주 사용되는 방법은 프로젝트의 모듈 파일들을 단일 디렉토리에 모아서 최상위 CMakeLists.txt 파일의 시작 근처에서 CMAKE_MODULE_PATH에 모듈이 모여있는 디렉토리를 추가하는 것입니다.

일반적으로 프로젝트 root 폴더의 cmake 폴더에 모듈들을 위치시키는데,

이 경우에는 최상단의 CMakeLists.txt에 아래처럼 시작 부근에서 CMAKE_MODULE_PATH를 추가하고, 모듈을 include할 수 있습니다.

 

CMake가 모듈을 찾는 순서에 한 가지 예외가 존재하는데, include() 커맨드로 호출하는 파일 자체가 CMake의 자체 내부 모듈, 즉, CMake에서 원래 제공되는 모듈인 경우 CMAKE_MODULE_PATH를 참조하기 전에 내부 모듈 디렉토리를 먼저 검색합니다. 따라서 CMake 프로젝트에서 실수로 CMake 공식 모듈을 다른 모듈로 바꾸는 것을 방지할 수 있습니다.

 

---

모듈을 사용하는 다른 방법은 find_package() 커맨드를 사용하는 것입니다.

모듈 이외에도 다른 용법으로 사용할 수 있지만, 우선 find_package() 커맨드로 모듈을 찾을 수 있다는 것만 알고 넘어가겠습니다. 이 커맨드로 모듈을 찾으면, CMake가 'PackageName.cmake' 파일이 아닌 'FindPackageName.cmake' 파일을 찾게 됩니다. (include() 커맨드와의 차이점)

find_package 커맨드는 가져온 외부 패키지의 세부 정보(Target, 변수, 라이브러리 혹은 프로그램 등)를 현재 빌드로 가져와주는 역할도 합니다. 따라서, find_package() 커맨드는 include() 보다 더 많은 옵션들을 가지고 옵니다. 이 부분은 추후에 예제 프로젝트를 실제로 구성해보면서 더 자세하게 다루도록 하겠습니다.

 

이번 글에서는 CMake에서 공식적으로 제공하는 몇 가지 유용한 모듈을 소개하고 마무리하도록 하겠습니다.

---

CMakePrintHelpers

CMakePrintHelpers 모듈은 개발 중에 속성의 값이나 변수의 값을 보다 편리하게 출력할 수 있도록 두 개의 매크로를 제공합니다. 이는 일시적으로 해당 정보를 빠르고 쉽게 기록하는데 도움이 됩니다.

cmake_print_properties 매크로는 기본적으로 get_property()와 message()를 결합한 것입니다. 속성 타입 중의 하나를 필수로 입력해야하고, 나열된 entity에 대한 정의된 속성들이 출력됩니다. 이는 여러 entity나 속성을 로깅하는데 편리합니다. 이 매크로는 아래처럼 사용될 수 있습니다.

위 코드의 출력은 다음과 같습니다.

 

이 모듈은 또한 변수의 값을 로깅하는데 유사한 매크로를 제공합니다.

이 매크로는 변수가 명시적으로 프로젝트에서 설정되었든지, 아니면 CMake에서 자동으로 설정했는지와 관계없이 모든 변수를 출력할 수 있습니다.

예를 들어, 아래 코드는

다음과 같습니다.

 

---

TestBigEndian

다양한 아키텍처를 가진 임베디드 플랫폼이나 프로젝트에서 작업하는 경우, 대상 Target 시스템의 엔디안 시스템이 무엇인지 알아야합니다. TestBigEndian 모듈은 작은 테스트 프로그램을 컴파일하여 타켓의 엔디안을 검사하는 test_big_endian() 매크로를 제공합니다. 그런 다음에는 이 결과가 캐시되어 다음 CMake 실행부터는 테스트를 다시 실행할 필요가 없습니다. 매크로는 결과(부울 타입)를 저장할 변수 이름인 argument 하나만 취합니다.

(TRUE인 경우 시스템이 빅엔디안입니다.)

 

---

CheckCSourceCompiles, CheckCXXSourceCompiles, CheckFortranSourceCompiles

위 모듈들은 짧은 테스트 코드(각 언어)를 작성한 다음 컴파일을 시도하고 실행하여, 성공 또는 실패를 반환하는 모듈입니다. 이런 모듈의 이름은 Check<Language>SourceCompiles라는 형식의 이름을 갖고, 각각은 테스트를 수행하기 위한 관련 매크로를 제공합니다.

각 매크로에 대해 code는 선택한 엉어에 대한 실행파일을 생성해야 하는 소스 코드가 포함된 문자열이어야 합니다. code를 컴파일하고 링크하는 시도의 결과는 resultVar에 캐시 변수로 저장되며 TRUE는 코드 실행 성공을 의미합니다. FALSE 값은 상황에 따라 빈 문자열, 오류 메세지 등이 될 수 있습니다. 테스트가 한 번 수행된 후, 다음 CMake 실행에서는 테스트를 다시 수행하는 대신 캐시된 결과를 사용합니다. 따라서, 테스트 코드가 변경된 경우도 캐시 변수가 사용되므로 강제로 다시 테스트하려면 캐시에서 변수를 수동으로 제거해야 합니다.

 

FAIL_REGEX 옵션이 지정되면 추가 테스트가 적용됩니다. 테스트 코드의 컴파일 및 링크가 성공하더라도 그 출력이 정규표현식과 일치해야 성공한 것으로 간주합니다.

 

포트란의 경우 파일 확장자가 컴파일러가 소스 파일을 처리하는 방식에 영향을 줄 수 있으므로, SRC_EXT 옵션을 사용하여 파일 확장자를 명시적으로 지정해야지 예상되는 동작을 얻을 수 있습니다.

 

이외에 CMAKE_REQUIRED_... 형태의 여러 변수들은 컴파일 테스트 매크로를 호출하기 전에 설정하여 코드를 컴파일하는 방법에 영향을 줄 수 있습니다.

• CMAKE_REQUIRED_FLAG : 컴파일러 커맨드에 전달할 CMAKE_<LANG>_FLAGS와 CMAKE_<LANG>_FLAGS_<CONFIG> 변수 뒤에 추가되는 플래그입니다. CMake 리스트와 달리 공백으로 구분된 여러 플래그가 있는 단일 문자열이어야 합니다.
• CMAKE_REQUIRED_DEFINITIONS : '-DFOO' 또는 '-DFOO=bar'과 같은 형태의 컴파일 정의를 담은 리스트입니다.
• CMAKE_REQUIRED_INCLUDES : 헤더를 검색할 디렉토리를 설정합니다. 여러 경로들을 CMake 리스트로 지정해야하고 공백은 경로의 일부로 처리해야합니다.
• CMAKE_REQUIRED_LIBRARIES : 링크 단계에 추가할 라이브러리의 CMake 리스트입니다. 라이브러리 이름에 -I 옵션이나 이와 유사한 접두사를 붙이지 말고 라이브러리 이름 또는 import된 target이어야 합니다.
• CMAKE_REQUIRED_QUIET : 이 옵션이 존재하면, 매크로는 어떤 status message도 출력하지 않습니다.

위 변수들은 테스트를 수행하기 위해 try_compile() 커맨드 호출을 위한 arguments를 구성하는데 사용됩니다. 

 

---

CheckCSourceRuns, CheckCXXSourceRuns

코드를 빌드할 수 있는지 여부를 확인하는 것 외에도 CMake에서는 C 또는 C++ 코드를 성공적으로 실행할 수 있는지 여부를 테스트하는 모듈도 제공합니다. 성공 여부는 제공된 코드에서 생성된 실행 파일의 종료 코드로 판단하며, 0은 성공으로 판단하고 다른 모든 값은 실패로 간주합니다.

성공 또는 실패가 단순히 테스트 코드의 종료 코드에 의해 결정되기 때문에 이러한 매크로에는 FAIL_REGEX 옵션이 없습니다. 또한, 코드를 빌드할 수 없는 경우에도 실패도 처리됩니다. 위에서 설명한 테스트 매크로를 호출하기 전에 설정할 수 있는 변수들은 이 두 모듈의 테스트에도 동일한 영향을 미칩니다.

 

다른 타겟 플랫폼에서 크로스 컴파일되는 빌드의 경우, check_c_source_runs() 및 check_cxx_source_runs() 매크로는 매우 다르게 동작합니다. 만약 필요한 세부 정보들이 제공된 경우 시뮬레이터에서 코드가 동작할 수 있고, 이는 CMake 처리 속도가 꽤 느려질 수 있습니다. 시뮬레이터에 관한 세부 정보가 제공되지 않은 경우, 매크로는 변수들을 통해 미리 결정된 결과를 반환하고 아무것도 실행하지 않습니다.

(꽤 고급 주제인데, 저도 아직까지는 잘 모르는 부분입니다. 이 내용은 매크로가 내부적으로 검사를 수행할 때 사용하는 try_run() 커맨드 공식 문서를 참조바랍니다 !)

 

---

CheckCCompilerFlag, CheckCXXCompilerFlag, CheckFortranCompilerFlag

이 모듈들은 컴파일러 플래그, 전처리기 심볼, 함수 변수, 헤더 파일 등을 검사하는데 사용합니다.

Check<LAGN>CompilerFlag 모듈로 특정 컴파일러 플래그에 대해 검사를 수행할 수 있습니다.

플래그를 체크하는 매크로는 내부적으로 CMAKE_REQUIRED_DEFINITIONS 변수를 업데이트하고, check_<LANG>_source_compiles()를 호출합니다. 그리고 내부적으로 일치하는 진단 메세지가 발생하는지 정규표현식으로 검사하여, 발생 여부를 체크합니다. 일치하는 진단 메세지가 출력되지 않으면 결과는 TRUE입니다. 

 

---

CheckSymbolExists, CheckCXXSymbolExists

CheckSymbolExists는 테스트 C 실행파일을 빌드하는 매크로를 제공하고 CheckCXXSymbolExists는 C++ 실행 파일을 빌드하는 매크로를 제공합니다. 두 모듈모두 특정 심볼이 전처리기 심볼, 함수 또는 변수로 존재하는지 확인합니다.

headers에 특정 아이템이 지정되면, 테스트코드에 #include로 이 헤더들이 소스코드에 추가됩니다. (헤더가 여러개라면 리스트로 지정합니다.) 대부분의 경우 심볼은 이 헤더들 중에서 정의된 것으로 확인됩니다. 테스트 결과는 일반적인 방법으로 resultVar 캐시 변수에 저장됩니다.

 

함수나 변수인 경우, 심볼은 테스트 실행파일의 일부로 resolve되어야합니다. 만약 함수나 변수가 라이브러리로 제공된다면, 라이브러리는 반드시 테스트의 일부로 링크되어야 하고 이때, CMAKE_REQUIRED_LIBRARIES 변수를 사용하여 링크할 수 있습니다.

다만 이러한 매크로로 확인할 수 있는 함수와 변수의 종류에는 한계가 있는데, 오직 전처리기 심볼로 사용될 수 있는 네이밍 요구사항을 만족하는 심볼에 대해서만 가능합니다. 이 한계는 check_cxx_symbol_exits() 커맨드에서 치명적인데, 이는 global namespace에 존재하는 non-template 함수나 변수, 즉 scoping(::)이나 템플릿마커(<>)가 없는 함수 및 변수만 검사할 수 있다는 것을 의미합니다. 또한 동일한 이름의 오버로딩된 함수를 구별하는 것도 불가능합니다.

 

이 모듈과 유사하거나 하위호환하는 CheckFunctionExists와 CheckVariableExists 모듈도 있습니다만, CheckFunctionExists대신 CheckSymbolExists를 사용하라고 문서에서 언급하고 있으며, CheckVariableExists는 CheckSymbolExists와 동일한 기능(변수에 대해서)을 가지고 있습니다.

 

---

CheckStructHasMember, CheckPrototypeDefinition, CheckTypeSize 등

더 자세한 검사는 위와 같은 모듈들로 가능합니다. 구조체 멤버는 CheckStructHasMember 모듈로 검사할 수 있고, 특정 C 또는 C++ 함수 프로토 타입은 CheckPrototypeDefinition 모듈로 검사할 수 있으며, non-user 타입의 사이즈는 CheckTypeSize 모듈로 검사할 수 있습니다. 또한, CheckLanguage, CheckLibraryExists 등 다양한 검사를 제공하는 CheckIncludeFile... 모듈도 있습니다. CMake 버전이 올라가면서 계속 모듈이 추가되므로, 사용가능한 모듈 정보를 보려면 링크를 참조해주세요 !

 

---

CMakePushCheckState

여러 테스트가 수행되면서 테스트의 영향을 받지 않도록 나머지로부터 격리해야하는 상황에서는 테스트 전후의 상태를 수작업으로 저장하고 복원하는 것이 번거로울 수 있습니다. 특히 다양한 CMAKE_REQUIRED_... 변수를 저장하고 복원하는 경우가 많습니다. 이를 위해서 CMake에서는 다음의 세 개의 매크로를 정의하는 CMakePushCheckState 모듈을 제공합니다.

이러한 매크로를 사용하면 다양한 CMAKE_REQUIRED_... 변수를 세트로 취급하여 해당 상태를 가상의 스택에 push/pop할 수 있습니다. cmake_push_check_state()가 호출될 때마다 CMAKE_REQUIRED_... 변수 (또한 CheckTypeSize 모듈에서만 사용되는 CMAKE_EXTRA_INCLUDEFILES 변수)를 가상 스택에 push 합니다.

cmake_pop_check_state()는 반대로 동작하며, CMAKE_REQUIRED_... 변수의 현재 값을 버리고 이전 스택의 값으로 복원합니다. cmake_reset_check_state()는 모든 CMAKE_REQUIRED_... 변수를 지우는데 편리합니다. 또한, chekc_push_check_state()에 RESET 옵션은 푸시된 변수를 지우는데 편리합니다. (CMake 3.10 이전에는 버그가 존재하여 RESET 옵션이 동작하지 않았습니다.)