• Stars
    star
    1,749
  • Rank 26,614 (Top 0.6 %)
  • Language
    Groovy
  • License
    Other
  • Created over 9 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Protobuf Plugin for Gradle

Please read release notes before upgrading the plugin, as usage or compatibility requirements may change.

Protobuf Plugin for Gradle

The Gradle plugin that compiles Protocol Buffer (aka. Protobuf) definition files (*.proto) in your project. There are two pieces of its job:

  1. It assembles the Protobuf Compiler (protoc) command line and uses it to generate Java source files out of your proto files.
  2. It adds the generated Java source files to the input of the corresponding Java compilation unit (sourceSet in a Java project; variant in an Android project), so that they can be compiled along with your Java sources.
    • Note if you are generating non-Java/Kotlin source files, they will not be included for compilation automatically, you will need to add them to sources for language-specific compilations. See details in Default options section.

For more information about the Protobuf Compiler, please refer to Google Developers Site.

Latest Version

The latest version is 0.9.4. It requires at least Gradle 5.6 and Java 8. To use it with Groovy DSL:

plugins {
  id "com.google.protobuf" version "0.9.4"
}

Development Version

To try out the head version, you can download the source and build it with ./gradlew publishToMavenLocal -x test (we skip tests here because they require Android SDK), then in settings.gradle:

pluginManagement {
  repositories {
    gradlePluginPortal()
    mavenLocal()
  }
}

And in build.gradle:

plugins {
  id "com.google.protobuf" version "0.10.0-SNAPSHOT"
}

Examples

Stand-alone examples are available for each of gradle's supported languages.

  • Groovy (Default)
    • Run ../../gradlew build under the example directory to test it out.
  • Kotlin (Experimental)
    • Run ./gradlew build under the Kotlin example directory to test it out. This example is set up with Gradle 4.10, the minimum required version.

Directories that start with testProject can also serve as usage examples for advanced options, although they cannot be compiled as individual projects.

Adding the plugin to your project

This plugin must work with either the Java plugin or the Android plugin.

Configuring Protobuf compilation

The Protobuf plugin assumes Protobuf files (*.proto) are organized in the same way as Java source files, in sourceSets. The Protobuf files of a sourceSet (or variant in an Android project) are compiled in a single protoc run, and the generated files are added to the input of the Java compilation run of that sourceSet (or variant).

Customizing source directories

The plugin adds a new sources block named proto alongside java to every sourceSet. By default, it includes all *.proto files under src/$sourceSetName/proto. You can customize it in the same way as you would customize the java sources.

Java projects: use the top-level sourceSet:

sourceSets {
  main {
    proto {
      // In addition to the default 'src/main/proto'
      srcDir 'src/main/protobuf'
      srcDir 'src/main/protocolbuffers'
      // In addition to the default '**/*.proto' (use with caution).
      // Using an extension other than 'proto' is NOT recommended,
      // because when proto files are published along with class files, we can
      // only tell the type of a file from its extension.
      include '**/*.protodevel'
    }
    java {
      ...
    }
  }
  test {
    proto {
      // In addition to the default 'src/test/proto'
      srcDir 'src/test/protocolbuffers'
    }
  }
}

Android projects: use android.sourceSets:

android {
  sourceSets {
    main {
      proto {
        ...
      }
      java {
        ...
      }
    }
  }
}

Customizing Protobuf compilation

The plugin adds a protobuf block to the project. It provides all the configuration knobs.

Locate external executables

By default the plugin will search for the protoc executable in the system search path. We recommend you to take the advantage of pre-compiled protoc that we have published on Maven Central:

protobuf {
  ...
  // Configure the protoc executable
  protoc {
    // Download from repositories
    artifact = 'com.google.protobuf:protoc:3.0.0'
  }
  ...
}

You may also specify a local path.

protobuf {
  ...
  protoc {
    path = '/usr/local/bin/protoc'
  }
  ...
}

Multiple assignments are allowed in the protoc block. The last one wins.

You may also run protoc with codegen plugins. For a codegen plugin named as "foo", protoc will by default use protoc-gen-foo from system search path. You can also specify a downloadable artifact or a local path for it in the plugins block, in the same syntax as in the protoc block above. This will not apply the plugins. You need to configure the tasks in the generateProtoTasks block introduced below to apply the plugins defined here.

protobuf {
  ...
  // Locate the codegen plugins
  plugins {
    // Locate a plugin with name 'grpc'. This step is optional.
    // If you leave it empty, it uses the current directory.
    // If you don't specify it, protoc will try to use "protoc-gen-grpc" from
    // system search path.
    grpc {
      artifact = 'io.grpc:protoc-gen-grpc-java:1.0.0-pre2'
      // or
      // path = 'tools/protoc-gen-grpc-java'
    }
    // Any other plugins
    ...
  }
  ...
}

The syntax for artifact follows Artifact Classifiers where the default classifier is project.osdetector.classifier (ie "${project.osdetector.os}-${project.osdetector.arch}") and the default extension is "exe". Non-C++ implementations of codegen plugins can be used if a constant classifier is specified (eg "com.example:example-generator:1.0.0:-jvm8_32").

Customize code generation tasks

The Protobuf plugin generates a task for each protoc run, which is for a sourceSet in a Java project, or a variant in an Android project. The task has configuration interfaces that allow you to control the type of outputs, the codegen plugins to use, and parameters.

You must configure these tasks in the generateProtoTasks block, which provides you helper functions to conveniently access tasks that are tied to a certain build element, and also ensures you configuration will be picked up correctly by the plugin.

DONOTs:

  • DO NOT assume the names of the tasks, as they may change.
  • DO NOT configure the tasks outside of the generateProtoTasks block, because there are subtle timing constraints on when the tasks should be configured.
protobuf {
  ...
  generateProtoTasks {
    // all() returns the collection of all protoc tasks
    all().configureEach { task ->
      // Here you can configure the task
    }

    // In addition to all(), you may select tasks by various criteria:

    // (Java-only) returns tasks for a sourceSet
    ofSourceSet('main')

    // (Android-only selectors)
    // Returns tasks for a flavor
    ofFlavor('demo')
    // Returns tasks for a buildType
    ofBuildType('release')
    // Returns tasks for a variant
    ofVariant('demoRelease')
    // Returns non-androidTest tasks
    ofNonTest()
    // Return androidTest tasks
    ofTest()
  }
}

Each code generation task has two collections:

  • builtins: code generators built in protoc, e.g., java, cpp, python.
  • plugins: code generation plugins that work with protoc, e.g., grpc. They must be defined in the protobuf.plugins block in order to be added to a task.

Configure what to generate

Code generation is done by protoc builtins and plugins. Each builtin/plugin generates a certain type of code. To add or configure a builtin/plugin on a task, list its name followed by a braces block. Put options in the braces if wanted. For example:

task.builtins {
  // This yields
  // "--java_out=example_option1=true,example_option2:/path/to/output"
  // on the protoc commandline, which is equivalent to
  // "--java_out=/path/to/output --java_opt=example_option1=true,example_option2"
  // with the latest version of protoc.
  java {
    option 'example_option1=true'
    option 'example_option2'
  }
  // Add cpp output without any option.
  // DO NOT omit the braces if you want this builtin to be added.
  // This yields
  // "--cpp_out=/path/to/output" on the protoc commandline.
  cpp { }
}

task.plugins {
  // Add grpc output without any option.  grpc must have been defined in the
  // protobuf.plugins block.
  // This yields
  // "--grpc_out=/path/to/output" on the protoc commandline.
  grpc { }
}

Default outputs

Java projects: the java builtin is added by default: without any further specification, Java classes will be generated during the build process.

Python output can be generated by adding the python builtin:

protobuf {
  generateProtoTasks {
    all().configureEach { task ->
      task.builtins {
        // Generates Python code
        python { }

        // If you wish to avoid generating Java files:
        remove java
      }
    }
  }
}

Note the generated Python code will not be included for compilation, you will need to add them as sources to Python's compilation tasks manually. See this section for details about where the code will be generated.

Android projects: no default output will be added. Since Protobuf 3.0.0, the lite runtime is the recommended Protobuf library for Android.

For Protobuf versions from 3.0.x through 3.7.x, lite code generation is provided as a protoc plugin (protobuf-lite). Example:

dependencies {
  // You need to depend on the lite runtime library, not protobuf-java
  implementation 'com.google.protobuf:protobuf-lite:3.0.0'
}

protobuf {
  protoc {
    // You still need protoc like in the non-Android case
    artifact = 'com.google.protobuf:protoc:3.7.0'
  }
  plugins {
    javalite {
      // The codegen for lite comes as a separate artifact
      artifact = 'com.google.protobuf:protoc-gen-javalite:3.0.0'
    }
  }
  generateProtoTasks {
    all().configureEach { task ->
      task.builtins {
        // In most cases you don't need the full Java output
        // if you use the lite output.
        remove java
      }
      task.plugins {
        javalite { }
      }
    }
  }
}

Starting from Protobuf 3.8.0, lite code generation is built into protoc's "java" output. Example:

dependencies {
  // You need to depend on the lite runtime library, not protobuf-java
  implementation 'com.google.protobuf:protobuf-javalite:3.8.0'
}

protobuf {
  protoc {
    artifact = 'com.google.protobuf:protoc:3.8.0'
  }
  generateProtoTasks {
    all().configureEach { task ->
      task.builtins {
        java {
          option "lite"
        }
      }
    }
  }
}

Generate descriptor set files

{ task ->
  // If true, will generate a descriptor_set.desc file under
  // task.outputBaseDir. Default is false.
  // See --descriptor_set_out in protoc documentation about what it is.
  task.generateDescriptorSet = true

  // Allows to override the default for the descriptor set location
  task.descriptorSetOptions.path =
    "${projectDir}/build/descriptors/${task.sourceSet.name}.dsc"

  // If true, the descriptor set will contain line number information
  // and comments. Default is false.
  task.descriptorSetOptions.includeSourceInfo = true

  // If true, the descriptor set will contain all transitive imports and
  // is therefore self-contained. Default is false.
  task.descriptorSetOptions.includeImports = true
}

Change where files are generated

Generated files are under task.outputBaseDir with a subdirectory per builtin and plugin. This produces a folder structure of $buildDir/generated/source/proto/$sourceSet/$builtinPluginName.

The subdirectory name, which is by default $builtinPluginName, can be changed by setting the outputSubDir property in the builtins or plugins block of a task configuration within generateProtoTasks block (see previous section). E.g.,

{ task ->
  task.plugins {
    grpc {
      // Use subdirectory 'grpcjava' instead of the default 'grpc'
      outputSubDir = 'grpcjava'
    }
  }
}

Protos in dependencies

If a Java project contains proto files, they will be packaged in the jar files along with the compiled classes.

Protos in dependencies (e.g. upstream jars) can be put in either in the compile configuration or the protobuf configuration.

If the dependency is put in the compile configuration, the proto files are extracted to an extracted-include-protos directory and added to the --proto_path flag of the protoc command line, so that they can be imported by the proto files of the current project. The imported proto files will not be compiled since they have already been compiled in their own projects. Example:

dependencies {
  implementation project(':someProjectWithProtos')
  testImplementation files("lib/some-testlib-with-protos.jar")
}

If the dependency is put in the protobuf configuration, the proto files are extracted to a extracted-protos directory and added to the protoc command line as files to compile, in the same protoc invocation as the current project's proto files (if any). Example:

dependencies {
  // protos can be from a local package,
  protobuf files('lib/protos.tar.gz')
  // ... a local directory,
  protobuf files('ext/')   // NEVER use fileTree(). See issue #248.
  // ... or an artifact from a repository
  testProtobuf 'com.example:published-protos:1.0.0'
}

Pre-compiled protoc artifacts

This Maven Central directory lists pre-compiled protoc artifacts that can be used by this plugin.

Tips for IDEs

IntelliJ IDEA

Be sure to enable delegate IDE build/run actions to Gradle so that Intellij does not use its internal build mechanism to compile source code. This plugin ensures that code generation happens before Gradle's build step. If the setting is off, Intellij's own build system will be used instead of Gradle.

Enable the setting with:

Settings -> Build, Execution, Deployment
  -> Build Tools -> Gradle -> Runner
  -> Delegate IDE build/run actions to gradle.

This plugin integrates with the idea plugin and automatically registers the proto files and generated Java code as sources.

Testing the plugin

testProject* are testing projects that uses this plugin to compile .proto files. Because the tests include an Android project, you need to install Android SDK Tools.

After you made any change to the plugin, be sure to run these tests.

$ ./gradlew test

More Repositories

1

material-design-icons

Material Design icons by Google (Material Symbols)
50,560
star
2

guava

Google core libraries for Java
Java
48,313
star
3

zx

A tool for writing better scripts
JavaScript
42,760
star
4

styleguide

Style guides for Google-originated open-source projects
HTML
37,420
star
5

leveldb

LevelDB is a fast key-value storage library written at Google that provides an ordered mapping from string keys to string values.
C++
36,205
star
6

googletest

GoogleTest - Google Testing and Mocking Framework
C++
34,040
star
7

material-design-lite

Material Design Components in HTML/CSS/JS
HTML
32,281
star
8

comprehensive-rust

This is the Rust course used by the Android team at Google. It provides you the material to quickly teach Rust.
Rust
27,842
star
9

python-fire

Python Fire is a library for automatically generating command line interfaces (CLIs) from absolutely any Python object.
Python
26,842
star
10

mediapipe

Cross-platform, customizable ML solutions for live and streaming media.
C++
25,626
star
11

gson

A Java serialization/deserialization library to convert Java Objects into JSON and back
Java
23,317
star
12

flatbuffers

FlatBuffers: Memory Efficient Serialization Library
C++
23,037
star
13

iosched

The Google I/O Android App
Kotlin
21,772
star
14

ExoPlayer

This project is deprecated and stale. The latest ExoPlayer code is available in https://github.com/androidx/media
Java
21,710
star
15

eng-practices

Google's Engineering Practices documentation
19,942
star
16

web-starter-kit

Web Starter Kit - a workflow for multi-device websites
HTML
18,422
star
17

flexbox-layout

Flexbox for Android
Kotlin
18,230
star
18

fonts

Font files available from Google Fonts, and a public issue tracker for all things Google Fonts
HTML
18,222
star
19

filament

Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS, and WebGL2
C++
17,554
star
20

cadvisor

Analyzes resource usage and performance characteristics of running containers.
Go
17,078
star
21

gvisor

Application Kernel for Containers
Go
15,733
star
22

libphonenumber

Google's common Java, C++ and JavaScript library for parsing, formatting, and validating international phone numbers.
C++
15,728
star
23

WebFundamentals

Former git repo for WebFundamentals on developers.google.com
JavaScript
13,851
star
24

yapf

A formatter for Python files
Python
13,755
star
25

brotli

Brotli compression format
TypeScript
13,363
star
26

tink

Tink is a multi-language, cross-platform, open source library that provides cryptographic APIs that are secure, easy to use correctly, and hard(er) to misuse.
Java
13,318
star
27

deepdream

13,212
star
28

wire

Compile-time Dependency Injection for Go
Go
12,919
star
29

guetzli

Perceptual JPEG encoder
C++
12,917
star
30

guice

Guice (pronounced 'juice') is a lightweight dependency injection framework for Java 11 and above, brought to you by Google.
Java
12,458
star
31

blockly

The web-based visual programming editor.
TypeScript
12,392
star
32

sanitizers

AddressSanitizer, ThreadSanitizer, MemorySanitizer
C
11,410
star
33

or-tools

Google's Operations Research tools:
C++
11,144
star
34

dopamine

Dopamine is a research framework for fast prototyping of reinforcement learning algorithms.
Jupyter Notebook
10,529
star
35

grumpy

Grumpy is a Python to Go source code transcompiler and runtime.
Go
10,464
star
36

oss-fuzz

OSS-Fuzz - continuous fuzzing for open source software.
Shell
10,389
star
37

auto

A collection of source code generators for Java.
Java
10,234
star
38

go-github

Go library for accessing the GitHub v3 API
Go
10,206
star
39

go-cloud

The Go Cloud Development Kit (Go CDK): A library and tools for open cloud development in Go.
Go
9,546
star
40

sentencepiece

Unsupervised text tokenizer for Neural Network-based text generation.
C++
8,657
star
41

tsunami-security-scanner

Tsunami is a general purpose network security scanner with an extensible plugin system for detecting high severity vulnerabilities with high confidence.
Java
8,232
star
42

re2

RE2 is a fast, safe, thread-friendly alternative to backtracking regular expression engines like those used in PCRE, Perl, and Python. It is a C++ library.
C++
8,190
star
43

traceur-compiler

Traceur is a JavaScript.next-to-JavaScript-of-today compiler
JavaScript
8,173
star
44

trax

Trax — Deep Learning with Clear Code and Speed
Python
8,051
star
45

pprof

pprof is a tool for visualization and analysis of profiling data
Go
7,875
star
46

skia

Skia is a complete 2D graphic library for drawing Text, Geometries, and Images.
C++
7,874
star
47

benchmark

A microbenchmark support library
C++
7,812
star
48

magika

Detect file content types with deep learning
Rust
7,680
star
49

android-classyshark

Android and Java bytecode viewer
Java
7,492
star
50

accompanist

A collection of extension libraries for Jetpack Compose
Kotlin
7,442
star
51

closure-compiler

A JavaScript checker and optimizer.
Java
7,394
star
52

agera

Reactive Programming for Android
Java
7,227
star
53

latexify_py

A library to generate LaTeX expression from Python code.
Python
7,160
star
54

diff-match-patch

Diff Match Patch is a high-performance library in multiple languages that manipulates plain text.
Python
7,132
star
55

flutter-desktop-embedding

Experimental plugins for Flutter for Desktop
C++
7,102
star
56

glog

C++ implementation of the Google logging module
C++
7,017
star
57

jsonnet

Jsonnet - The data templating language
Jsonnet
6,938
star
58

model-viewer

Easily display interactive 3D models on the web and in AR!
TypeScript
6,858
star
59

lovefield

Lovefield is a relational database for web apps. Written in JavaScript, works cross-browser. Provides SQL-like APIs that are fast, safe, and easy to use.
JavaScript
6,847
star
60

error-prone

Catch common Java mistakes as compile-time errors
Java
6,818
star
61

draco

Draco is a library for compressing and decompressing 3D geometric meshes and point clouds. It is intended to improve the storage and transmission of 3D graphics.
C++
6,459
star
62

gops

A tool to list and diagnose Go processes currently running on your system
Go
6,375
star
63

gopacket

Provides packet processing capabilities for Go
Go
6,289
star
64

automl

Google Brain AutoML
Jupyter Notebook
6,230
star
65

osv-scanner

Vulnerability scanner written in Go which uses the data provided by https://osv.dev
Go
6,222
star
66

flax

Flax is a neural network library for JAX that is designed for flexibility.
Jupyter Notebook
6,085
star
67

grafika

Grafika test app
Java
6,071
star
68

snappy

A fast compressor/decompressor
C++
6,068
star
69

physical-web

The Physical Web: walk up and use anything
Java
6,017
star
70

j2objc

A Java to iOS Objective-C translation tool and runtime.
Java
5,990
star
71

gemma.cpp

lightweight, standalone C++ inference engine for Google's Gemma models.
C++
5,961
star
72

ios-webkit-debug-proxy

A DevTools proxy (Chrome Remote Debugging Protocol) for iOS devices (Safari Remote Web Inspector).
C
5,918
star
73

seesaw

Seesaw v2 is a Linux Virtual Server (LVS) based load balancing platform.
Go
5,634
star
74

EarlGrey

🍵 iOS UI Automation Test Framework
Objective-C
5,616
star
75

seq2seq

A general-purpose encoder-decoder framework for Tensorflow
Python
5,577
star
76

google-java-format

Reformats Java source code to comply with Google Java Style.
Java
5,538
star
77

mesop

Rapidly build AI apps in Python
Python
5,401
star
78

wireit

Wireit upgrades your npm/pnpm/yarn scripts to make them smarter and more efficient.
TypeScript
5,385
star
79

syzkaller

syzkaller is an unsupervised coverage-guided kernel fuzzer
Go
5,350
star
80

uuid

Go package for UUIDs based on RFC 4122 and DCE 1.1: Authentication and Security Services.
Go
5,284
star
81

clusterfuzz

Scalable fuzzing infrastructure.
Python
5,283
star
82

battery-historian

Battery Historian is a tool to analyze battery consumers using Android "bugreport" files.
Go
5,249
star
83

gemma_pytorch

The official PyTorch implementation of Google's Gemma models
Python
5,242
star
84

bbr

5,156
star
85

gumbo-parser

An HTML5 parsing library in pure C99
HTML
5,141
star
86

git-appraise

Distributed code review system for Git repos
Go
5,122
star
87

google-authenticator

Open source version of Google Authenticator (except the Android app)
Java
5,077
star
88

gts

☂️ TypeScript style guide, formatter, and linter.
TypeScript
5,071
star
89

closure-library

Google's common JavaScript library
JavaScript
4,881
star
90

grr

GRR Rapid Response: remote live forensics for incident response
Python
4,757
star
91

cameraview

[DEPRECATED] Easily integrate Camera features into your Android app
Java
4,734
star
92

pytype

A static type analyzer for Python code
Python
4,731
star
93

liquidfun

2D physics engine for games
C++
4,559
star
94

clasp

🔗 Command Line Apps Script Projects
TypeScript
4,525
star
95

google-ctf

Google CTF
Python
4,477
star
96

gxui

An experimental Go cross platform UI library.
Go
4,450
star
97

santa

A binary authorization and monitoring system for macOS
Objective-C++
4,402
star
98

bloaty

Bloaty: a size profiler for binaries
C++
4,386
star
99

tcmalloc

C++
4,339
star
100

ko

Build and deploy Go applications on Kubernetes
Go
4,329
star