CMake 시작하기

CMake 는 애플리케이션을 빌드하고, 테스트하며, 패키징할 수 있게 해주는 도구 모음입니다. Qt와 마찬가지로 모든 주요 개발 플랫폼에서 사용할 수 있습니다. 또한 Qt CreatorVisual Studio Code를 비롯한 다양한 IDE에서도 지원됩니다.

이 섹션에서는 CMake 프로젝트에서 Qt를 사용하는 가장 기본적인 방법을 보여드리겠습니다. 먼저, 기본적인 콘솔 애플리케이션을 생성합니다. 그런 다음, 프로젝트를 확장하여 Qt GUI 애플리케이션을 생성합니다. Qt Widgets를 사용하는 GUI 애플리케이션으로 확장해 보겠습니다.

기존 CMake 프로젝트를 Qt로 빌드하는 방법을 알고 싶다면, 명령줄에서 CMake를 사용하여 프로젝트를 빌드하는 방법에 대한 문서를 참조하십시오.

CMake 시작에 대한 기본 사항을 배우려면 Qt Academy의 ‘CMake를 이용한 빌드: CMake 및 Qt 시작하기’ 강좌를 수강하세요.

C++ 콘솔 애플리케이션 빌드하기

CMake 프로젝트는 CMake 언어로 작성된 파일들로 정의됩니다. 메인 파일은 ` CMakeLists.txt`이며, 일반적으로 실제 프로그램 소스 코드와 동일한 디렉터리에 위치합니다.

다음은 Qt를 사용하여 C++로 작성된 콘솔 애플리케이션의 일반적인 CMakeLists.txt 파일 예시입니다:

cmake_minimum_required(VERSION 3.16)

project(helloworld VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt6 REQUIRED COMPONENTS Core)

qt_standard_project_setup()

qt_add_executable(helloworld
    main.cpp
)

target_link_libraries(helloworld PRIVATE Qt6::Core)

이제 내용을 하나씩 살펴보겠습니다.

cmake_minimum_required(VERSION 3.16)

cmake_minimum_required() 프로젝트를 성공적으로 구성하는 데 필요한 최소 CMake 버전을 지정합니다. Qt에서 요구하는 최소 버전은 ‘지원되는 CMake 버전’을 참조하십시오.

project(helloworld VERSION 1.0.0 LANGUAGES CXX)

project() 프로젝트 이름과 기본 프로젝트 버전을 설정합니다. ` LANGUAGES ` 인수는 해당 프로그램이 C++로 작성되었음을 CMake에 알립니다.

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

Qt 6은 C++ 버전 17 이상을 지원하는 컴파일러가 필요합니다. CMAKE_CXX_STANDARD, CMAKE_CXX_STANDARD_REQUIRED 변수를 설정하여 이 조건을 강제 적용하면, 컴파일러 버전이 너무 오래된 경우 CMake가 오류 메시지를 출력합니다.

find_package(Qt6 REQUIRED COMPONENTS Core)

이렇게 하면 CMake가 Qt 6을 검색하고 Core 모듈을 사용할 수 있게 합니다. CMake 가 모듈을 찾을 수 없는 경우 계속 진행할 의미가 없으므로, 이 경우 CMake가 작업을 중단하도록 REQUIRED 플래그를 설정합니다. 자세한 내용은 CMake 프로젝트에서 Qt 사용하기 문서를 참조하십시오.

성공하면, 이 모듈은 ‘모듈 변수’에 설명된 몇 가지 CMake 변수를 설정합니다. 또한 아래에서 사용할 Qt6::Core 타깃을 가져옵니다.

qt_standard_project_setup()

qt_standard_project_setup() 명령어는 일반적인 Qt 애플리케이션에 대해 프로젝트 전체에 적용되는 기본값을 설정합니다.

이 명령은 무엇보다도 CMAKE_AUTOMOC 변수를 ON 로 설정하는데, 이는 CMake가 필요할 때 Qt의 Meta-Object Compiler (moc) 가 투명하게 호출되도록 규칙을 자동으로 설정하도록 지시합니다.

자세한 내용은 qt_standard_project_setup()의 참조 문서를 참조하십시오.

qt_add_executable(helloworld
    main.cpp
)

qt_add_executable()은 CMake에 helloworld 이라는 실행 파일(라이브러리가 아님)을 타깃으로 빌드하고자 함을 알립니다. 이 함수는 내장된 ` add_executable() ` 명령을 감싸는 래퍼이며, 정적 Qt 빌드에서 Qt 플러그인의 링크 처리나 플랫폼별 라이브러리 이름 사용자 정의 등과 같은 작업을 자동으로 처리하는 추가 로직을 제공합니다.

이 타깃은 C++ 소스 파일 main.cpp 을 기반으로 빌드되어야 합니다.

일반적으로 여기에는 헤더 파일을 나열하지 않습니다. 이는 qmake와 다른 점인데, qmake의 경우 헤더 파일이 Meta-Object Compiler (moc)에 의해 처리되도록 명시적으로 나열해야 합니다.

라이브러리를 생성하려면 qt_add_library()를 참조하십시오.

target_link_libraries(helloworld PRIVATE Qt6::Core)

마지막으로, ` target_link_libraries `는 CMake에게 ` helloworld ` 실행 파일이 Qt CoreQt6::Core find_package() 타깃을 참조함으로써 이를 알립니다. 이는 링커에 올바른 인수를 추가할 뿐만 아니라, 올바른 포함 디렉터리와 컴파일러 정의가 C++ 컴파일러에 전달되도록 보장합니다. 키워드는 실행 파일 타깃에 반드시 필요한 것은 아니지만, 이를 명시하는 것이 좋은 관행입니다. 만약 가 실행 파일이 아닌 라이브러리라면, 또는 를 지정해야 합니다(라이브러리의 헤더 파일에 에 언급된 내용이 포함되어 있다면 , 그렇지 않은 경우 ). PRIVATE helloworld PRIVATE PUBLIC Qt6::CorePUBLIC PRIVATE

C++ GUI 애플리케이션 빌드하기

지난 섹션에서는 간단한 콘솔 애플리케이션의 CMakeLists.txt 파일을 살펴보았습니다. 이제 Qt Widgets 모듈을 사용하는 GUI 애플리케이션을 만들어 보겠습니다.

다음은 전체 프로젝트 파일입니다:

cmake_minimum_required(VERSION 3.16)

project(helloworld VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt6 REQUIRED COMPONENTS Widgets)

qt_standard_project_setup()

qt_add_executable(helloworld
    mainwindow.ui
    mainwindow.cpp
    main.cpp
)

target_link_libraries(helloworld PRIVATE Qt6::Widgets)

set_target_properties(helloworld PROPERTIES
    WIN32_EXECUTABLE ON
    MACOSX_BUNDLE ON
)

이제 우리가 적용한 변경 사항을 하나씩 살펴보겠습니다.

find_package(Qt6 REQUIRED COMPONENTS Widgets)

find_package 호출에서 Core 을 Widgets 으로 대체합니다. 이렇게 하면 Qt6Widgets 모듈을 찾아내고, 나중에 링크할 Qt6::Widgets 타깃을 제공하게 됩니다.

qt_standard_project_setup()

CMAKE_AUTOMOC 외에도, qt_standard_project_setup() 은 CMAKE_AUTOUIC 변수를 ON 로 설정합니다. 이렇게 하면 .ui 소스 파일에 대해 Qt의 User Interface Compiler (uic) 를 호출하는 규칙이 자동으로 생성됩니다.

qt_add_executable(helloworld
    mainwindow.ui
    mainwindow.cpp
    main.cpp
)

다음 파일을 추가합니다. Qt Widgets Designer 파일(mainwindow.ui)과 이에 대응하는 C++ 소스 파일(mainwindow.cpp)을 애플리케이션 타깃의 소스 목록에 추가합니다.

target_link_libraries(helloworld PRIVATE Qt6::Widgets)

target_link_libraries 명령에서는 Qt6::Core 대신 Qt6::Widgets 에 대해 링크를 수행합니다. Qt6::Widgets 가 Qt6::Core 에 의존하므로, 애플리케이션은 여전히 에 대해 링크된다는 점에 유의하십시오.

set_target_properties(helloworld PROPERTIES
    WIN32_EXECUTABLE ON
    MACOSX_BUNDLE ON
)

마지막으로, 애플리케이션 타깃에 다음과 같은 효과를 주는 속성을 설정합니다:

• Windows에서 콘솔 창이 생성되지 않도록 방지합니다.
• macOS에서 애플리케이션 번들을 생성합니다.

이러한 타깃 속성에 대한 자세한 내용은 CMake 문서를 참조하십시오.

프로젝트 구조 구성

하나 이상의 타깃을 포함하는 프로젝트의 경우, 명확한 프로젝트 파일 구조를 갖추면 유용합니다. 여기서는 CMake의 하위 디렉터리 기능을 사용할 것입니다.

앞으로 더 많은 타깃을 추가하여 프로젝트를 확장할 계획이므로, 애플리케이션의 소스 파일을 하위 디렉터리로 이동하고 그 안에 새로운 ` CMakeLists.txt ` 파일을 생성합니다.

<project root>
├── CMakeLists.txt
└── src
    └── app
        ├── CMakeLists.txt
        ├── main.cpp
        ├── mainwindow.cpp
        ├── mainwindow.h
        └── mainwindow.ui

최상위 CMakeLists.txt 에는 전체 프로젝트 설정과 find_package 및 add_subdirectory 호출이 포함되어 있습니다:

cmake_minimum_required(VERSION 3.16)

project(helloworld VERSION 1.0.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(Qt6 REQUIRED COMPONENTS Widgets)
qt_standard_project_setup()

add_subdirectory(src/app)

이 파일에서 설정된 변수들은 하위 디렉터리의 프로젝트 파일에서도 확인할 수 있습니다.

애플리케이션의 프로젝트 파일인 src/app/CMakeLists.txt 에는 실행 파일 타깃이 포함되어 있습니다:

qt_add_executable(helloworld
    mainwindow.ui
    mainwindow.cpp
    main.cpp
)

target_link_libraries(helloworld PRIVATE Qt6::Widgets)

set_target_properties(helloworld PROPERTIES
    WIN32_EXECUTABLE ON
    MACOSX_BUNDLE ON
)

이러한 구조를 통해 라이브러리나 단위 테스트와 같은 추가 타깃을 프로젝트에 쉽게 추가할 수 있습니다.

라이브러리 빌드

프로젝트가 커짐에 따라, 애플리케이션 코드의 일부를 애플리케이션과 단위 테스트에서 사용할 수 있는 라이브러리로 분리하고 싶을 수 있습니다. 이 섹션에서는 이러한 라이브러리를 만드는 방법을 설명합니다.

현재 우리 애플리케이션은 ` main.cpp` 파일에 비즈니스 로직을 직접 포함하고 있습니다. 이전 섹션에서 설명한 대로, 이 코드를 ` "src/businesslogic" ` 하위 디렉터리에 ` businesslogic `라는 새로운 정적 라이브러리로 추출합니다.

간결함을 위해 이 라이브러리는 단 하나의 C++ 소스 파일과, 애플리케이션의 ` main.cpp`에서 포함되는 해당 헤더 파일로만 구성됩니다:

<project root>
├── CMakeLists.txt
└── src
    ├── app
    │   ├── ...
    │   └── main.cpp
    └── businesslogic
        ├── CMakeLists.txt
        ├── businesslogic.cpp
        └── businesslogic.h

이제 라이브러리의 프로젝트 파일(src/businesslogic/CMakeLists.txt)을 살펴보겠습니다.

qt_add_library(businesslogic STATIC
    businesslogic.cpp
)
target_link_libraries(businesslogic PRIVATE Qt6::Core)
target_include_directories(businesslogic INTERFACE ${CMAKE_CURRENT_SOURCE_DIR})

이제 내용을 하나씩 살펴보겠습니다.

qt_add_library(businesslogic STATIC
    businesslogic.cpp
)

add_library 명령어는 businesslogic 라이브러리를 생성합니다. 나중에 애플리케이션이 이 타깃에 링크되도록 할 것입니다.

STATIC 키워드는 정적 라이브러리를 나타냅니다. 공유 라이브러리나 동적 라이브러리를 생성하려면 SHARED 키워드를 사용합니다.

target_link_libraries(businesslogic PRIVATE Qt6::Core)

정적 라이브러리를 사용하므로 다른 라이브러리를 실제로 링크할 필요는 없습니다. 하지만 이 라이브러리가 QtCore 의 클래스를 사용하므로, Qt6::Core 에 대한 링크 종속성을 추가합니다. 이렇게 하면 필요한 QtCore 포함 경로와 전처리기 정의가 자동으로 포함됩니다.

target_include_directories(businesslogic INTERFACE ${CMAKE_CURRENT_SOURCE_DIR})

라이브러리 API는 헤더 파일 businesslogic/businesslogic.h 에 정의되어 있습니다. target_include_directories를 호출함으로써, businesslogic 디렉터리의 절대 경로가 우리 라이브러리를 사용하는 모든 타깃의 포함 경로로 자동으로 추가되도록 합니다.

이를 통해 main.cpp 파일에서 businesslogic.h 파일을 찾기 위해 상대 경로를 사용할 필요가 없어집니다. 대신 다음과 같이 작성하면 됩니다.

#include <businesslogic.h>

마지막으로, 라이브러리의 하위 디렉터리를 최상위 프로젝트 파일에 추가해야 합니다:

add_subdirectory(src/app)
add_subdirectory(src/businesslogic)

라이브러리 사용

이전 섹션에서 만든 라이브러리를 사용하려면, CMake가 해당 라이브러리와 링크되도록 지시합니다:

target_link_libraries(helloworld PRIVATE
    businesslogic
    Qt6::Widgets
)

이렇게 하면 main.cpp가 컴파일될 때 businesslogic.h 가 확실히 찾아집니다. 또한, businesslogic 정적 라이브러리는 helloworld 실행 파일의 일부가 됩니다.

CMake 용어로 말하자면, businesslogic 라이브러리는 이 라이브러리를 사용하는 모든 애플리케이션이 충족해야 하는 사용 요건 (포함 경로)을 지정합니다. target_link_libraries 명령어가 이를 처리합니다.

리소스 추가하기

애플리케이션에 몇 가지 이미지를 표시하고자 하므로, Qt 리소스 시스템을 사용하여 이미지를 추가합니다.

qt_add_resources(helloworld imageresources
    PREFIX "/images"
    FILES logo.png splashscreen.png
)

qt_add_resources() 명령어는 참조된 이미지를 포함하는 Qt 리소스를 자동으로 생성합니다. C++ 소스 코드에서는 지정된 리소스 접두사를 앞에 붙여 이미지에 접근할 수 있습니다:

logoLabel->setPixmap(QPixmap(":/images/logo.png"));

qt_add_resources() 명령은 첫 번째 인수로 변수 이름이나 타깃 이름 중 하나를 받습니다. 위 예제에서 보여준 것처럼, 이 명령의 타깃 기반 변형을 사용하는 것을 권장합니다.

번역 추가하기

Qt 프로젝트의 문자열 번역은 .ts 파일에 인코딩됩니다. 이러한 .ts 파일은 바이너리 .qm 파일로 컴파일되며, 이 파일들은 실행 시 Qt 애플리케이션에 의해 로드됩니다. 자세한 내용은 ‘Qt를 이용한 국제화’를 참조하십시오.

이 섹션에서는 helloworld 애플리케이션에 독일어 및 프랑스어 번역을 추가하는 방법을 설명합니다.

qt_standard_project_setup()을 사용하여 두 언어를 모두 지정합니다:

qt_standard_project_setup(I18N_TRANSLATED_LANGUAGES de fr)

그런 다음, .qm 파일을 불러올 대상에 대해 qt_add_translations()를 호출합니다:

qt_add_translations(helloworld)

첫 번째 구성 시, 이 명령어는 프로젝트의 소스 디렉터리에 helloworld_de.ts 및 helloworld_fr.ts 파일을 생성합니다. 이 파일들에는 번역된 문자열이 포함되며, 버전 관리 시스템에 포함되어야 합니다.

또한 이 명령어는 .ts 파일에서 .qm 파일을 자동으로 생성하는 빌드 시스템 규칙을 생성합니다. 기본적으로 .qm 파일은 리소스에 내장되며, "/i18n" 리소스 접두사를 통해 접근할 수 있습니다.

.ts 파일의 항목을 업데이트하려면 update_translations 타깃을 빌드하십시오:

$ cmake --build . --target update_translations

.qm 파일의 생성을 수동으로 트리거하려면 release_translations 타깃을 빌드하십시오:

$ cmake --build . --target release_translations

.ts 파일의 처리 방식 및 리소스에의 삽입을 조정하는 방법에 대한 자세한 내용은 qt_add_translations 문서를 참조하십시오.

qt_add_translations() 명령어는 편의성을 위해 제공되는 래퍼입니다. .ts 파일과 .qm 파일의 처리 방식을 더 세밀하게 제어하려면, 기본 명령어인 qt_add_lupdate() 와 qt_add_lrelease()를 사용하십시오.

추가 참고 자료

공식 CMake 문서는 CMake를 다루는 데 있어 매우 귀중한 자료입니다.

공식 CMake 튜토리얼 에서는 일반적인 빌드 시스템 작업들을 다룹니다.

『 Professional CMake: A Practical Guide 』라는 책은 가장 중요한 CMake 기능에 대한 훌륭한 입문서를 제공합니다.