qt_add_protobuf

Erzeugt Qt-basierten C++-Quellcode anhand eines Protobuf-Schemas.

Der Befehl ist in der Protobuf-Komponente des Qt6-Pakets definiert. Laden Sie das Paket mit:

find_package(Qt6 REQUIRED COMPONENTS Protobuf)

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`-Schemas für Ihre Projekte zu generieren. `qtprotobufgen ` würde über CMake mit dem Befehl ` qt_add_protobuf ` aufgerufen werden.

Übersicht

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
)

Wenn versionlose Befehle deaktiviert sind, verwenden Sie stattdessen „ qt6_add_protobuf() “. Dieser Befehl unterstützt dieselben Argumente wie der vorgenannte Befehl.

Beschreibung

Die von qtprotobufgen generierten Quelldateien werden anschließend dem Ziel hinzugefügt. Wenn das Ziel bereits existiert, werden die generierten Dateien zur Quelldateiliste des Ziels hinzugefügt. Wenn das Ziel nicht existiert, wird es als Bibliothek erstellt, die Sie einbinden müssen.

• PROTO_FILES Gibt die Liste der .proto-Dateien an, die bei der Codegenerierung verwendet werden.
• PROTO_INCLUDES Gibt die Liste der Verzeichnisse an, in denen nach Protobuf-Abhängigkeiten gesucht werden soll.

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

• QML Aktiviert die Generierung von QML-kompatiblen Nachrichtentypen aus Protobuf-Definitionen und registriert diese als QML-Modul. Wird ` qt_add_protobuf ` für ein nicht vorhandenes Ziel oder ein Ziel aufgerufen, das kein QML-Modul ist, 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
      ...
  )

  Ist „target“ ein bereits vorhandenes QML-Modul, fügt „ qt_add_protobuf “ die generierten Protobuf-Typen diesem Modul hinzu.

  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 Aufruf von `find_package` einfügen. Siehe Beispiele oben.

• QML_URI definiert das für das QML-Modul verwendete „ URI “.

  Jedes QML-Modul muss ein „ URI “ definieren, das in Import-Anweisungen verwendet wird, um seine Protobuf-Typen für QML verfügbar zu machen.

  qt_add_protobuf(target
      QML
      QML_URI proto.uri.example
  )

  Wird ` QML_URI ` weggelassen, wird der Protobuf-Paketname als ` URI` des Moduls verwendet.

  Hinweis: Wird der „ QML_URI “ weggelassen, müssen alle im Abschnitt „ PROTO_FILES “ angegebenen .proto-Dateien denselben Protobuf-Paketnamen tragen, da dieser als Standard-„ URI “ für das resultierende QML-Modul verwendet wird.

  Hinweis: Sie sollten es vermeiden, 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 jedoch bereits existiert, wird das Argument „ QML_URI “ ignoriert.

  Lesen Sie den Abschnitt „Identifizierte Module“, um weitere detaillierte Informationen zum „ URI “ zu erhalten.

• OUTPUT_DIRECTORY definiert das Verzeichnis, in dem die generierten Dateien abgelegt werden. Standardmäßig wird das aktuelle Build-Verzeichnis verwendet.
• GENERATE_PACKAGE_SUBFOLDERS Verwendet den Paketnamen aus den „ .proto “-Dateien, um die Ordnerstruktur für die generierten Dateien zu erstellen. Wenn das Paket beispielsweise als „ package io.qt.test “ definiert ist, 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 beim Erstellen einer neuen gemeinsam genutzten Bibliothek aus dem <target>. Diese Option legt den Basisnamen für das im generierten Code verwendete Export-Makro fest. Der endgültige Makroname wird als „ QPB_<EXPORT_MACRO>_EXPORT “ gebildet. Wenn diese Option nicht gesetzt ist, wird der Zielname als „ EXPORT_MACRO “ verwendet.

  Weitere ausführliche Informationen finden Sie unter „Erstellen von gemeinsam genutzten Bibliotheken “.

• OUTPUT_HEADERS Gibt eine Variable an, in der die Liste der generierten Header gespeichert wird. Diese Liste kann für die Definition benutzerdefinierter Projektinstallationsregeln nützlich sein.
• OUTPUT_TARGETS Legt eine Variable fest, in der die Liste der generierten Ziele gespeichert wird. Diese Liste kann für die Definition benutzerdefinierter Projektinstallationsregeln nützlich sein.
• HEADER_GUARD Legt den Mechanismus fest, der verwendet wird, um generierte Header-Dateien vor mehrfacher Einbindung zu schützen. Mögliche Werte sind „ pragma “ und „ filename “. Der Standardwert ist „ filename “. Wenn die Option auf „ pragma “ gesetzt wird, wird der moderne Pragma-Header-Guard generiert:

  #pragma once
  ...

  Wird die Option weggelassen oder auf „ filename “ gesetzt, wird der „ ifdef “-Wrapping-Guard generiert und der Dateiname „.proto“ als Guard-Infix verwendet:

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

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

• GENERATE_NON_FINAL_MESSAGES (seit Qt 6.11) generiert „ QtProtobuf “-Meldungsklassen ohne den Spezifizierer „ final “. Diese Option dient der Abwärtskompatibilität. Seit Qt 6.11 werden „ QtProtobuf “-Meldungsklassen standardmäßig als „ final “ generiert. Um das Verhalten generierter Meldungen zu erweitern, sollten Sie Komposition gegenüber Vererbung bevorzugen. Diese Option wird in Qt 7 entfernt.
• GENERATE_NON_FINAL_PROPERTIES (seit Qt 6.12) generiert Eigenschaften von „ QtProtobuf “-Nachrichtenklassen ohne den Spezifizierer „ FINAL “. Der Spezifizierer „ FINAL “ ermöglicht es den QML-Tools, Leistungsoptimierungen anzuwenden und effizienteren Code zu generieren. Seit Qt 6.12 werden QtProtobuf -Nachrichten-Eigenschaften standardmäßig mit dem Spezifizierer „ FINAL “ generiert. Diese Option dient ausschließlich der Abwärtskompatibilität und wird in Qt 7 entfernt. Weitere Informationen zum Spezifizierer „ FINAL “ finden Sie unter Qt Property System.

Auflösen von Abhängigkeiten zwischen Protobuf-Zielen

Der Befehl „ qt_add_protobuf “ berücksichtigt keine Abhängigkeiten zwischen „ .proto “-Dateien, die zur Codegenerierung für verschiedene Ziele verwendet werden.

Das Projekt kann zwei oder mehr „ .proto “-Dateien mit Abhängigkeiten enthalten:

// 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 zur Generierung der eigenständigen Bibliotheken verwendet werden:

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

Da das Ziel „ test_extensions “ von Meldungen des Ziels „ test_messages “ abhängt, müssen Sie in Ihren „ CMake “-Skripten manuell Verweise auf diese Ziele einfügen:

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 generieren wir eine Bibliothek namens „ MyMessages “, die die Nachrichtentypen enthält, die in den an die Option „ PROTO_FILES “ übergebenen Pfaden definiert sind. Die Option „ GENERATE_PACKAGE_SUBFOLDERS “ dient dazu, eine Ordnerstruktur für die generierten Dateien zu erstellen. 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.

Erweitertes QML-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 generieren wir durch den ersten Aufruf von ` qt_add_protobuf ` ein QML-Modul namens „ MyMessagesPlugin “, das die Nachrichtentypen enthält, die in den an die Option ` PROTO_FILES ` übergebenen Pfaden definiert sind. Wir verwenden die Option „ QML “, die die Registrierung von Proto-Nachrichtentypen im Kontext von „ QML “ ermöglicht. Die registrierten Typen stehen unter „ QML “ zur Verfügung, indem ein Pfad importiert wird, der durch „ QML_URI “ festgelegt wird. Mit dem zweiten Aufruf von „ qt_add_protobuf “ fügen wir automatisch generierten Code in das bestehende QML-Modul „ MyApp “ ein. „ QML_URI “ ist in solchen Fällen nicht erforderlich. Abschließend erstellen wir ein Ziel für eine ausführbare Datei namens „ MyApp “, die über ein QML-Modul für den grafischen Teil verfügt und „ MyMessagesPlugin “ über den Import „ my.messages.module.uri “ in die Datei „main.qml“ lädt.

Installation der eigenständigen „ Qt Protobuf “-Bibliothek

Der Befehl ` qt_add_protobuf ` erzeugt außerdem Listen mit Artefakten für die weitere Installation. Sie können diese Artefakte einsehen, 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 vom Befehl „ qt_add_protobuf “ erzeugten Header-Dateien und Ziele entsprechend in den Variablen „ public_headers “ und „ generated_targets “.

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

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 anschließend die generierte „ MyProtoLibTargets “-Konfiguration in der Paketkonfigurationsdatei. Weitere Informationen zum Prozess der Paketerstellung finden Sie in der offiziellen CMake-Dokumentation.

Nach der Installation steht die Bibliothek als eigenständiges CMake-Paket zur Verfügung:

find_package(Qt6 COMPONENTS Protobuf)
find_package(MyProtoLib CONFIG)

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