From f7d6d4141429c30062459f733b56627e9caf974f Mon Sep 17 00:00:00 2001
From: George Barnett <gbarnett@apple.com>
Date: Fri, 24 Jan 2025 09:55:24 +0000
Subject: [PATCH] Add an article explaining how to install `protoc`

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
---
 .../Articles/Installing-protoc.md             | 59 +++++++++++++++++++
 .../Documentation.docc/Documentation.md       |  8 ++-
 2 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 Sources/GRPCProtobuf/Documentation.docc/Articles/Installing-protoc.md

diff --git a/Sources/GRPCProtobuf/Documentation.docc/Articles/Installing-protoc.md b/Sources/GRPCProtobuf/Documentation.docc/Articles/Installing-protoc.md
new file mode 100644
index 0000000..85486d4
--- /dev/null
+++ b/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.
diff --git a/Sources/GRPCProtobuf/Documentation.docc/Documentation.md b/Sources/GRPCProtobuf/Documentation.docc/Documentation.md
index 1d1f0d5..fe78734 100644
--- a/Sources/GRPCProtobuf/Documentation.docc/Documentation.md
+++ b/Sources/GRPCProtobuf/Documentation.docc/Documentation.md
@@ -4,13 +4,19 @@ A package integrating Swift Protobuf with gRPC Swift.
 
 ## Overview
 
-This package provides two products:
+This package provides three products:
 - ``GRPCProtobuf``, a module providing runtime serialization and deserialization components for
   [SwiftProtobuf](https://github.com/apple/swift-protobuf).
 - `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
   `grpc-swift` documentation on the [Swift Package
   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