|
@@ -3,6 +3,7 @@
|
|
|
gRPC and Protobuf generator and bindings for Qt framework
|
|
|
> see [Protobuf](https://developers.google.com/protocol-buffers) and [gRPC](https://grpc.io/) for more information
|
|
|
|
|
|
+
|
|
|
### Test results
|
|
|
|
|
|
| Branch | Results |
|
|
@@ -10,6 +11,7 @@ gRPC and Protobuf generator and bindings for Qt framework
|
|
|
| [master](https://github.com/semlanik/qtprotobuf/tree/master) |  |
|
|
|
| [0.1.0](https://github.com/semlanik/qtprotobuf/tree/0.1.0) |  |
|
|
|
|
|
|
+
|
|
|
# Table of contents
|
|
|
|
|
|
[API Reference](https://semlanik.github.io/qtprotobuf)
|
|
@@ -20,29 +22,39 @@ gRPC and Protobuf generator and bindings for Qt framework
|
|
|
|
|
|
[Usage](#usage)
|
|
|
|
|
|
-[CMake functions reference](#cmake-functions-reference)
|
|
|
+[Integration with CMake project](#integration-with-cmake-project)
|
|
|
+
|
|
|
+[Integration with qmake project](#integration-with-qmake-project)
|
|
|
|
|
|
-[qmake integration](#qmake-integration)
|
|
|
+[Generated and QtProtobuf types registation](#generated-and-qtprotobuf-types-registation)
|
|
|
|
|
|
-[Running tests](#running-tests)
|
|
|
+[Code exceptions](#code-exceptions)
|
|
|
|
|
|
+[QtProtobuf development](#qtprotobuf-development)
|
|
|
+
|
|
|
+
|
|
|
+# Linux Build
|
|
|
+## Prerequesties
|
|
|
|
|
|
-## Linux Build
|
|
|
-### Prerequesties
|
|
|
Check installation of following packages in your system:
|
|
|
- protobuf 3.6.0 or higher
|
|
|
- grpc 1.15.0 or higher
|
|
|
- golang 1.10 or higher (Mandatory dependency for any type of build)
|
|
|
|
|
|
-**Note:** Older versions could be supported as well but not officially tested.
|
|
|
+>**Note:** Older versions could be supported as well but not officially tested.
|
|
|
+
|
|
|
+
|
|
|
+### For Ubuntu
|
|
|
|
|
|
-#### For Ubuntu
|
|
|
Install GRPC packages in system:
|
|
|
|
|
|
```bash
|
|
|
sudo apt-get install libgrpc++-dev protobuf-compiler-grpc libgrpc++1 libgrpc-dev libgrpc6
|
|
|
```
|
|
|
-#### All-in-one build
|
|
|
+
|
|
|
+
|
|
|
+### All-in-one build
|
|
|
+
|
|
|
If required versions of libraries are not found in your system, you may use all-in-one build procedure for prerequesties
|
|
|
|
|
|
Update submodules to fetch 3rdparty dependencies:
|
|
@@ -50,22 +62,19 @@ Update submodules to fetch 3rdparty dependencies:
|
|
|
```bash
|
|
|
git submodule update --init --recursive
|
|
|
```
|
|
|
-### Build
|
|
|
+
|
|
|
+
|
|
|
+## Build
|
|
|
```bash
|
|
|
mkdir build
|
|
|
cd build
|
|
|
-
|
|
|
-#In case Qt installed in system, use:
|
|
|
-cmake ..
|
|
|
-
|
|
|
-#In case you have Qt installed from qt installer, use:
|
|
|
-cmake .. -DCMAKE_PREFIX_PATH="<path/to/qt/installation>/Qt<qt_version>/<qt_version>/gcc_64/lib/cmake"
|
|
|
-
|
|
|
+cmake .. [-DCMAKE_PREFIX_PATH="<path/to/qt/installation>/Qt<qt_version>/<qt_version>/gcc_64/lib/cmake"]
|
|
|
cmake --build . [--config <RELEASE|DEBUG>] -- -j<N>
|
|
|
```
|
|
|
|
|
|
-## Windows Build
|
|
|
-### Prerequesties
|
|
|
+
|
|
|
+# Windows Build
|
|
|
+## Prerequesties
|
|
|
|
|
|
Download and install:
|
|
|
|
|
@@ -76,7 +85,7 @@ Download and install:
|
|
|
- Yasm 1.3 or higher [5](http://yasm.tortall.net/Download.html)
|
|
|
- Actual Visual Studio Compiler with cmake support that required by Qt [6](https://visualstudio.microsoft.com/downloads/)
|
|
|
|
|
|
-**Note:** All applications should be in PATH
|
|
|
+>**Note:** All applications should be in PATH
|
|
|
|
|
|
Update submodules to fetch 3rdparty dependencies:
|
|
|
|
|
@@ -84,7 +93,7 @@ Update submodules to fetch 3rdparty dependencies:
|
|
|
git submodule update --init --recursive
|
|
|
```
|
|
|
|
|
|
-### Build
|
|
|
+## Build
|
|
|
Open Qt MSVC command line and follow steps:
|
|
|
|
|
|
```bash
|
|
@@ -96,15 +105,14 @@ cmake ..
|
|
|
cmake --build . [--config <RELEASE|DEBUG>] -- /m:<N>
|
|
|
```
|
|
|
|
|
|
-## Usage
|
|
|
+# Usage
|
|
|
+## Direct usage of generator
|
|
|
|
|
|
-### Direct usage of generator
|
|
|
-
|
|
|
```bash
|
|
|
[QT_PROTOBUF_OPTIONS="[SINGLE|MULTI]:QML:COMMENTS"] protoc --plugin=protoc-gen-qtprotobuf=<path/to/bin/>qtprotobufgen --qtprotobuf_out=<output_dir> [-I/extra/proto/include/path] <protofile>.proto
|
|
|
```
|
|
|
|
|
|
-**QT_PROTOBUF_OPTIONS**
|
|
|
+### QT_PROTOBUF_OPTIONS
|
|
|
|
|
|
For protoc command you also may specify extra options using QT_PROTOBUF_OPTIONS environment variable and colon-separated format:
|
|
|
|
|
@@ -116,18 +124,17 @@ Following options are supported:
|
|
|
|
|
|
*SINGLE* - enables single-file generation when for each *.proto* file single pair of *.h* *.cpp* files is generated
|
|
|
|
|
|
-**Note:** Enabled by default. Excluded by SINGLE
|
|
|
+>**Note:** Enabled by default. Excluded by SINGLE
|
|
|
|
|
|
*MULTI* - enables multi-file generation when for each message separate pair of *.h* *.cpp*
|
|
|
|
|
|
-**Note:** Has higher priority than SINGLE
|
|
|
+>**Note:** Has higher priority than SINGLE
|
|
|
|
|
|
*QML* - enables QML code generation in protobuf classes. If is set QML-related code for lists and QML registration to be generated.
|
|
|
|
|
|
*COMMENTS* - enables comments copying from .proto files
|
|
|
|
|
|
-
|
|
|
-### Integration with project
|
|
|
+## Integration with CMake project
|
|
|
|
|
|
You can integrate QtProtobuf as submodule in your project or as installed in system package. Add following line in your project CMakeLists.txt:
|
|
|
|
|
@@ -135,86 +142,43 @@ You can integrate QtProtobuf as submodule in your project or as installed in sys
|
|
|
...
|
|
|
find_package(QtProtobufProject CONFIG REQUIRED COMPONENTS QtProtobuf QtGrpc)
|
|
|
file(GLOB PROTO_FILES ABSOLUTE ${CMAKE_CURRENT_SOURCE_DIR}/path/to/protofile1.proto
|
|
|
- ${CMAKE_CURRENT_SOURCE_DIR}/path/to/protofile2.proto
|
|
|
- ...
|
|
|
- ${CMAKE_CURRENT_SOURCE_DIR}/path/to/protofileN.proto)
|
|
|
+ ${CMAKE_CURRENT_SOURCE_DIR}/path/to/protofile2.proto
|
|
|
+ ...
|
|
|
+ ${CMAKE_CURRENT_SOURCE_DIR}/path/to/protofileN.proto)
|
|
|
# Function below generates source files for specified PROTO_FILES,
|
|
|
# and link them to the MyTarget as static library
|
|
|
add_executable(MyTarget main.cpp) # Add your target here
|
|
|
qtprotobuf_generate(TARGET MyTarget
|
|
|
- OUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/generated
|
|
|
- PROTO_FILES ${PROTO_FILES})
|
|
|
+OUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/generated
|
|
|
+PROTO_FILES ${PROTO_FILES})
|
|
|
|
|
|
```
|
|
|
|
|
|
-**Optional:**
|
|
|
-
|
|
|
-You also may pre-specify expected generated headers to prevent dummy-parser mistakes
|
|
|
+Another option is to pre-specify expected generated headers to prevent dummy-parser mistakes
|
|
|
|
|
|
```cmake
|
|
|
...
|
|
|
set(GENERATED_HEADERS
|
|
|
- # List of artifacts expected after qtprotobufgen job done.
|
|
|
- # Usually it's full list of messages in all packages with .h header suffix
|
|
|
- ...
|
|
|
- )
|
|
|
-...
|
|
|
-qtprotobuf_generate(TARGET MyTarget
|
|
|
- OUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/generated
|
|
|
- PROTO_FILES ${PROTO_FILES}
|
|
|
- GENERATED_HEADERS ${GENERATED_HEADERS})
|
|
|
-...
|
|
|
-```
|
|
|
-
|
|
|
-#### Usage
|
|
|
-
|
|
|
-To enable QtProtobuf project you need to register protobuf types. It's good practice to make it in 'main' function.
|
|
|
-
|
|
|
-```cpp
|
|
|
+# List of artifacts expected after qtprotobufgen job done.
|
|
|
+# Usually it's full list of messages in all packages with .h header suffix
|
|
|
...
|
|
|
-#include <QtProtobufTypes>
|
|
|
-...
|
|
|
-int main(int argc, char *argv[])
|
|
|
-{
|
|
|
- QtProtobuf::qRegisterProtobufTypes();
|
|
|
- ... //Qt application initialization and run
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-### Code exceptions
|
|
|
-
|
|
|
-If any prohibited Qt/QML keyword is used as field name, generator appends '*Proto*' suffix to generated filed name. It's required to omit overloading for example QML reserved names like '*id*' or '*objectName*'.
|
|
|
-
|
|
|
-E.g. for message:
|
|
|
-```
|
|
|
-message MessageReserved {
|
|
|
- sint32 import = 1;
|
|
|
- sint32 property = 2;
|
|
|
- sint32 id = 3;
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-Following properties will be generated:
|
|
|
-```cpp
|
|
|
+)
|
|
|
...
|
|
|
- Q_PROPERTY(QtProtobuf::sint32 importProto READ importProto WRITE setImport NOTIFY importProtoChanged)
|
|
|
- Q_PROPERTY(QtProtobuf::sint32 propertyProto READ propertyProto WRITE setProperty NOTIFY propertyProtoChanged)
|
|
|
- Q_PROPERTY(QtProtobuf::sint32 idProto READ idProto WRITE setId NOTIFY idProtoChanged)
|
|
|
+qtprotobuf_generate(TARGET MyTarget
|
|
|
+OUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/generated
|
|
|
+PROTO_FILES ${PROTO_FILES}
|
|
|
+GENERATED_HEADERS ${GENERATED_HEADERS})
|
|
|
...
|
|
|
-
|
|
|
```
|
|
|
|
|
|
-**Note:** List of exceptions might be extended in future releases.
|
|
|
-
|
|
|
-## CMake functions reference
|
|
|
-
|
|
|
-### qtprotobuf_generate
|
|
|
+### CMake functions reference
|
|
|
+#### qtprotobuf_generate
|
|
|
|
|
|
qtprotobuf_generate is cmake helper function that automatically generates STATIC library target from your .proto files
|
|
|
|
|
|
Due to cmake restrictions it's required to specify resulting artifacts manually as list of header files expected after generator job finished.
|
|
|
|
|
|
-**Parameters:**
|
|
|
+***Parameters:***
|
|
|
|
|
|
*TARGET* - name of you target that generated code archive will be linked to
|
|
|
|
|
@@ -228,50 +192,50 @@ Due to cmake restrictions it's required to specify resulting artifacts manually
|
|
|
|
|
|
*PROTO_FILES* - List of .proto files that will be used in generation procedure
|
|
|
|
|
|
-**Options:**
|
|
|
+***Options:***
|
|
|
|
|
|
*MULTI* - Enables multi-files generation mode. If provided in parameter list generator will create pair of header/source files for each message
|
|
|
|
|
|
-**Note:** multi-files generation mode is defined as deprecated by QtProtobuf team, and might have poor support in future
|
|
|
+>**Note:** multi-files generation mode is defined as deprecated by QtProtobuf team, and might have poor support in future
|
|
|
|
|
|
*QML* - Enables QML code generation in protobuf classes. If provided in parameter list QML related code for lists and QML registration to be generated.
|
|
|
|
|
|
*COMMENTS* - Enables comments copying from .proto files. If provided in parameter list message and field related comments will be copied to generated header files.
|
|
|
|
|
|
-### qtprotobuf_link_archive
|
|
|
+#### qtprotobuf_link_archive
|
|
|
|
|
|
qtprotobuf_link_archive is cmake helper function that links whole archive to your library or executable target. It's useful when you try to link generated target to shared library or/and to executable that doesn't utilize all protobuf generated classes directly from C++ code, but requires them from QML.
|
|
|
|
|
|
-**Parameters:**
|
|
|
+***Parameters:***
|
|
|
|
|
|
*TARGET* - name of target to link to
|
|
|
|
|
|
*GENERATED_TARGET* - protobuf generated target name
|
|
|
|
|
|
+#### Usefull definitions
|
|
|
|
|
|
-### Usefull definitions
|
|
|
+*QT_PROTOBUF_MAKE_COVERAGE* - if **TRUE/ON** for QtProtobuf project build, QtProtobuf will be built with gcov intergration, to collect code coverage reports(usefull for developers). **FALSE** by default
|
|
|
|
|
|
-*QTPROTOBUF_MAKE_COVERAGE* - if **TRUE/ON** for QtProtobuf project build, QtProtobuf will be built with gcov intergration, to collect code coverage reports(usefull for developers). **FALSE** by default
|
|
|
+*QT_PROTOBUF_MAKE_TESTS* - if **TRUE/ON** for QtProtobuf project build, tests for QtProtobuf will be built. **TRUE** by default
|
|
|
|
|
|
-*QTPROTOBUF_MAKE_TESTS* - if **TRUE/ON** for QtProtobuf project build, tests for QtProtobuf will be built. **TRUE** by default
|
|
|
-
|
|
|
-*QTPROTOBUF_MAKE_EXAMPLES* - if **TRUE/ON** for QtProtobuf project build, built-in examples will be built. **TRUE** by default
|
|
|
+*QT_PROTOBUF_MAKE_EXAMPLES* - if **TRUE/ON** for QtProtobuf project build, built-in examples will be built. **TRUE** by default
|
|
|
|
|
|
*QT_PROTOBUF_STATIC* - if **TRUE/ON** for QtProtobuf project build, static libraries will be produced for all QtProtobuf targets except qml plugin. **FALSE** by default
|
|
|
|
|
|
-*QTPROTOBUF_EXECUTABLE* - contains full path to QtProtobuf generator add_executable
|
|
|
+*QT_PROTOBUF_EXECUTABLE* - contains full path to QtProtobuf generator add_executable
|
|
|
|
|
|
-## qmake integration
|
|
|
+## Integration with qmake project
|
|
|
|
|
|
-**Note:** Available in QtProtobuf version >=0.2.0
|
|
|
+>**Note:** Available in QtProtobuf version >=0.2.0
|
|
|
|
|
|
QtProtobuf has limited qmake build procedures support. It's only available and tested on linux platforms. To use it in your qmake project, first you need build and install QtProtobuf as standalone project in your system paths:
|
|
|
|
|
|
```bash
|
|
|
mkdir build
|
|
|
cd build
|
|
|
-cmake .. [-DCMAKE_PREFIX_PATH="<path/to/qt/installation>/Qt<qt_version>/<qt_version>/gcc_64/lib/cmake"] -DCMAKE_INSTALL_PREFIX=/usr -DQTPROTOBUF_MAKE_TESTS=OFF -DQTPROTOBUF_MAKE_EXAMPLES=OFF
|
|
|
-sudo cmake --build . [--config <RELEASE|DEBUG>] -- -j<N> install
|
|
|
+cmake .. [-DCMAKE_PREFIX_PATH="<path/to/qt/installation>/Qt<qt_version>/<qt_version>/gcc_64/lib/cmake"] -DCMAKE_INSTALL_PREFIX=/usr -DQT_PROTOBUF_MAKE_TESTS=OFF -DQT_PROTOBUF_MAKE_EXAMPLES=OFF
|
|
|
+cmake --build . [--config <RELEASE|DEBUG>] -- -j<N>
|
|
|
+sudo cmake --build . [--config <RELEASE|DEBUG>] --target install
|
|
|
```
|
|
|
|
|
|
Commands above will install qt protobuf into you system paths prefixed with */usr* folder.
|
|
@@ -284,32 +248,86 @@ QT += grpc #for grpc libraries support
|
|
|
```
|
|
|
To generate source code and link it to you project use predefined *qtprotobuf_generate* function
|
|
|
|
|
|
-### qtprotobuf_generate([generate_qml=false])
|
|
|
+### CMake functions reference
|
|
|
+#### qtprotobuf_generate([generate_qml=false])
|
|
|
|
|
|
qtprotobuf_generate is qmake helper [test function](https://doc.qt.io/qt-5/qmake-language.html#test-functions) that generates QtProtobuf source code based on files provided by PROTO_FILES global context variable
|
|
|
|
|
|
-**Parameters:**
|
|
|
+***Parameters:***
|
|
|
|
|
|
*generate_qml* - Enables/disables QML code generation in protobuf classes. If set to `true` QML-related code for lists and QML registration to be generated.
|
|
|
|
|
|
|
|
|
-**Note:** see examples/qmakeexample for details
|
|
|
+>**Note:** see examples/qmakeexample for details
|
|
|
+
|
|
|
+## Generated and QtProtobuf types registation
|
|
|
+
|
|
|
+To enable QtProtobuf project you need to register protobuf types. It's good practice to make it in 'main' function.
|
|
|
+
|
|
|
+```cpp
|
|
|
+...
|
|
|
+#include <QtProtobufTypes>
|
|
|
+...
|
|
|
+int main(int argc, char *argv[])
|
|
|
+{
|
|
|
+QtProtobuf::qRegisterProtobufTypes();
|
|
|
+... //Qt application initialization and run
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## Code exceptions
|
|
|
+
|
|
|
+If any prohibited Qt/QML keyword is used as field name, generator appends '*Proto*' suffix to generated filed name. It's required to omit overloading for example QML reserved names like '*id*' or '*objectName*'.
|
|
|
+
|
|
|
+E.g. for message:
|
|
|
+```
|
|
|
+message MessageReserved {
|
|
|
+sint32 import = 1;
|
|
|
+sint32 property = 2;
|
|
|
+sint32 id = 3;
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+Following properties will be generated:
|
|
|
+```cpp
|
|
|
+...
|
|
|
+Q_PROPERTY(QtProtobuf::sint32 importProto READ importProto WRITE setImport NOTIFY importProtoChanged)
|
|
|
+Q_PROPERTY(QtProtobuf::sint32 propertyProto READ propertyProto WRITE setProperty NOTIFY propertyProtoChanged)
|
|
|
+Q_PROPERTY(QtProtobuf::sint32 idProto READ idProto WRITE setId NOTIFY idProtoChanged)
|
|
|
+...
|
|
|
+
|
|
|
+```
|
|
|
|
|
|
+>**Note:** List of exceptions might be extended in future releases.
|
|
|
+
|
|
|
+# QtProtobuf development
|
|
|
## Running tests
|
|
|
+
|
|
|
```bash
|
|
|
cd <build directory>
|
|
|
ctest
|
|
|
```
|
|
|
+
|
|
|
## Documentation generation
|
|
|
|
|
|
Project uses doxygen for documentation generation.
|
|
|
|
|
|
-#### For Windows additionally install:
|
|
|
+### Ubuntu
|
|
|
+
|
|
|
+Install doxygen and graphviz packages:
|
|
|
+```
|
|
|
+sudo apt-get install -y doxygen graphviz
|
|
|
+```
|
|
|
+
|
|
|
+### Windows
|
|
|
+
|
|
|
+Install doxygen and graphviz packages:
|
|
|
* [doxygen](http://www.doxygen.nl/download.html)
|
|
|
* [graphviz](https://graphviz.gitlab.io/_pages/Download/Download_windows.html)
|
|
|
|
|
|
+### Generation
|
|
|
|
|
|
-You can generate documentation:
|
|
|
+You can generate documentation for actual version using following commands:
|
|
|
|
|
|
```bash
|
|
|
mkdir build
|