Setup Protoc

What is protoc?

protoc is the compiler for Google's Protocol Buffers. Protocol buffers are Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data – think XML, but smaller, faster, and simpler.

Biblio back office uses protocol buffers to define it's messaging formats for gRPC capable API's. Instead of directly expressing the format and the API's in Go, the definitions are written in Proto, an IDL (Interface Definition Language) which allows you to describe API's in an abstract, language agnostic fashion. protoc will compile the proto definition into a target language: go, python, javascript, haskell, python,... A lot of heavy lifting is done for you.

Setting up protoc and it's associated plugins

// make sure you have the protoc compiler
$ PROTOC_ZIP=protoc-3.21.5-linux-x86_64.zip
$ curl -OL https://github.com/protocolbuffers/protobuf/releases/download/v3.14.0/$PROTOC_ZIP
$ sudo unzip -o $PROTOC_ZIP -d /usr/local bin/protoc
$ sudo unzip -o $PROTOC_ZIP -d /usr/local 'include/*'
$ rm -f $PROTOC_ZIP

// and install the go plugins with
$ go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
$ go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

// Compile proto code included in biblio-backend
$ cd <path-to-code>
$ protoc --go_out=. --go_opt=paths=source_relative --go-grpc_out=. --go-grpc_opt=paths=source_relative api/v1/<filename>.proto

If all went well, you should have two new files api/v1/<filename>.pb.go and api/v1/<filename_grpc>.pb.go containing freshly generated code.

Caveats

It's possible to install protoc via a package manager like brew, apt-get or dnf. However, the provided packages may not include the include/* directory which will be installed in /usr/local/include. This contains indispensable .proto files such as timestamp.proto. Your compiler (as well as your IDE) might complain about not finding these files. Fedora, at least, doesn't include these files in through the protoc-compiler package.

If you hit errors: try installing protoc manually per the instructions above.