From 58b98401c3912d971fc8579b42482abe5e6acd89 Mon Sep 17 00:00:00 2001 From: Joshua Humphries Date: Wed, 12 Jun 2019 15:41:57 -0400 Subject: [PATCH] overhaul README --- README.md | 32 ++++++++++++++++++++------------ 1 file changed, 20 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 3193553..6c369cd 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,29 @@ # Go-protoc [![Build Status](https://travis-ci.org/jhump/goprotoc.svg?branch=master)](https://travis-ci.org/jhump/goprotoc/branches) [![Go Report Card](https://goreportcard.com/badge/github.com/jhump/goprotoc)](https://goreportcard.com/report/github.com/jhump/goprotoc) +[![GoDoc](https://godoc.org/github.com/jhump/goprotoc/plugins?status.svg)](https://godoc.org/github.com/jhump/goprotoc/plugins) -This library makes it easy to implement `protoc` plugins in Go. It includes an interface that plugins implement -as well as libraries to take care of integration with `protoc` (e.g. implementing the proper plugin protocol) and -to provide "name resolution" logic: computing qualified names in Go source code for elements in proto descriptors. +This repo makes it easy to work in the protobuf tool chain using Go. -[![GoDoc](https://godoc.org/github.com/jhump/goprotoc/plugins?status.svg)](https://godoc.org/github.com/jhump/goprotoc/plugins) +## Writing Plugins for `protoc` +First and foremost, the included `plugins` package makes it easy to implement `protoc` plugins in Go. It defines +an interface that plugins implement as well as facilities to actually integrate with `protoc` (e.g. implementing +the proper plugin protocol). It also provides "name resolution" logic: computing qualified names in Go source +code for elements in proto descriptors. This makes it a snap to write plugins in Go that generate additional Go +code from your proto sources. + +## Pure Go version of `protoc` +This repo also contains a pure-Go re-implementation of `protoc`. This new version of `protoc`, named `goprotoc` +(of course!), will delegate to a `protoc` executable on the path, driving it as if it were a plugin, for generating +C++, C#, Objective-C, Java, JavaScript, Python, PHP, and Ruby code (since they are implemented in `protoc` itself). +But it provides descriptors to `protoc`, parsed by `goprotoc`, instead of having `protoc` re-parse all of the source +code. And it can invoke any other plugins (such as `protoc-gen-go`) the same way that `protoc` would. -## Other Goodies -It also includes a `protoc` plugin named `protoc-gen-gox` that can be the entry point for generating Go code. It +In addition to the `goprotoc` command, this repo provides a package that other Go programs can use as the +entry-point to running Protocol Buffer code gen, without having to shell out to an external program. + +## Extras +You'll also find a `protoc` plugin named `protoc-gen-gox` that can be the entry point for generating Go code. It will delegate to `protoc-gen-go` for standard code gen and gRPC code gen, but it can also be configured to execute other plugins that emit additional Go code. It's sort of like a plugin multiplexer that supports a configuration file for enabling and configuring the various plugins that it invokes. - -As an interesting exercise, this repo also contains a pure-Go re-implementation of `protoc`. This new version of -`protoc`, named `goprotoc` (of course!), will delegate to a `protoc` executable on the path, driving it as if it -were a plugin, for generating C++, C#, Objective-C, Java, JavaScript, Python, PHP, and Ruby code (since they are -implemented in `protoc` itself). But it provides descriptors to `protoc`, parsed by `goprotoc`, instead of having -`protoc` re-parse all of the source code.