qt_add_protobuf

protobuf 스키마를 사용하여 Qt 기반 C++ 소스 코드를 생성합니다.

이 명령어는 Qt6 패키지의 Protobuf 구성 요소에 정의되어 있습니다. 다음 명령어로 패키지를 불러오십시오:

find_package(Qt6 REQUIRED COMPONENTS Protobuf)

이 명령어는 Qt 6.5에서 도입되었습니다.

CMake 스크립트에서 `qt_add_protobuf`를 사용하여 ` qtprotobufgen `를 호출하고, 프로젝트의 .proto 스키마로부터 코드를 생성할 수 있습니다. `qtprotobufgen `는 CMake에서 ` qt_add_protobuf ` 명령어를 통해 호출됩니다.

구문

qt_add_protobuf(<target>
    PROTO_FILES <file> ...
    [PROTO_INCLUDES <path> ...]
    [QML [QML_URI <uri>]]
    [OUTPUT_DIRECTORY <dir>]
    [GENERATE_PACKAGE_SUBFOLDERS]
    [COPY_COMMENTS]
    [EXPORT_MACRO <infix>]
    [OUTPUT_HEADERS <var>]
    [OUTPUT_TARGETS <var>]
    [HEADER_GUARD <pragma|filename>]
    [GENERATE_NON_FINAL_MESSAGES] # since Qt 6.11
    [GENERATE_NON_FINAL_PROPERTIES] # since Qt 6.12
)

버전 정보가 없는 명령어가 비활성화된 경우, 대신 qt6_add_protobuf() 를 사용하십시오. 이 명령어는 본 명령어와 동일한 인자 세트를 지원합니다.

설명

qtprotobufgen 에 의해 생성된 소스 파일은 대상(target)에 추가됩니다. 대상이 이미 존재하는 경우, 생성된 파일은 대상의 소스 목록에 추가됩니다. 대상이 존재하지 않는 경우, 링크해야 하는 라이브러리로 생성됩니다.

• PROTO_FILES 코드 생성 절차에서 사용되는 .proto 파일 목록을 지정합니다.
• PROTO_INCLUDES protobuf 종속성을 검색할 디렉터리 목록을 지정합니다.

  참고: PROTO_FILES 의위치는 암묵적으로 protobuf 포함 경로의 일부로 간주됩니다.

• QML protobuf 정의로부터 QML 호환 메시지 유형을 생성하고 이를 QML 모듈로 등록합니다. qt_add_protobuf 가 존재하지 않는 대상이나 QML 모듈이 아닌 대상에 대해 호출될 경우, 새로운 QML 모듈이 암시적으로 생성됩니다.

  find_package(Qt6 6.8 REQUIRED COMPONENTS Quick Protobuf ProtobufQuick)
  ...
  qt_add_executable(target
      ...
  )
  // creates a new QML module
  qt_add_protobuf(target
      QML
      ...
  )

  target이 기존 QML 모듈인 경우, qt_add_protobuf 는 생성된 protobuf 유형을 해당 모듈에 연결합니다.

  find_package(Qt6 6.8 REQUIRED COMPONENTS Quick Protobuf ProtobufQuick)
  ...
  qt_add_qml_module(target
      ...
  )
  // adds to existing QML module
  qt_add_protobuf(target
      QML
      ...
  )

  참고: QML 인수를 사용하는경우 , find_package 호출에 ProtobufQuick을 추가해야 합니다. 위의 예제를 참조하십시오.

• QML_URI QML 모듈에 사용되는 URI 를 정의합니다.

  모든 QML 모듈은 URI 를 정의해야 하며, 이는 import 문에서 해당 모듈의 protobuf 타입을 QML에 노출하는 데 사용됩니다.

  qt_add_protobuf(target
      QML
      QML_URI proto.uri.example
  )

  QML_URI 가 생략되면, protobuf 패키지 이름이 모듈의 URI 으로 사용됩니다.

  참고: ` QML_URI `를 생략한경우 , ` PROTO_FILES ` 섹션에 지정된 모든 `.proto ` 파일은 동일한 protobuf 패키지 이름을 공유해야 합니다. 이는 결과 QML 모듈의 기본 ` URI `로 사용되기 때문입니다.

  참고: 동일한 QML_URI 또는 proto 패키지 이름을 가진 여러 개의 protobuf QML 모듈을 생성하는 것은 QML 컨텍스트에서 가져오기 오류를 유발할 수 있으므로 피해야합니다 .

  참고: QML_URI 가 qt_add_protobuf 함수에 전달되었으나 대상 모듈이 이미 존재하는경우 , QML_URI 인수는 무시됩니다.

  URI 에 대한 더 자세한 내용은 ‘식별된 모듈(Identified Modules )’을 참조하십시오.

• OUTPUT_DIRECTORY 생성된 파일이 저장될 디렉터리를 정의합니다. 기본적으로 현재 빌드 디렉터리가 사용됩니다.
• GENERATE_PACKAGE_SUBFOLDERS .proto 파일의 패키지 이름 지정자를 사용하여 생성된 파일의 폴더 구조를 만듭니다. 예를 들어, 패키지가 로 정의된 경우, 생성된 파일은 OUTPUT_DIRECTORY/io/qt/test/에 배치됩니다 package io.qt.test.
• COPY_COMMENTS .proto 파일의 주석을 생성된 코드로 복사합니다.
• EXPORT_MACRO <target>에서 새로운 공유 라이브러리를 생성할 때만 적용됩니다. 이 옵션은 생성된 코드에서 사용되는 export 매크로의 기본 이름을 지정합니다. 최종 매크로 이름은 QPB_<EXPORT_MACRO>_EXPORT 형식으로 구성됩니다. 이 옵션이 설정되지 않은 경우, 대상 이름이 EXPORT_MACRO 형식으로 사용됩니다.

  더 자세한 내용은 ‘공유 라이브러리 생성 ’을 참조하십시오.

• OUTPUT_HEADERS 생성된 헤더 목록을 저장할 변수를 지정합니다. 이 목록은 사용자 정의 프로젝트 설치 규칙을 정의하는 데 유용할 수 있습니다.
• OUTPUT_TARGETS 생성된 타깃 목록을 저장할 변수를 지정합니다. 이 목록은 사용자 정의 프로젝트 설치 규칙을 정의하는 데 유용할 수 있습니다.
• HEADER_GUARD 생성된 헤더 파일이 중복으로 포함되는 것을 방지하는 데 사용되는 메커니즘을 지정합니다. 가능한 값은 pragma, filename 입니다. 기본값은 filename 입니다. 이 옵션을 pragma 로 설정하면 현대식 프래그마 헤더 가드가 생성됩니다:

  #pragma once
  ...

  이 옵션을 생략하거나 filename 로 설정하면 ifdef 래핑 가드가 생성되며, '.proto' 파일 이름이 가드 접미사로 사용됩니다:

  #ifdef MYMESSAGES_QPB_H
  #define MYMESSAGES_QPB_H
  ...
  #endif // MYMESSAGES_QPB_H

  프로젝트 구조에 따라 선호하는 가드 스타일을 선택하십시오.

• GENERATE_NON_FINAL_MESSAGES (Qt 6.11부터) final 지정자 없이 QtProtobuf 메시지 클래스를 생성합니다. 이 옵션은 하위 호환성을 위해 제공됩니다. Qt 6.11부터 QtProtobuf 메시지 클래스는 기본적으로 final 로 생성됩니다. 생성된 메시지의 동작을 확장하려면 상속보다는 구성(composition)을 우선적으로 사용하십시오. 이 옵션은 Qt 7에서 제거될 예정입니다.
• GENERATE_NON_FINAL_PROPERTIES (Qt 6.12부터) ` FINAL ` 지정자 없이 ` QtProtobuf ` 메시지 클래스의 속성을 생성합니다. FINAL 지정자는 QML 툴링이 성능 최적화를 적용하고 더 효율적인 코드를 생성할 수 있도록 합니다. Qt 6.12부터 QtProtobuf 메시지 속성은 기본적으로 FINAL 지정자와 함께 생성됩니다. 이 옵션은 하위 호환성을 위해 제공되는 것으로, Qt 7에서 제거될 예정입니다. FINAL 지정자에 대한 자세한 내용은 Qt 속성 시스템을 참조하십시오.

protobuf 대상 간의 종속성 해결

qt_add_protobuf 명령어는 서로 다른 타깃에 대한 코드 생성에 사용되는 .proto 파일 간의 종속성을 고려하지 않습니다.

프로젝트에는 상호 의존성을 가진 두 개 이상의 .proto 파일이 있을 수 있습니다:

// test_messages.proto
syntax = "proto3";

package test.messages;

message MyMessage {
    int32 myField = 1;
}

// test_extensions.proto
syntax = "proto3";

import "test_messages.proto";

package test.extensions;

message MyExtension {
    test.messages.MyMessage baseMessage = 1;
    int32 extension = 2;
}

위의 .proto 파일들은 독립형 라이브러리를 생성하는 데 사용될 수 있습니다:

qt_add_protobuf(test_messages
    PROTO_FILES
        test_messages.proto
)
...
qt_add_protobuf(test_extensions
    PROTO_FILES
        test_extensions.proto
)
...

test_extensions 타깃은 test_messages 타깃의 메시지에 의존하므로, CMake 스크립트에서 해당 타깃들을 수동으로 링크해야 합니다:

target_link_libraries(test_extensions PUBLIC test_messages)

예시

qt_add_protobuf 사용

cmake_minimum_required(VERSION 3.16...3.22)
project(MyThings)

find_package(Qt6 REQUIRED COMPONENTS Protobuf)
qt_standard_project_setup()

qt_add_protobuf(MyMessages
    GENERATE_PACKAGE_SUBFOLDERS
    PROTO_FILES
        path/to/message.proto
        path/to/other_message.proto
    PROTO_INCLUDES
        /path/to/proto/include
)

qt_add_executable(MyApp main.cpp)

target_link_libraries(MyApp PRIVATE MyMessages)

위의 예제에서는 MyMessages 라는 라이브러리를 생성하며, 이 라이브러리에는 PROTO_FILES 옵션에 전달된 경로에 정의된 메시지 유형이 포함됩니다. GENERATE_PACKAGE_SUBFOLDERS 옵션은 생성된 파일을 위한 폴더 구조를 생성합니다. 또한 PROTO_INCLUDES 옵션은 protoc가 지정된 디렉터리에서 종속성이나 임포트를 검색하도록 지시합니다. MyApp 라는 실행 파일용 타깃을 생성하고, 이를 MyMessages 라이브러리에 링크합니다.

QML 확장 protobuf 예제

cmake_minimum_required(VERSION 3.16...3.22)
project(MyThings)

find_package(Qt6 REQUIRED COMPONENTS Protobuf ProtobufQuick Quick)
qt_standard_project_setup()

qt_add_protobuf(MyMessagesPlugin
    QML
    QML_URI my.messages.module.uri
    PROTO_FILES
        path/to/message.proto
        path/to/other_message.proto
    PROTO_INCLUDES
        /path/to/proto/include
)

qt_add_protobuf(MyApp
    QML
    PROTO_FILES
        path/to/internal_message.proto
    PROTO_INCLUDES
        /path/to/proto/include
)

qt_add_qml_module(MyApp
    URI example.uri
    VERSION 1.0
    QML_FILES qml/main.qml
)

qt_add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE Quick)

위의 QML 확장 예제에서, 첫 번째 qt_add_protobuf 호출을 통해 MyMessagesPlugin 라는 QML 모듈을 생성하며, 이 모듈에는 PROTO_FILES 옵션에 전달된 경로에 정의된 메시지 유형들이 포함됩니다. 우리는 QML 옵션을 사용하여 QML 컨텍스트에서 proto 메시지 유형 등록을 활성화합니다. 등록된 유형은 QML_URI 에서 설정된 경로를 가져옴으로써 QML 에서 사용할 수 있게 됩니다. 두 번째 qt_add_protobuf 호출을 통해 기존 MyApp QML 모듈에 자동 생성된 코드를 추가합니다. 이러한 경우에는 QML_URI 가 필요하지 않습니다. 마지막으로, MyApp 라는 실행 파일을 위한 타깃을 생성합니다. 이 실행 파일은 그래픽 부분을 담당하는 QML 모듈을 포함하고 있으며, my.messages.module.uri 임포트를 통해 MyMessagesPlugin 를 main.qml 파일에 불러옵니다.

Qt Protobuf 라이브러리 독립형 설치

qt_add_protobuf 명령어는 추가 설치를 위한 아티팩트 목록도 생성합니다. 다음과 같이 OUTPUT_HEADERS 및 OUTPUT_TARGETS 인수를 지정하여 이러한 아티팩트 목록을 확인할 수 있습니다:

qt_add_protobuf(MyProtoLib
    PROTO_FILES
        mylib.proto
    OUTPUT_HEADERS
        public_headers
    OUTPUT_TARGETS
        generated_targets
)

이 명령어는 qt_add_protobuf 명령어로 생성된 헤더 파일 및 타깃 목록을 각각 public_headers 및 generated_targets 변수에 저장합니다.

표준 CMake install 명령어를 사용하여 아티팩트를 설치하고 라이브러리에 대한 config 파일을 생성하십시오:

include(GNUInstallDirs)
set_target_properties(MyProtoLib PROPERTIES
    PUBLIC_HEADER
        "${public_headers}"
    INTERFACE_INCLUDE_DIRECTORIES
        "$<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_INCLUDEDIR}>"
)
install(TARGETS ${generated_targets} EXPORT MyProtoLibTargets
    PUBLIC_HEADER
        DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
)
install(EXPORT MyProtoLibTargets NAMESPACE MyProtoLib:: DESTINATION lib/cmake/MyProtoLib)

그런 다음 패키지 구성 파일에서 생성된 MyProtoLibTargets 구성을 사용하십시오. 패키지 생성 과정에 대한 자세한 내용은 공식 CMake 문서에서 확인할 수 있습니다.

설치가 완료되면 라이브러리를 독립형 CMake 패키지로 사용할 수 있습니다:

find_package(Qt6 COMPONENTS Protobuf)
find_package(MyProtoLib CONFIG)

add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE MyProtoLib::MyProtoLib Qt6::Protobuf)