# 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 security and maintainability reasons.**

# Usage

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

    implementation("com.google.protobuf4:1.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`.**

**`.proto` files must contain the line `option optimize_for = LITE_RUNTIME;`.**

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

Even though Protobuf4 takes more ROM and RAM than the older Protobuf3 library, **it is still highly recommended to favor
Protobuf4 over Protobuf3 for 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        | 43.5KB                                         |                 88.9KB (+104%)                  |
| Implementation | 43.9KB                                         |                  31.1KB (-29%)                  |
| Total          | 87.4KB                                         |                  120.0KB(+37%)                  |

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

One can notice that the library footprint of Protobuf4 is much larger than the footprint of Protobuf3, but that the
generated code is lighter.
For projects that use Protobuf extensively, the difference between Protobuf3 and Protobuf4 will reduce, as the
proportion of generated code compared to the core library becomes more significant, thereby balancing the overall
footprint.

### 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 (+21%)                   |
| Maximum |                     8.6KB                      |                  15.1KB (+76%)                  |

These RAM footprints were measured across a dozen different tests.

# 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._