Before being quick, you need to read this lame joke:
Why did the noodle get voted out by his friends? Because everyone thought he was the impasta.
Quick start using package management
Pre-compiled packages are available from the Gitlab Package Registry for the following programming languages:
- Kotlin (JVM)
Additionally, output is generated for Rust.
Go to the Gitlab Package Registry (Maven) and select
protosdc-model-java in a suitable version. Gitlab provides you with all information that is needed to include the library in your application.
protosdc-model-java comprises protobuf model classes and gRPC services.
Go to the Gitlab Package Registry (Maven) which offers you to pick from the following packages to start with your Kotlin application:
protosdc-model-kt: compiled protobuf classes and gRPC services
biceps-model-kt: Kotlin data class powered BICEPS model independent of protobuf
proto-kotlin-mapper: API to map between the protobuf and Kotlin model classes
Gitlab provides you with all information that is needed to include the libraries in your application.
Go to the Gitlab Package Registry (PyPI) and select
proto-model in a suitable version. Gitlab provides you with all information that is needed to include the library in your application.
proto-model comprises protobuf model classes and gRPC services.
proto-model is currently also being build for Rust, the resulting crates are not being deployed to a registry. Gitlab Package Registry currently lacks the support. This will change in the future by deploying the crates to the official package registry at crates.io. For now, it is recommended to utilize a git submodule for Rust projects integrating protoSDC. This provides the following crates:
protosdc-proto: contains the pre-generated protobuf and gRPC data, utilizing tonic and prost.
protosdc-biceps: Rust structs representing the BICEPS model for an indepentent internal representation of data
protosdc-mappers: API to map between the protobuf transport representation and the internal representation model
Quick start checking out the Proto Model project
This section describes the manual checkout and invocation of the Proto Model generation tool. Running the Proto Model tool manually should only be required if there is no pre-compiled package available that supports your preferred programming language.
If this is the case, please consider to contribute by adding your programming language to the Proto Model ecosystem. Contributing →
Building the proto model on Microsoft Windows is currently not officially supported as the build script makes use of symbolic links which cannot be processed properly by Windows. Solutions to enable the required support exist, but are outside of the scope of protoSDC.
Consider using the Windows Subsystem for Linux or installing a Virtual Machine and running a Unix-based operating system virtually to get Proto Model operating correctly. Proto Model on Windows has successfully been tested with Oracle VM Box and Manjaro. A tutorial is availabe at linuxhint.com.
Step-by-step model generation
1. Clone the repository
$ git clone https://gitlab.com/sdc-suite/proto-model.git
2. Run the Proto Converter
$ cd proto-model
$ ./gradlew executeConverter
This executes the Proto Converter with the BICEPS participant and message model as input. The Proto Converter creates the following output folders:
proto_out: includes BICEPS as protobuf message types
kotlin_out: includes BICEPS as Kotlin data classes
proto_kotlin_out: includes mapping between protobuf and Kotlin data classes
rust_out: includes BICEPS as Rust structs
proto_rust_out: includes mapping between protobuf and Rust structs
3. Run protoc
After the model conversion has been performed, the folder
proto includes the full protoSDC model consisting of
- the BICEPS participant and message model as protobuf message types (via a symbolic link),
- discovery and metadata protobuf message types, and
- BICEPS, discovery, and metadata service definitions.
It is now ready to be compiled with
protoc. For example, you can compile to Java by running
$ cd proto
$ mkdir java_classes
$ protoc --java_out=./java_classes \
$(find -L . -iname "*.proto")
This generates protobuf Java classes into
java_classes. In order to generate gRPC Java classes into the same folder, first make sure you have the gRPC plugin for protoc in place. The following call then starts the code generation:
$ protoc --plugin=protoc-gen-grpc-java=/path/to/grpc-java-executable \
$(find -L . -iname "*.proto")