Protocol Buffers Deployment & Usage Guide

1. Prerequisites

System Requirements

Operating System: Linux, macOS, or Windows
C++ Compiler (if building from source): GCC 7+, Clang 5+, or MSVC 2017+
Build System: CMake 3.10+ or Bazel 6.0+ (Bazel 8+ recommended for Bzlmod)
Git: For cloning source code
Abseil C++: Required dependency when building from source (automatically fetched by Bazel or CMake)

Language-Specific Requirements

Java: JDK 8+ and Maven/Gradle
Python: Python 3.8+ and pip
C#: .NET Core SDK or Visual Studio
Go: Go 1.18+ (separate repository: protobuf-go)

2. Installation

Option A: Pre-built Binaries (Recommended for Non-C++ Users)

Download platform-specific binaries from GitHub Releases:

# Linux/macOS example (replace VERSION and PLATFORM)
wget https://github.com/protocolbuffers/protobuf/releases/download/vVERSION/protoc-VERSION-linux-x86_64.zip
unzip protoc-VERSION-linux-x86_64.zip -d /usr/local
export PATH=$PATH:/usr/local/bin

# Verify installation
protoc --version

Package Contents: protoc binary + standard .proto files (google/protobuf/*.proto)

Option B: Build from Source (C++ Users & Contributors)

# Clone repository (pin to release tag for stability)
git clone https://github.com/protocolbuffers/protobuf.git
cd protobuf
git checkout v29.0  # Replace with desired release tag

# CMake build (recommended)
cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/usr/local \
  -Dprotobuf_BUILD_TESTS=OFF \
  -Dprotobuf_ABSL_PROVIDER=module

cmake --build build --parallel 8
sudo cmake --build build --target install

# Or Bazel build
bazel build :protoc :protobuf

Note: See src/README.md for detailed C++ build instructions and dependency management.

Option C: Package Managers

# macOS
brew install protobuf

# Ubuntu/Debian
sudo apt-get install -y protobuf-compiler libprotobuf-dev

# Alpine Linux
apk add protoc protobuf-dev

3. Configuration

Environment Variables

# Add protoc to PATH (if using pre-built binaries)
export PATH=$PATH:/usr/local/protobuf/bin

# Library path for C++ runtime (Linux/macOS)
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH  # Linux
export DYLD_LIBRARY_PATH=/usr/local/lib:$DYLD_LIBRARY_PATH  # macOS

Bazel Integration (Bzlmod - Bazel 8+)

Add to your MODULE.bazel:

bazel_dep(name = "protobuf", version = "29.0")

For backward compatibility with WORKSPACE naming:

bazel_dep(name = "protobuf", version = "29.0", repo_name = "com_google_protobuf")

Bazel Integration (Legacy WORKSPACE)

Add to WORKSPACE:

http_archive(
    name = "com_google_protobuf",
    strip_prefix = "protobuf-29.0",
    sha256 = "HASH",
    url = "https://github.com/protocolbuffers/protobuf/releases/download/v29.0/protobuf-29.0.tar.gz",
)

load("@com_google_protobuf//:protobuf_deps.bzl", "protobuf_deps")
protobuf_deps()

# Java support (30.x+)
load("@rules_java//java:rules_java_deps.bzl", "rules_java_dependencies")
rules_java_dependencies()
load("@rules_java//java:repositories.bzl", "rules_java_toolchains")
rules_java_toolchains()

# Python support (30.x+)
load("@rules_python//python:repositories.bzl", "py_repositories")
py_repositories()

4. Build & Run

Compiling .proto Files

C++ Example:

# Generate C++ source files
protoc --cpp_out=./src --proto_path=./protos mymessage.proto

# Compile with your project
g++ -std=c++17 myapp.cpp mymessage.pb.cc -lprotobuf -labsl_log_internal_message -o myapp

Multi-language Example:

# Generate for multiple languages simultaneously
protoc --cpp_out=./cpp --java_out=./java --python_out=./python \
  --proto_path=./protos mymessage.proto

Running Examples

# Navigate to examples directory
cd examples

# Compile example
protoc --cpp_out=. addressbook.proto

# Build C++ example
make cpp  # or manually compile add_person.cc list_people.cc

# Run
./add_person addressbook.data
./list_people addressbook.data

Testing Your Build

If building from source with tests enabled:

# CMake
cmake -S . -B build -Dprotobuf_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build --parallel 8

# Bazel
bazel test :all

5. Deployment

CI/CD Integration

GitHub Actions:

- name: Install Protobuf
  run: |
    wget https://github.com/protocolbuffers/protobuf/releases/download/v29.0/protoc-29.0-linux-x86_64.zip
    unzip protoc-29.0-linux-x86_64.zip -d $HOME/.local
    echo "$HOME/.local/bin" >> $GITHUB_PATH

Docker:

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y protobuf-compiler libprotobuf-dev
COPY . /app
WORKDIR /app
RUN protoc --cpp_out=. *.proto

Library Distribution

Static Linking (Recommended for deployment):

Link against libprotobuf.a (CMake: -Dprotobuf_BUILD_SHARED_LIBS=OFF)
No runtime dependencies on target system

Shared Libraries:

Ensure libprotobuf.so is installed on target systems
Version compatibility required between protoc and runtime library

Version Pinning Strategy

For production stability:

Pin to specific release tags (e.g., v29.0) not main branch
Use release branches for critical fixes (29.x branch)
Match protoc version with runtime library version exactly

6. Troubleshooting

Common Build Issues

Error: ABSL not found or absl/log/log.h: No such file

Solution: Install Abseil or use -Dprotobuf_ABSL_PROVIDER=module to fetch automatically
Bazel users: Ensure protobuf_deps() is called in WORKSPACE

Error: protoc: error while loading shared libraries: libprotobuf.so.XX

Solution:

sudo ldconfig  # Linux
# Or set LD_LIBRARY_PATH to installation lib directory

Error: This file was generated by a newer version of protoc

Solution: Regenerate .pb.cc and .pb.h files with the current protoc version
```
protoc --cpp_out=. --proto_path=. myfile.proto
```

Bazel-Specific Issues

Error: rules_java or rules_python not found (30.x+)

Solution: Add the additional load statements shown in Configuration section above

Error: Bzlmod compatibility

Solution: Use Bazel 8+ for Bzlmod support, or disable with --enable_bzlmod=false

Version Compatibility

Protoc Version	C++ Runtime	Java Runtime	Notes
29.x	29.x	4.29.x	Must match major version
28.x	28.x	4.28.x	Breaking changes in 29.0

Check versions:

protoc --version  # libprotoc 29.0
# Compare with runtime library version in your application

Getting Help

Documentation: https://protobuf.dev
Examples: See examples/ directory in repository
Issues: https://github.com/protocolbuffers/protobuf/issues
Language-Specific Issues: Check respective language directories (java/, python/, etc.)

How to Deploy & Use google/protobuf