Generating source code
When working on your project you write your proto files defining the message structure. Next, you would like to use them in your source code. This requires you to generate the code based on the definitions you have written. As of version 4.0.0 there are two ways to do this. The embeddedproto command does everything for you. Alternatively, you call protoc yourself with our plugin, as in earlier versions.
The embeddedproto command
The command comes with the package and runs the protobuf compiler that was installed along with it. Use the following command to generate the code:
embeddedproto -I LOCATION/PROTO/FILES --eams_out=GENERATED/SRC/DIR PROTO_MESSAGE_FILE.protoThe option -I includes the folder where your *.proto files are located. The option --eams_out specifies the location where to store the generated source code. Finally, a specific proto file is set to be parsed. These are the standard options of protoc. Every other option of protoc is accepted as well and passed on unchanged.
Behind the scenes the command adds three things to the protoc call: the plugin, the folder with the Embedded Proto custom options file and the folder with the well known types of Google. You do not have to specify these yourself.
When you installed Embedded Proto as a submodule, the command lives in the virtual environment of the submodule:
./EmbeddedProto/venv/bin/embeddedproto -I LOCATION/PROTO/FILES --eams_out=GENERATED/SRC/DIR PROTO_MESSAGE_FILE.protoUsing your own protoc
Do you already have protoc in your toolchain, for instance to generate the code for the other side of the communication line? Then you can instruct it to use our plugin with the --plugin option. The plugin is an executable called protoc-gen-eams. With a pip install it is in the same folder as the embeddedproto command, which is on your path when the virtual environment is active.
On Linux:
protoc --plugin=protoc-gen-eams -I LOCATION/PROTO/FILES --eams_out=GENERATED/SRC/DIR PROTO_MESSAGE_FILE.protoOn Windows:
protoc --plugin=protoc-gen-eams=protoc-gen-eams.exe -I LOCATION\PROTO\FILES --eams_out=GENERATED\SRC\DIR PROTO_MESSAGE_FILE.protoWhen using the submodule, two small scripts in the root of the submodule start the plugin from its virtual environment. Point the --plugin option at protoc-gen-eams on Linux, or protoc-gen-eams.bat on Windows.
Please note that protoc does not know where to find the Embedded Proto custom options file. When your proto files import embedded_proto_options.proto, add the folder of the EmbeddedProto Python package with an additional -I. Inside the submodule this is the EmbeddedProto folder.
The generated code
After running protoc without any errors the generated source code is located in the folder specified by --eams_out. Each proto file becomes one header, reading.proto becomes reading.h. The extension can be changed in the options file. This folder is to be included in your project. This is not the only folder to be included. The generated source files depend on the headers and source files of the Embedded Proto library. Where to find them and how to add them to your toolchain is described on the installation page.
Please note that when your project is linked with a C compiler, as many embedded toolchains do, you have to pass -lstdc++ to the linker. Without it the linker reports errors like undefined reference to on the generated code.
Each generated file records the version of the plugin which made it. When you compile it against a library of a different major version, the compiler stops with the error Major version mismatch between generated code and library. A different minor version gives a warning. In both cases, regenerate the code with the plugin matching your library.
Would you like to set the size of your fields without editing the proto file? Read about the options file. Various examples of how to use and integrate Embedded Proto in your project are given in the Examples section.
