# Overview

MicroEJ Add-On Library: `Protobuf4`.

This library implements the Lite version of Google's Protocol Buffer library for Java.
It supports Java files generated by `.proto` files compiled
with [protoc 4.33.5](https://repo.maven.apache.org/maven2/com/google/protobuf/protoc/4.33.5/).

**This library should be favored over the older `Protobuf3` library for performance, security and maintainability reasons.**

# Usage

Add the following line to your `build.gradle.kts`:

    implementation("com.google:protobuf4:2.0.0")

Compile your `.proto` files with the following command line, depending on your OS:

- Windows: `protoc --plugin=protoc-gen-microej=.\tools\protoc-gen-microej.bat --microej_out=<output_dir> <input_file>`
- Linux / MacOS:
  `protoc --plugin=protoc-gen-microej=./tools/protoc-gen-microej.py --microej_out=<output_dir> <input_file>`

**The `protoc-gen-microej` must be used to generate MicroEJ-compatible Java classes.**
It is available in the `tools.zip` archive within the library package.

**You must use version `4.33.5` of `protoc`.**

## Generator options

Pass an option to the generator with `--microej_opt`:

    protoc --plugin=protoc-gen-microej=./tools/protoc-gen-microej.py \
           --microej_out=<output_dir> \
           --microej_opt=package_name=com.example.model \
           <input_file>

| Option | Default | Effect |
| --- | --- | --- |
| `package_name` | none | Sets the Java package of every generated class, overriding the `java_package` option of the `.proto` file. |

If this library is exposed as Kernel API, the `ProtobufKernel.initialize()` method should be called by the Kernel before
a Feature calls one of the Protobuf APIs.

# Footprints

**It is highly recommended to favor Protobuf4 over Protobuf3 for performance, security and maintainability reasons**.

### ROM Footprint

|                | Protobuf3<br/>(based on Google Protobuf 3.7.1) | Protobuf4<br/>(based on Google Protobuf 4.33.5) |
|----------------|:-----------------------------------------------|:-----------------------------------------------:|
| Library        | 45.7KB                                         |                  47.0KB (+2.8%)                 |
| Implementation | 31.3KB                                         |                  10.2KB (-67%)                  |
| Total          | 77.1KB                                         |                  57.2KB (-26%)                  |

*The `Implementation` row refer to the protoc-generated code of a representative example.*

The ROM saving of Protobuf4 increases with the number of messages in the application, as the footprint of each
generated message is much smaller than with Protobuf3.

### RAM Footprint

|         | Protobuf3<br/>(based on Google Protobuf 3.7.1) | Protobuf4<br/>(based on Google Protobuf 4.33.5) |
|---------|:----------------------------------------------:|:-----------------------------------------------:|
| Minimum |                     2.4KB                      |                   2.5KB (+5%)                   |
| Average |                     4.4KB                      |                  5.3KB (+22%)                   |
| Maximum |                     8.6KB                      |                  11.6KB (+35%)                  |

These RAM footprints were measured over a set of representative scenarios.

# Requirements

This library requires the following Foundation Libraries:

- edc 1.3.7

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

This library has been forked and adapted
from [Google's Protobuf 4.33.5 library](https://github.com/protocolbuffers/protobuf/releases/tag/v4.33.5).

The version 4.33.5 of `protoc` can be
downloaded [here](https://repo.maven.apache.org/maven2/com/google/protobuf/protoc/4.33.5/).

# Restrictions

None.

---  
_Markdown_  
_Copyright 2020-2026 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._
_Build: 7E4D1F7C_
