qt_add_protobuf

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

이 명령은 Qt 6.5에 도입되었습니다.

qt_add_protobuf를 사용하여 CMake 스크립트에서 qtprotobufgen 을 호출하고 프로젝트의 .proto 스키마에서 코드를 생성합니다.qtprotobufgen 은 qt_add_protobuf 명령을 사용하여 CMake를 통해 호출됩니다.

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>]
)

그런 다음 qtprotobufgen 에서 생성된 소스 파일이 대상에 추가됩니다. 타깃이 이미 존재하는 경우 생성된 파일이 타깃 소스 목록에 추가됩니다. 타깃이 존재하지 않으면 링크해야 하는 라이브러리로 생성됩니다.

인수

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

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

• QML 는 protobuf 정의에서 QML 호환 메시지 유형을 생성하고 이를 QML 모듈로 등록할 수 있도록 합니다. 존재하지 않는 대상 또는 QML 모듈이 아닌 대상에서 qt_add_protobuf 을 호출하면 암시적으로 새 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
      ...
  )

  대상이 기존 QML 모듈인 경우 qt_add_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 를 정의해야 하며, 이는 임포트 문에서 해당 프로토뷰 유형을 QML에 노출하는 데 사용됩니다.

  qt_add_protobuf(target
      QML
      QML_URI proto.uri.example
  )

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

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

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

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

  URI 에 대한 자세한 내용은 식별된 모듈을 참조하세요.

• OUTPUT_DIRECTORY 는 생성된 파일이 저장될 디렉터리를 정의합니다. 기본적으로 현재 빌드 디렉터리가 사용됩니다.
• GENERATE_PACKAGE_SUBFOLDERS 는 .proto 파일의 패키지 이름 지정자를 사용하여 생성된 파일의 폴더 구조를 만듭니다. 예를 들어 패키지가 다음과 같이 정의된 경우 package io.qt.test 로 정의된 경우 생성된 파일은 출력 디렉토리/io/qt/test/에 배치됩니다.
• COPY_COMMENTS 는 .proto 파일의 주석을 생성된 코드에 복사합니다.
• EXPORT_MACRO <대상>에서 새 공유 라이브러리를 생성할 때만 적용됩니다 . 이 옵션은 생성된 코드에 사용되는 내보내기 매크로의 기본 이름을 지정합니다. 최종 매크로 이름은 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

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

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)

위의 예에서는 PROTO_FILES 옵션에 전달된 경로에 정의된 메시지 유형이 포함된 MyMessages 라는 라이브러리를 생성합니다. GENERATE_PACKAGE_SUBFOLDERS 옵션은 생성된 파일에 대한 폴더 구조를 생성합니다. 그리고 PROTO_INCLUDES 옵션은 지정된 디렉터리에서 종속성 또는 임포트를 찾도록 protoc에 지시합니다. MyApp 라는 실행 파일의 대상을 만들고 MyMessages 라이브러리에 링크합니다.

QML 확장 프로토뷰 예제

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 호출을 통해 PROTO_FILES 옵션에 전달된 경로에 정의된 메시지 유형이 포함된 MyMessagesPlugin 이라는 QML 모듈을 생성합니다. QML 컨텍스트에서 프로토 메시지 유형을 등록할 수 있는 QML 옵션을 사용합니다. 등록된 유형은 QML_URI 에서 설정한 경로를 가져와 QML 에서 사용할 수 있습니다. 두 번째 qt_add_protobuf 호출을 통해 자동 생성된 코드를 기존 MyApp QML 모듈에 추가합니다. 이 경우 QML_URI 은 필요하지 않습니다. 마지막으로 그래픽 부분에 대한 QML 모듈이 있는 MyApp 이라는 실행 파일의 대상을 만들고 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)