qt_add_protobuf

Erzeugt Qt-basierten C++-Quellcode unter Verwendung eines Protobuf-Schemas

Dieser Befehl wurde in Qt 6.5 eingeführt.

Verwenden Sie qt_add_protobuf, um qtprotobufgen in Ihren CMake-Skripten aufzurufen und den Code aus den .proto-Schemata für Ihre Projekte zu generieren.qtprotobufgen würde durch CMake mit dem Befehl qt_add_protobuf aufgerufen werden.

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

Die von qtprotobufgen erzeugten Quelldateien werden dann zum Ziel hinzugefügt. Wenn das Ziel bereits existiert, werden die generierten Dateien zur Liste der Zielquellen hinzugefügt. Wenn das Ziel nicht existiert, wird es als Bibliothek erstellt, mit der Sie linken müssen.

Argumente

• PROTO_FILES gibt die Liste der .proto-Dateien an, die von der Code-Generierungsprozedur verwendet werden.
• PROTO_INCLUDES gibt die Liste der Verzeichnisse an, die nach Protobuf-Abhängigkeiten durchsucht werden sollen.

  Hinweis: Der Speicherort von PROTO_FILES wird implizit als Teil des protobuf-Include-Pfads betrachtet.

• QML ermöglicht die Erzeugung von QML-kompatiblen Nachrichtentypen aus Protobuf-Definitionen und registriert sie als QML-Modul. Wenn qt_add_protobuf für ein nicht existierendes Ziel oder ein Ziel, das kein QML-Modul ist, aufgerufen wird, wird implizit ein neues QML-Modul erstellt.

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

  Wenn das Ziel ein bestehendes QML-Modul ist, fügt qt_add_protobuf die generierten Protobuf-Typen diesem Modul zu.

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

  Hinweis: Wenn Sie das QML-Argument verwenden, müssen Sie ProtobufQuick in den find_package-Aufruf aufnehmen. Siehe Beispiele oben.

• QML_URI definiert die URI, die für das QML-Modul verwendet wird.

  Jedes QML-Modul muss ein URI definieren, das in Import-Anweisungen verwendet wird, um seine Protobuf-Typen für QML freizugeben.

  qt_add_protobuf(target
      QML
      QML_URI proto.uri.example
  )

  Wenn QML_URI weggelassen wird, wird der Name des protobuf-Pakets als URI des Moduls verwendet.

  Hinweis: Wenn QML_URI weggelassen wird, müssen alle im Abschnitt PROTO_FILES angegebenen .proto-Dateien denselben protobuf-Paketnamen haben, da dieser als Standard URI für das resultierende QML-Modul verwendet wird.

  Hinweis: Es sollte vermieden werden, mehrere protobuf QML-Module mit demselben QML_URI oder proto-Paketnamen zu erstellen, da dies zu Importfehlern im QML-Kontext führt.

  Hinweis: Wenn QML_URI an die Funktion qt_add_protobuf übergeben wird, das Ziel aber bereits existiert, wird das Argument QML_URI ignoriert.

  Lesen Sie Identifizierte Module für eine weitergehende Diskussion der URI.

• OUTPUT_DIRECTORY definiert das Verzeichnis, in dem die generierten Dateien abgelegt werden. Standardmäßig wird das aktuelle Build-Verzeichnis verwendet.
• GENERATE_PACKAGE_SUBFOLDERS verwendet die Paketnamensangabe aus den .proto Dateien, um die Ordnerstruktur für die generierten Dateien zu erstellen. Wenn das Paket zum Beispiel definiert ist als: package io.qt.test werden die generierten Dateien in OUTPUT_DIRECTORY/io/qt/test/ abgelegt.
• COPY_COMMENTS kopiert Kommentare aus den .proto Dateien in den generierten Code.
• EXPORT_MACRO gilt nur für die Erstellung einer neuen Shared Library aus <target>. Diese Option gibt den Basisnamen für das im generierten Code verwendete Exportmakro an. Der endgültige Makroname wird wie QPB_<EXPORT_MACRO>_EXPORT aufgebaut. Wenn diese Option nicht gesetzt ist, wird der Zielname EXPORT_MACRO verwendet.

  Weitere ausführliche Informationen finden Sie unter Gemeinsame Bibliotheken erstellen.

• OUTPUT_HEADERS gibt eine Variable an, in der die Liste der generierten Header gespeichert wird. Diese Liste kann für die Definition von benutzerdefinierten Projektinstallationsregeln nützlich sein.
• OUTPUT_TARGETS gibt eine Variable an, in der die Liste der generierten Targets gespeichert wird. Diese Liste kann für die Definition von benutzerdefinierten Projektinstallationsregeln nützlich sein.
• HEADER_GUARD spezifiziert den Mechanismus, der verwendet wird, um generierte Header-Dateien vor mehrfacher Einbindung zu schützen. Mögliche Werte sind pragma, filename. Der Standardwert ist filename. Wenn Sie die Option auf pragma setzen, wird das moderne pragma header guard erzeugt:

  #pragma once
  ...

  Das Weglassen der Option oder das Setzen der Option auf filename erzeugt den ifdef Wrapping Guard und verwendet den '.proto' Dateinamen als Guard-Infix:

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

  Wählen Sie den bevorzugten Guard-Stil entsprechend Ihrer Projektstruktur.

Auflösen von Abhängigkeiten zwischen protobuf-Zielen

Der Befehl qt_add_protobuf berücksichtigt nicht die Abhängigkeiten zwischen .proto Dateien, die verwendet werden, um Code für verschiedene Ziele zu erzeugen.

Das Projekt kann zwei oder mehr .proto Dateien mit Abhängigkeiten haben:

// 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;
}

Die oben genannten .proto Dateien können verwendet werden, um die Standalone-Bibliotheken zu generieren:

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

Da das test_extensions -Ziel von Nachrichten aus dem test_messages -Ziel abhängt, müssen Sie in Ihren CMake -Skripten manuell auf diese Ziele verlinken:

target_link_libraries(test_extensions PUBLIC test_messages)

Beispiel

Verwendung von 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)

Im obigen Beispiel wird eine Bibliothek mit dem Namen MyMessages erzeugt, die die Nachrichtentypen enthält, die in den mit der Option PROTO_FILES übergebenen Pfaden definiert sind. Die Option GENERATE_PACKAGE_SUBFOLDERS generiert eine Ordnerstruktur für die erzeugten Dateien. Und die Option PROTO_INCLUDES weist protoc an, in den angegebenen Verzeichnissen nach Abhängigkeiten oder Importen zu suchen. Wir erstellen ein Ziel für eine ausführbare Datei namens MyApp, die wir mit der Bibliothek MyMessages verknüpfen.

QML erweitertes protobuf Beispiel

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)

Im obigen erweiterten QML-Beispiel wird durch den ersten Aufruf von qt_add_protobuf ein QML-Modul mit der Bezeichnung MyMessagesPlugin erzeugt, das die in den an die Option PROTO_FILES übergebenen Pfaden definierten Nachrichtentypen enthält. Wir verwenden die Option QML, die die Registrierung von Proto-Nachrichtentypen im Kontext QML ermöglicht. Die registrierten Typen stehen in QML zur Verfügung, indem ein Pfad importiert wird, der mit QML_URI festgelegt wurde. Mit dem zweiten Aufruf von qt_add_protobuf fügen wir automatisch generierten Code in das bestehende MyApp QML-Modul ein. Die QML_URI ist in solchen Fällen nicht erforderlich. Schließlich erstellen wir ein Ziel für eine ausführbare Datei namens MyApp, die ein QML-Modul für den grafischen Teil enthält und MyMessagesPlugin über den my.messages.module.uri -Import in die Datei main.qml lädt.

Installation der eigenständigen Bibliothek Qt Protobuf

Der Befehl qt_add_protobuf erzeugt auch Listen von Artefakten für die weitere Installation. Sie können diese Artefakte lesen, indem Sie die Argumente OUTPUT_HEADERS, und OUTPUT_TARGETS wie folgt angeben:

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

Der Befehl speichert die Liste der Header-Dateien und Targets, die durch den Befehl qt_add_protobuf erzeugt wurden, in den Variablen public_headers und generated_targets.

Verwenden Sie den Standard CMake install Befehl, um die Artefakte zu installieren und die config Dateien für Ihre Bibliothek zu erzeugen:

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)

Verwenden Sie dann die generierte MyProtoLibTargets config in der Paketkonfigurationsdatei. Sie können mehr über den Prozess der Paketerstellung in der offiziellen CMake-Dokumentation lesen.

Nach der Installation ist die Bibliothek als eigenständiges CMake-Paket verfügbar:

find_package(Qt6 COMPONENTS Protobuf)
find_package(MyProtoLib CONFIG)

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