Browse Source

Add an article explaining how to install `protoc` (#36)

Motivation:

The official instructions for installing `protoc` don't include
instructions for using a package manager. A number of our docs refernce
having `protoc` installed as a prerequisite, it'd be useful to have docs
on how to install using a package manager.

Modifications:

- Add a doc about installing protoc

Result:

More docs
George Barnett 1 year ago
parent
commit
7d129cecc3

+ 59 - 0
Sources/GRPCProtobuf/Documentation.docc/Articles/Installing-protoc.md

@@ -0,0 +1,59 @@
+# Installing protoc
+
+Learn how to install `protoc`, the Protocol Buffers compiler.
+
+## Overview
+
+The Protocol Buffers compiler is a command line tool for generating source code from `.proto`
+files and is required to generate gRPC stubs and messages. You can learn more about it on the
+[Protocol Buffers website](https://protobuf.dev/).
+
+You can install `protoc` in a number of ways including:
+
+1. Via a package manager,
+2. By downloading the binary.
+
+### Install via a package manager
+
+Using a package manager is the easiest way to install `protoc`.
+
+On macOS you can use [Homebrew](https://brew.sh):
+
+```sh
+brew install protobuf
+```
+
+On Ubuntu and Debian you can use `apt`:
+
+```sh
+apt update && apt install -y protobuf-compiler
+```
+
+On Fedora you can use `dnf`:
+
+```sh
+dnf install -y protobuf-compiler
+```
+
+### Installing a pre-built binary
+
+If you're unable to use a package manager to install `protoc` then you may be able
+to download a pre-built binary from the [Protocol Buffers GitHub
+repository](https://github.com/protocolbuffers/protobuf).
+
+First, find and download the appropriate binary for your system from the
+ [releases](https://github.com/protocolbuffers/protobuf/releases) page.
+
+Next, unzip the artifact to a directory called `protoc`:
+
+```sh
+unzip /path/to/downloaded/protoc-{VERSION}-{OS}.zip -d protoc
+```
+
+Finally, move `protoc/bin/protoc` to somewhere in your `$PATH` such as `/usr/local/bin`:
+
+```sh
+mv protoc/bin/protoc /usr/local/bin
+```
+
+You can now remove the `protoc` directory.

+ 7 - 1
Sources/GRPCProtobuf/Documentation.docc/Documentation.md

@@ -4,13 +4,19 @@ A package integrating Swift Protobuf with gRPC Swift.
 
 
 ## Overview
 ## Overview
 
 
-This package provides two products:
+This package provides three products:
 - ``GRPCProtobuf``, a module providing runtime serialization and deserialization components for
 - ``GRPCProtobuf``, a module providing runtime serialization and deserialization components for
   [SwiftProtobuf](https://github.com/apple/swift-protobuf).
   [SwiftProtobuf](https://github.com/apple/swift-protobuf).
 - `protoc-gen-grpc-swift`, an executable which is a plugin for `protoc`, the Protocol Buffers
 - `protoc-gen-grpc-swift`, an executable which is a plugin for `protoc`, the Protocol Buffers
   compiler. An article describing how to generate gRPC Swift stubs using it is available with the
   compiler. An article describing how to generate gRPC Swift stubs using it is available with the
   `grpc-swift` documentation on the [Swift Package
   `grpc-swift` documentation on the [Swift Package
   Index](https://swiftpackageindex.com/grpc/grpc-swift/documentation).
   Index](https://swiftpackageindex.com/grpc/grpc-swift/documentation).
+- `GRPCProtobufGenerator`, a Swift Package build plugin for generating stubs as part of the build
+  process.
+
+## Essentials
+
+- <doc:Installing-protoc>
 
 
 ## Topics
 ## Topics